feat(di): Angular-shaped InjectOptions on inject() and Injector.get()

optional resolves to null instead of throwing for unknown tokens (a
found-but-misconfigured provider still throws); skipSelf starts at the
parent, escaping a child scope's shadowing entry; self refuses parent
fallthrough. self+skipSelf throws. host is deliberately absent - it is
an Angular component-tree concept with no analog in this hierarchy.

get()'s former second parameter - the legacy per-call ctorArguments bag
- had exactly one caller, the facade's own resolve(name, bag). It moves
to a protected getWithLegacyArguments channel, so the public get()
aligns with Angular's shape today rather than after the legacy paths
are deleted.

Author: edusperoni

dependency-injection.md

@@ -95,6 +95,21 @@ string name — all three return the same instance. The string forms exist for
 interoperability with the legacy registry; use the class token whenever one
 exists.
 
+Both `inject()` and `get()` take Angular-shaped options as their second
+argument:
+
+```ts
+inject(DoctorService, { optional: true }); // DoctorService | null — no throw
+inject("logger", { skipSelf: true });      // start at the parent: escapes a
+                                           // child scope's shadowing entry
+inject("options", { self: true });         // this level only — no fallthrough
+```
+
+`optional` covers not-found only; a found-but-misconfigured provider still
+throws. `self` and `skipSelf` cannot be combined. There is deliberately no
+`host` option: it is an Angular component-tree concept with no analog in the
+CLI's injector hierarchy.
+
 Registering: providers
 ----------------------
 

lib/common/di/index.ts

@@ -1,4 +1,5 @@
 export { Injector } from "./injector";
