clear-router 2.9.1 → 2.9.2

package/dist/core/bindings.cjs

@@ -1,54 +1,189 @@
 const require_Request = require('./Request.cjs');
 const require_Response = require('./Response.cjs');
+let node_async_hooks = require("node:async_hooks");
 
 //#region src/core/bindings.ts
 const metadataKey = Symbol.for("clear-router:binding-metadata");
 const bindings = /* @__PURE__ */ new WeakMap();
-var Container = class {
-	static registry = /* @__PURE__ */ new Map();
-	static bind(token, value) {
-		this.registry.set(token, value);
+var InjectionToken = class {
+	key;
+	constructor(description) {
+		this.description = description;
+		this.key = Symbol(description);
+	}
+	toString() {
+		return `InjectionToken(${this.description})`;
+	}
+};
+var ContainerResolutionError = class extends Error {
+	constructor(message, path) {
+		super(`${message}\nResolution path: ${path.map(describeToken).join(" -> ")}`);
+		this.path = path;
+		this.name = "ContainerResolutionError";
+	}
+};
+var Container = class Container {
+	static activeScope = new node_async_hooks.AsyncLocalStorage();
+	static containers = /* @__PURE__ */ new Set();
+	static globalContainer = new Container();
+	registry = /* @__PURE__ */ new Map();
+	instances = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	constructor(parent, context, requestScope = false) {
+		this.parent = parent;
+		this.context = context;
+		this.requestScope = requestScope;
+	}
+	static get global() {
+		return this.globalContainer;
+	}
+	static current() {
+		return this.activeScope.getStore() ?? this.globalContainer;
+	}
+	static run(container, callback) {
+		return this.activeScope.run(container, callback);
+	}
+	static create(parent = this.globalContainer) {
+		const container = new Container(parent);
+		this.containers.add(container);
+		return container;
+	}
+	createRequestScope(ctx) {
+		return new Container(this, ctx, true);
+	}
+	static bind(token, value, options) {
+		this.globalContainer.bind(token, value, options);
 	}
 	static unbind(token) {
-		this.registry.delete(token);
+		this.globalContainer.unbind(token);
 	}
 	static clear() {
-		this.registry.clear();
+		this.globalContainer.clear();
+		for (const container of this.containers) container.clear();
 	}
 	static has(token) {
-		return this.registry.has(token) || Boolean(this.findEquivalentToken(token));
+		return this.current().has(token);
 	}
 	static bindings() {
-		return Object.fromEntries(this.registry.entries());
+		return this.current().bindings();
 	}
 	static async resolve(token, ctx, autoDiscover = false) {
-		if (token === require_Request.Request) return ctx.clearRequest;
-		if (token === require_Response.Response) return ctx.clearResponse;
-		const binding = this.getBinding(token);
-		if (binding) return this.resolveBinding(binding, ctx, autoDiscover);
-		if (autoDiscover && typeof token === "function") return new token();
-	}
-	static getBinding(token) {
-		if (this.registry.has(token)) return this.registry.get(token);
+		return this.current().resolve(token, ctx, autoDiscover);
+	}
+	bind(token, value, options) {
+		this.registry.set(token, normalizeProvider(value, options));
+		this.instances.delete(token);
+	}
+	unbind(token) {
+		this.registry.delete(token);
+		this.instances.delete(token);
+	}
+	clear() {
+		this.registry.clear();
+		this.instances.clear();
+		this.pending.clear();
+	}
+	has(token) {
+		return Boolean(this.findProvider(token));
+	}
+	entries() {
+		const entries = /* @__PURE__ */ new Map();
+		for (const container of this.lineage().reverse()) for (const [token, provider] of container.registry) entries.set(token, provider);
+		return entries;
+	}
+	bindings() {
+		return Object.fromEntries(Array.from(this.entries(), ([token, provider]) => [describeToken(token), provider]));
+	}
+	async resolve(token, ctx = this.context, autoDiscover = false) {
+		return this.resolveToken(token, ctx, {
+			autoDiscover,
+			stack: []
+		});
+	}
+	async resolveOrFail(token, ctx = this.context, autoDiscover = false) {
+		const resolved = await this.resolve(token, ctx, autoDiscover);
+		if (typeof resolved === "undefined") throw new ContainerResolutionError(`Cannot resolve ${describeToken(token)}`, [token]);
+		return resolved;
+	}
+	async resolveToken(token, ctx, state) {
+		if (token === require_Request.Request) return ctx?.clearRequest;
+		if (token === require_Response.Response) return ctx?.clearResponse;
+		if (state.stack.includes(token)) throw new ContainerResolutionError(`Circular dependency detected while resolving ${describeToken(token)}`, [...state.stack, token]);
+		const nextState = {
+			...state,
+			stack: [...state.stack, token]
+		};
+		const found = this.findProvider(token);
+		if (found) return this.resolveProvider(found.token, found.provider, found.owner, ctx, nextState);
+		if (state.autoDiscover && typeof token === "function") return this.instantiate(token, void 0, ctx, nextState);
+	}
+	findProvider(token) {
+		if (this.registry.has(token)) return {
+			token,
+			provider: this.registry.get(token),
+			owner: this
+		};
 		const equivalent = this.findEquivalentToken(token);
-		return equivalent ? this.registry.get(equivalent) : void 0;
+		if (equivalent) return {
+			token: equivalent,
+			provider: this.registry.get(equivalent),
+			owner: this
+		};
+		return this.parent?.findProvider(token);
+	}
+	async resolveProvider(token, provider, owner, ctx, state) {
+		if ("useExisting" in provider) return this.resolveToken(provider.useExisting, ctx, state);
+		const cache = provider.scope === "singleton" ? owner : provider.scope === "request" ? this.findRequestScope() : void 0;
+		if (cache?.instances.has(token)) return cache.instances.get(token);
+		if (cache?.pending.has(token)) return cache.pending.get(token);
+		const create = async () => {
+			if ("useValue" in provider) return provider.useValue;
+			if ("useClass" in provider) return this.instantiate(provider.useClass, provider.dependencies, ctx, state);
+			return provider.useFactory(ctx);
+		};
+		if (!cache) return create();
+		const promise = create();
+		cache.pending.set(token, promise);
+		try {
+			const resolved = await promise;
+			if (typeof resolved !== "undefined") cache.instances.set(token, resolved);
+			return resolved;
+		} finally {
+			cache.pending.delete(token);
+		}
+	}
+	async instantiate(Type, dependencies, ctx, state) {
+		const tokens = dependencies ?? getInjectTokens(Type);
+		const args = [];
+		for (const dependency of tokens) {
+			const resolved = await this.resolveToken(dependency, ctx, state);
+			if (typeof resolved === "undefined") throw new ContainerResolutionError(`Cannot resolve ${describeToken(dependency)} required by ${describeToken(Type)}`, [...state.stack, dependency]);
+			args.push(resolved);
+		}
+		return new Type(...args);
 	}
-	static findEquivalentToken(token) {
+	findRequestScope() {
+		if (this.requestScope) return this;
+		return this.parent?.findRequestScope();
+	}
+	lineage() {
+		return [this, ...this.parent?.lineage() ?? []];
+	}
+	findEquivalentToken(token) {
+		if (typeof token !== "function") return void 0;
 		const name = token.name;
-		if (!name) return;
+		if (!name) return void 0;
 		const tokenParent = Object.getPrototypeOf(token);
 		const tokenProps = this.getComparableStaticProps(token);
 		for (const registered of this.registry.keys()) {
-			if (registered === token) continue;
-			if (registered.name !== name) continue;
+			if (typeof registered !== "function" || registered === token || registered.name !== name) continue;
 			const registeredParent = Object.getPrototypeOf(registered);
 			if (tokenParent && registeredParent && tokenParent.name !== registeredParent.name) continue;
 			const registeredProps = this.getComparableStaticProps(registered);
-			if (!this.staticPropsMatch(token, registered, tokenProps, registeredProps)) continue;
-			return registered;
+			if (this.staticPropsMatch(token, registered, tokenProps, registeredProps)) return registered;
 		}
 	}
-	static getComparableStaticProps(token) {
+	getComparableStaticProps(token) {
 		return Object.getOwnPropertyNames(token).filter((prop) => {
 			return ![
 				"length",
@@ -59,23 +194,38 @@ var Container = class {
 			].includes(prop);
 		});
 	}
-	static staticPropsMatch(token, registered, tokenProps, registeredProps) {
+	staticPropsMatch(token, registered, tokenProps, registeredProps) {
 		if (tokenProps.length !== registeredProps.length) return false;
-		for (const prop of tokenProps) {
-			if (!registeredProps.includes(prop)) return false;
-			if (Reflect.get(token, prop) !== Reflect.get(registered, prop)) return false;
-		}
+		for (const prop of tokenProps) if (!registeredProps.includes(prop) || Reflect.get(token, prop) !== Reflect.get(registered, prop)) return false;
 		return true;
 	}
-	static async resolveBinding(binding, ctx, autoDiscover) {
-		if (!binding) return void 0;
-		if (typeof binding !== "function") return binding;
-		if (isClass(binding)) return new binding();
-		const resolved = await binding(ctx);
-		if (typeof resolved === "function" && autoDiscover && isClass(resolved)) return new resolved();
-		return resolved;
-	}
 };
+function normalizeProvider(value, options) {
+	if (isProvider(value)) return {
+		scope: "transient",
+		...value
+	};
+	if (isClass(value)) return {
+		useClass: value,
+		scope: options?.scope ?? "transient"
+	};
+	if (typeof value === "function") return {
+		useFactory: value,
+		scope: options?.scope ?? "transient"
+	};
+	return { useValue: value };
+}
+function isProvider(value) {
+	return Boolean(value && typeof value === "object" && ("useValue" in value || "useClass" in value || "useFactory" in value || "useExisting" in value));
+}
+function getInjectTokens(Type) {
+	return Type.inject ?? getDesignParamTypes(Type);
+}
+function describeToken(token) {
+	if (token instanceof InjectionToken) return token.toString();
+	if (typeof token === "symbol") return token.description ?? token.toString();
+	return token.name || "<anonymous class>";
+}
 function Bind(...tokens) {
 	return ((target, propertyKeyOrContext) => {
 		if (isStandardClassContext(propertyKeyOrContext)) {
@@ -103,6 +253,9 @@ function Bind(...tokens) {
 		});
 	});
 }
+function getMetadataKey() {
+	return metadataKey;
+}
 function getStandardMetadata(metadata, propertyKey) {
 	const store = metadata && metadata[metadataKey];
 	if (!store) return void 0;
@@ -153,7 +306,13 @@ function isClass(value) {
 //#endregion
 exports.Bind = Bind;
 exports.Container = Container;
+exports.ContainerResolutionError = ContainerResolutionError;
+exports.InjectionToken = InjectionToken;
+exports.getBindingMetadata = getBindingMetadata;
 exports.getBindingMetadataFromTargets = getBindingMetadataFromTargets;
 exports.getDesignParamTypes = getDesignParamTypes;
+exports.getMetadataKey = getMetadataKey;
 exports.getStandardMetadata = getStandardMetadata;
-exports.isClass = isClass;
+exports.isClass = isClass;
+exports.setBindingMetadata = setBindingMetadata;
+exports.setStandardMetadata = setStandardMetadata;

package/dist/core/bindings.d.cts

@@ -1,25 +1,96 @@
 //#region src/core/bindings.d.ts
-type BindToken<T = any> = abstract new (...args: any[]) => T;
+type BindClass<T = any> = abstract new (...args: any[]) => T;
+type BindToken<T = any> = BindClass<T> | InjectionToken<T> | symbol;
 type BindFactory<T = any> = (ctx: any) => T | Promise<T>;
-type BindValue<T = any> = T | BindFactory<T> | BindToken<T>;
+type BindingScope = 'singleton' | 'request' | 'transient';
+type BindingOptions = {
+  scope?: BindingScope;
+};
+type ValueProvider<T = any> = {
+  useValue: T;
+};
+type ClassProvider<T = any> = BindingOptions & {
+  useClass: BindClass<T>;
+  dependencies?: BindToken[];
+};
+type FactoryProvider<T = any> = BindingOptions & {
+  useFactory: BindFactory<T>;
+};
+type ExistingProvider<T = any> = {
+  useExisting: BindToken<T>;
+};
+type BindProvider<T = any> = ValueProvider<T> | ClassProvider<T> | FactoryProvider<T> | ExistingProvider<T>;
+type BindValue<T = any> = T | BindFactory<T> | BindClass<T> | BindProvider<T>;
 type BindDecorator = MethodDecorator & ClassDecorator & {
   <This, Value extends (this: This, ...args: any[]) => any>(value: Value, context: ClassMethodDecoratorContext<This, Value>): void | Value;
   <Value extends abstract new (...args: any[]) => any>(value: Value, context: ClassDecoratorContext<Value>): void | Value;
 };
+type BindingMetadata = {
+  tokens?: BindToken[];
+  method?: PropertyKey;
+};
+declare class InjectionToken<T = any> {
+  readonly description: string;
+  readonly __type?: T;
+  readonly key: symbol;
+  constructor(description: string);
+  toString(): string;
+}
+declare class ContainerResolutionError extends Error {
+  readonly path: BindToken[];
+  constructor(message: string, path: BindToken[]);
+}
 declare class Container {
-  private static readonly registry;
-  static bind<T>(token: BindToken<T>, value: BindValue<T>): void;
+  readonly parent?: Container | undefined;
+  private readonly context?;
+  private readonly requestScope;
+  private static readonly activeScope;
+  private static readonly containers;
+  private static readonly globalContainer;
+  private readonly registry;
+  private readonly instances;
+  private readonly pending;
+  constructor(parent?: Container | undefined, context?: any | undefined, requestScope?: boolean);
+  static get global(): Container;
+  static current(): Container;
+  static run<T>(container: Container, callback: () => T): T;
+  static create(parent?: Container): Container;
+  createRequestScope(ctx: any): Container;
+  static bind<T>(token: BindToken<T>, value: BindValue<T>, options?: BindingOptions): void;
   static unbind<T>(token: BindToken<T>): void;
   static clear(): void;
   static has<T>(token: BindToken<T>): boolean;
   static bindings<V = any>(): Record<string, BindValue<V>>;
-  static resolve<T>(token: BindToken<T>, ctx: any, autoDiscover?: boolean): Promise<T | undefined>;
-  private static getBinding;
-  private static findEquivalentToken;
-  private static getComparableStaticProps;
-  private static staticPropsMatch;
-  private static resolveBinding;
+  static resolve<T>(token: BindToken<T>, ctx?: any, autoDiscover?: boolean): Promise<T | undefined>;
+  bind<T>(token: BindToken<T>, value: BindValue<T>, options?: BindingOptions): void;
+  unbind<T>(token: BindToken<T>): void;
+  clear(): void;
+  has<T>(token: BindToken<T>): boolean;
+  entries(): ReadonlyMap<BindToken, BindProvider>;
+  bindings<V = any>(): Record<string, BindValue<V>>;
+  resolve<T>(token: BindToken<T>, ctx?: any, autoDiscover?: boolean): Promise<T | undefined>;
+  resolveOrFail<T>(token: BindToken<T>, ctx?: any, autoDiscover?: boolean): Promise<T>;
+  private resolveToken;
+  private findProvider;
+  private resolveProvider;
+  private instantiate;
+  private findRequestScope;
+  private lineage;
+  private findEquivalentToken;
+  private getComparableStaticProps;
+  private staticPropsMatch;
 }
 declare function Bind(...tokens: BindToken[]): BindDecorator;
+declare function getMetadataKey(): symbol;
+declare function getStandardMetadata(metadata: object | undefined, propertyKey?: PropertyKey): BindingMetadata | undefined;
+declare function setStandardMetadata(metadata: object | undefined, propertyKey: PropertyKey, value: BindingMetadata): void;
+declare function getBindingMetadataFromTargets(targets: Array<{
+  target?: object;
+  propertyKey?: PropertyKey;
+}>): BindingMetadata | undefined;
+declare function getBindingMetadata(target: object, propertyKey?: PropertyKey): BindingMetadata | undefined;
+declare function setBindingMetadata(target: object, propertyKey: PropertyKey, metadata: BindingMetadata): void;
+declare function getDesignParamTypes(target: object, propertyKey?: PropertyKey): BindToken[];
+declare function isClass(value: any): boolean;
 //#endregion
-export { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container };
+export { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, Container, ContainerResolutionError, ExistingProvider, FactoryProvider, InjectionToken, ValueProvider, getBindingMetadata, getBindingMetadataFromTargets, getDesignParamTypes, getMetadataKey, getStandardMetadata, isClass, setBindingMetadata, setStandardMetadata };

package/dist/core/bindings.d.mts

@@ -1,25 +1,96 @@
 //#region src/core/bindings.d.ts
-type BindToken<T = any> = abstract new (...args: any[]) => T;
+type BindClass<T = any> = abstract new (...args: any[]) => T;
+type BindToken<T = any> = BindClass<T> | InjectionToken<T> | symbol;
 type BindFactory<T = any> = (ctx: any) => T | Promise<T>;
-type BindValue<T = any> = T | BindFactory<T> | BindToken<T>;
+type BindingScope = 'singleton' | 'request' | 'transient';
+type BindingOptions = {
+  scope?: BindingScope;
+};
+type ValueProvider<T = any> = {
+  useValue: T;
+};
+type ClassProvider<T = any> = BindingOptions & {
+  useClass: BindClass<T>;
+  dependencies?: BindToken[];
+};
+type FactoryProvider<T = any> = BindingOptions & {
+  useFactory: BindFactory<T>;
+};
+type ExistingProvider<T = any> = {
+  useExisting: BindToken<T>;
+};
+type BindProvider<T = any> = ValueProvider<T> | ClassProvider<T> | FactoryProvider<T> | ExistingProvider<T>;
+type BindValue<T = any> = T | BindFactory<T> | BindClass<T> | BindProvider<T>;
 type BindDecorator = MethodDecorator & ClassDecorator & {
   <This, Value extends (this: This, ...args: any[]) => any>(value: Value, context: ClassMethodDecoratorContext<This, Value>): void | Value;
   <Value extends abstract new (...args: any[]) => any>(value: Value, context: ClassDecoratorContext<Value>): void | Value;
 };
+type BindingMetadata = {
+  tokens?: BindToken[];
+  method?: PropertyKey;
+};
+declare class InjectionToken<T = any> {
+  readonly description: string;
+  readonly __type?: T;
+  readonly key: symbol;
+  constructor(description: string);
+  toString(): string;
+}
+declare class ContainerResolutionError extends Error {
+  readonly path: BindToken[];
+  constructor(message: string, path: BindToken[]);
+}
 declare class Container {
-  private static readonly registry;
-  static bind<T>(token: BindToken<T>, value: BindValue<T>): void;
+  readonly parent?: Container | undefined;
+  private readonly context?;
+  private readonly requestScope;
+  private static readonly activeScope;
+  private static readonly containers;
+  private static readonly globalContainer;
+  private readonly registry;
+  private readonly instances;
+  private readonly pending;
+  constructor(parent?: Container | undefined, context?: any | undefined, requestScope?: boolean);
+  static get global(): Container;
+  static current(): Container;
+  static run<T>(container: Container, callback: () => T): T;
+  static create(parent?: Container): Container;
+  createRequestScope(ctx: any): Container;
+  static bind<T>(token: BindToken<T>, value: BindValue<T>, options?: BindingOptions): void;
   static unbind<T>(token: BindToken<T>): void;
   static clear(): void;
   static has<T>(token: BindToken<T>): boolean;
   static bindings<V = any>(): Record<string, BindValue<V>>;
-  static resolve<T>(token: BindToken<T>, ctx: any, autoDiscover?: boolean): Promise<T | undefined>;
-  private static getBinding;
-  private static findEquivalentToken;
-  private static getComparableStaticProps;
-  private static staticPropsMatch;
-  private static resolveBinding;
+  static resolve<T>(token: BindToken<T>, ctx?: any, autoDiscover?: boolean): Promise<T | undefined>;
+  bind<T>(token: BindToken<T>, value: BindValue<T>, options?: BindingOptions): void;
+  unbind<T>(token: BindToken<T>): void;
+  clear(): void;
+  has<T>(token: BindToken<T>): boolean;
+  entries(): ReadonlyMap<BindToken, BindProvider>;
+  bindings<V = any>(): Record<string, BindValue<V>>;
+  resolve<T>(token: BindToken<T>, ctx?: any, autoDiscover?: boolean): Promise<T | undefined>;
+  resolveOrFail<T>(token: BindToken<T>, ctx?: any, autoDiscover?: boolean): Promise<T>;
+  private resolveToken;
+  private findProvider;
+  private resolveProvider;
+  private instantiate;
+  private findRequestScope;
+  private lineage;
+  private findEquivalentToken;
+  private getComparableStaticProps;
+  private staticPropsMatch;
 }
 declare function Bind(...tokens: BindToken[]): BindDecorator;
+declare function getMetadataKey(): symbol;
+declare function getStandardMetadata(metadata: object | undefined, propertyKey?: PropertyKey): BindingMetadata | undefined;
+declare function setStandardMetadata(metadata: object | undefined, propertyKey: PropertyKey, value: BindingMetadata): void;
+declare function getBindingMetadataFromTargets(targets: Array<{
+  target?: object;
+  propertyKey?: PropertyKey;
+}>): BindingMetadata | undefined;
+declare function getBindingMetadata(target: object, propertyKey?: PropertyKey): BindingMetadata | undefined;
+declare function setBindingMetadata(target: object, propertyKey: PropertyKey, metadata: BindingMetadata): void;
+declare function getDesignParamTypes(target: object, propertyKey?: PropertyKey): BindToken[];
+declare function isClass(value: any): boolean;
 //#endregion
-export { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container };
+export { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, Container, ContainerResolutionError, ExistingProvider, FactoryProvider, InjectionToken, ValueProvider, getBindingMetadata, getBindingMetadataFromTargets, getDesignParamTypes, getMetadataKey, getStandardMetadata, isClass, setBindingMetadata, setStandardMetadata };