@khapu2906/treasure-chest 1.4.1 → 1.5.0

package/dist/types/Graph.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Dependency graph for inspecting and filtering container bindings
+ *
+ * @module Graph
+ */
+import type { Lifecycle, ServiceKey } from './types';
+/** A single node in the dependency graph, representing one registered binding */
+export interface GraphNode {
+    /** Stable string form of the service key */
+    key: string;
+    /** Lifecycle of the binding (transient, singleton, scoped) */
+    lifecycle: Lifecycle;
+    /** Whether this binding is registered as lazy */
+    lazy: boolean;
+    /** Context this binding is scoped to, if it's a contextual binding */
+    context?: string;
+    /** Original key this node is an alias for, if any */
+    aliasOf?: string;
+    /** Whether this binding comes from a parent or composed container */
+    inherited: boolean;
+    /** Whether an instance has already been created and cached */
+    resolved: boolean;
+}
+/** A directed edge meaning `from` depends on `to` */
+export interface GraphEdge {
+    from: string;
+    to: string;
+}
+/** Raw data used to build a Graph; produced by Container#graph() */
+export interface GraphSnapshot {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/** A GraphNode nested with its dependencies, for tree-shaped UI rendering */
+export interface GraphTreeNode extends GraphNode {
+    children: GraphTreeNode[];
+    /**
+     * True if this key already appears higher up in the current branch.
+     * Recursion stops here instead of looping forever - `children` will be empty.
+     */
+    cyclic?: boolean;
+}
+/** Criteria for filtering graph nodes */
+export interface GraphNodeFilter {
+    /** Only include nodes matching this lifecycle (or one of these) */
+    lifecycle?: Lifecycle | Lifecycle[];
+    /** Only include nodes whose instance has (or hasn't) been resolved */
+    resolved?: boolean;
+    /** Only include lazy (or non-lazy) bindings */
+    lazy?: boolean;
+    /** Only include inherited (or own) bindings */
+    inherited?: boolean;
+    /** Only include keys matching this substring or RegExp */
+    key?: string | RegExp;
+}
+/**
+ * Read-only, filterable view over a container's bindings and the
+ * dependency edges discovered while resolving them.
+ *
+ * Edges are recorded as `resolve()` runs, so they only reflect
+ * dependencies that have actually been resolved at least once - this is
+ * a runtime graph, not a static analysis of factory source code.
+ *
+ * @example
+ * ```typescript
+ * const graph = container.graph();
+ *
+ * const singletons = graph.getNodes({ lifecycle: 'singleton' });
+ * const unresolved = graph.getNodes({ resolved: false });
+ * const deps = graph.dependenciesOf('userService');
+ *
+ * console.log(graph.toDot()); // paste into a Graphviz viewer
+ * ```
+ */
+export declare class Graph {
+    private readonly nodes;
+    private readonly edges;
+    private readonly byPlainKey;
+    constructor(snapshot: GraphSnapshot);
+    /**
+     * Get all nodes, optionally filtered
+     *
+     * @example
+     * ```typescript
+     * graph.getNodes({ lifecycle: ['singleton', 'scoped'], resolved: true });
+     * graph.getNodes({ key: /Repository$/ });
+     * ```
+     */
+    getNodes(filter?: GraphNodeFilter): GraphNode[];
+    /**
+     * Get a single (non-contextual) node by key
+     */
+    getNode(key: ServiceKey): GraphNode | undefined;
+    /**
+     * Get all edges, optionally filtered by source and/or target key
+     */
+    getEdges(filter?: {
+        from?: ServiceKey;
+        to?: ServiceKey;
+    }): GraphEdge[];
+    /**
+     * Direct dependencies of a key - the services it needs
+     */
+    dependenciesOf(key: ServiceKey): GraphNode[];
+    /**
+     * Direct dependents of a key - the services that need it
+     */
+    dependentsOf(key: ServiceKey): GraphNode[];
+    /**
+     * Nodes that nothing else depends on (candidate entry points)
+     */
+    roots(): GraphNode[];
+    /**
+     * Nodes with no recorded dependencies (leaves of the graph)
+     */
+    leaves(): GraphNode[];
+    /**
+     * Build a nested tree starting at `key`, recursively expanding
+     * dependencies into `children`. Handy for rendering a dependency tree in
+     * a UI (e.g. a collapsible tree view).
+     *
+     * A node that reappears along the same branch (A depends on B, B depends
+     * on A, recorded from two separate resolve() calls) is marked
+     * `cyclic: true` instead of recursing forever - `children` stays empty
+     * there. Nodes that appear in multiple, unrelated branches (e.g. two
+     * services sharing the same `db` dependency) are duplicated as separate
+     * tree nodes, which is expected for a tree view.
+     *
+     * @param key The root key to build the tree from
+     * @returns The tree, or undefined if `key` isn't a known node
+     *
+     * @example
+     * ```typescript
+     * const tree = container.graph().toTree('service');
+     * // { key: 'service', children: [{ key: 'repo', children: [{ key: 'db', children: [] }] }] }
+     * ```
+     */
+    toTree(key: ServiceKey, _visited?: Set<string>): GraphTreeNode | undefined;
+    /**
+     * Build a tree for every root (nodes nothing else depends on), covering
+     * the whole graph at once - ready to hand to a UI as-is.
+     *
+     * @example
+     * ```typescript
+     * const forest = container.graph().forest();
+     * // [{ key: 'service', children: [...] }, { key: 'unusedSingleton', children: [] }]
+     * ```
+     */
+    forest(): GraphTreeNode[];
+    /**
+     * Plain JSON-serializable snapshot of the graph
+     */
+    toJSON(): GraphSnapshot;
+    /**
+     * Export as Graphviz DOT source, for visualizing the graph
+     */
+    toDot(): string;
+}
+//# sourceMappingURL=Graph.d.ts.map

package/dist/types/Graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Graph.d.ts","sourceRoot":"","sources":["../../src/Graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErD,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,SAAS,EAAE,SAAS,CAAC;IACrB,iDAAiD;IACjD,IAAI,EAAE,OAAO,CAAC;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;IACnB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IACpC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;gBAExC,QAAQ,EAAE,aAAa;IAYnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,EAAE;IAsC/C;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS;IAI/C;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,UAAU,CAAC;QAAC,EAAE,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,SAAS,EAAE;IAgBtE;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,EAAE;IAQ5C;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,EAAE;IAQ1C;;OAEG;IACH,KAAK,IAAI,SAAS,EAAE;IAKpB;;OAEG;IACH,MAAM,IAAI,SAAS,EAAE;IAKrB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CACJ,GAAG,EAAE,UAAU,EACf,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,GAChC,aAAa,GAAG,SAAS;IAmB5B;;;;;;;;;OASG;IACH,MAAM,IAAI,aAAa,EAAE;IAMzB;;OAEG;IACH,MAAM,IAAI,aAAa;IAIvB;;OAEG;IACH,KAAK,IAAI,MAAM;CAehB"}

package/dist/types/index.d.ts

@@ -17,6 +17,7 @@
  *  - High-performance Map-based storage (v1.2.0)
  *  - Auto-dispose for IDisposable instances (v1.2.0)
  *  - Modular architecture (v1.2.0)
+ *  - Dependency graph inspection with filtering, tree, and DOT export (v1.5.0)
  *
  * @example
  * ```typescript
@@ -30,5 +31,7 @@
 export { Container } from './Container';
 export { Lazy } from './Lazy';
 export { Scope } from './Scope';
-export type { Lifecycle, IDisposable, DisposeFn } from './types';
+export { Graph } from './Graph';
+export type { Lifecycle, IDisposable, DisposeFn, ServiceKey } from './types';
+export type { GraphNode, GraphEdge, GraphSnapshot, GraphNodeFilter, GraphTreeNode, } from './Graph';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGhC,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,YAAY,EACV,SAAS,EACT,SAAS,EACT,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khapu2906/treasure-chest",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A lightweight TypeScript dependency injection container for managing service dependencies",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -43,7 +43,8 @@
     "example:12": "tsx examples/12-singleton-vs-composition.ts",
     "example:13": "tsx examples/13-hybrid-architecture.ts",
     "example:14": "tsx examples/14-explain-composition.ts",
-    "examples": "npm run example:01 && npm run example:02 && npm run example:03 && npm run example:04 && npm run example:05 && npm run example:06 && npm run example:07 && npm run example:08 && npm run example:09 && npm run example:10 && npm run example:11 && npm run example:12 && npm run example:13 && npm run example:14",
+    "example:15": "tsx examples/15-dependency-graph.ts",
+    "examples": "npm run example:01 && npm run example:02 && npm run example:03 && npm run example:04 && npm run example:05 && npm run example:06 && npm run example:07 && npm run example:08 && npm run example:09 && npm run example:10 && npm run example:11 && npm run example:12 && npm run example:13 && npm run example:14 && npm run example:15",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "format": "prettier --write \"**/*.{ts,json,md}\"",