di-bag 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export type { ReboundProviders, ReboundSelection } from './types';
 export type { CanonicalLifetime, ChildReplacementAdmission, CheckedChildContainerLifetimes, CheckedLifetimes, LifetimeObligation, Reach } from './lifetime-types';
 export type { DiBagPolicy } from './types';
 export type { CheckDependencyCompatibility, CheckDependencyCompleteness, RegistrationEntries, OverrideFactoryContext, RegistrationsFromEntries, OverrideRegistrations, Overrides, ServicesOf, SelectedRegistrations, Selection } from './types';
-export type { Presence, AcquisitionMetadataPresence, AcquisitionSnapshot, RegistrationSnapshot, BindingSnapshot, GraphSnapshot } from './inspection';
+export type { Presence, AcquisitionMetadataPresence, AcquisitionSnapshot, RegistrationSnapshot, BindingSnapshot, ModuleInstallationSnapshot, GraphSnapshot } from './inspection';
 export type { PositionalFactoryArguments, PositionalFactoryFunction } from './composition';
 export type { OptionalDependency, LazyDependency, DependencyReference } from './dependency-references';
 export type { PluginOutputValidator, PluginProvider } from './plugins';

package/dist/inspection.d.ts

@@ -53,6 +53,8 @@ export interface RegistrationSnapshot<M = Readonly<{}>, A extends readonly unkno
  * @see https://dany-fedorov.github.io/di-bag/guides/tutorial.html#attach-metadata-and-inspect-without-resolving
  */
 export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[] = readonly []> extends RegistrationSnapshot<M, A> {
+    /** Innermost module installation that introduced this binding; absent for host declarations and host replacements. */
+    readonly moduleInstallationId: symbol | undefined;
     /** Public names or token symbols that select this binding, in service key order; empty for a private module binding. */
     readonly serviceKeys: readonly (string | symbol)[];
     readonly lifetime: Lifetime;
@@ -65,6 +67,15 @@ export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[]
         readonly dependencyKind: 'required' | 'optional' | 'lazy';
     }[];
 }
