@avijs/di 0.0.0-stage → 0.1.0

package/dist/provider.js

@@ -0,0 +1,91 @@
+import { isToken, tokenName } from './token.js';
+/** Validates a provider and converts it to one internal shape. `where` labels errors. */
+export function normalizeProvider(provider, where) {
+    if (typeof provider === 'function') {
+        return classSpec(provider, provider, 'singleton', where);
+    }
+    if (typeof provider !== 'object' || provider === null) {
+        throw new TypeError(`Invalid provider at ${where}: ${String(provider)}${hint(provider)}`);
+    }
+    const p = provider;
+    if (!isToken(p['provide'])) {
+        throw new TypeError(`Invalid "provide" token at ${where}: ${String(p['provide'])}${hint(p['provide'])}`);
+    }
+    const token = p['provide'];
+    const label = `${where} (${tokenName(token)})`;
+    const kinds = ['useClass', 'useValue', 'useFactory'].filter((key) => key in p);
+    if (kinds.length !== 1) {
+        throw new TypeError(`Provider at ${label} needs exactly one of useClass, useValue or useFactory`);
+    }
+    if ('useValue' in p) {
+        const value = p['useValue'];
+        return {
+            token,
+            kind: 'value',
+            scope: 'singleton',
+            deps: [],
+            create: () => value,
+            dispose: undefined,
+        };
+    }
+    const scope = p['scope'] ?? 'singleton';
+    if (scope !== 'singleton' && scope !== 'transient' && scope !== 'request') {
+        throw new TypeError(`Invalid scope ${typeof scope === 'string' ? `"${scope}"` : typeof scope} at ${label}`);
+    }
+    if ('useClass' in p) {
+        if (typeof p['useClass'] !== 'function') {
+            throw new TypeError(`useClass at ${label} must be a class`);
+        }
+        return classSpec(token, p['useClass'], scope, label);
+    }
+    const factory = p['useFactory'];
+    if (typeof factory !== 'function')
+        throw new TypeError(`useFactory at ${label} must be a function`);
+    const deps = checkInject(p['inject'], `${label} inject`);
+    if (factory.length > deps.length) {
+        throw new TypeError(`Factory at ${label} takes ${String(factory.length)} arguments but inject lists ${String(deps.length)}`);
+    }
+    const dispose = p['dispose'];
+    if (dispose !== undefined && typeof dispose !== 'function') {
+        throw new TypeError(`dispose at ${label} must be a function`);
+    }
+    return {
+        token,
+        kind: 'factory',
+        scope,
+        deps,
+        create: (values) => factory(...values),
+        dispose: dispose,
+    };
+}
+function classSpec(token, cls, scope, where) {
+    const deps = checkInject(cls.inject, `${where} ${cls.name}.inject`);
+    if (cls.length > deps.length) {
+        throw new TypeError(`${cls.name || 'Class'} takes ${String(cls.length)} constructor arguments but static inject lists ${String(deps.length)} (at ${where})`);
+    }
+    const Ctor = cls;
+    return {
+        token,
+        kind: 'class',
+        scope,
+        deps,
+        create: (values) => new Ctor(...values),
+        dispose: undefined,
+    };
+}
+function checkInject(inject, where) {
+    if (inject === undefined)
+        return [];
+    if (!Array.isArray(inject))
+        throw new TypeError(`${where} must be an array of tokens`);
+    inject.forEach((token, i) => {
+        if (!isToken(token)) {
+            throw new TypeError(`Invalid token at ${where}[${String(i)}]: ${String(token)}${hint(token)}`);
+        }
+    });
+    return inject;
+}
+function hint(value) {
+    return value === undefined ? ' (is there a circular import?)' : '';
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/token.d.ts

@@ -0,0 +1,22 @@
+export type Class<T = unknown> = abstract new (...args: never[]) => T;
+/** A class Avi can construct. Dependencies are listed in `static inject`. */
+export type Constructor<T = unknown> = (new (...args: never[]) => T) & {
+    readonly inject?: readonly Token[];
+};
+declare const tokenType: unique symbol;
+/** A typed, non-class token. Created with `createToken<T>()`. */
+export interface InjectionToken<T> {
+    readonly description: string;
+    readonly [tokenType]?: T;
+}
+export type Token<T = unknown> = Class<T> | InjectionToken<T>;
+export type TokenType<K> = K extends Class<infer T> ? T : K extends InjectionToken<infer T> ? T : never;
+/** Maps an `inject` tuple to the tuple of values it resolves to. */
+export type ResolveTokens<K extends readonly Token[]> = {
+    -readonly [I in keyof K]: TokenType<K[I]>;
+};
+export declare function createToken<T>(description: string): InjectionToken<T>;
+export declare function isToken(value: unknown): value is Token;
+export declare function tokenName(token: Token): string;
+export {};
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,CAAC,CAAC,GAAG,OAAO,IAAI,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEtE,6EAA6E;AAC7E,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,GAAG;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;CACpC,CAAC;AAEF,OAAO,CAAC,MAAM,SAAS,EAAE,OAAO,MAAM,CAAC;AAEvC,iEAAiE;AACjE,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;CAC1B;AAED,MAAM,MAAM,KAAK,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;AAE9D,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE/E,oEAAoE;AACpE,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,SAAS,KAAK,EAAE,IAAI;IACtD,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,CAAC;AAEF,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAKrE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAOtD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAE9C"}

package/dist/token.js

@@ -0,0 +1,16 @@
+export function createToken(description) {
+    if (typeof description !== 'string' || description === '') {
+        throw new TypeError('createToken needs a non-empty description');
+    }
+    return Object.freeze({ description });
+}
+export function isToken(value) {
+    return (typeof value === 'function' ||
+        (typeof value === 'object' &&
+            value !== null &&
+            typeof value.description === 'string'));
+}
+export function tokenName(token) {
+    return typeof token === 'function' ? token.name || '(anonymous class)' : token.description;
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAyBA,MAAM,UAAU,WAAW,CAAI,WAAmB;IAChD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,CACL,OAAO,KAAK,KAAK,UAAU;QAC3B,CAAC,OAAO,KAAK,KAAK,QAAQ;YACxB,KAAK,KAAK,IAAI;YACd,OAAQ,KAAmC,CAAC,WAAW,KAAK,QAAQ,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;AAC7F,CAAC"}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@avijs/di",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Explicit, reflection-free dependency injection for Avi.js.",
+  "keywords": [
+    "avi",
+    "avi.js",
+    "dependency-injection",
+    "ioc",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Christopher Robin Chase",
+  "homepage": "https://github.com/chrischase011/avi-js#readme",
+  "bugs": {
+    "url": "https://github.com/chrischase011/avi-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischase011/avi-js.git",
+    "directory": "packages/di"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@avijs/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/src/container.ts

@@ -0,0 +1,469 @@
+import { normalizeProvider, type Provider, type ProviderSpec, type Scope } from './provider.js';
+import { isToken, tokenName, type Token } from './token.js';
+
+export interface ModuleDefinition {
+  readonly name?: string;
+  readonly imports?: readonly ModuleDefinition[];
+  readonly providers?: readonly Provider[];
+  /** Own providers, tokens re-exported from imports, or imported modules to re-export. */
+  readonly exports?: readonly (Token | ModuleDefinition)[];
+}
+
+export interface ContainerOptions {
+  /**
+   * Providers that replace the provider for the same token wherever it is declared. Meant for
+   * tests. An override that matches nothing is an error.
+   */
+  readonly overrides?: readonly Provider[];
+  /**
+   * Tokens whose values each request supplies through `requestScope()`, such as the request
+   * itself. Visible in every module, as request-scoped providers.
+   */
+  readonly requestTokens?: readonly Token[];
+}
+
+/** Request-scoped instances for one request. */
+export interface RequestScope {
+  /** Like `Container.resolve`, but request-scoped providers are created once for this scope. */
+  resolve(module: ModuleDefinition, token: Token): unknown;
+  /** Disposes this scope's instances in reverse creation order. */
+  dispose(): Promise<void>;
+}
+
+export interface ProviderDescription {
+  readonly token: string;
+  readonly kind: 'class' | 'value' | 'factory';
+  readonly scope: Scope;
+  readonly inject: readonly string[];
+}
+
+export interface ModuleDescription {
+  readonly name: string;
+  readonly imports: readonly string[];
+  readonly providers: readonly ProviderDescription[];
+  readonly exports: readonly string[];
+}
+
+interface ProviderRecord extends ProviderSpec {
+  readonly module: ModuleRecord;
+  links: ProviderRecord[];
+  /** Request-scoped, or transient with a request-scoped dependency. Set by `#check`. */
+  requestBound: boolean;
+  /** Supplied per request, see `requestTokens`. */
+  supplied: boolean;
+  state: 'unchecked' | 'checking' | 'checked';
+  instance: unknown;
+  ready: Promise<void> | undefined;
+}
+
+interface ModuleRecord {
+  readonly definition: ModuleDefinition;
+  readonly name: string;
+  readonly imports: ModuleRecord[];
+  readonly own: Map<Token, ProviderRecord>;
+  readonly exported: Map<Token, ProviderRecord>;
+}
+
+type Lookup = ProviderRecord | { ambiguous: string[] } | undefined;
+
+interface ScopeState {
+  readonly values: ReadonlyMap<Token, unknown>;
+  readonly instances: Map<ProviderRecord, unknown>;
+  readonly created: { record: ProviderRecord; value: unknown }[];
+}
+
+const REQUEST_MODULE: ModuleRecord = {
+  definition: { name: 'request' },
+  name: 'request',
+  imports: [],
+  own: new Map(),
+  exported: new Map(),
+};
+
+/**
+ * Builds and validates the module graph on construction. `init()` creates every singleton,
+ * `dispose()` tears them down in reverse creation order.
+ */
+export class Container {
+  readonly #modules = new Map<ModuleDefinition, ModuleRecord>();
+  readonly #roots: ModuleRecord[];
+  readonly #created: ProviderRecord[] = [];
+  readonly #overrides = new Map<Token, ProviderSpec>();
+  readonly #overridden = new Set<Token>();
+  readonly #supplied = new Map<Token, ProviderRecord>();
+  #state: 'new' | 'initializing' | 'ready' | 'disposed' = 'new';
+
+  constructor(roots: readonly ModuleDefinition[], options: ContainerOptions = {}) {
+    (options.overrides ?? []).forEach((provider, i) => {
+      const spec = normalizeProvider(provider, `overrides[${String(i)}]`);
+      if (this.#overrides.has(spec.token)) {
+        throw new Error(`${tokenName(spec.token)} is overridden twice`);
+      }
+      this.#overrides.set(spec.token, spec);
+    });
+
+    for (const token of options.requestTokens ?? []) {
+      this.#supplied.set(token, {
+        token,
+        kind: 'value',
+        scope: 'request',
+        deps: [],
+        create: () => undefined,
+        dispose: undefined,
+        module: REQUEST_MODULE,
+        links: [],
+        requestBound: true,
+        supplied: true,
+        state: 'checked',
+        instance: undefined,
+        ready: undefined,
+      });
+    }
+
+    this.#roots = roots.map((root, i) => this.#collect(root, [], `root module ${String(i)}`));
+    for (const token of this.#overrides.keys()) {
+      if (!this.#overridden.has(token)) {
+        throw new Error(`The override for ${tokenName(token)} matches no provider in the app`);
+      }
+    }
+    for (const module of this.#modules.values()) {
+      for (const record of module.own.values()) this.#check(record, [tokenName(record.token)]);
+    }
+  }
+
+  /** Module definitions in dependency order: imports before importers. */
+  get modules(): ModuleDefinition[] {
+    return [...this.#modules.keys()];
+  }
+
+  /** A plain description of the validated graph, without creating any provider. */
+  describe(): ModuleDescription[] {
+    return [...this.#modules.values()].map((module) => ({
+      name: module.name,
+      imports: module.imports.map((imported) => imported.name),
+      providers: [...module.own.values()].map((record) => ({
+        token: tokenName(record.token),
+        kind: record.kind,
+        scope: record.scope,
+        inject: record.deps.map(tokenName),
+      })),
+      exports: [...module.exported.keys()].map(tokenName),
+    }));
+  }
+
+  /** Throws if `tokens` cannot all be resolved from `module`. `label` starts the error path. */
+  check(module: ModuleDefinition, tokens: readonly Token[], label: string): void {
+    const record = this.#module(module);
+    for (const token of tokens) {
+      const target = this.#lookupOrThrow(record, token, [label]);
+      this.#check(target, [label, tokenName(token)]);
+    }
+  }
+
+  /** True if resolving any of `tokens` from `module` needs a request scope. */
+  needsRequest(module: ModuleDefinition, tokens: readonly Token[]): boolean {
+    const record = this.#module(module);
+    return tokens.some((token) => this.#lookupOrThrow(record, token, []).requestBound);
+  }
+
+  /** Starts a request scope. `values` supplies the `requestTokens`. */
+  requestScope(values: ReadonlyMap<Token, unknown>): RequestScope {
+    this.#assertReady();
+    const scope: ScopeState = { values, instances: new Map(), created: [] };
+    return {
+      resolve: (module, token) =>
+        this.#instance(this.#lookupOrThrow(this.#module(module), token, []), scope),
+      dispose: () => disposeAll(scope.created.splice(0)),
+    };
+  }
+
+  async init(): Promise<void> {
+    if (this.#state !== 'new') throw new Error(`Container is already ${this.#state}`);
+    this.#state = 'initializing';
+    try {
+      for (const module of this.#modules.values()) {
+        for (const record of module.own.values()) {
+          if (record.scope === 'singleton') await this.#ensure(record);
+          else await this.#ensureDeps(record);
+        }
+      }
+      this.#state = 'ready';
+    } catch (error) {
+      await this.dispose().catch(() => undefined);
+      throw error;
+    }
+  }
+
+  /** Resolves `token` as seen from `module`. Transients are created on every call. */
+  resolve(module: ModuleDefinition, token: Token): unknown {
+    this.#assertReady();
+    return this.#instance(this.#lookupOrThrow(this.#module(module), token, []));
+  }
+
+  /** Resolves `token` from what the root modules can see. Meant for tests and scripts. */
+  get(token: Token): unknown {
+    this.#assertReady();
+    const found = new Set<ProviderRecord>();
+    for (const root of this.#roots) {
+      const hit = lookup(root, token);
+      if (hit && 'ambiguous' in hit) {
+        throw new Error(`${tokenName(token)} is exported to ${root.name} by more than one import`);
+      }
+      if (hit) found.add(hit);
+    }
+    if (found.size === 0) throw new Error(`${tokenName(token)} is not visible to the root modules`);
+    if (found.size > 1)
+      throw new Error(`${tokenName(token)} is provided by more than one root module`);
+    return this.#instance([...found][0] as ProviderRecord);
+  }
+
+  async dispose(): Promise<void> {
+    this.#state = 'disposed';
+    await disposeAll(this.#created.splice(0).map((record) => ({ record, value: record.instance })));
+  }
+
+  #collect(definition: ModuleDefinition, stack: ModuleDefinition[], where: string): ModuleRecord {
+    if (typeof definition !== 'object' || (definition as unknown) === null) {
+      const value = definition as unknown;
+      const hint = value === undefined ? ' (is there a circular import?)' : '';
+      throw new TypeError(
+        `Invalid module at ${where}: ${value === null ? 'null' : typeof value}${hint}`,
+      );
+    }
+    const existing = this.#modules.get(definition);
+    if (existing) return existing;
+
+    const name = definition.name ?? '(anonymous module)';
+    if (stack.includes(definition)) {
+      const cycle = [...stack.slice(stack.indexOf(definition)), definition].map(moduleName);
+      throw new Error(`Module import cycle: ${cycle.join(' → ')}`);
+    }
+
+    const imports = (definition.imports ?? []).map((child, i) =>
+      this.#collect(child, [...stack, definition], `${name}.imports[${String(i)}]`),
+    );
+    const record: ModuleRecord = { definition, name, imports, own: new Map(), exported: new Map() };
+
+    (definition.providers ?? []).forEach((provider, i) => {
+      const declared = normalizeProvider(provider, `${name}.providers[${String(i)}]`);
+      if (record.own.has(declared.token)) {
+        throw new Error(`${tokenName(declared.token)} is provided twice in ${name}`);
+      }
+      const spec = this.#overrides.get(declared.token) ?? declared;
+      if (spec !== declared) this.#overridden.add(declared.token);
+      record.own.set(spec.token, {
+        ...spec,
+        module: record,
+        links: [],
+        requestBound: false,
+        supplied: false,
+        state: 'unchecked',
+        instance: undefined,
+        ready: undefined,
+      });
+    });
+
+    for (const entry of definition.exports ?? []) exportEntry(record, entry);
+    this.#modules.set(definition, record);
+    return record;
+  }
+
+  #module(definition: ModuleDefinition): ModuleRecord {
+    const record = this.#modules.get(definition);
+    if (!record) throw new Error(`${moduleName(definition)} is not part of this application`);
+    return record;
+  }
+
+  #lookupOrThrow(module: ModuleRecord, token: Token, path: string[]): ProviderRecord {
+    const hit = lookup(module, token) ?? this.#supplied.get(token);
+    const chain = [...path, tokenName(token)].join(' → ');
+    if (!hit) {
+      const imports = module.imports.map((m) => m.name).join(', ') || 'none';
+      throw new Error(
+        `Cannot resolve ${chain} in ${module.name}: ${tokenName(token)} is not provided by ${module.name} or exported by its imports (${imports})`,
+      );
+    }
+    if ('ambiguous' in hit) {
+      throw new Error(
+        `Cannot resolve ${chain} in ${module.name}: ${tokenName(token)} is exported by more than one import (${hit.ambiguous.join(', ')})`,
+      );
+    }
+    return hit;
+  }
+
+  /** Links dependencies and detects missing providers and cycles. */
+  #check(record: ProviderRecord, path: string[]): void {
+    if (record.state === 'checked') return;
+    if (record.state === 'checking') {
+      const start = path.indexOf(tokenName(record.token));
+      throw new Error(`Dependency cycle: ${path.slice(start).join(' → ')}`);
+    }
+    record.state = 'checking';
+    record.links = record.deps.map((token) => {
+      const target = this.#lookupOrThrow(record.module, token, path);
+      this.#check(target, [...path, tokenName(token)]);
+      return target;
+    });
+    record.requestBound =
+      record.scope === 'request' ||
+      (record.scope === 'transient' && record.links.some((link) => link.requestBound));
+    const bound = record.scope === 'singleton' && record.links.find((link) => link.requestBound);
+    if (bound) {
+      const name = tokenName(record.token);
+      const chain = [...path, tokenName(bound.token)].join(' → ');
+      throw new Error(
+        `Singleton ${name} in ${record.module.name} depends on request-scoped ${tokenName(bound.token)} (${chain}). A singleton outlives the request; make ${name} request-scoped or transient.`,
+      );
+    }
+    record.state = 'checked';
+  }
+
+  #ensure(record: ProviderRecord): Promise<void> {
+    record.ready ??= (async () => {
+      await this.#ensureDeps(record);
+      let value = this.#create(record);
+      if (record.kind === 'factory' && value instanceof Promise) {
+        try {
+          value = await (value as Promise<unknown>);
+        } catch (error) {
+          throw creationError(record, error);
+        }
+      }
+      record.instance = value;
+      if (record.kind !== 'value') this.#created.push(record);
+    })();
+    return record.ready;
+  }
+
+  async #ensureDeps(record: ProviderRecord): Promise<void> {
+    for (const dep of record.links) {
+      if (dep.scope === 'singleton') await this.#ensure(dep);
+      else await this.#ensureDeps(dep);
+    }
+  }
+
+  #create(record: ProviderRecord, scope?: ScopeState): unknown {
+    const deps = record.links.map((dep) => this.#instance(dep, scope));
+    try {
+      return record.create(deps);
+    } catch (error) {
+      throw creationError(record, error);
+    }
+  }
+
+  #instance(record: ProviderRecord, scope?: ScopeState): unknown {
+    if (record.scope === 'singleton') return record.instance;
+    if (record.scope === 'request') {
+      if (!scope) {
+        throw new Error(
+          `${tokenName(record.token)} is request-scoped and can only be resolved while handling a request`,
+        );
+      }
+      if (record.supplied) {
+        if (!scope.values.has(record.token)) {
+          throw new Error(`This request scope has no value for ${tokenName(record.token)}`);
+        }
+        return scope.values.get(record.token);
+      }
+      if (scope.instances.has(record)) return scope.instances.get(record);
+      const value = this.#createSync(record, scope);
+      scope.instances.set(record, value);
+      scope.created.push({ record, value });
+      return value;
+    }
+    return this.#createSync(record, scope);
+  }
+
+  #createSync(record: ProviderRecord, scope: ScopeState | undefined): unknown {
+    const value = this.#create(record, scope);
+    if (record.kind === 'factory' && value instanceof Promise) {
+      (value as Promise<unknown>).catch(() => undefined);
+      const kind = record.scope === 'request' ? 'Request-scoped' : 'Transient';
+      throw new Error(
+        `${kind} provider ${tokenName(record.token)} in ${record.module.name} returned a Promise; only singletons may be async`,
+      );
+    }
+    return value;
+  }
+
+  #assertReady(): void {
+    if (this.#state !== 'ready')
+      throw new Error('The container is not initialized; call init() first');
+  }
+}
+
+function lookup(module: ModuleRecord, token: Token): Lookup {
+  const own = module.own.get(token);
+  if (own) return own;
+  const hits = new Map<ProviderRecord, string>();
+  for (const imported of module.imports) {
+    const hit = imported.exported.get(token);
+    if (hit && !hits.has(hit)) hits.set(hit, imported.name);
+  }
+  if (hits.size > 1) return { ambiguous: [...hits.values()] };
+  return hits.keys().next().value;
+}
+
+function exportEntry(module: ModuleRecord, entry: unknown): void {
+  const imported = module.imports.find((m) => m.definition === entry);
+  if (imported) {
+    for (const [token, record] of imported.exported) module.exported.set(token, record);
+    return;
+  }
+  if (!isToken(entry)) {
+    throw new TypeError(
+      `Invalid export in ${module.name}: expected a token or an imported module${entry === undefined ? ' (is there a circular import?)' : ''}`,
+    );
+  }
+  const hit = lookup(module, entry);
+  if (!hit) {
+    throw new Error(
+      `${module.name} exports ${tokenName(entry)}, which it neither provides nor imports`,
+    );
+  }
+  if ('ambiguous' in hit) {
+    throw new Error(
+      `${module.name} exports ${tokenName(entry)}, which more than one import provides (${hit.ambiguous.join(', ')})`,
+    );
+  }
+  module.exported.set(entry, hit);
+}
+
+/** Disposes in reverse order, continuing past failures. */
+async function disposeAll(
+  created: readonly { record: ProviderRecord; value: unknown }[],
+): Promise<void> {
+  const errors: unknown[] = [];
+  for (const { record, value } of [...created].reverse()) {
+    try {
+      await disposeValue(record, value);
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, `Failed to dispose ${String(errors.length)} provider(s)`);
+  }
+}
+
+async function disposeValue(record: ProviderRecord, instance: unknown): Promise<void> {
+  if (record.dispose) {
+    await record.dispose(instance);
+    return;
+  }
+  const value = instance as Partial<AsyncDisposable & Disposable> | null | undefined;
+  const asyncDispose = value?.[Symbol.asyncDispose];
+  const syncDispose = value?.[Symbol.dispose];
+  if (typeof asyncDispose === 'function') await asyncDispose.call(value);
+  else if (typeof syncDispose === 'function') syncDispose.call(value);
+}
+
+function creationError(record: ProviderRecord, cause: unknown): Error {
+  return new Error(`Failed to create ${tokenName(record.token)} in ${record.module.name}`, {
+    cause,
+  });
+}
+
+function moduleName(definition: ModuleDefinition): string {
+  return definition.name ?? '(anonymous module)';
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { Container } from './container.js';
+export type {
+  ContainerOptions,
+  ModuleDefinition,
+  ModuleDescription,
+  ProviderDescription,
+  RequestScope,
+} from './container.js';
+export type { ClassProvider, FactoryProvider, Provider, Scope, ValueProvider } from './provider.js';
+export { createToken } from './token.js';
+export type {
+  Class,
+  Constructor,
+  InjectionToken,
+  ResolveTokens,
+  Token,
+  TokenType,
+} from './token.js';