@khapu2906/treasure-chest 1.4.1 → 1.5.1

package/dist/cjs/Graph.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Dependency graph for inspecting and filtering container bindings
+ *
+ * @module Graph
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Graph = void 0;
+/**
+ * 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
+ * ```
+ */
+class Graph {
+    /**
+     * @param snapshot Nodes and edges, keyed by label
+     * @param keyLabels Optional map from real service keys to their labels.
+     *   Container#graph() passes this so lookups by a Symbol find that exact
+     *   Symbol's node, even if another Symbol has the same description.
+     */
+    constructor(snapshot, keyLabels) {
+        this.nodes = snapshot.nodes;
+        this.edges = snapshot.edges;
+        this.keyLabels = keyLabels;
+        this.byPlainKey = new Map();
+        for (const node of this.nodes) {
+            if (!this.byPlainKey.has(node.key)) {
+                this.byPlainKey.set(node.key, node);
+            }
+        }
+    }
+    /**
+     * Turn a service key (or an already-known label) into its node label
+     * @private
+     */
+    toLabel(key) {
+        var _a, _b;
+        return (_b = (_a = this.keyLabels) === null || _a === void 0 ? void 0 : _a.get(key)) !== null && _b !== void 0 ? _b : key.toString();
+    }
+    /**
+     * Get all nodes, optionally filtered
+     *
+     * @example
+     * ```typescript
+     * graph.getNodes({ lifecycle: ['singleton', 'scoped'], resolved: true });
+     * graph.getNodes({ key: /Repository$/ });
+     * ```
+     */
+    getNodes(filter) {
+        let result = this.nodes;
+        if (!filter) {
+            return [...result];
+        }
+        if (filter.lifecycle) {
+            const lifecycles = Array.isArray(filter.lifecycle)
+                ? filter.lifecycle
+                : [filter.lifecycle];
+            result = result.filter((n) => lifecycles.includes(n.lifecycle));
+        }
+        if (filter.resolved !== undefined) {
+            result = result.filter((n) => n.resolved === filter.resolved);
+        }
+        if (filter.lazy !== undefined) {
+            result = result.filter((n) => n.lazy === filter.lazy);
+        }
+        if (filter.inherited !== undefined) {
+            result = result.filter((n) => n.inherited === filter.inherited);
+        }
+        if (filter.key !== undefined) {
+            const matcher = filter.key;
+            result = result.filter((n) => matcher instanceof RegExp
+                ? matcher.test(n.key)
+                : n.key.includes(matcher));
+        }
+        return [...result];
+    }
+    /**
+     * Get a single (non-contextual) node by key
+     */
+    getNode(key) {
+        return this.byPlainKey.get(this.toLabel(key));
+    }
+    /**
+     * Get all edges, optionally filtered by source and/or target key
+     */
+    getEdges(filter) {
+        if (!filter) {
+            return [...this.edges];
+        }
+        const from = filter.from !== undefined ? this.toLabel(filter.from) : undefined;
+        const to = filter.to !== undefined ? this.toLabel(filter.to) : undefined;
+        return this.edges.filter((e) => {
+            if (from !== undefined && e.from !== from)
+                return false;
+            if (to !== undefined && e.to !== to)
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Direct dependencies of a key - the services it needs
+     */
+    dependenciesOf(key) {
+        return this.dependenciesOfLabel(this.toLabel(key));
+    }
+    /** @private */
+    dependenciesOfLabel(keyStr) {
+        return this.edges
+            .filter((e) => e.from === keyStr)
+            .map((e) => this.byPlainKey.get(e.to))
+            .filter((n) => n !== undefined);
+    }
+    /**
+     * Direct dependents of a key - the services that need it
+     */
+    dependentsOf(key) {
+        const keyStr = this.toLabel(key);
+        return this.edges
+            .filter((e) => e.to === keyStr)
+            .map((e) => this.byPlainKey.get(e.from))
+            .filter((n) => n !== undefined);
+    }
+    /**
+     * Nodes that nothing else depends on (candidate entry points)
+     */
+    roots() {
+        const dependedOn = new Set(this.edges.map((e) => e.to));
+        return this.nodes.filter((n) => !dependedOn.has(n.key));
+    }
+    /**
+     * Nodes with no recorded dependencies (leaves of the graph)
+     */
+    leaves() {
+        const withDeps = new Set(this.edges.map((e) => e.from));
+        return this.nodes.filter((n) => !withDeps.has(n.key));
+    }
+    /**
+     * 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) {
+        return this.toTreeByLabel(this.toLabel(key), new Set());
+    }
+    /**
+     * Recursion works on labels directly (never back through toLabel), so a
+     * label can't be re-mapped to a different key mid-walk.
+     * @private
+     */
+    toTreeByLabel(keyStr, _visited) {
+        const node = this.byPlainKey.get(keyStr);
+        if (!node)
+            return undefined;
+        if (_visited.has(keyStr)) {
+            return { ...node, children: [], cyclic: true };
+        }
+        const visited = new Set(_visited);
+        visited.add(keyStr);
+        const children = this.dependenciesOfLabel(keyStr)
+            .map((dep) => this.toTreeByLabel(dep.key, visited))
+            .filter((n) => n !== undefined);
+        return { ...node, children };
+    }
+    /**
+     * 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() {
+        return this.roots()
+            .map((root) => this.toTreeByLabel(root.key, new Set()))
+            .filter((n) => n !== undefined);
+    }
+    /**
+     * Plain JSON-serializable snapshot of the graph
+     */
+    toJSON() {
+        return { nodes: [...this.nodes], edges: [...this.edges] };
+    }
+    /**
+     * Export as Graphviz DOT source, for visualizing the graph
+     */
+    toDot() {
+        const lines = ['digraph Container {'];
+        for (const node of this.nodes) {
+            const label = `${node.key}\\n(${node.lifecycle}${node.lazy ? ', lazy' : ''})`;
+            lines.push(`  "${node.key}" [label="${label}"];`);
+        }
+        for (const edge of this.edges) {
+            lines.push(`  "${edge.from}" -> "${edge.to}";`);
+        }
+        lines.push('}');
+        return lines.join('\n');
+    }
+}
+exports.Graph = Graph;
+//# sourceMappingURL=Graph.js.map

package/dist/cjs/Graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Graph.js","sourceRoot":"","sources":["../../src/Graph.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.js

@@ -18,6 +18,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
@@ -29,7 +30,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Scope = exports.Lazy = exports.Container = void 0;
+exports.Graph = exports.Scope = exports.Lazy = exports.Container = void 0;
 // Export main classes
 var Container_1 = require("./Container");
 Object.defineProperty(exports, "Container", { enumerable: true, get: function () { return Container_1.Container; } });
@@ -37,4 +38,6 @@ var Lazy_1 = require("./Lazy");
 Object.defineProperty(exports, "Lazy", { enumerable: true, get: function () { return Lazy_1.Lazy; } });
 var Scope_1 = require("./Scope");
 Object.defineProperty(exports, "Scope", { enumerable: true, get: function () { return Scope_1.Scope; } });
+var Graph_1 = require("./Graph");
+Object.defineProperty(exports, "Graph", { enumerable: true, get: function () { return Graph_1.Graph; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAEH,sBAAsB;AACtB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAClB,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,iCAAgC;AAAvB,8FAAA,KAAK,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,sBAAsB;AACtB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAClB,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,iCAAgC;AAAvB,8FAAA,KAAK,OAAA;AACd,iCAAgC;AAAvB,8FAAA,KAAK,OAAA"}

package/dist/esm/Container.js

@@ -5,6 +5,38 @@
  */
 import { Lazy } from './Lazy';
 import { Scope } from './Scope';
+import { Graph } from './Graph';
+/**
+ * Two-level map keyed by (service key, optional context key).
+ *
+ * Keys are compared by identity, never by their string form, so two
+ * distinct Symbols with the same description (`Symbol('x')` twice) or a
+ * string key that looks like a Symbol (`'Symbol(x)'`) never collide.
+ */
+class KeyContextMap {
+    constructor() {
+        this.map = new Map();
+    }
+    get(key, context) {
+        var _a;
+        return (_a = this.map.get(key)) === null || _a === void 0 ? void 0 : _a.get(context);
+    }
+    has(key, context) {
+        var _a, _b;
+        return (_b = (_a = this.map.get(key)) === null || _a === void 0 ? void 0 : _a.has(context)) !== null && _b !== void 0 ? _b : false;
+    }
+    set(key, context, value) {
+        let inner = this.map.get(key);
+        if (!inner) {
+            inner = new Map();
+            this.map.set(key, inner);
+        }
+        inner.set(context, value);
+    }
+    clear() {
+        this.map.clear();
+    }
+}
 /**
  * Container class for dependency injection
  * Manages service bindings, instances, and resolution logic
@@ -24,30 +56,35 @@ export class Container {
     constructor(parent) {
         /** Map-based storage for bindings - O(1) lookup */
         this.bindings = new Map();
-        /** Cache for singleton instances */
+        /** Cache for singleton instances, keyed by (service key, binding context) */
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.instances = new KeyContextMap();
+        /** Cache for lazy singleton wrappers */
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.instances = new Map();
+        this.lazyInstances = new Map();
         /** Mapping of aliases to original keys */
         this.aliases = new Map();
         /** Cache for resolved bindings - performance optimization */
-        this.bindingCache = new Map();
+        this.bindingCache = new KeyContextMap();
         /** Composed containers for composition pattern */
         this.composedContainers = [];
         /** Resolution stack for circular dependency detection */
         this.resolutionStack = [];
+        /** Dependency edges observed while resolving: consumerKey -> Set of dependency keys */
+        this.dependencyEdges = new Map();
         this.parent = parent;
     }
     /**
-     * Generates a consistent string key for caching, handling both strings and symbols.
-     * This is a simple implementation; it assumes no string keys will collide with `Symbol().toString()`.
+     * Record that `from` depends on `to`, for later inspection via graph()
      * @private
      */
-    _toCacheKey(key, context) {
-        const keyStr = key.toString();
-        if (context) {
-            return `${keyStr}::${context.toString()}`;
-        }
-        return keyStr;
+    _recordEdge(from, to) {
+        var _a;
+        if (from === to)
+            return;
+        const deps = (_a = this.dependencyEdges.get(from)) !== null && _a !== void 0 ? _a : new Set();
+        deps.add(to);
+        this.dependencyEdges.set(from, deps);
     }
     /**
      * Register a transient binding (new instance on each resolve)
@@ -225,11 +262,25 @@ export class Container {
      * @returns The matching binding or undefined
      */
     findBinding(key, context) {
+        var _a;
+        return (_a = this.findBindingEntry(key, context)) === null || _a === void 0 ? void 0 : _a.binding;
+    }
+    /**
+     * Find the appropriate binding for a given key and context, along with
+     * the container that actually declared it (the "owner"). Searches in
+     * current container and parent containers. Uses cached result when
+     * possible for performance.
+     *
+     * @private
+     * @param key The service key to find
+     * @param context Optional context for contextual binding
+     * @returns The matching binding paired with its owning container, or undefined
+     */
+    findBindingEntry(key, context) {
         const realKey = this.aliases.get(key) || key;
-        const cacheKey = this._toCacheKey(realKey, context);
         // Check cache first
-        if (this.bindingCache.has(cacheKey)) {
-            return this.bindingCache.get(cacheKey);
+        if (this.bindingCache.has(realKey, context)) {
+            return this.bindingCache.get(realKey, context);
         }
         // O(1) Map lookup instead of O(n) array filter
         const bindings = this.bindings.get(realKey);
@@ -241,15 +292,18 @@ export class Container {
             const match = bindings.find((b) => b.context === context && (!b.condition || b.condition(this))) ||
                 bindings.find((b) => !b.context && (!b.condition || b.condition(this))) ||
                 bindings[0];
-            // Cache the result only if no conditions (conditions are dynamic)
-            if (match && !match.condition) {
-                this.bindingCache.set(cacheKey, match);
+            if (match) {
+                const entry = { binding: match, owner: this };
+                // Cache the result only if no conditions (conditions are dynamic)
+                if (!match.condition) {
+                    this.bindingCache.set(realKey, context, entry);
+                }
+                return entry;
             }
-            return match;
         }
         // Try parent container
         if (this.parent) {
-            return this.parent.findBinding(key, context);
+            return this.parent.findBindingEntry(key, context);
         }
         return undefined;
     }
@@ -279,12 +333,18 @@ export class Container {
                 .join(' -> ');
             throw new Error(`Circular dependency detected: ${chain}`);
         }
+        // Record dependency edge: whatever is currently resolving depends on this key
+        if (this.resolutionStack.length > 0) {
+            const consumer = this.resolutionStack[this.resolutionStack.length - 1];
+            this._recordEdge(consumer, realKey);
+        }
         const prevContext = this.currentContext;
         this.currentContext = context || key;
-        const binding = this.findBinding(key, this.currentContext);
-        if (!binding) {
+        const entry = this.findBindingEntry(key, this.currentContext);
+        if (!entry) {
             throw new Error(`No binding found for key: ${realKey.toString()}`);
         }
+        const { binding, owner } = entry;
         // Add to resolution stack
         this.resolutionStack.push(realKey);
         try {
@@ -296,7 +356,9 @@ export class Container {
             // Handle different lifecycles
             switch (binding.lifecycle) {
                 case 'singleton':
-                    return this.resolveSingleton(binding, realKey);
+                    // Cached on the owning container so the instance is truly
+                    // shared across every child that inherits the binding.
+                    return owner.resolveSingleton(binding, realKey);
                 case 'scoped':
                     return this.resolveScoped(binding, realKey);
                 case 'transient':
@@ -322,13 +384,12 @@ export class Container {
      * @private
      */
     resolveSingleton(binding, cacheKey) {
-        // Singletons can be contextual, so we use a string-based key for the instance map.
-        const fullCacheKey = this._toCacheKey(cacheKey, binding.context);
-        if (this.instances.has(fullCacheKey)) {
-            return this.instances.get(fullCacheKey);
+        // Singletons can be contextual, so instances are keyed by (key, context).
+        if (this.instances.has(cacheKey, binding.context)) {
+            return this.instances.get(cacheKey, binding.context);
         }
         const instance = binding.factory(this);
-        this.instances.set(fullCacheKey, instance);
+        this.instances.set(cacheKey, binding.context, instance);
         return instance;
     }
     /**
@@ -351,13 +412,13 @@ export class Container {
      * @private
      */
     resolveLazy(binding, cacheKey) {
-        const fullCacheKey = `lazy::${this._toCacheKey(cacheKey)}`;
-        if (this.instances.has(fullCacheKey)) {
-            return this.instances.get(fullCacheKey);
+        const cached = this.lazyInstances.get(cacheKey);
+        if (cached) {
+            return cached;
         }
         const lazy = new Lazy(() => binding.factory(this));
         if (binding.lifecycle === 'singleton') {
-            this.instances.set(fullCacheKey, lazy);
+            this.lazyInstances.set(cacheKey, lazy);
         }
         return lazy;
     }
@@ -442,6 +503,152 @@ export class Container {
         const parentKeys = this.parent ? this.parent.keys() : [];
         return [...new Set([...ownKeys, ...parentKeys])];
     }
+    /**
+     * Collect this container's bindings (own, inherited from a parent, and
+     * inherited from composed containers), plus the dependency edges observed
+     * so far. Keys are kept as real ServiceKeys here; graph() turns them into
+     * unique display labels afterwards.
+     *
+     * @private
+     * @param seen Keys already captured by a more specific (closer) container
+     */
+    inspect(seen = new Set()) {
+        var _a;
+        const nodes = [];
+        for (const [key, bindingList] of this.bindings) {
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            for (const binding of bindingList) {
+                nodes.push({
+                    key,
+                    lifecycle: binding.lifecycle,
+                    lazy: !!binding.lazy,
+                    context: binding.context,
+                    inherited: false,
+                    resolved: this.instances.has(key, binding.context) ||
+                        this.lazyInstances.has(key),
+                });
+            }
+        }
+        for (const [aliasKey, originalKey] of this.aliases) {
+            if (seen.has(aliasKey))
+                continue;
+            seen.add(aliasKey);
+            const target = this.findBinding(aliasKey);
+            nodes.push({
+                key: aliasKey,
+                lifecycle: (_a = target === null || target === void 0 ? void 0 : target.lifecycle) !== null && _a !== void 0 ? _a : 'transient',
+                lazy: !!(target === null || target === void 0 ? void 0 : target.lazy),
+                aliasOf: originalKey,
+                inherited: false,
+                resolved: false,
+            });
+        }
+        const edges = [];
+        for (const [from, tos] of this.dependencyEdges) {
+            for (const to of tos) {
+                edges.push({ from, to });
+            }
+        }
+        const ancestors = [
+            ...(this.parent ? [this.parent] : []),
+            ...this.composedContainers,
+        ];
+        for (const ancestor of ancestors) {
+            const snapshot = ancestor.inspect(seen);
+            for (const node of snapshot.nodes) {
+                nodes.push({ ...node, inherited: true });
+            }
+            edges.push(...snapshot.edges);
+        }
+        return { nodes, edges };
+    }
+    /**
+     * Assign every distinct service key a unique, human-readable label.
+     *
+     * String keys always keep their own value as label. Other keys use
+     * `toString()`; when that is already taken by a different key (e.g. two
+     * `Symbol('db')`s, or `Symbol('db')` next to the string `'Symbol(db)'`),
+     * a `#2`, `#3`, ... suffix is appended so graph nodes never merge.
+     *
+     * @private
+     */
+    static labelKeys(keys) {
+        const all = [...new Set(keys)];
+        const labels = new Map();
+        const used = new Set();
+        for (const key of all) {
+            if (typeof key === 'string') {
+                labels.set(key, key);
+                used.add(key);
+            }
+        }
+        for (const key of all) {
+            if (typeof key === 'string')
+                continue;
+            const base = key.toString();
+            let label = base;
+            for (let n = 2; used.has(label); n++) {
+                label = `${base}#${n}`;
+            }
+            labels.set(key, label);
+            used.add(label);
+        }
+        return labels;
+    }
+    /**
+     * Build a filterable dependency graph of this container's bindings and
+     * the dependency edges observed while resolving them.
+     *
+     * @returns A Graph snapshot you can filter/inspect
+     *
+     * @example
+     * ```typescript
+     * const graph = container.graph();
+     * const singletons = graph.getNodes({ lifecycle: 'singleton' });
+     * const deps = graph.dependenciesOf('userService');
+     * ```
+     */
+    graph() {
+        const raw = this.inspect();
+        const keys = [];
+        for (const node of raw.nodes) {
+            keys.push(node.key);
+            if (node.context !== undefined)
+                keys.push(node.context);
+            if (node.aliasOf !== undefined)
+                keys.push(node.aliasOf);
+        }
+        for (const edge of raw.edges) {
+            keys.push(edge.from, edge.to);
+        }
+        const labels = Container.labelKeys(keys);
+        const label = (key) => labels.get(key);
+        const nodes = raw.nodes.map((node) => {
+            const out = {
+                key: label(node.key),
+                lifecycle: node.lifecycle,
+                lazy: node.lazy,
+                inherited: node.inherited,
+                resolved: node.resolved,
+            };
+            // Preserve the node shape graph() has always produced: binding nodes
+            // carry `context` (possibly undefined), alias nodes carry `aliasOf`.
+            if ('context' in node) {
+                out.context =
+                    node.context !== undefined ? label(node.context) : undefined;
+            }
+            if (node.aliasOf !== undefined)
+                out.aliasOf = label(node.aliasOf);
+            return out;
+        });
+        const edges = raw.edges.map((edge) => ({
+            from: label(edge.from),
+            to: label(edge.to),
+        }));
+        return new Graph({ nodes, edges }, labels);
+    }
     /**
      * Reset the container to its initial state
      * Clears all bindings, instances, aliases, and context
@@ -457,8 +664,10 @@ export class Container {
     reset() {
         this.bindings.clear();
         this.instances.clear();
+        this.lazyInstances.clear();
         this.aliases.clear();
         this.bindingCache.clear();
+        this.dependencyEdges.clear();
         this.currentContext = undefined;
         this.currentScope = undefined;
         this.resolutionStack = [];