feat(di): add InjectionToken for non-class dependencies

@contract covers services, which have an abstract class to decorate.
Registrations whose value is a module namespace object or a plain value
have nothing to decorate, so they could not be given a typed token at
all.

InjectionToken's description doubles as the legacy registry name, so a
token is a typed alias over an existing registration: resolution is
token identity first, then the name, per injector level. Names are
minted in the registry @contract already uses, so the two kinds cannot
claim the same name.

Mints XCODE and PBXPROJ_DOM_XCODE over the existing lib/node/
registrations; the injection sites are not migrated yet.

Author: edusperoni

dependency-injection.md

@@ -63,6 +63,45 @@ Rules:
 - Implementations do not become tokens by extending or implementing a contract;
   only the decorated class itself is a token.
 
+Tokens for non-classes: `InjectionToken`
+----------------------------------------
+
+Some registrations have no class to decorate — an imported module namespace, a
+plain value, a function. `InjectionToken` is the typed key for those:
+
+```ts
+import { InjectionToken, inject } from "nativescript/contracts";
+
+export const XCODE = new InjectionToken<typeof import("nativescript-dev-xcode")>(
+	"xcode",
+);
+
+class ProjectPatcher {
+	private xcode = inject(XCODE); // typeof import("nativescript-dev-xcode")
+}
+```
+
+The description **is** the registry name, exactly as a contract's name is, so a
+token is a typed alias onto an existing registration and nothing has to change
+where the value is registered — `injector.register("xcode", xcode)` keeps
+serving `inject(XCODE)`. A leading `$` in the description is stripped.
+
+Names are minted in the same registry `@Contract` uses, so a token and a
+contract cannot claim the same name: the second one **throws at load time**,
+rather than silently aliasing one registration under two tokens.
+
+Tokens are used anywhere a contract class is — `inject()`, `get()`, `provide()`
+and the provider literals:
+
+```ts
+{ provide: XCODE, useValue: xcode }
+{ provide: XCODE, useFactory: () => require("nativescript-dev-xcode") }
+```
+
+Prefer a `@Contract` class when the dependency is a service: it also carries
+the service's shape. Reach for `InjectionToken` only when there is nothing to
+decorate.
+
 Resolving: `inject()` and `Injector`
 ------------------------------------
 
