mako-tree

> The build tree structure used internally by mako

[![npm version][npm-badge]][npm]
[![npm dependencies][david-badge]][david]
[![npm dev dependencies][david-dev-badge]][david-dev]

API

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

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

$3

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.

$3

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

`js
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.

$3

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

$3

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

$3

Returns the File instance for the given file ID.

$3

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.

$3

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.

$3

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.

$3

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.

$3

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.

$3

Removes the dependency link between parent and child.

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

$3

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.

$3

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.

$3

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.

$3

Removes the dependency link between parent and child.

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

$3

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.

$3

Returns the number of files in the tree.

$3

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

$3

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

$3

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)

$3

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

$3

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.

$3

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

$3

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 })

$3

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

$3

A getter that retrieves the original path for this file.

$3

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

$3

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.

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

Returns a cloned object that can be JSON-serialized.

$3

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

$3

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

$3

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

[david-badge]: https://img.shields.io/david/makojs/tree.svg
[david-dev-badge]: https://img.shields.io/david/dev/makojs/tree.svg
[david-dev]: https://david-dm.org/makojs/tree#info=devDependencies
[david]: https://david-dm.org/makojs/tree
[npm-badge]: https://img.shields.io/npm/v/mako-tree.svg
[npm]: https://www.npmjs.com/package/mako-tree