@codefast/di 0.3.13-canary.4

package/dist/scope-validation.mjs

@@ -0,0 +1,34 @@
+import { ScopeViolationError } from "./errors.mjs";
+import { registryKeyLabel } from "./binding-select.mjs";
+import { listResolvedDependencies } from "./dependency-graph.mjs";
+//#region src/scope-validation.ts
+/**
+* Walks every binding in the registry and throws {@link ScopeViolationError} on the first
+* captive-dependency violation found: a singleton that directly or transitively depends on a
+* scoped or transient binding. Constant bindings are exempt (no stateful instance to capture).
+*
+* Called by {@link Container.validate} and automatically after each `load()` in non-production
+* environments.
+*/
+function validateScopeRules(context) {
+	const reader = context.getMetadataReader();
+	const lookupBindings = (key) => context.lookupBindings(key);
+	for (const registryKey of context.collectAllRegistryKeys()) {
+		const bindings = lookupBindings(registryKey);
+		if (bindings === void 0 || bindings.length === 0) continue;
+		for (const consumer of bindings) {
+			const deps = listResolvedDependencies(consumer, lookupBindings, reader, [registryKeyLabel(registryKey)]);
+			for (const dep of deps) if (consumer.scope === "singleton" && dep.binding.kind !== "constant" && (dep.binding.scope === "transient" || dep.binding.scope === "scoped")) throw new ScopeViolationError({
+				consumerBindingId: consumer.id,
+				consumerKind: consumer.kind,
+				consumerScope: consumer.scope,
+				dependencyBindingId: dep.binding.id,
+				dependencyKind: dep.binding.kind,
+				dependencyScope: dep.binding.scope,
+				resolutionPath: dep.path
+			});
+		}
+	}
+}
+//#endregion
+export { validateScopeRules };

package/dist/scope.d.mts

@@ -0,0 +1,80 @@
+import { Binding, BindingIdentifier } from "./binding.mjs";
+
+//#region src/scope.d.ts
+/**
+ * Caches singleton and scoped instances and runs deactivation hooks on disposal.
+ */
+declare class ScopeManager {
+  /** Cached singleton instances: `bindingId → { binding, instance }`. */
+  private readonly singletonCache;
+  /** Cached scoped instances for this container level: `bindingId → { binding, instance }`. */
+  private readonly scopedCache;
+  private readonly ownsSingletonDisposal;
+  /** In-flight async singleton creation promises (deduplicate concurrent resolveAsync calls). */
+  private readonly singletonPendingPromises;
+  private readonly scopedPendingPromises;
+  private constructor();
+  /** Creates a root scope manager that owns both the singleton cache and scoped cache. */
+  static createRoot(): ScopeManager;
+  /**
+   * Shares the parent singleton cache; receives a fresh scoped cache (for child containers).
+   */
+  createChildScope(): ScopeManager;
+  /**
+   * Whether a singleton/scoped binding currently has a cached instance (always false for transient).
+   */
+  isBindingCached(binding: Binding<unknown>): boolean;
+  /** Returns the cached instance for singleton/scoped bindings, or calls `createInstance` on first access. */
+  getOrCreate(binding: Binding<unknown>, createInstance: () => unknown): unknown;
+  /**
+   * Async variant of {@link getOrCreate}. Deduplicates concurrent creation calls for the same
+   * binding using an in-flight promise map, preventing double-instantiation under parallel resolves.
+   */
+  getOrCreateAsync(binding: Binding<unknown>, createInstance: () => Promise<unknown>): Promise<unknown>;
+  /**
+   * Runs synchronous `onDeactivation` hooks for scoped instances owned by this manager.
+   * Throws if any hook returns a Promise.
+   */
+  dispose(): void;
+  /**
+   * Runs `onDeactivation` hooks for scoped instances; root also disposes shared singletons.
+   */
+  disposeAsync(): Promise<void>;
+  /**
+   * Drops a cached singleton/scoped instance for `bindingId` and runs `onDeactivation` synchronously.
+   */
+  releaseByBindingId(bindingId: BindingIdentifier): void;
+  /**
+   * Drops a cached singleton/scoped instance for `bindingId` and awaits `onDeactivation`.
+   */
+  releaseByBindingIdAsync(bindingId: BindingIdentifier): Promise<void>;
+  /**
+   * Drops a cached singleton/scoped instance for `binding.id` and runs `onDeactivation` synchronously.
+   */
+  releaseBinding(binding: Binding<unknown>): void;
+  /**
+   * Drops a cached singleton/scoped instance for `binding.id` and awaits `onDeactivation`.
+   */
+  releaseBindingAsync(binding: Binding<unknown>): Promise<void>;
+  /**
+   * Removes a single entry from `store`, runs `onDeactivation` synchronously, then calls
+   * `@preDestroy`. Throws {@link InternalError} if the handler returns a Promise.
+   */
+  private releaseFromStore;
+  /**
+   * Async counterpart of {@link releaseFromStore}: awaits `onDeactivation` then `@preDestroy`.
+   */
+  private releaseFromStoreAsync;
+  /**
+   * Iterates all entries in `store`, clears each one, runs `onDeactivation` + `@preDestroy`
+   * synchronously. Throws {@link InternalError} if any handler returns a Promise.
+   */
+  private disposeMap;
+  /**
+   * Async counterpart of {@link disposeMap}: clears the store first, then runs all
+   * deactivation hooks; collects errors and rethrows as `AggregateError` when multiple fail.
+   */
+  private disposeMapAsync;
+}
+//#endregion
+export { ScopeManager };

