@vltpkg/graph 0.0.0-0.1730239248325

package/dist/esm/diff.js

@@ -0,0 +1,123 @@
+import { error } from '@vltpkg/error-cause';
+// XXX should file deps *always* be considered changed?
+// unless the thing containing it wasn't possibly changed because it's inside
+// a dep that didn't change?
+// Same with remote deps
+const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
+/**
+ * A Diff object is a representation of a set of changes from one
+ * graph to another, typically from the actual graph as it is reified
+ * on disk, to an intended ideal graph.
+ *
+ * The naming convention can get a bit confusing here, because it's a
+ * set of directed changes from one set of directed objects to another.
+ *
+ * Within the context the Diff object, `from` is the Graph we're coming from,
+ * and `to` is the Graph we're trying to create.
+ */
+export class Diff {
+    from;
+    to;
+    projectRoot;
+    /**
+     * If changes need to be made later for failures of optional nodes,
+     * set this flag so that we know to call graph.gc() at the appropriate time.
+     */
+    hadOptionalFailures = false;
+    /**
+     * Collection of nodes to add and delete
+     */
+    nodes = {
+        /** Nodes in the `to` graph that are not in the `from` graph */
+        add: new Set(),
+        /** Nodes in the `from` graph that are not in the `to` graph */
+        delete: new Set(),
+    };
+    /**
+     * Collection of nodes to add and delete
+     */
+    edges = {
+        /** Edges in the `to` graph that are not found in the `from` graph */
+        add: new Set(),
+        /** Edges in the `from` graph that are not found in the `to` graph */
+        delete: new Set(),
+    };
+    get [Symbol.toStringTag]() {
+        return '@vltpkg/graph.Diff';
+    }
+    constructor(from, to) {
+        this.from = from;
+        this.to = to;
+        this.projectRoot = from.projectRoot;
+        if (to.projectRoot !== from.projectRoot) {
+            throw error('projectRoot mismatch in Graph diff', {
+                wanted: from.projectRoot,
+                found: to.projectRoot,
+            });
+        }
+        for (const [id, node] of this.from.nodes) {
+            if (!this.to.nodes.get(id)?.equals(node)) {
+                this.nodes.delete.add(node);
+            }
+        }
+        for (const [id, node] of this.to.nodes) {
+            if (!this.from.nodes.get(id)?.equals(node)) {
+                this.nodes.add.add(node);
+            }
+        }
+        for (const edge of this.to.edges) {
+            // the node with this dep, in the from  graph
+            const fromNode = this.from.nodes.get(edge.from.id);
+            const fromEdge = fromNode?.edgesOut.get(edge.spec.name);
+            if (fromEdge?.to?.id === edge.to?.id)
+                continue;
+            if (fromEdge?.to)
+                this.edges.delete.add(fromEdge);
+            if (edge.to)
+                this.edges.add.add(edge);
+        }
+        for (const edge of this.from.edges) {
+            // the node with this dep, in the to graph
+            const toNode = this.to.nodes.get(edge.from.id);
+            const toEdge = toNode?.edgesOut.get(edge.spec.name);
+            if (toEdge?.to?.id === edge.to?.id)
+                continue;
+            if (edge.to)
+                this.edges.delete.add(edge);
+            if (toEdge?.to)
+                this.edges.add.add(toEdge);
+        }
+    }
+    [kCustomInspect](_, options) {
+        const red = options?.colors ? ['\x1b[31m', '\x1b[m'] : ['', ''];
+        const green = options?.colors ? ['\x1b[32m', '\x1b[m'] : ['', ''];
+        const lines = [];
+        for (const node of this.nodes.add) {
+            lines.push(`+ ${node.id}`);
+        }
+        for (const node of this.nodes.delete) {
+            lines.push(`- ${node.id}`);
+        }
+        for (const edge of this.edges.add) {
+            /* c8 ignore next */
+            const to = edge.to?.id ?? '';
+            lines.push(`+ ${edge.from.id} ${edge.type} ${edge.spec} ${to}`.trim());
+        }
+        for (const edge of this.edges.delete) {
+            /* c8 ignore next */
+            const to = edge.to?.id ?? '';
+            lines.push(`- ${edge.from.id} ${edge.type} ${edge.spec} ${to}`.trim());
+        }
+        const wrap = (s, c) => c.join(s);
+        const color = options?.colors ?
+            (s) => wrap(s, s.startsWith('+') ? green : red)
+            : (s) => s;
+        return `${this[Symbol.toStringTag]} {
+${lines
+            .sort((a, b) => a.substring(1).localeCompare(b.substring(1), 'en'))
+            .map(s => '  ' + color(s))
+            .join('\n')}
+}`;
+    }
+}
+//# sourceMappingURL=diff.js.map