+export type { InjectOptions } from "./injector";
 export { inject, runInInjectionContext } from "./inject";
 export { forwardRef, resolveForwardRef } from "./forward-ref";
 export {

lib/common/di/inject.ts

@@ -1,4 +1,4 @@
-import type { Injector } from "./injector";
+import type { Injector, InjectOptions } from "./injector";
 import type { ProviderToken } from "./providers";
 
 // Sync-only by design (no AsyncLocalStorage): `current` is restored in a
@@ -7,7 +7,19 @@ import type { ProviderToken } from "./providers";
 // later lookups.
 let current: Injector | null = null;
 
-export function inject<T = any>(token: ProviderToken<T>): T {
+export function inject<T = any>(token: ProviderToken<T>): T;
+export function inject<T = any>(
+	token: ProviderToken<T>,
+	options: InjectOptions & { optional: true },
+): T | null;
+export function inject<T = any>(
+	token: ProviderToken<T>,
+	options: InjectOptions,
+): T;
+export function inject<T = any>(
+	token: ProviderToken<T>,
+	options?: InjectOptions,
+): T | null {
 	if (!current) {
 		throw new Error(
 			"inject() can only be called from an injection context — a field " +
@@ -16,7 +28,7 @@ export function inject<T = any>(token: ProviderToken<T>): T {
 				"the Injector itself and use injector.get() for late lookups.",
 		);
 	}
-	return current.get(token);
+	return current.get(token, options);
 }
 
 export function runInInjectionContext<T>(injector: Injector, fn: () => T): T {

lib/common/di/injector.ts

@@ -6,6 +6,18 @@ import type { Provider, ProviderToken, Type } from "./providers";
 
 type TokenKey = string | Function;
 
+export interface InjectOptions {
+	/** Resolve to null instead of throwing when the token is not registered. */
+	optional?: boolean;
+	/** Resolve at this injector's level only — no parent fallthrough. */
+	self?: boolean;
+	/**
+	 * Start resolution at the parent — escapes a child scope's shadowing
+	 * entry (e.g. a hook payload key that collides with a service name).
+	 */
+	skipSelf?: boolean;
+}
+
 type ProviderKind = "value" | "class" | "factory" | "lazyClass" | "legacyClass";
 
 interface IProviderRecord {
@@ -56,10 +68,41 @@ export class Injector {
 	 */
 	// T defaults to any so string tokens (which give inference no source and
 	// would otherwise land on unknown) stay ergonomic during the migration.
+	public get<T = any>(token: ProviderToken<T>): T;
+	public get<T = any>(
+		token: ProviderToken<T>,
+		options: InjectOptions & { optional: true },
+	): T | null;
+	public get<T = any>(token: ProviderToken<T>, options: InjectOptions): T;
 	public get<T = any>(
 		token: ProviderToken<T>,
+		options?: InjectOptions,
+	): T | null {
+		if (options && options.self && options.skipSelf) {
+			throw new Error("inject options cannot combine self and skipSelf");
+		}
+		token = resolveForwardRef(token);
+		const found = this.findRecord(token, options);
+		if (!found) {
+			if (options && options.optional) {
+				return null;
+			}
+			throw new Error("unable to resolve " + displayNameOf(token));
+		}
+		return found.owner.instantiate(found.record);
+	}
+
+	/**
+	 * The legacy facade's channel for Yok's `resolve(name, bag)` sites: the
+	 * bag applies to the construction this call itself triggers, with raw
+	 * own-key semantics, and never propagates to nested resolutions. Not part
+	 * of the public API — new code passes per-call providers to
+	 * createInstance instead.
+	 */
+	protected getWithLegacyArguments(
+		token: ProviderToken,
 		ctorArguments?: { [key: string]: any },
-	): T {
+	): any {
 		token = resolveForwardRef(token);
 		const found = this.findRecord(token);
 		if (!found) {
@@ -237,12 +280,20 @@ export class Injector {
 		return name !== undefined ? this.providers.get(name) : undefined;
 	}
 
+	// self/skipSelf apply to the entry level only: the parent walk below is
+	// always an ordinary full lookup from that injector on.
 	private findRecord(
 		token: ProviderToken,
+		options?: InjectOptions,
 	): { record: IProviderRecord; owner: Injector } | undefined {
-		const local = this.findRecordLocal(token);
-		if (local) {
-			return { record: local, owner: this };
+		if (!options || !options.skipSelf) {
+			const local = this.findRecordLocal(token);
+			if (local) {
+				return { record: local, owner: this };
+			}
+			if (options && options.self) {
+				return undefined;
+			}
 		}
 		return this.parent ? this.parent.findRecord(token) : undefined;
 	}

lib/common/yok.ts

@@ -505,7 +505,7 @@ export class Yok extends Injector implements IInjector {
 			// track these instances for disposal either.
 			return this.createInstance(<Function>param, [], ctorArguments);
 		}
-		return this.get(<string>param, ctorArguments);
+		return this.getWithLegacyArguments(<string>param, ctorArguments);
 	}
 
 	/* Regex to match dynamic calls in the following format:

lib/contracts/index.ts

@@ -14,6 +14,7 @@ export type { IContractOptions } from "../common/di/contract";
 export { inject, runInInjectionContext } from "../common/di/inject";
 export { forwardRef, resolveForwardRef } from "../common/di/forward-ref";
 export { Injector } from "../common/di/injector";
+export type { InjectOptions } from "../common/di/injector";
 export { provide, provideLazy } from "../common/di/providers";
 export type {
 	Provider,

test/di.ts

@@ -187,6 +187,66 @@ describe("di: forwardRef", () => {
 	});
 });
 
+describe("di: inject options", () => {
+	it("optional resolves to null for an unknown token, and normally for a known one", () => {
+		const injector = new Injector([provide(Greeter, GreeterImpl)]);
+
+		assert.isNull(injector.get("nothing-here", { optional: true }));
+		assert.instanceOf(injector.get(Greeter, { optional: true }), GreeterImpl);
+
+		runInInjectionContext(injector, () => {
+			assert.isNull(inject("nothing-here", { optional: true }));
+		});
+	});
+
+	it("optional does not swallow a found-but-misconfigured record", () => {
+		const injector = new Injector([
+			{ provide: "brokenLiteral", useValue: {}, shared: false },
+		]);
+
+		assert.throws(
+			() => injector.get("brokenLiteral", { optional: true }),
+			/no resolver registered/,
+		);
+	});
+
+	it("skipSelf escapes a child scope's shadowing entry", () => {
+		const root = new Injector([
+			{ provide: "logger", useValue: { from: "root" } },
+		]);
+		const child = root.createChild([
+			{ provide: "logger", useValue: { from: "payload" } },
+		]);
+
+		assert.equal(child.get<any>("logger").from, "payload");
+		assert.equal(child.get<any>("logger", { skipSelf: true }).from, "root");
+		// On the root there is no parent to skip to.
+		assert.isNull(root.get("logger", { skipSelf: true, optional: true }));
+	});
+
+	it("self refuses parent fallthrough", () => {
+		const root = new Injector([{ provide: "rootOnly", useValue: { tag: 1 } }]);
+		const child = root.createChild([
+			{ provide: "childOnly", useValue: { tag: 2 } },
+		]);
+
+		assert.equal(child.get<any>("childOnly", { self: true }).tag, 2);
+		assert.throws(
+			() => child.get("rootOnly", { self: true }),
+			/unable to resolve/,
+		);
+		assert.isNull(child.get("rootOnly", { self: true, optional: true }));
+	});
+
+	it("rejects combining self and skipSelf", () => {
+		const injector = new Injector();
+		assert.throws(
+			() => injector.get("anything", { self: true, skipSelf: true }),
+			/cannot combine self and skipSelf/,
+		);
+	});
+});
+
 describe("di: cycles", () => {
 	it("reports the full resolution path", () => {
 		class CycleA {