+/** One occurrence of a sealed module in a container graph. */
+export interface ModuleInstallationSnapshot {
+    /** Stable identity for this occurrence in the graph. */
+    readonly installationId: symbol;
+    /** Exact label supplied when the module was sealed, if any. */
+    readonly moduleLabel: string | undefined;
+    /** Enclosing installation, if this module was installed inside another module. */
+    readonly parentInstallationId: symbol | undefined;
+}
 /**
  * A frozen description of every binding a container can resolve, plus the edges observed so far.
  * Named dependencies read from a factory's object parameter are not knowable until the factory
@@ -73,6 +84,8 @@ export interface BindingSnapshot<M = Readonly<{}>, A extends readonly unknown[]
  */
 export interface GraphSnapshot {
     readonly containerId: symbol;
+    /** Module occurrences in installation order, with each parent preceding its contiguous descendants. */
+    readonly moduleInstallations: readonly ModuleInstallationSnapshot[];
     /** Public bindings in service key order, then contributions in group order, then remaining private bindings. */
     readonly bindings: readonly BindingSnapshot<object, readonly unknown[]>[];
     readonly contributions: readonly {

package/dist/module.d.ts

@@ -39,6 +39,8 @@ declare class Module<ExportedServices extends object, RequiredServices extends o
     /** @internal */
     readonly [moduleInvariant]: (value: [ExportedServices, RequiredServices, Constraints, PublicProviders]) => [ExportedServices, RequiredServices, Constraints, PublicProviders];
     constructor(description: ModuleDescription);
+    /** The exact label supplied when this module was sealed, if any. Reading it never acquires a service. */
+    get moduleLabel(): string | undefined;
     /**
      * Return a module view with one string-named export renamed through an options object.
      * @param options - The current export and its noncolliding new name.

package/dist/module.js

@@ -27,6 +27,10 @@ class Module {
         });
         Object.freeze(this);
     }
+    /** The exact label supplied when this module was sealed, if any. Reading it never acquires a service. */
+    get moduleLabel() {
+        return descriptions.get(this).label;
+    }
     /**
      * Return a module view with one string-named export renamed through an options object.
      * @param options - The current export and its noncolliding new name.
@@ -171,6 +175,19 @@ function moduleGraph(value, index) {
         throw (0, errors_1.libraryError)('DI_BAG_INVALID_MODULE', `withInstalledModules requires genuine modules: element ${index} is not one`, { operation: 'withInstalledModules', index });
     }
     const { graph, exports, label, requirementRenames } = description;
+    const installationId = Symbol('module installation');
+    const remapped = new Map();
+    for (const nested of graph.moduleInstallations ?? [])
+        remapped.set(nested.installationId, Symbol('module installation'));
+    const moduleInstallations = [
+        { installationId, moduleLabel: label, parentInstallationId: undefined },
+        ...(graph.moduleInstallations ?? []).map(nested => ({
+            installationId: remapped.get(nested.installationId),
+            moduleLabel: nested.moduleLabel,
+            parentInstallationId: nested.parentInstallationId === undefined
+                ? installationId : remapped.get(nested.parentInstallationId),
+        })),
+    ];
     const exported = new Set();
     for (const localKey of exports.values())
         exported.add(graph.publicSlots.get(localKey));
@@ -219,6 +236,8 @@ function moduleGraph(value, index) {
         bindings.set(fresh, {
             id: fresh, label: labelOf(id, binding), registration: binding.registration,
             localNames: localNamesFor(binding),
+            moduleInstallationId: binding.moduleInstallationId === undefined
+                ? installationId : remapped.get(binding.moduleInstallationId),
         });
     }
     const publicSlots = new Map();
@@ -232,5 +251,6 @@ function moduleGraph(value, index) {
         publicSlots,
         contributions,
         tokenKinds: new Map(graph.tokenKinds ?? []),
+        moduleInstallations,
     };
 }

package/dist/runtime.d.ts

@@ -1,7 +1,7 @@
 import { ScopeAcquisitions } from './acquisition';
 import { normalize } from './registration';
 import type { ProviderOrFactory, Registrations } from './registration';
-import type { GraphSnapshot, RegistrationSnapshot } from './inspection';
+import type { GraphSnapshot, ModuleInstallationSnapshot, RegistrationSnapshot } from './inspection';
 import type { RuntimeContext } from './acquisition-mode';
 import { type TokenKind } from './tokens';
 import type { LifetimeKind } from './lifetime';
@@ -19,12 +19,14 @@ export interface BindingDescription {
     readonly label: string;
     readonly registration: ProviderOrFactory;
     readonly localNames: ReadonlyMap<BindingKey, BindingRef>;
+    readonly moduleInstallationId?: symbol;
 }
 export interface GraphDescription {
     readonly bindings: ReadonlyMap<BindingId, BindingDescription>;
     readonly publicSlots: ReadonlyMap<BindingKey, BindingId>;
     readonly contributions?: ReadonlyMap<symbol, readonly BindingId[]>;
     readonly tokenKinds?: ReadonlyMap<symbol, TokenKind>;
+    readonly moduleInstallations?: readonly ModuleInstallationSnapshot[];
 }
 type Normalized = Readonly<ReturnType<typeof normalize>>;
 /** Immutable descriptions and path-copied lookup storage. Retained maps never escape. */
@@ -60,6 +62,8 @@ export declare class BindingGraph {
     registration(id: BindingId): Normalized;
     private requireRegistration;
     label(id: BindingId): string;
+    moduleInstallationId(id: BindingId): symbol | undefined;
+    moduleInstallations(): readonly ModuleInstallationSnapshot[];
     withPublicRegistrations(registrations: Registrations, operation?: string): BindingGraph;
     /** Replace ordered slots and prune only unreferenced public replacement history. */
     withPublicBindings(entries: readonly (readonly [BindingKey, ProviderOrFactory])[], operation?: string): BindingGraph;

package/dist/runtime.js

@@ -12,6 +12,7 @@ const tokens_1 = require("./tokens");
 const lifetime_1 = require("./lifetime");
 const emptyContributions = Object.freeze([]);
 const emptyNames = new Map();
+const emptyModuleInstallations = Object.freeze([]);
 /** Immutable descriptions and path-copied lookup storage. Retained maps never escape. */
 class BindingGraph {
     #bindings = new persistent_map_1.PersistentMap();
@@ -32,12 +33,16 @@ class BindingGraph {
     // First public registration order by key, for module snapshots. Keys are
     // never unregistered, so this retains nothing a graph would otherwise drop.
     #publicOrder;
+    #moduleInstallations;
     #bindingCache = new Map();
     #registrationCache = new Map();
     #publicCache = new Map();
     #contributionCache = new Map();
     #explicitlyClassified = false;
     constructor(description = { bindings: new Map(), publicSlots: new Map() }) {
+        if (description.moduleInstallations?.length) {
+            this.#moduleInstallations = { values: Object.freeze(description.moduleInstallations.map(record => Object.freeze({ ...record }))) };
+        }
         const declaredKinds = description.tokenKinds ?? new Map();
         const lexicalSnapshots = new Map();
         for (const [id, binding] of description.bindings) {
@@ -59,7 +64,10 @@ class BindingGraph {
             this.#lexicalUsers = this.#lexicalUsers.set(lexical.id, (this.#lexicalUsers.get(lexical.id) ?? 0) + 1);
             const entry = {
                 lexical,
-                description: Object.freeze({ id: binding.id, label: binding.label, registration: binding.registration, localNames: lexical.names }),
+                description: Object.freeze({
+                    id: binding.id, label: binding.label, registration: binding.registration, localNames: lexical.names,
+                    ...(binding.moduleInstallationId === undefined ? {} : { moduleInstallationId: binding.moduleInstallationId }),
+                }),
                 normalized: Object.freeze((0, registration_1.normalize)(binding.registration)),
             };
             this.retainBindingTokenKinds(entry, 'withInstalledModules');
@@ -98,6 +106,7 @@ class BindingGraph {
         graph.#tokenKindOwners = this.#tokenKindOwners;
         graph.#directTokenKinds = this.#directTokenKinds;
         graph.#publicOrder = this.#publicOrder;
+        graph.#moduleInstallations = this.#moduleInstallations;
         return graph;
     }
     entry(id) {
@@ -253,6 +262,12 @@ class BindingGraph {
         return registration;
     }
     label(id) { return (this.#bindingCache.get(id) ?? this.entry(id)?.description)?.label ?? String(id); }
+    moduleInstallationId(id) {
+        return (this.#bindingCache.get(id) ?? this.entry(id)?.description)?.moduleInstallationId;
+    }
+    moduleInstallations() {
+        return this.#moduleInstallations ? (0, persistent_sequence_1.materialize)(this.#moduleInstallations) : emptyModuleInstallations;
+    }
     withPublicRegistrations(registrations, operation = 'register') {
         return this.withPublicBindings(Object.keys(registrations).map(key => [key, registrations[key]]), operation);
     }
@@ -360,7 +375,7 @@ class BindingGraph {
         for (const [key, kind] of this.#tokenKinds) {
             tokenKinds.set(key, kind);
         }
-        return { bindings, publicSlots, contributions, tokenKinds };
+        return { bindings, publicSlots, contributions, tokenKinds, moduleInstallations: this.moduleInstallations() };
     }
     /** Every retained binding in `describe()` order, with the public keys that select it. */
     bindingSummaries() {
@@ -396,6 +411,9 @@ class BindingGraph {
             this.assertTokenKind(key, kind, operation);
         }
         const graph = this.copy();
+        if (description.moduleInstallations?.length) {
+            graph.#moduleInstallations = (0, persistent_sequence_1.append)(graph.#moduleInstallations, installation.#moduleInstallations);
+        }
         const pending = [];
         // Publish all incoming protection before releasing overwritten descriptions.
         for (const [id, count] of installation.#lexicalUsers)
@@ -485,6 +503,7 @@ class BagRuntime {
             const description = this.graph.registration(id);
             return Object.freeze({
                 ...this.inspectBinding(id),
+                moduleInstallationId: this.graph.moduleInstallationId(id),
                 serviceKeys: keys,
                 lifetime: (0, lifetime_1.publicLifetime)(description.lifetime.kind),
                 factoryReturnKind: description.factoryReturnKind,
@@ -494,6 +513,7 @@ class BagRuntime {
         });
         return Object.freeze({
             containerId: this.acquisitions.ownerId,
+            moduleInstallations: this.graph.moduleInstallations(),
             bindings: Object.freeze(bindings),
             contributions: this.graph.contributionGroups(),
             observedEdges: this.acquisitions.observedEdges(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "di-bag",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "DI container for agent-built codebases: the compiler checks the wiring, modules stay private, resources get cleaned up.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",