package/dist/esm/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/diff.ts"],"names":[],"mappings":"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","sourcesContent":["import { error } from '@vltpkg/error-cause'\nimport { InspectOptions } from 'node:util'\nimport { Edge } from './edge.js'\nimport { Graph } from './graph.js'\nimport { Node } from './node.js'\n\n// XXX should file deps *always* be considered changed?\n// unless the thing containing it wasn't possibly changed because it's inside\n// a dep that didn't change?\n// Same with remote deps\n\nconst kCustomInspect = Symbol.for('nodejs.util.inspect.custom')\n\n/**\n * A Diff object is a representation of a set of changes from one\n * graph to another, typically from the actual graph as it is reified\n * on disk, to an intended ideal graph.\n *\n * The naming convention can get a bit confusing here, because it's a\n * set of directed changes from one set of directed objects to another.\n *\n * Within the context the Diff object, `from` is the Graph we're coming from,\n * and `to` is the Graph we're trying to create.\n */\nexport class Diff {\n  from: Graph\n  to: Graph\n\n  projectRoot: string\n\n  /**\n   * If changes need to be made later for failures of optional nodes,\n   * set this flag so that we know to call graph.gc() at the appropriate time.\n   */\n  hadOptionalFailures = false\n\n  /**\n   * Collection of nodes to add and delete\n   */\n  nodes = {\n    /** Nodes in the `to` graph that are not in the `from` graph */\n    add: new Set<Node>(),\n    /** Nodes in the `from` graph that are not in the `to` graph */\n    delete: new Set<Node>(),\n  }\n\n  /**\n   * Collection of nodes to add and delete\n   */\n  edges = {\n    /** Edges in the `to` graph that are not found in the `from` graph */\n    add: new Set<Edge>(),\n    /** Edges in the `from` graph that are not found in the `to` graph */\n    delete: new Set<Edge>(),\n  }\n\n  get [Symbol.toStringTag]() {\n    return '@vltpkg/graph.Diff'\n  }\n\n  constructor(from: Graph, to: Graph) {\n    this.from = from\n    this.to = to\n    this.projectRoot = from.projectRoot\n    if (to.projectRoot !== from.projectRoot) {\n      throw error('projectRoot mismatch in Graph diff', {\n        wanted: from.projectRoot,\n        found: to.projectRoot,\n      })\n    }\n\n    for (const [id, node] of this.from.nodes) {\n      if (!this.to.nodes.get(id)?.equals(node)) {\n        this.nodes.delete.add(node)\n      }\n    }\n\n    for (const [id, node] of this.to.nodes) {\n      if (!this.from.nodes.get(id)?.equals(node)) {\n        this.nodes.add.add(node)\n      }\n    }\n\n    for (const edge of this.to.edges) {\n      // the node with this dep, in the from  graph\n      const fromNode = this.from.nodes.get(edge.from.id)\n      const fromEdge = fromNode?.edgesOut.get(edge.spec.name)\n      if (fromEdge?.to?.id === edge.to?.id) continue\n      if (fromEdge?.to) this.edges.delete.add(fromEdge)\n      if (edge.to) this.edges.add.add(edge)\n    }\n    for (const edge of this.from.edges) {\n      // the node with this dep, in the to graph\n      const toNode = this.to.nodes.get(edge.from.id)\n      const toEdge = toNode?.edgesOut.get(edge.spec.name)\n      if (toEdge?.to?.id === edge.to?.id) continue\n      if (edge.to) this.edges.delete.add(edge)\n      if (toEdge?.to) this.edges.add.add(toEdge)\n    }\n  }\n\n  [kCustomInspect](_: number, options?: InspectOptions): string {\n    const red: [string, string] =\n      options?.colors ? ['\\x1b[31m', '\\x1b[m'] : ['', '']\n    const green: [string, string] =\n      options?.colors ? ['\\x1b[32m', '\\x1b[m'] : ['', '']\n    const lines: string[] = []\n    for (const node of this.nodes.add) {\n      lines.push(`+ ${node.id}`)\n    }\n    for (const node of this.nodes.delete) {\n      lines.push(`- ${node.id}`)\n    }\n    for (const edge of this.edges.add) {\n      /* c8 ignore next */\n      const to = edge.to?.id ?? ''\n      lines.push(\n        `+ ${edge.from.id} ${edge.type} ${edge.spec} ${to}`.trim(),\n      )\n    }\n    for (const edge of this.edges.delete) {\n      /* c8 ignore next */\n      const to = edge.to?.id ?? ''\n      lines.push(\n        `- ${edge.from.id} ${edge.type} ${edge.spec} ${to}`.trim(),\n      )\n    }\n    const wrap = (s: string, c: [string, string]) => c.join(s)\n    const color =\n      options?.colors ?\n        (s: string) => wrap(s, s.startsWith('+') ? green : red)\n      : (s: string) => s\n\n    return `${this[Symbol.toStringTag]} {\n${lines\n  .sort((a, b) => a.substring(1).localeCompare(b.substring(1), 'en'))\n  .map(s => '  ' + color(s))\n  .join('\\n')}\n}`\n  }\n}\n"]}

