refactor(yok)!: the facade extends Injector instead of wrapping one

Yok is now an Injector - class Yok extends Injector - so the new API
works on the facade directly (get, register with Providers, createChild,
runInInjectionContext($injector, ...)) and inject(Injector) inside
legacy-constructed classes returns the facade itself instead of a
second, inner container identity. The di bridge is gone. register()
dispatches by argument shape: a string first argument is the legacy
name-based form, anything else is a Provider.

IInjector now extends the Injector class type, which constrains
implementers to the real class hierarchy (Yok and its subclasses) -
intentional, since the interface only ever described Yok.

Author: edusperoni

dependency-injection.md

@@ -195,11 +195,13 @@ and resolve late (see above).
 Working alongside the legacy `$injector`
 ----------------------------------------
 
-The `Yok` facade (`global.$injector`) delegates to the token-based container,
-exposed as `$injector.di`. Everything is one registry:
+The `Yok` facade (`global.$injector`) IS an `Injector` — the class extends the
+token-based container — so the new API works on it directly:
 
 ```ts
-$injector.resolve("doctorService") === $injector.di.get(DoctorService); // true
+$injector.resolve("doctorService") === $injector.get(DoctorService); // true
+$injector.register(provide(DoctorService, DoctorServiceImpl));
+runInInjectionContext($injector, () => inject(DoctorService));
 ```
 
 - Legacy string names are permanent: a contract's token name is its interop
@@ -244,8 +246,8 @@ The first tranche, growing as services migrate:
 Legacy → new quick reference
 ----------------------------
 
-`di` below is the token-based container backing the facade (`$injector.di`),
-or any `Injector` you hold directly.
+`di` below is any `Injector` you hold — including `$injector` itself, which
+extends `Injector`.
 
 | Legacy (`$injector`) | New |
 |---|---|

lib/common/definitions/yok.d.ts

@@ -1,30 +1,22 @@
-import { IDisposable, IDictionary } from "../declarations";
+import { IDictionary } from "../declarations";
 import { ICommand } from "./commands";
 import { IKeyCommand, IValidKeyName } from "./key-commands";
 import { Injector } from "../di/injector";
+import { Provider } from "../di/providers";
 
 /**
- * The legacy injector facade surface. Every member is individually
- * @deprecated in favor of the token-based container in lib/common/di;
- * the interface itself survives until the hook/extension deprecation
- * completes.
+ * The legacy injector facade surface. It extends the token-based `Injector` —
+ * the facade IS an injector — and adds the legacy subsystems, whose members
+ * are individually @deprecated. Only the `Yok` class hierarchy implements
+ * this; the interface survives until the hook/extension deprecation completes.
  */
