feat(di): add a token-based injector with @contract tokens

Purpose-built container with an Angular-compatible surface (inject,
runInInjectionContext, Injector, provide/provideLazy, forwardRef).
Lookup is class-object first with a fallback to the decorator-set name,
per injector level, so per-call string overrides and duplicated contract
copies in the extensions tree resolve to the same provider. Includes a
legacy provider kind that constructs Yok-style classes via annotate(),
lazy side-effect loaders for path-based registration, transient
retention, and reverse-instantiation-order disposal.

Author: edusperoni

lib/common/di/contract.ts

@@ -0,0 +1,70 @@
+/**
+ * The name is stored under a `Symbol.for` key deliberately: extensions install
+ * into their own node_modules tree, so a duplicated copy of this module (and
+ * of any contract class) must write and read the same property key. A unique
+ * `Symbol()` would make duplicate copies mutually invisible and break the
+ * name-fallback lookup in `Injector.get()`.
+ */
+export const CONTRACT_NAME = Symbol.for("nativescript:di:contractName");
+
+export interface IContractOptions {
+	/**
+	 * Canonical token name, without the `$` prefix. Must be an explicit string
+	 * literal — never derive it from `class.name`, which changes under
+	 * minification.
+	 */
+	name: string;
+}
+
+// Per module instance on purpose: a duplicated CLI copy in an extensions tree
+// carries its own registry, so contracts redeclared by another copy never
+// false-positive here.
+const mintedNames = new Map<string, Function>();
+
+/**
+ * Marks an abstract class as a DI token. The decorated class resolves by
+ * object identity first and by its name on a miss, so duplicated copies of a
+ * contract remain interchangeable across node_modules trees.
+ */
+export function Contract(
+	options: IContractOptions,
+): (target: Function) => void {
+	const { name } = options;
+	return (target: Function): void => {
+		const existing = mintedNames.get(name);
+		if (existing && existing !== target) {
+			throw new Error(
+				`@Contract name '${name}' is already used by '${
+					existing.name || "another contract"
+				}'. Token names must be unique — a duplicate silently aliases two contracts.`,
+			);
+		}
+		mintedNames.set(name, target);
+		Object.defineProperty(target, CONTRACT_NAME, {
+			value: name,
+			writable: false,
+			enumerable: false,
+			configurable: false,
+		});
+	};
+}
+
+/**
+ * Reads the decorator-set name. Own-property check only: an implementation
+ * class extending a contract inherits the property, but must not itself act
+ * as a token.
+ */
+export function getContractName(token: any): string | undefined {
+	if (
+		typeof token === "function" &&
+		Object.prototype.hasOwnProperty.call(token, CONTRACT_NAME)
+	) {
+		return (<any>token)[CONTRACT_NAME];
+	}
+	return undefined;
+}
+
+/** Test seam — the duplicate-name registry otherwise persists per process. */
+export function clearMintedContractNames(): void {
+	mintedNames.clear();
+}

lib/common/di/forward-ref.ts

@@ -0,0 +1,25 @@
+// `Symbol.for` so a duplicated CLI copy in an extensions tree marks thunks
+// with the same key this copy reads — mirrors the CONTRACT_NAME reasoning.
+const FORWARD_REF = Symbol.for("nativescript:di:forwardRef");
+
+/**
+ * Defers a token reference until the container reads it — for provider arrays
+ * evaluated at module load, where a class declared later in the file (TDZ) or
+ * reached through a circular import is not yet a usable binding. Same
+ * semantics as Angular's forwardRef; resolved at registration and lookup.
+ *
+ * This defers *references*, not construction: it cannot break an
+ * instantiation cycle between two services. For that, inject the Injector and
+ * resolve late.
+ */
+export function forwardRef<T>(fn: () => T): T {
+	(<any>fn)[FORWARD_REF] = true;
+	return <any>fn;
+}
+
+export function resolveForwardRef<T>(token: T): T {
+	if (typeof token === "function" && (<any>token)[FORWARD_REF] === true) {
+		return (<any>token)();
+	}
+	return token;
+}

lib/common/di/index.ts

@@ -0,0 +1,23 @@
+export { Injector } from "./injector";
+export { inject, runInInjectionContext } from "./inject";
+export { forwardRef, resolveForwardRef } from "./forward-ref";
+export {
+	Contract,
+	getContractName,
+	CONTRACT_NAME,
+	clearMintedContractNames,
+} from "./contract";
+export type { IContractOptions } from "./contract";
+export { provide, provideLazy } from "./providers";
+export type {
+	Provider,
+	ProviderToken,
+	Type,
+	AbstractType,
+	IClassProvider,
+	IValueProvider,
+	IFactoryProvider,
+	ILazyClassProvider,
+	ILegacyClassProvider,
+	ILazyRequireProvider,
+} from "./providers";

lib/common/di/inject.ts

@@ -0,0 +1,30 @@
+import type { Injector } from "./injector";
+import type { ProviderToken } from "./providers";
+
+// Sync-only by design (no AsyncLocalStorage): `current` is restored in a
+// finally, so inject() is valid in field initializers, constructor bodies and
+// provider factories — and never after an await. Self-inject the Injector for
+// later lookups.
+let current: Injector | null = null;
+
+export function inject<T = any>(token: ProviderToken<T>): T {
+	if (!current) {
+		throw new Error(
+			"inject() can only be called from an injection context — a field " +
+				"initializer, a constructor, or a provider factory running under " +
+				"runInInjectionContext(). It is not valid after an await; inject " +
+				"the Injector itself and use injector.get() for late lookups.",
+		);
+	}
+	return current.get(token);
+}
+
+export function runInInjectionContext<T>(injector: Injector, fn: () => T): T {
+	const previous = current;
+	current = injector;
+	try {
+		return fn();
+	} finally {
+		current = previous;
+	}
+}