package/dist/esm/edge.d.ts

@@ -0,0 +1,41 @@
+import { Spec } from '@vltpkg/spec';
+import { InspectOptions } from 'util';
+import { DependencyTypeShort } from './dependencies.js';
+import { Node } from './node.js';
+import { EdgeLike } from './types.js';
+declare const kCustomInspect: unique symbol;
+export declare class Edge implements EdgeLike {
+    get [Symbol.toStringTag](): string;
+    [kCustomInspect](_: number, options: InspectOptions): string;
+    /**
+     * The Node this Edge is connecting from, this is usually the dependent.
+     */
+    from: Node;
+    /**
+     * The node this Edge is connecting to, this is usually a direct dependency.
+     */
+    to?: Node;
+    /**
+     * What type of dependency relationship `from` and `to` nodes have.
+     */
+    type: DependencyTypeShort;
+    /**
+     * The defined spec value for `to` as parsed from the dependent metadata.
+     */
+    spec: Spec;
+    constructor(type: DependencyTypeShort, spec: Spec, from: Node, to?: Node);
+    /**
+     * The name of the dependency `to` as defined in the dependent metadata.
+     */
+    get name(): string;
+    /**
+     * This edge was defined as part of a `devDependencies` in `package.json`
+     */
+    get dev(): boolean;
+    get optional(): boolean;
+    get peer(): boolean;
+    get peerOptional(): boolean;
+    valid(): boolean;
+}
+export {};
+//# sourceMappingURL=edge.d.ts.map

package/dist/esm/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/edge.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAW,cAAc,EAAE,MAAM,MAAM,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErC,QAAA,MAAM,cAAc,eAA2C,CAAA;AAE/D,qBAAa,IAAK,YAAW,QAAQ;IACnC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,WAEvB;IAED,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;IAanD;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;IAEV;;OAEG;IACH,EAAE,CAAC,EAAE,IAAI,CAAA;IAET;;OAEG;IACH,IAAI,EAAE,mBAAmB,CAAA;IAEzB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;gBAGR,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,EAAE,CAAC,EAAE,IAAI;IAQX;;OAEG;IACH,IAAI,IAAI,WAEP;IAED;;OAEG;IACH,IAAI,GAAG,IAAI,OAAO,CAEjB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,KAAK,IAAI,OAAO;CAUjB"}

package/dist/esm/edge.js