-interface IInjector extends IDisposable {
+interface IInjector extends Injector {
 	/**
-	 * The token-based container backing this facade — the bridge to the
-	 * new-style API. Registrations and lookups by token go here; code already
-	 * running in an injection context should prefer inject(Injector).
-	 */
-	readonly di: Injector;
-
-	/**
-	 * @deprecated Use provideLazy() from lib/common/di — the same deferred
-	 * loading, token-based.
+	 * @deprecated Use provideLazy() — the same deferred loading, token-based.
 	 */
 	require(name: string, file: string): void;
 	/**
-	 * @deprecated Use provideLazy() from lib/common/di — the same deferred
-	 * loading, token-based.
+	 * @deprecated Use provideLazy() — the same deferred loading, token-based.
 	 */
 	require(names: string[], file: string): void;
 	/**
@@ -52,23 +44,21 @@ interface IInjector extends IDisposable {
 	/**
 	 * Resolves an implementation by constructor function.
 	 * The injector will create new instances for every call.
-	 * @deprecated Use Injector.createInstance from lib/common/di.
+	 * @deprecated Use Injector.createInstance.
 	 */
 	resolve(ctor: Function, ctorArguments?: { [key: string]: any }): any;
 	/**
-	 * @deprecated Use Injector.createInstance from lib/common/di.
+	 * @deprecated Use Injector.createInstance.
 	 */
 	resolve<T>(ctor: Function, ctorArguments?: { [key: string]: any }): T;
 	/**
 	 * Resolves an implementation by name.
 	 * The injector will create only one instance per name and return the same instance on subsequent calls.
-	 * @deprecated Use inject(Token) in an injection context, or Injector.get
-	 * from lib/common/di.
+	 * @deprecated Use inject(Token) in an injection context, or Injector.get.
 	 */
 	resolve(name: string, ctorArguments?: IDictionary<any>): any;
 	/**
-	 * @deprecated Use inject(Token) in an injection context, or Injector.get
-	 * from lib/common/di.
+	 * @deprecated Use inject(Token) in an injection context, or Injector.get.
 	 */
 	resolve<T>(name: string, ctorArguments?: IDictionary<any>): T;
 
@@ -81,10 +71,11 @@ interface IInjector extends IDisposable {
 	 */
 	resolveKeyCommand(key: string): IKeyCommand;
 	/**
-	 * @deprecated Use provide() / Injector.register from lib/common/di; a
-	 * contract's token name keeps string spellings resolvable.
+	 * @deprecated Legacy name-based registration. Use the Provider overload or
+	 * provide(); a contract's token name keeps string spellings resolvable.
 	 */
 	register(name: string, resolver: any, shared?: boolean): void;
+	register(providers: Provider | Provider[]): void;
 	/**
 	 * @deprecated Slated for replacement by defineCommand and manifest-declared
 	 * commands.

lib/common/yok.ts

@@ -9,6 +9,7 @@ import { IInjector } from "./definitions/yok";
 import { ICommandArgument, ICommand } from "./definitions/commands";
 import { IKeyCommand, IValidKeyName } from "./definitions/key-commands";
 import { Injector } from "./di/injector";
+import type { Provider } from "./di/providers";
 
 /**
  * The legacy global facade binding. New code should obtain the container via
@@ -47,22 +48,20 @@ export interface IDependency {
 }
 
 /**
- * The Yok facade: the externally reachable injector surface (every IInjector
- * member, the global $injector, subclassability) kept intact while storage and
- * resolution live in the token-based `Injector` (lib/common/di). Command
- * routing, the key-command namespace, and the public-API builder still live
- * here — they are separate subsystems that only share the container.
+ * The Yok facade IS the token-based `Injector` — it extends it — plus the
+ * legacy surface: command routing, the key-command namespace, the module
+ * loader, and the public-API builder. Those subsystems historically shared
+ * the container object and migrate out separately; until then they live here,
+ * individually marked @deprecated.
  */
-export class Yok implements IInjector {
+export class Yok extends Injector implements IInjector {
 	/**
 	 * @deprecated Escape hatch of the legacy require-time module map.
 	 */
 	public overrideAlreadyRequiredModule: boolean = false;
 
-	/** The token-based container backing this facade. */
-	private container = new Injector();
-
 	constructor() {
+		super();
 		this.register("injector", this);
 	}
 
@@ -76,11 +75,6 @@ export class Yok implements IInjector {
 	private KEY_COMMANDS_NAMESPACE: string = "keyCommands";
 	private hierarchicalCommands: IDictionary<string[]> = {};
 
-	/** New-style access to the backing container, for token-based registration. */
-	public get di(): Injector {
-		return this.container;
-	}
-
 	/**
 	 * @deprecated Path-based command registration; slated for replacement by
 	 * manifest-declared commands.
@@ -94,7 +88,7 @@ export class Yok implements IInjector {
 			if (commands.length > 1) {
 				if (
 					_.startsWith(commands[1], "*") &&
-					this.container.has(this.createCommandName(commands[0])) &&
+					this.has(this.createCommandName(commands[0])) &&
 					!this.synthesizedParents.has(commands[0])
 				) {
 					throw new Error(
@@ -115,7 +109,7 @@ export class Yok implements IInjector {
 
 			if (
 				commands.length > 1 &&
-				!this.container.has(this.createCommandName(commands[0]))
+				!this.has(this.createCommandName(commands[0]))
 			) {
 				this.require(this.createCommandName(commands[0]), file);
 				if (commands[1] && !commandName.match(/\|\*/)) {
@@ -191,7 +185,7 @@ export class Yok implements IInjector {
 	}
 
 	private resolveInstance(name: string): any {
-		let classInstance = this.container.peek(name);
+		let classInstance = this.peek(name);
 		if (!classInstance) {
 			classInstance = this.resolve(name);
 		}
@@ -207,11 +201,11 @@ export class Yok implements IInjector {
 			? relativePath
 			: file;
 
-		if (!this.container.has(name) || this.overrideAlreadyRequiredModule) {
+		if (!this.has(name) || this.overrideAlreadyRequiredModule) {
 			// Yok replaced the whole record on an allowed re-require, dropping any
 			// resolver and cached instances with it — preserved via remove().
-			this.container.remove(name);
-			this.container.register({
+			this.remove(name);
+			this.register({
 				provide: name,
 				useLazyRequire: () => require(dependencyPath),
 			});
@@ -427,22 +421,33 @@ export class Yok implements IInjector {
 	}
 
 	/**
-	 * @deprecated Use provide() / Injector.register from lib/common/di (via
-	 * `Yok.di`); a contract's token name keeps string spellings resolvable.
+	 * @deprecated Legacy name-based registration. Use a Provider (the overload
+	 * below) or provide(); a contract's token name keeps string spellings
+	 * resolvable.
 	 */
-	public register(name: string, resolver: any, shared?: boolean): void {
-		shared = shared === undefined ? true : shared;
+	public register(name: string, resolver: any, shared?: boolean): void;
+	public register(providers: Provider | Provider[]): void;
+	public register(
+		nameOrProviders: string | Provider | Provider[],
+		resolver?: any,
+		shared?: boolean,
+	): void {
+		if (typeof nameOrProviders !== "string") {
+			super.register(nameOrProviders);
+			return;
+		}
 
+		shared = shared === undefined ? true : shared;
 		if (_.isFunction(resolver)) {
 			// Classes and factory functions alike: the legacy provider kind
 			// annotate()s the resolver and calls or news it by casing.
-			this.container.register({
-				provide: name,
+			super.register({
+				provide: nameOrProviders,
 				useLegacyClass: resolver,
 				shared,
 			});
 		} else {
-			this.container.register({ provide: name, useValue: resolver, shared });
+			super.register({ provide: nameOrProviders, useValue: resolver, shared });
 		}
 	}
 
@@ -452,7 +457,7 @@ export class Yok implements IInjector {
 	public resolveCommand(name: string): ICommand {
 		let command: ICommand;
 		const commandModuleName = this.createCommandName(name);
-		if (!this.container.has(commandModuleName)) {
+		if (!this.has(commandModuleName)) {
 			return null;
 		}
 		command = this.resolve(commandModuleName);
@@ -466,7 +471,7 @@ export class Yok implements IInjector {
 	public resolveKeyCommand(name: string): IKeyCommand {
 		let command: IKeyCommand;
 		const commandModuleName = this.createKeyCommandName(name);
-		if (!this.container.has(commandModuleName)) {
+		if (!this.has(commandModuleName)) {
 			return null;
 		}
 
@@ -483,9 +488,9 @@ export class Yok implements IInjector {
 		if (_.isFunction(param)) {
 			// By-class resolution is transient and never retained — Yok did not
 			// track these instances for disposal either.
-			return this.container.createInstance(<Function>param, [], ctorArguments);
+			return this.createInstance(<Function>param, [], ctorArguments);
 		}
-		return this.container.get(<string>param, ctorArguments);
+		return this.get(<string>param, ctorArguments);
 	}
 
 	/* Regex to match dynamic calls in the following format:
@@ -535,7 +540,7 @@ export class Yok implements IInjector {
 	 * and help, so the `|` encoding is user-visible.
 	 */
 	public getRegisteredCommandsNames(includeDev: boolean): string[] {
-		const commandsNames = this.container.getRegisteredNames(
+		const commandsNames = this.getRegisteredNames(
 			`${this.COMMANDS_NAMESPACE}.`,
 		);
 		let commands = _.map(commandsNames, (commandName: string) =>
@@ -551,7 +556,7 @@ export class Yok implements IInjector {
 	 * @deprecated Legacy command-registry enumeration.
 	 */
 	public getRegisteredKeyCommandsNames(): string[] {
-		const commandsNames = this.container.getRegisteredNames(
+		const commandsNames = this.getRegisteredNames(
 			`${this.KEY_COMMANDS_NAMESPACE}.`,
 		);
 		const commands = _.map(commandsNames, (commandName: string) =>
@@ -579,8 +584,8 @@ export class Yok implements IInjector {
 	 * @deprecated Delegates to Injector.dispose (reverse instantiation order);
 	 * new code disposes the di container directly.
 	 */
-	public dispose(): void {
-		this.container.dispose([this]);
+	public dispose(exclude: any[] = []): void {
+		super.dispose([this, ...exclude]);
 	}
 }
 

test/compat/injector-facade-surface.ts

@@ -1,5 +1,6 @@
 import { assert } from "chai";
 import { Yok } from "../../lib/common/yok";
+import { Injector, inject, runInInjectionContext } from "../../lib/common/di";
 
 // Pins the externally reachable injector surface: every IInjector member
 // (lib/common/definitions/yok.d.ts) plus dispose, subclassability, the
@@ -65,6 +66,24 @@ describe("injector facade surface", () => {
 		}
 	});
 
+	it("IS an Injector: instanceof holds and the new API works on the facade directly", () => {
+		const inj = new Yok();
+		assert.instanceOf(inj, Injector);
+
+		// Provider-form registration dispatches to the container...
+		inj.register({ provide: "viaProvider", useValue: { tag: 1 } });
+		assert.equal(inj.get<any>("viaProvider").tag, 1);
+		// ...while string-form registration keeps legacy semantics.
+		inj.register("viaLegacy", { tag: 2 });
+		assert.equal(inj.resolve("viaLegacy").tag, 2);
+		assert.strictEqual(inj.get("viaLegacy"), inj.resolve("viaLegacy"));
+
+		// One identity: the injection context IS the facade.
+		runInInjectionContext(inj, () => {
+			assert.strictEqual(inject(Injector), inj);
+		});
+	});
+
 	it("calls lowercase/anonymous resolvers as factories instead of new-ing them", () => {
 		const inj = new Yok();
 		inj.register("factoryMade", function () {

test/compat/legacy-hooks.ts

@@ -283,7 +283,7 @@ describe("legacy hook contract", () => {
 		});
 
 		assert.strictEqual(capture.logger, testInjector.resolve("logger"));
-		assert.strictEqual(capture.container, testInjector.di);
+		assert.strictEqual(capture.container, testInjector);
 		assert.strictEqual(capture.hookArgs, payload);
 	});