mako-tree

The build tree structure used internally by mako

API

The Tree constructor (documented below) is the primary export for the module. It must be used with the new keyword.

var Tree = require('mako-tree');
var tree = new Tree();

Tree([root]) (constructor)

Each instance represents a build tree. Internally, a graph is used to manage the relationships between all the files being tracked.

The root is a project root that will determine all file.base properties. Only 1 root is supported per tree. Also, this value will override any base parameter you specify in when adding files.

Tree@@iterable

This class implements the Iterable interface, which iterates the files in the tree in topological order. (see Tree#getFiles() for more information)

for (const file of tree) {
  // iterate files in topological order
}

This sugar allows you to treat the tree itself as an iterable, which can be useful in interacting with other APIs.

Tree#hasFile(file)

Returns a Boolean reflecting if the given file exists in the tree.

Tree#addFile(params)

Creates a file with the given params and adds it to the tree.

Tree#getFile(file)

Returns the File instance for the given file ID.

Tree#findFile(path)

Searches the tree for a file that has the given path. (either currently, or at any point in it's history) If none is found, it simply returns undefined.

Tree#getFiles([options])

Returns an Array of all the File objects in this graph.

If options.topological is set, the returned list will be in topological order, which respects all dependencies so processing is safe where order matters.

Tree#removeFile(file, [options])

Removes the given file from the tree. It will throw an exception if that file has any current dependency links.

If options.force is set, it will forcefully remove the file, as well as any remaining links.

Tree#hasDependency(parent, child, [options])

Returns a Boolean reflecting if the dependency relationship between parent and child already exists in the tree.

If options.recursive is true, it will check the dependency tree recursively.

Tree#addDependency(parent, child)

Adds a new dependency relationship to the graph setting parent as depending on child.

If either parent or child are not already in the graph, it will throw.

Tree#removeDependency(parent, child)

Removes the dependency link between parent and child.

If this link does not already exist, this will throw.

Tree#dependenciesOf(file, [options])

Returns an Array of files that are direct dependencies of the given file.

If options.recursive is set, it will return all the files down the entire dependency chain.

Tree#hasDependant(child, parent, [options])

Returns a Boolean reflecting if the dependency relationship between child and parent already exists in the tree.

If options.recursive is true, it will check the dependency tree recursively.

Tree#addDependant(child, parent)

Adds a new dependency relationship to the graph setting child as depended on by parent.

If either parent or child are not already in the graph, it will throw.

Tree#removeDependant(child, parent)

Removes the dependency link between parent and child.

If this link does not already exist, this will throw.

Tree#dependantsOf(file, [options])

Returns an Array of files that directly depend on the given file.

If options.recursive is set, it will return all the files up the entire dependency chain.

Tree#size()

Returns the number of files in the tree.

Tree#clone()

Returns a new Tree object that is an effective clone of the original.

Tree#prune([anchors])

Removes any files from the graph that are unaccessible by any of the provided anchors files.

Tree#removeCycles()

Removes any cycles found in the tree. This is only a last-ditch effort before attempting topological sorting, so it makes no guarantees about where it breaks cycles. (circular dependencies should work, but that doesn't change the fact that they should be avoided if possible)

Tree#toJSON()

Returns a trimmed object that can be serialized as JSON. (it should be possible to reconstruct the tree from the output)

Tree#toString([space])

Serializes the tree into a JSON string, which can be written to disk (and then read back) to help reduce the amount of duplicate work between different runs of mako.

The space parameter is there if you want to "pretty-print" the JSON output.

Tree.fromString(input)

Unserializes a JSON string into a Tree instance. (see Tree#toJSON())

File(params, tree) (constructor)

This file class extends vinyl. The params will be passed directly to that constructor. (except where params is a string, then it will be passed as { path: params })

File#type

A getter/setter for the extension name. (without a leading .)

File#initialPath

A getter that retrieves the original path for this file.

File#initialType

A getter that retrieves the original type for this file. (without a leading .)

File#contents

A Buffer containing the contents for this file.

NOTE: using strings is no longer supported for this property as Vinyl only supports Buffer and Stream values.

File#hasDependency(child)

Short-hand for tree.hasDependency(file.path, child).

File#addDependency(child)

Short-hand for tree.addDependency(file.path, child).

File#removeDependency(child)

Short-hand for tree.removeDependency(file.path, child).

File#dependencies([options])

Short-hand for tree.dependenciesOf(file.path, options).

File#hasDependant(parent)

Short-hand for tree.hasDependant(file.path, parent).

File#addDependant(parent)

Short-hand for tree.addDependency(file.path, parent).

File#removeDependant(parent)

Short-hand for tree.removeDependant(file.path, parent).

File#dependants([options])

Short-hand for tree.dependantsOf(file.path, options).

File#reset()

Used by mako to reset a file enough that it can be safely processed again.

File#clone()

Creates a clone of this file, such as when cloning the parent Tree.

File#copy(newPath, [options])

Copies this file to a newPath (relative to current path) with a new ID that can be added to a Tree as a distinct file.

Available options:

• resetPath when enabled, the path history will only contain the newPath

File#toJSON()

Returns a cloned object that can be JSON-serialized.

File#toString()

Returns a string representation via Vinyl#inspect() useful for logging.

File.fromObject(input, tree)

Takes a plain object and converts it into a File instance.

File.id()

The id generator for files, exposed here to allow public use and customization.