@@ -0,0 +1,66 @@
+import { satisfies } from '@vltpkg/satisfies';
+import { inspect } from 'util';
+const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
+export class Edge {
+    get [Symbol.toStringTag]() {
+        return '@vltpkg/graph.Edge';
+    }
+    [kCustomInspect](_, options) {
+        const str = inspect({
+            from: this.from.id,
+            type: this.type,
+            spec: String(this.spec),
+            to: this.to?.id,
+        }, options);
+        return `${this[Symbol.toStringTag]} ${str}`;
+    }
+    /**
+     * The Node this Edge is connecting from, this is usually the dependent.
+     */
+    from;
+    /**
+     * The node this Edge is connecting to, this is usually a direct dependency.
+     */
+    to;
+    /**
+     * What type of dependency relationship `from` and `to` nodes have.
+     */
+    type;
+    /**
+     * The defined spec value for `to` as parsed from the dependent metadata.
+     */
+    spec;
+    constructor(type, spec, from, to) {
+        this.from = from;
+        this.to = to;
+        this.type = type;
+        this.spec = spec;
+    }
+    /**
+     * The name of the dependency `to` as defined in the dependent metadata.
+     */
+    get name() {
+        return this.spec.name;
+    }
+    /**
+     * This edge was defined as part of a `devDependencies` in `package.json`
+     */
+    get dev() {
+        return this.type === 'dev';
+    }
+    get optional() {
+        return this.type === 'peerOptional' || this.type === 'optional';
+    }
+    get peer() {
+        return this.type === 'peer' || this.type === 'peerOptional';
+    }
+    get peerOptional() {
+        return this.type === 'peerOptional';
+    }
+    valid() {
+        return !this.to ?
+            this.optional
+            : satisfies(this.to.id, this.spec, this.from.location, this.from.projectRoot);
+    }
+}
+//# sourceMappingURL=edge.js.map

package/dist/esm/edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../src/edge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAE7C,OAAO,EAAE,OAAO,EAAkB,MAAM,MAAM,CAAA;AAK9C,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAA;AAE/D,MAAM,OAAO,IAAI;IACf,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QACtB,OAAO,oBAAoB,CAAA;IAC7B,CAAC;IAED,CAAC,cAAc,CAAC,CAAC,CAAS,EAAE,OAAuB;QACjD,MAAM,GAAG,GAAG,OAAO,CACjB;YACE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;YAClB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;YACvB,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE;SAChB,EACD,OAAO,CACR,CAAA;QACD,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,GAAG,EAAE,CAAA;IAC7C,CAAC;IAED;;OAEG;IACH,IAAI,CAAM;IAEV;;OAEG;IACH,EAAE,CAAO;IAET;;OAEG;IACH,IAAI,CAAqB;IAEzB;;OAEG;IACH,IAAI,CAAM;IAEV,YACE,IAAyB,EACzB,IAAU,EACV,IAAU,EACV,EAAS;QAET,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;QACZ,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;IACvB,CAAC;IAED;;OAEG;IACH,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAA;IAC5B,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,KAAK,cAAc,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,CAAA;IACjE,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,cAAc,CAAA;IAC7D,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,IAAI,KAAK,cAAc,CAAA;IACrC,CAAC;IAED,KAAK;QACH,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACb,IAAI,CAAC,QAAQ;YACf,CAAC,CAAC,SAAS,CACP,IAAI,CAAC,EAAE,CAAC,EAAE,EACV,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,IAAI,CAAC,QAAQ,EAClB,IAAI,CAAC,IAAI,CAAC,WAAW,CACtB,CAAA;IACP,CAAC;CACF","sourcesContent":["import { satisfies } from '@vltpkg/satisfies'\nimport { Spec } from '@vltpkg/spec'\nimport { inspect, InspectOptions } from 'util'\nimport { DependencyTypeShort } from './dependencies.js'\nimport { Node } from './node.js'\nimport { EdgeLike } from './types.js'\n\nconst kCustomInspect = Symbol.for('nodejs.util.inspect.custom')\n\nexport class Edge implements EdgeLike {\n  get [Symbol.toStringTag]() {\n    return '@vltpkg/graph.Edge'\n  }\n\n  [kCustomInspect](_: number, options: InspectOptions) {\n    const str = inspect(\n      {\n        from: this.from.id,\n        type: this.type,\n        spec: String(this.spec),\n        to: this.to?.id,\n      },\n      options,\n    )\n    return `${this[Symbol.toStringTag]} ${str}`\n  }\n\n  /**\n   * The Node this Edge is connecting from, this is usually the dependent.\n   */\n  from: Node\n\n  /**\n   * The node this Edge is connecting to, this is usually a direct dependency.\n   */\n  to?: Node\n\n  /**\n   * What type of dependency relationship `from` and `to` nodes have.\n   */\n  type: DependencyTypeShort\n\n  /**\n   * The defined spec value for `to` as parsed from the dependent metadata.\n   */\n  spec: Spec\n\n  constructor(\n    type: DependencyTypeShort,\n    spec: Spec,\n    from: Node,\n    to?: Node,\n  ) {\n    this.from = from\n    this.to = to\n    this.type = type\n    this.spec = spec\n  }\n\n  /**\n   * The name of the dependency `to` as defined in the dependent metadata.\n   */\n  get name() {\n    return this.spec.name\n  }\n\n  /**\n   * This edge was defined as part of a `devDependencies` in `package.json`\n   */\n  get dev(): boolean {\n    return this.type === 'dev'\n  }\n\n  get optional(): boolean {\n    return this.type === 'peerOptional' || this.type === 'optional'\n  }\n\n  get peer(): boolean {\n    return this.type === 'peer' || this.type === 'peerOptional'\n  }\n\n  get peerOptional(): boolean {\n    return this.type === 'peerOptional'\n  }\n\n  valid(): boolean {\n    return !this.to ?\n        this.optional\n      : satisfies(\n          this.to.id,\n          this.spec,\n          this.from.location,\n          this.from.projectRoot,\n        )\n  }\n}\n"]}