package/dist/scope.mjs

@@ -0,0 +1,185 @@
+import { InternalError } from "./errors.mjs";
+import { runPreDestroy, runPreDestroyAsync } from "./lifecycle.mjs";
+//#region src/scope.ts
+/** Returns `true` when `value` is a thenable (duck-typed Promise check). */
+function isPromiseLike(value) {
+	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+/**
+* Caches singleton and scoped instances and runs deactivation hooks on disposal.
+*/
+var ScopeManager = class ScopeManager {
+	/** Cached singleton instances: `bindingId → { binding, instance }`. */
+	singletonCache;
+	/** Cached scoped instances for this container level: `bindingId → { binding, instance }`. */
+	scopedCache;
+	ownsSingletonDisposal;
+	/** In-flight async singleton creation promises (deduplicate concurrent resolveAsync calls). */
+	singletonPendingPromises;
+	scopedPendingPromises;
+	constructor(singletonCache, scopedCache, ownsSingletonDisposal, singletonPendingPromises, scopedPendingPromises) {
+		this.singletonCache = singletonCache;
+		this.scopedCache = scopedCache;
+		this.ownsSingletonDisposal = ownsSingletonDisposal;
+		this.singletonPendingPromises = singletonPendingPromises;
+		this.scopedPendingPromises = scopedPendingPromises;
+	}
+	/** Creates a root scope manager that owns both the singleton cache and scoped cache. */
+	static createRoot() {
+		return new ScopeManager(/* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), true, /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map());
+	}
+	/**
+	* Shares the parent singleton cache; receives a fresh scoped cache (for child containers).
+	*/
+	createChildScope() {
+		return new ScopeManager(this.singletonCache, /* @__PURE__ */ new Map(), false, this.singletonPendingPromises, /* @__PURE__ */ new Map());
+	}
+	/**
+	* Whether a singleton/scoped binding currently has a cached instance (always false for transient).
+	*/
+	isBindingCached(binding) {
+		if (binding.scope === "transient") return false;
+		return (binding.scope === "singleton" ? this.singletonCache : this.scopedCache).has(binding.id);
+	}
+	/** Returns the cached instance for singleton/scoped bindings, or calls `createInstance` on first access. */
+	getOrCreate(binding, createInstance) {
+		if (binding.scope === "transient") return createInstance();
+		const cache = binding.scope === "singleton" ? this.singletonCache : this.scopedCache;
+		const cached = cache.get(binding.id);
+		if (cached !== void 0) return cached.instance;
+		const instance = createInstance();
+		cache.set(binding.id, {
+			binding,
+			instance
+		});
+		return instance;
+	}
+	/**
+	* Async variant of {@link getOrCreate}. Deduplicates concurrent creation calls for the same
+	* binding using an in-flight promise map, preventing double-instantiation under parallel resolves.
+	*/
+	async getOrCreateAsync(binding, createInstance) {
+		if (binding.scope === "transient") return createInstance();
+		const cache = binding.scope === "singleton" ? this.singletonCache : this.scopedCache;
+		const pendingCreationMap = binding.scope === "singleton" ? this.singletonPendingPromises : this.scopedPendingPromises;
+		const cached = cache.get(binding.id);
+		if (cached !== void 0) return cached.instance;
+		let pendingCreation = pendingCreationMap.get(binding.id);
+		if (pendingCreation === void 0) {
+			pendingCreation = (async () => {
+				try {
+					const instance = await createInstance();
+					cache.set(binding.id, {
+						binding,
+						instance
+					});
+					return instance;
+				} finally {
+					pendingCreationMap.delete(binding.id);
+				}
+			})();
+			pendingCreationMap.set(binding.id, pendingCreation);
+		}
+		return pendingCreation;
+	}
+	/**
+	* Runs synchronous `onDeactivation` hooks for scoped instances owned by this manager.
+	* Throws if any hook returns a Promise.
+	*/
+	dispose() {
+		this.disposeMap(this.scopedCache);
+		if (this.ownsSingletonDisposal) this.disposeMap(this.singletonCache);
+	}
+	/**
+	* Runs `onDeactivation` hooks for scoped instances; root also disposes shared singletons.
+	*/
+	async disposeAsync() {
+		await this.disposeMapAsync(this.scopedCache);
+		if (this.ownsSingletonDisposal) await this.disposeMapAsync(this.singletonCache);
+	}
+	/**
+	* Drops a cached singleton/scoped instance for `bindingId` and runs `onDeactivation` synchronously.
+	*/
+	releaseByBindingId(bindingId) {
+		this.releaseFromStore(this.singletonCache, bindingId);
+		this.releaseFromStore(this.scopedCache, bindingId);
+	}
+	/**
+	* Drops a cached singleton/scoped instance for `bindingId` and awaits `onDeactivation`.
+	*/
+	async releaseByBindingIdAsync(bindingId) {
+		await this.releaseFromStoreAsync(this.singletonCache, bindingId);
+		await this.releaseFromStoreAsync(this.scopedCache, bindingId);
+	}
+	/**
+	* Drops a cached singleton/scoped instance for `binding.id` and runs `onDeactivation` synchronously.
+	*/
+	releaseBinding(binding) {
+		this.releaseByBindingId(binding.id);
+	}
+	/**
+	* Drops a cached singleton/scoped instance for `binding.id` and awaits `onDeactivation`.
+	*/
+	async releaseBindingAsync(binding) {
+		await this.releaseByBindingIdAsync(binding.id);
+	}
+	/**
+	* Removes a single entry from `store`, runs `onDeactivation` synchronously, then calls
+	* `@preDestroy`. Throws {@link InternalError} if the handler returns a Promise.
+	*/
+	releaseFromStore(store, bindingId) {
+		const entry = store.get(bindingId);
+		if (entry === void 0) return;
+		store.delete(bindingId);
+		const handler = entry.binding.onDeactivation;
+		if (handler !== void 0) {
+			if (isPromiseLike(handler(entry.instance))) throw new InternalError("onDeactivation returned a Promise during synchronous scope release; use releaseBindingAsync() or unloadAsync().");
+		}
+		if (entry.binding.kind === "class") runPreDestroy(entry.binding.implementationClass, entry.instance);
+	}
+	/**
+	* Async counterpart of {@link releaseFromStore}: awaits `onDeactivation` then `@preDestroy`.
+	*/
+	async releaseFromStoreAsync(store, bindingId) {
+		const entry = store.get(bindingId);
+		if (entry === void 0) return;
+		store.delete(bindingId);
+		const handler = entry.binding.onDeactivation;
+		if (handler !== void 0) await handler(entry.instance);
+		if (entry.binding.kind === "class") await runPreDestroyAsync(entry.binding.implementationClass, entry.instance);
+	}
+	/**
+	* Iterates all entries in `store`, clears each one, runs `onDeactivation` + `@preDestroy`
+	* synchronously. Throws {@link InternalError} if any handler returns a Promise.
+	*/
+	disposeMap(store) {
+		for (const [bindingId, entry] of [...store.entries()]) {
+			store.delete(bindingId);
+			const handler = entry.binding.onDeactivation;
+			if (handler !== void 0) {
+				if (isPromiseLike(handler(entry.instance))) throw new InternalError("onDeactivation returned a Promise; use disposeAsync() instead of dispose().");
+			}
+			if (entry.binding.kind === "class") runPreDestroy(entry.binding.implementationClass, entry.instance);
+		}
+	}
+	/**
+	* Async counterpart of {@link disposeMap}: clears the store first, then runs all
+	* deactivation hooks; collects errors and rethrows as `AggregateError` when multiple fail.
+	*/
+	async disposeMapAsync(store) {
+		const entries = [...store.values()];
+		store.clear();
+		const errors = [];
+		for (const entry of entries) try {
+			const handler = entry.binding.onDeactivation;
+			if (handler !== void 0) await handler(entry.instance);
+			if (entry.binding.kind === "class") await runPreDestroyAsync(entry.binding.implementationClass, entry.instance);
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "disposeAsync: multiple deactivation handlers failed");
+	}
+};
+//#endregion
+export { ScopeManager };

package/dist/token.d.mts

@@ -0,0 +1,20 @@
+//#region src/token.d.ts
+declare const TOKEN_BRAND: unique symbol;
+/**
+ * Opaque injection key branded by `Value` so distinct tokens do not unify in the type system.
+ * Registry keys rely on **reference equality** — always reuse the same `token()` result as the key.
+ */
+type Token<Value> = {
+  readonly [TOKEN_BRAND]: Value;
+  readonly name: string;
+};
+/**
+ * Extracts the value type carried by a {@link Token}.
+ */
+type TokenValue<Type> = Type extends Token<infer Value> ? Value : Type extends (abstract new (...args: never[]) => infer Value) ? Value : never;
+/**
+ * Creates a type-safe injection token identified by `name` (for debugging and errors).
+ */
+declare function token<Value>(name: string): Token<Value>;
+//#endregion
+export { Token, TokenValue, token };

package/dist/token.mjs

@@ -0,0 +1,9 @@
+//#region src/token.ts
+/**
+* Creates a type-safe injection token identified by `name` (for debugging and errors).
+*/
+function token(name) {
+	return Object.freeze({ name });
+}
+//#endregion
+export { token };

package/package.json

@@ -0,0 +1,157 @@
+{
+  "name": "@codefast/di",
+  "version": "0.3.13-canary.4",
+  "description": "Lightweight dependency injection primitives for Codefast",
+  "keywords": [
+    "codefast",
+    "dependency-injection",
+    "di",
+    "inversion-of-control",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Vuong Phan <mr.thevuong@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codefastlabs/codefast.git",
+    "directory": "packages/di"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "imports": {
+    "#/*": [
+      "./src/*",
+      "./src/*.ts",
+      "./src/*.tsx",
+      "./src/*/index.ts",
+      "./src/*/index.tsx"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./binding": {
+      "types": "./dist/binding.d.mts",
+      "import": "./dist/binding.mjs"
+    },
+    "./binding-select": {
+      "types": "./dist/binding-select.d.mts",
+      "import": "./dist/binding-select.mjs"
+    },
+    "./constraints": {
+      "types": "./dist/constraints.d.mts",
+      "import": "./dist/constraints.mjs"
+    },
+    "./container": {
+      "types": "./dist/container.d.mts",
+      "import": "./dist/container.mjs"
+    },
+    "./decorators/inject": {
+      "types": "./dist/decorators/inject.d.mts",
+      "import": "./dist/decorators/inject.mjs"
+    },
+    "./decorators/injectable": {
+      "types": "./dist/decorators/injectable.d.mts",
+      "import": "./dist/decorators/injectable.mjs"
+    },
+    "./decorators/lifecycle-decorators": {
+      "types": "./dist/decorators/lifecycle-decorators.d.mts",
+      "import": "./dist/decorators/lifecycle-decorators.mjs"
+    },
+    "./dependency-graph": {
+      "types": "./dist/dependency-graph.d.mts",
+      "import": "./dist/dependency-graph.mjs"
+    },
+    "./environment": {
+      "types": "./dist/environment.d.mts",
+      "import": "./dist/environment.mjs"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.mts",
+      "import": "./dist/errors.mjs"
+    },
+    "./inspector": {
+      "types": "./dist/inspector.d.mts",
+      "import": "./dist/inspector.mjs"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle.d.mts",
+      "import": "./dist/lifecycle.mjs"
+    },
+    "./metadata/metadata-keys": {
+      "types": "./dist/metadata/metadata-keys.d.mts",
+      "import": "./dist/metadata/metadata-keys.mjs"
+    },
+    "./metadata/metadata-types": {
+      "types": "./dist/metadata/metadata-types.d.mts",
+      "import": "./dist/metadata/metadata-types.mjs"
+    },
+    "./metadata/param-registry": {
+      "types": "./dist/metadata/param-registry.d.mts",
+      "import": "./dist/metadata/param-registry.mjs"
+    },
+    "./metadata/symbol-metadata-reader": {
+      "types": "./dist/metadata/symbol-metadata-reader.d.mts",
+      "import": "./dist/metadata/symbol-metadata-reader.mjs"
+    },
+    "./module": {
+      "types": "./dist/module.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.mts",
+      "import": "./dist/registry.mjs"
+    },
+    "./resolver": {
+      "types": "./dist/resolver.d.mts",
+      "import": "./dist/resolver.mjs"
+    },
+    "./scope": {
+      "types": "./dist/scope.d.mts",
+      "import": "./dist/scope.mjs"
+    },
+    "./scope-validation": {
+      "types": "./dist/scope-validation.d.mts",
+      "import": "./dist/scope-validation.mjs"
+    },
+    "./token": {
+      "types": "./dist/token.d.mts",
+      "import": "./dist/token.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@typescript/native-preview": "7.0.0-dev.20260411.1",
+    "@vitest/coverage-v8": "^4.1.4",
+    "typescript": "^6.0.2",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.4",
+    "@codefast/typescript-config": "0.3.13-canary.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsgo --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}