@@ -90,10 +129,10 @@ class EnvironmentChecker {
 }
 ```
 
-`Injector.get()` accepts a contract class, a string name, or a `$`-prefixed
-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.
+`Injector.get()` accepts a contract class, an `InjectionToken`, a string name,
+or a `$`-prefixed string name — all of them return the same instance. The
+string forms exist for interoperability with the legacy registry; use the token
+whenever one exists.
 
 Both `inject()` and `get()` take Angular-shaped options as their second
 argument:
@@ -155,7 +194,8 @@ instance. Transient instances are still retained by the container so
 String keys are accepted anywhere a token is (`{ provide: "logger", useValue }`)
 — that is how the legacy facade registers, and how per-call overrides address
 not-yet-migrated dependencies. New registrations should mint a `@Contract`
-token instead of a new string name.
+class, or an `InjectionToken` when there is no class to decorate, instead of a
+new string name.
 
 For per-call construction with overrides (a fresh instance of a class with some
 dependencies replaced), use `createInstance`:
@@ -173,16 +213,17 @@ owns them and never see the per-call providers.
 Resolution semantics
 --------------------
 
-- Lookup is **class object first, token name on a miss**, checked per injector
-  level before delegating to the parent. Both keys index the same provider
-  record, so re-registering a service by its string name (as plugins are
-  documented to do with `$logger`) stays visible to `inject(Logger)` consumers.
+- Lookup is **token identity first, token name on a miss**, checked per
+  injector level before delegating to the parent. Both keys index the same
+  provider record, so re-registering a service by its string name (as plugins
+  are documented to do with `$logger`) stays visible to `inject(Logger)`
+  consumers. This holds for `@Contract` classes and `InjectionToken`s alike.
 - A leading `$` is stripped from string tokens: `get("$fs")` and `get("fs")`
   are the same registration.
-- The name fallback also makes **duplicated contract copies interchangeable**:
-  if an extension's dependency tree carries its own copy of a contract class,
-  that copy resolves to the same provider by name. "Works locally, breaks when
-  installed" is not a failure mode of this design.
+- The name fallback also makes **duplicated token copies interchangeable**: if
+  an extension's dependency tree carries its own copy of a contract class or
+  injection token, that copy resolves to the same provider by name. "Works
+  locally, breaks when installed" is not a failure mode of this design.
 - Cyclic dependencies fail with the full resolution path
   (`Cyclic dependency detected on dependency 'a'. Resolution path: a -> b -> a`).
 
@@ -284,6 +325,13 @@ contract and every existing caller sees it.
 | `Prompter` | `prompter` |
 | `TempService` | `tempService` |
 
+And the injection tokens, for registrations that are not classes:
+
+| Token | Legacy name | Value |
+|---|---|---|
+| `XCODE` | `xcode` | the `nativescript-dev-xcode` module |
+| `PBXPROJ_DOM_XCODE` | `pbxprojDomXcode` | the `pbxproj-dom/xcode` module |
+
 Related guides
 --------------
 

lib/common/di/contract.ts

@@ -19,7 +19,30 @@ export interface IContractOptions {
 // 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>();
+const mintedNames = new Map<string, object>();
+
+function describeOwner(owner: object): string {
+	if (typeof owner === "function") {
+		return `contract '${owner.name || "<anonymous>"}'`;
+	}
+	return "an injection token";
+}
+
+/**
+ * Claims a token name for `owner`. Both `@Contract` and `InjectionToken` mint
+ * here so the two kinds share one namespace: a contract and a token that claim
+ * the same name would be two tokens silently aliasing one registration.
+ */
+export function mintTokenName(name: string, owner: object): void {
+	const existing = mintedNames.get(name);
+	if (existing && existing !== owner) {
+		throw new Error(
+			`Token name '${name}' is already used by ${describeOwner(existing)}. ` +
+				`Token names must be unique — a duplicate silently aliases two tokens.`,
+		);
+	}
+	mintedNames.set(name, owner);
+}
 
 /**
  * Marks an abstract class as a DI token. The decorated class resolves by
@@ -31,15 +54,7 @@ export function Contract(
 ): (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);
+		mintTokenName(name, target);
 		Object.defineProperty(target, CONTRACT_NAME, {
 			value: name,
 			writable: false,
@@ -64,7 +79,10 @@ export function getContractName(token: any): string | undefined {
 	return undefined;
 }
 
-/** Test seam — the duplicate-name registry otherwise persists per process. */
+/**
+ * Test seam — the duplicate-name registry (contracts and injection tokens
+ * alike) otherwise persists per process.
+ */
 export function clearMintedContractNames(): void {
 	mintedNames.clear();
 }

lib/common/di/index.ts

@@ -9,6 +9,11 @@ export {
 	clearMintedContractNames,
 } from "./contract";
 export type { IContractOptions } from "./contract";
+export {
+	InjectionToken,
+	getInjectionTokenName,
+	INJECTION_TOKEN_NAME,
+} from "./injection-token";
 export { provide, provideLazy } from "./providers";
 export type {
 	Provider,

lib/common/di/injection-token.ts

@@ -0,0 +1,72 @@
+import { mintTokenName } from "./contract";
+
+/**
+ * Mirrors CONTRACT_NAME's `Symbol.for` reasoning: an extension's duplicated
+ * copy of this module must read the marker off tokens minted by the running
+ * copy, which a unique `Symbol()` would hide.
+ */
+export const INJECTION_TOKEN_NAME = Symbol.for(
+	"nativescript:di:injectionTokenName",
+);
+
+/**
+ * A typed DI token for a dependency that is not a class — an imported module
+ * namespace, a plain value, a function. `@Contract` covers services, which
+ * have an abstract class to decorate; this covers everything else.
+ *
+ * The description doubles as the legacy registry name, exactly as a contract's
+ * name does, so a token is a typed alias over the registration it names:
+ *
+ * ```ts
+ * const XCODE = new InjectionToken<typeof import("nativescript-dev-xcode")>(
+ * 	"xcode",
+ * );
+ * inject(XCODE); // finds register("xcode", …) untouched
+ * ```
+ */
+export class InjectionToken<T = any> {
+	/**
+	 * Phantom, never assigned: with no member mentioning `T` the type parameter
+	 * is erased and every token becomes assignable to every other one.
+	 */
+	declare private readonly resolvedType: T;
+
+	/**
+	 * @param description Canonical registry name. A leading `$` is stripped, so
+	 * the token always keys the same record the string spellings do.
+	 */
+	constructor(description: string) {
+		const name = description[0] === "$" ? description.slice(1) : description;
+		mintTokenName(name, this);
+		Object.defineProperty(this, INJECTION_TOKEN_NAME, {
+			value: name,
+			writable: false,
+			enumerable: false,
+			configurable: false,
+		});
+	}
+
+	public get description(): string {
+		return (<any>this)[INJECTION_TOKEN_NAME];
+	}
+
+	public toString(): string {
+		return `InjectionToken(${this.description})`;
+	}
+}
+
+/**
+ * Reads the constructor-set name. Own-property check, and by marker rather
+ * than `instanceof`, so tokens minted by a duplicated copy of this module are
+ * still recognized.
+ */
+export function getInjectionTokenName(token: any): string | undefined {
+	if (
+		token !== null &&
+		typeof token === "object" &&
+		Object.prototype.hasOwnProperty.call(token, INJECTION_TOKEN_NAME)
+	) {
+		return token[INJECTION_TOKEN_NAME];
+	}
+	return undefined;
+}

lib/common/di/injector.ts

@@ -2,14 +2,15 @@ import { annotate } from "../helpers";
 import { getContractName } from "./contract";
 import { resolveForwardRef } from "./forward-ref";
 import { runInInjectionContext } from "./inject";
+import { getInjectionTokenName } from "./injection-token";
 import type {
 	InternalProvider,
 	Provider,
 	ProviderToken,
 	Type,
 } from "./providers";
 
-type TokenKey = string | Function;
+type TokenKey = string | object;
 
 export interface InjectOptions {
 	/** Resolve to null instead of throwing when the token is not registered. */
@@ -241,7 +242,7 @@ export class Injector {
 		if (typeof token === "string") {
 			return [normalizeName(token)];
 		}
-		const name = getContractName(token);
+		const name = tokenNameOf(token);
 		return name !== undefined ? [token, name] : [token];
 	}
 
@@ -294,7 +295,7 @@ export class Injector {
 		if (direct) {
 			return direct;
 		}
-		const name = getContractName(token);
+		const name = tokenNameOf(token);
 		return name !== undefined ? this.providers.get(name) : undefined;
 	}
 
@@ -412,9 +413,23 @@ function normalizeName(name: string): string {
 	return name[0] === "$" ? name.slice(1) : name;
 }
 
+/** The name a non-string token aliases in the legacy registry, if it has one. */
+function tokenNameOf(token: ProviderToken): string | undefined {
+	const injectionTokenName = getInjectionTokenName(token);
+	return injectionTokenName !== undefined
+		? injectionTokenName
+		: getContractName(token);
+}
+
 function displayNameOf(token: ProviderToken): string {
 	if (typeof token === "string") {
 		return normalizeName(token);
 	}
-	return getContractName(token) || token.name || "<anonymous class>";
+	const injectionTokenName = getInjectionTokenName(token);
+	if (injectionTokenName !== undefined) {
+		return `InjectionToken(${injectionTokenName})`;
+	}
+	return (
+		getContractName(token) || (<Function>token).name || "<anonymous class>"
+	);
 }

lib/common/di/providers.ts

@@ -1,7 +1,10 @@
+import type { InjectionToken } from "./injection-token";
+
 export type Type<T> = new (...args: any[]) => T;
 export type AbstractType<T> = abstract new (...args: any[]) => T;
 
-export type ProviderToken<T = any> = string | Type<T> | AbstractType<T>;
+export type ProviderToken<T = any> =
+	string | Type<T> | AbstractType<T> | InjectionToken<T>;
 
 interface IBaseProvider<T> {
 	provide: ProviderToken<T>;
@@ -57,11 +60,11 @@ export type InternalProvider<T = any> = Provider<T> | ILazyRequireProvider;
 
 /** Enforces at compile time that the implementation satisfies the token. */
 export const provide = <T>(
-	token: AbstractType<T> | string,
+	token: AbstractType<T> | InjectionToken<T> | string,
 	impl: Type<T>,
 ): Provider<T> => ({ provide: token, useClass: impl });
 
 export const provideLazy = <T>(
-	token: AbstractType<T> | string,
+	token: AbstractType<T> | InjectionToken<T> | string,
 	load: () => Type<T>,
 ): Provider<T> => ({ provide: token, useLazyClass: load });

lib/contracts/index.ts

@@ -11,6 +11,11 @@ export {
 	CONTRACT_NAME,
 } from "../common/di/contract";
 export type { IContractOptions } from "../common/di/contract";
+export {
+	InjectionToken,
+	getInjectionTokenName,
+	INJECTION_TOKEN_NAME,
+} from "../common/di/injection-token";
 export { inject, runInInjectionContext } from "../common/di/inject";
 export { forwardRef, resolveForwardRef } from "../common/di/forward-ref";
 export { Injector } from "../common/di/injector";
@@ -38,6 +43,9 @@ export { ProjectNameService } from "./project-name-service";
 export { Prompter } from "./prompter";
 export { TempService } from "./temp-service";
 
+export { PBXPROJ_DOM_XCODE } from "./pbxproj-dom-xcode";
+export { XCODE } from "./xcode";
+
 export {
 	defineCommand,
 	isCommandDefinition,

lib/contracts/pbxproj-dom-xcode.ts

@@ -0,0 +1,12 @@
+import { InjectionToken } from "../common/di/injection-token";
+// Type-only: this entry point must stay side-effect-free, and the token is an
+// alias over the registration in lib/node/pbxproj-dom-xcode.ts, not a second
+// loader.
+import type * as pbxprojDomXcode from "pbxproj-dom/xcode";
+
+/**
+ * DOM-style reader/writer for Xcode project files.
+ */
+export const PBXPROJ_DOM_XCODE = new InjectionToken<typeof pbxprojDomXcode>(
+	"pbxprojDomXcode",
+);

lib/contracts/xcode.ts

@@ -0,0 +1,9 @@
+import { InjectionToken } from "../common/di/injection-token";
+// Type-only: this entry point must stay side-effect-free, and the token is an
+// alias over the registration in lib/node/xcode.ts, not a second loader.
+import type * as xcode from "nativescript-dev-xcode";
+
+/**
+ * Reads and edits `.pbxproj` files.
+ */
+export const XCODE = new InjectionToken<typeof xcode>("xcode");