package/dist/esm/graph.d.ts

@@ -0,0 +1,123 @@
+import { type DepID } from '@vltpkg/dep-id';
+import { Spec, type SpecOptions } from '@vltpkg/spec';
+import { type Manifest } from '@vltpkg/types';
+import { Monorepo } from '@vltpkg/workspaces';
+import { InspectOptions } from 'util';
+import { DependencyTypeShort } from './dependencies.js';
+import { type Edge } from './edge.js';
+import { Node } from './node.js';
+import { GraphLike, NodeLike } from './types.js';
+declare const kCustomInspect: unique symbol;
+export type ManifestInventory = Map<DepID, Manifest>;
+export type GraphOptions = SpecOptions & {
+    /**
+     * The main importer manifest info.
+     */
+    mainManifest: Manifest;
+    /**
+     * An inventory of seen manifests.
+     */
+    manifests?: ManifestInventory;
+    /**
+     * A {@link Monorepo} object, for managing workspaces
+     */
+    monorepo?: Monorepo;
+    /**
+     * Root of the project this graph represents
+     */
+    projectRoot: string;
+};
+export declare class Graph implements GraphLike {
+    #private;
+    get [Symbol.toStringTag](): string;
+    /**
+     * A {@link Monorepo} instance, used for managing workspaces.
+     */
+    monorepo?: Monorepo;
+    /**
+     * An inventory with all manifests related to an install.
+     */
+    manifests: ManifestInventory;
+    /**
+     * A set of all edges in this graph.
+     */
+    edges: Set<Edge>;
+    /**
+     * Map registered dep ids to the node that represent them in the graph.
+     */
+    nodes: Map<DepID, Node>;
+    /**
+     * Map of nodes by their name
+     */
+    nodesByName: Map<string, Set<Node>>;
+    /**
+     * Cached resolutions for spec lookups
+     */
+    resolutions: Map<string, Node>;
+    /**
+     * Reverse map of resolutions
+     */
+    resolutionsReverse: Map<Node, Set<string>>;
+    /**
+     * A set of importer nodes in this graph.
+     */
+    importers: Set<Node>;
+    /**
+     * The {@link Node} that represents the project root `package.json`.
+     */
+    mainImporter: Node;
+    /**
+     * A set of extraneous dependencies found when building the graph.
+     */
+    extraneousDependencies: Set<Edge>;
+    /**
+     * The root of the project this graph represents
+     */
+    projectRoot: string;
+    constructor(options: GraphOptions);
+    /**
+     * Delete all nodes that are unreachable from the importers.
+     * The collection of deleted nodes is returned.
+     *
+     * NOTE: This can be extremely slow for large graphs, and is almost always
+     * unnecessary! Only call when it is known that some unreachable nodes may
+     * have been created, for example when deleting the unneeded subgraph when an
+     * optional node fails to resolve/install.
+     */
+    gc(): Map<DepID, Node>;
+    /**
+     * Create a new edge between two nodes of the graph in case both exist,
+     * in case the destination node does not exists, then a dangling edge,
+     * pointing to nothing will be created to represent that missing dependency.
+     */
+    addEdge(type: DependencyTypeShort, spec: Spec, from: NodeLike, to?: NodeLike): Edge;
+    /**
+     * Find an existing node to satisfy a dependency
+     */
+    findResolution(spec: Spec, fromNode: Node): Node | undefined;
+    /**
+     * Create a new node in the graph.
+     */
+    addNode(id?: DepID, manifest?: Manifest, spec?: Spec, name?: string, version?: string): Node;
+    /**
+     * Place a new package into the graph representation, creating the new
+     * edges and possibly new nodes that are to be expected when traversing
+     * the graph in a top-down direction, e.g: from importers to leafs.
+     *
+     * For different uses that are not a direct top-down traversal of the graph
+     * consider using `addNode()` and `addEdge()` instead.
+     */
+    placePackage(fromNode: Node, depType: DependencyTypeShort, spec: Spec, manifest?: Manifest, id?: DepID): Node | undefined;
+    /**
+     * Removes a node and its relevant edges from the graph.
+     *
+     * If a replacement is provided, then any edges that were previously
+     * pointing to the removed node will be directed to the replacement,
+     * if it is valid to do so.
+     */
+    removeNode(node: Node, replacement?: Node): void;
+    toJSON(): import("./index.js").LockfileData;
+    [kCustomInspect](_: number, options: InspectOptions): string;
+}
+export {};
+//# sourceMappingURL=graph.d.ts.map

