AssetGraph

AssetGraph

A graph model of a website, consisting of Assets (edges) and Relations.

Constructor

new AssetGraph(options)

Source:

Create a new AssetGraph instance.

Options:

  • root (optional) The root URL of the graph, either as a fully qualified file: or http: url or file system path. Defaults to the current directory, ie. file://<process.cwd()>/. The purpose of the root option is to allow resolution of root-relative urls (eg. <a href="/foo.html">) from file: locations.

Examples:

new AssetGraph()
    // => root: "file:///current/working/dir/"

new AssetGraph({root: '/absolute/fs/path'});
    // => root: "file:///absolute/fs/path/"

new AssetGraph({root: 'relative/path'})
    // => root: "file:///current/working/dir/relative/path/"
Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Description
root String <optional>

AssetGraph root, allowing root relative URL resolution
canonicalRoot String <optional>

Canonical URL root of deployed graph. Matching relations will be treated as root relative

Extends

  • EventEmitter

Members

canonicalRoot :String

Source:

The absolute root url of the graph if it was deployed on its production domain.

Some URLs must be canonical and point to the domain as well, which poses some problems when populating a dependency graph from disc. Canonical URLs will be treated as cross origin if canonicalRoot is not set.

When canonicalUrl is set, any encounter of a relation to an asset with a canonical URL will be assumed to also exist on disc at the corresponding AssetGraph.root relative URL, and thus loaded from there.

Setting a Relation to have relation.canonical = true will cause the relations href to be absolute and prepended with the graphs canonicalRoot

Type:
  • String

root :String

Source:

The absolute root url of the graph, always includes a trailing slash. A normalized version of the root option provided to the constructor.

Type:
  • String

Methods

(static) registerAsset(Constructor, type)

Source:

Register a new Asset type in AssetGraph

Parameters:
Name Type Description
Constructor function

An Asset constructor
type String

a unique type for the asset

(static) registerRelation(fileNameOrConstructor, type)

Source:

Register a new Relation type in AssetGraph

Parameters:
Name Type Description
fileNameOrConstructor function | String

A Relation constructor or a file name that exports one
type String

A unique type for the relation

addAsset(assetConfig) → {Asset}

Source:

Add an asset to the graph.

Parameters:
Name Type Description
assetConfig Asset | String | AssetConfig

The Asset, Url or AssetConfig to construct an Asset from
Returns:

The assets instance that was added

Type
Asset

addAssets(…assetConfigs) → {Array.<Asset>}

Source:

Add assets to the graph.

Parameters:
Name Type Attributes Description
assetConfigs Array.<Asset> | String | Array.<String> | AssetConfig | Array.<AssetConfig> <repeatable>

The asset specs to add
Returns:

The assets instances that were added

Type
Array.<Asset>

buildRootRelativeUrl()

Source:
Deprecated:
  • Use the more generic AssetGraph#buildHref instead

findAssets(queryObjopt) → {Array.<Asset>}

Source:

Query assets in the graph.

Example usage:

const allAssetsInGraph = ag.findAssets();

const htmlAssets = ag.findAssets({type: 'Html'});

const localImageAssets = ag.findAssets({
    url: { protocol: 'file:', extension: { $regex: /^(?:png|gif|jpg)$/ }
});

const orphanedJavaScriptAssets = ag.findAssets(function (asset) {
    return asset.type === 'JavaScript' &&
           ag.findRelations({to: asset}).length === 0;
});

const textBasedAssetsOnGoogleCom = ag.findAssets({
    isText: true,
    url: {$regex: /^https?:\/\/(?:www\.)google\.com\//}
});
Parameters:
Name Type Attributes Default Description
queryObj Object <optional>
 {}

Query to match assets against. Will match all assets if not provided.
Returns:

The found assets.

Type
Array.<Asset>

findRelations(queryObjopt) → {Array.<Relation>}

Source:

Query relations in the graph.

Example usage:

const allRelationsInGraph = ag.findRelations();

const allHtmlScriptRelations = ag.findRelations({
    type: 'HtmlScript'
});

const htmlAnchorsPointingAtLocalImages = ag.findRelations({
    type: 'HtmlAnchor',
    to: {isImage: true, url: {$regex: /^file:/}}
});
Parameters:
Name Type Attributes Default Description
queryObj Object <optional>
 {}

Query to match Relations against. Will match all relations if not provided.
Returns:

The found relations.

Type
Array.<Relation>

info(messageOrError)

Source:

Emit a info event on the event bus.

Info events are helpful hints informing of encounters of possible problems, where an automated fix has been applied and everything has been handled

Parameters:
Name Type Description
messageOrError String | Error

The message or error to emit

removeAsset(asset) → {AssetGraph}

Source:

Remove an asset from the graph. Also removes the incoming and outgoing relations of the asset.

Parameters:
Name Type Description
asset Asset

The asset to remove.
Returns:

The AssetGraph instance (chaining-friendly).

Type
AssetGraph

warn(messageOrError)

Source:

Emit a warning event on the event bus.

Warnings events are emitted when AssetGraph encounters an error during it's lifecycle, which doesn't stop it dead in its track.

Warning events are usually errors on a website that you want to fix, since the model might not correspond to your mental model i they go unfixed.

If no event listeners are intercepting warning events, they will escalate to throw.

Parameters:
Name Type Description
messageOrError String | Error

The message or error to emit