package/dist/esm/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAGlE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAW,cAAc,EAAE,MAAM,MAAM,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAA;AAErC,OAAO,EAAE,IAAI,EAAe,MAAM,WAAW,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEhD,QAAA,MAAM,cAAc,eAA2C,CAAA;AAM/D,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AAEpD,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG;IACvC;;OAEG;IACH,YAAY,EAAE,QAAQ,CAAA;IACtB;;OAEG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,qBAAa,KAAM,YAAW,SAAS;;IACrC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,WAEvB;IAMD;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAEnB;;OAEG;IACH,SAAS,EAAE,iBAAiB,CAAA;IAE5B;;OAEG;IACH,KAAK,YAAkB;IAEvB;;OAEG;IACH,KAAK,mBAAyB;IAE9B;;OAEG;IACH,WAAW,yBAA+B;IAE1C;;OAEG;IACH,WAAW,oBAA0B;IAErC;;OAEG;IACH,kBAAkB,yBAA+B;IAEjD;;OAEG;IACH,SAAS,YAAkB;IAE3B;;OAEG;IACH,YAAY,EAAE,IAAI,CAAA;IAElB;;OAEG;IACH,sBAAsB,YAAkB;IAExC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;gBAEP,OAAO,EAAE,YAAY;IA+CjC;;;;;;;;OAQG;IACH,EAAE;IAqBF;;;;OAIG;IACH,OAAO,CACL,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,QAAQ,EACd,EAAE,CAAC,EAAE,QAAQ;IAmCf;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI;IA4BzC;;OAEG;IACH,OAAO,CACL,EAAE,CAAC,EAAE,KAAK,EACV,QAAQ,CAAC,EAAE,QAAQ,EACnB,IAAI,CAAC,EAAE,IAAI,EACX,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM;IA+BlB;;;;;;;OAOG;IACH,YAAY,CACV,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,IAAI,EACV,QAAQ,CAAC,EAAE,QAAQ,EACnB,EAAE,CAAC,EAAE,KAAK;IAkDZ;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,IAAI;IAgCzC,MAAM;IAQN,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;CAIpD"}