clear-router 2.5.4 → 2.5.6

package/README.md

@@ -50,6 +50,10 @@ yarn add clear-router express
 - Controller handlers receive hydrated `this.body`, `this.query`, `this.params`, and `this.clearRequest`
 - `clearRequest` is passed as second handler argument for controller handlers
 - Route handlers can return response values directly across Express, Fastify, Hono, H3, and Koa
+- Optional decorated container binding for controller method arguments
+- Plugin API for registering container bindings from external packages
+- Supports TS 5.2+ standard decorators with explicit `@Bind(...)` tokens
+- Optional `clear-router/decorators/setup` entry imports `reflect-metadata` and enables container binding defaults
 - Auto-binds controller methods
 - Full CommonJS, ESM, and TypeScript support
 - Error handling delegated to Express | H3 | Fastify | Hono | Koa
@@ -98,6 +102,7 @@ See [API.md](https://arkstack-hq.github.io/clear-router/api) for complete API do
 - If [Controller, 'method']: auto-instantiated (if needed), method is called
 - First handler arg is always context (`{ req, res, next }` for Express, H3 event for H3, Koa context for Koa)
 - Second handler arg is `clearRequest` for controller handlers
+- Decorated controller methods can opt into resolved arguments with `@Bind(...)`
 
 ## Testing
 

package/dist/bindings-CV1e5jho.d.mts

@@ -0,0 +1,20 @@
+//#region src/core/bindings.d.ts
+type BindToken<T = any> = abstract new (...args: any[]) => T;
+type BindFactory<T = any> = (ctx: any) => T | Promise<T>;
+type BindValue<T = any> = T | BindFactory<T> | BindToken<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;
+};
+declare class Container {
+  private static readonly registry;
+  static bind<T>(token: BindToken<T>, value: BindValue<T>): void;
+  static unbind<T>(token: BindToken<T>): void;
+  static clear(): void;
+  static has<T>(token: BindToken<T>): boolean;
+  static resolve<T>(token: BindToken<T>, ctx: any, autoDiscover?: boolean): Promise<T | undefined>;
+  private static resolveBinding;
+}
+declare function Bind(...tokens: BindToken[]): BindDecorator;
+//#endregion
+export { BindValue as a, BindToken as i, BindDecorator as n, Container as o, BindFactory as r, Bind as t };

package/dist/bindings-DIanvIVd.mjs

@@ -0,0 +1,211 @@
+//#region src/ClearRequest.ts
+var ClearRequest = class {
+	/**
+	* @param body - Parsed request body
+	*/
+	body;
+	/**
+	* @param query - Parsed query parameters
+	*/
+	query;
+	/**
+	* @param params - Parsed route parameters
+	*/
+	params;
+	route;
+	constructor(init) {
+		Object.assign(this, init);
+	}
+};
+
+//#endregion
+//#region src/core/Request.ts
+var Request = class extends ClearRequest {
+	original;
+	method = "GET";
+	path = "/";
+	url = "/";
+	headers = {};
+	constructor(init) {
+		super(init);
+		Object.assign(this, init);
+	}
+	getBody() {
+		return this.body ?? {};
+	}
+	header(name) {
+		if (typeof this.headers.get === "function") return this.headers.get(name) || "";
+		const headers = this.headers;
+		const value = headers[name] ?? headers[name.toLowerCase()];
+		return Array.isArray(value) ? String(value[0] ?? "") : String(value ?? "");
+	}
+	param(name) {
+		return this.params?.[name];
+	}
+	input(name) {
+		return this.body?.[name] ?? this.query?.[name] ?? this.params?.[name];
+	}
+	is(method) {
+		return this.method.toLowerCase() === String(method).toLowerCase();
+	}
+};
+
+//#endregion
+//#region src/core/Response.ts
+var Response = class {
+	body;
+	headers = new Headers();
+	sent = false;
+	statusCode = 200;
+	constructor(init) {
+		Object.assign(this, init);
+		if (init?.headers && !(init.headers instanceof Headers)) this.headers = new Headers(init.headers);
+	}
+	status(code) {
+		this.statusCode = code;
+		return this;
+	}
+	code(code) {
+		return this.status(code);
+	}
+	setHeader(name, value) {
+		this.headers.set(name, value);
+		return this;
+	}
+	header(name, value) {
+		return this.setHeader(name, value);
+	}
+	set(name, value) {
+		return this.setHeader(name, value);
+	}
+	type(contentType) {
+		return this.setHeader("Content-Type", contentType);
+	}
+	send(body) {
+		this.body = body;
+		this.sent = true;
+		return this;
+	}
+	json(body) {
+		return this.type("application/json; charset=utf-8").send(body);
+	}
+	html(body) {
+		return this.type("text/html; charset=utf-8").send(body);
+	}
+	text(body) {
+		return this.type("text/plain; charset=utf-8").send(body);
+	}
+	noContent() {
+		return this.status(204).send(null);
+	}
+};
+
+//#endregion
+//#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);
+	}
+	static unbind(token) {
+		this.registry.delete(token);
+	}
+	static clear() {
+		this.registry.clear();
+	}
+	static has(token) {
+		return this.registry.has(token);
+	}
+	static async resolve(token, ctx, autoDiscover = false) {
+		if (token === Request) return ctx.clearRequest;
+		if (token === Response) return ctx.clearResponse;
+		if (this.registry.has(token)) return this.resolveBinding(this.registry.get(token), ctx, autoDiscover);
+		if (autoDiscover && typeof token === "function") return new token();
+	}
+	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 Bind(...tokens) {
+	return ((target, propertyKeyOrContext) => {
+		if (isStandardClassContext(propertyKeyOrContext)) {
+			setClassBindingMetadata(target, tokens);
+			setStandardMetadata(propertyKeyOrContext.metadata, "__class__", { tokens });
+			return;
+		}
+		if (isStandardMethodContext(propertyKeyOrContext)) {
+			const method = propertyKeyOrContext.name;
+			const metadata = {
+				tokens,
+				method
+			};
+			setBindingMetadata(target, "__route_handler__", metadata);
+			setStandardMetadata(propertyKeyOrContext.metadata, method, metadata);
+			return;
+		}
+		if (typeof propertyKeyOrContext === "undefined") {
+			setClassBindingMetadata(target, tokens);
+			return;
+		}
+		setBindingMetadata(target, propertyKeyOrContext, {
+			tokens,
+			method: propertyKeyOrContext
+		});
+	});
+}
+function getStandardMetadata(metadata, propertyKey) {
+	const store = metadata && metadata[metadataKey];
+	if (!store) return void 0;
+	return propertyKey ? store[propertyKey] : void 0;
+}
+function setStandardMetadata(metadata, propertyKey, value) {
+	if (!metadata) return;
+	const record = metadata;
+	record[metadataKey] = record[metadataKey] ?? {};
+	record[metadataKey][propertyKey] = value;
+}
+function isStandardMethodContext(value) {
+	return Boolean(value && typeof value === "object" && value.kind === "method" && typeof value.name !== "undefined");
+}
+function isStandardClassContext(value) {
+	return Boolean(value && typeof value === "object" && value.kind === "class" && typeof value.name !== "undefined");
+}
+function setClassBindingMetadata(target, tokens) {
+	setBindingMetadata(target, "__class__", { tokens });
+	const prototype = target.prototype;
+	if (prototype) setBindingMetadata(prototype, "__class__", { tokens });
+}
+function getBindingMetadataFromTargets(targets) {
+	for (const { target, propertyKey } of targets) {
+		if (!target) continue;
+		const metadata = getBindingMetadata(target, propertyKey);
+		if (metadata) return metadata;
+		const standardMetadata = getStandardMetadata(target[Symbol.metadata], propertyKey);
+		if (standardMetadata) return standardMetadata;
+	}
+}
+function getBindingMetadata(target, propertyKey) {
+	if (propertyKey) return bindings.get(target)?.get(propertyKey);
+	return bindings.get(target)?.get("__route_handler__");
+}
+function setBindingMetadata(target, propertyKey, metadata) {
+	const map = bindings.get(target) ?? /* @__PURE__ */ new Map();
+	map.set(propertyKey, metadata);
+	bindings.set(target, map);
+}
+function getDesignParamTypes(target, propertyKey) {
+	return Reflect.getMetadata?.("design:paramtypes", target, propertyKey) ?? [];
+}
+function isClass(value) {
+	return typeof value === "function" && /^class\s/.test(Function.prototype.toString.call(value));
+}
+
+//#endregion
+export { getStandardMetadata as a, getDesignParamTypes as i, Container as n, Response as o, getBindingMetadataFromTargets as r, Request as s, Bind as t };

package/dist/bindings-DvV2DXWi.cjs

@@ -0,0 +1,253 @@
+
+//#region src/ClearRequest.ts
+var ClearRequest = class {
+	/**
+	* @param body - Parsed request body
+	*/
+	body;
+	/**
+	* @param query - Parsed query parameters
+	*/
+	query;
+	/**
+	* @param params - Parsed route parameters
+	*/
+	params;
+	route;
+	constructor(init) {
+		Object.assign(this, init);
+	}
+};
+
+//#endregion
+//#region src/core/Request.ts
+var Request = class extends ClearRequest {
+	original;
+	method = "GET";
+	path = "/";
+	url = "/";
+	headers = {};
+	constructor(init) {
+		super(init);
+		Object.assign(this, init);
+	}
+	getBody() {
+		return this.body ?? {};
+	}
+	header(name) {
+		if (typeof this.headers.get === "function") return this.headers.get(name) || "";
+		const headers = this.headers;
+		const value = headers[name] ?? headers[name.toLowerCase()];
+		return Array.isArray(value) ? String(value[0] ?? "") : String(value ?? "");
+	}
+	param(name) {
+		return this.params?.[name];
+	}
+	input(name) {
+		return this.body?.[name] ?? this.query?.[name] ?? this.params?.[name];
+	}
+	is(method) {
+		return this.method.toLowerCase() === String(method).toLowerCase();
+	}
+};
+
+//#endregion
+//#region src/core/Response.ts
+var Response = class {
+	body;
+	headers = new Headers();
+	sent = false;
+	statusCode = 200;
+	constructor(init) {
+		Object.assign(this, init);
+		if (init?.headers && !(init.headers instanceof Headers)) this.headers = new Headers(init.headers);
+	}
+	status(code) {
+		this.statusCode = code;
+		return this;
+	}
+	code(code) {
+		return this.status(code);
+	}
+	setHeader(name, value) {
+		this.headers.set(name, value);
+		return this;
+	}
+	header(name, value) {
+		return this.setHeader(name, value);
+	}
+	set(name, value) {
+		return this.setHeader(name, value);
+	}
+	type(contentType) {
+		return this.setHeader("Content-Type", contentType);
+	}
+	send(body) {
+		this.body = body;
+		this.sent = true;
+		return this;
+	}
+	json(body) {
+		return this.type("application/json; charset=utf-8").send(body);
+	}
+	html(body) {
+		return this.type("text/html; charset=utf-8").send(body);
+	}
+	text(body) {
+		return this.type("text/plain; charset=utf-8").send(body);
+	}
+	noContent() {
+		return this.status(204).send(null);
+	}
+};
+
+//#endregion
+//#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);
+	}
+	static unbind(token) {
+		this.registry.delete(token);
+	}
+	static clear() {
+		this.registry.clear();
+	}
+	static has(token) {
+		return this.registry.has(token);
+	}
+	static async resolve(token, ctx, autoDiscover = false) {
+		if (token === Request) return ctx.clearRequest;
+		if (token === Response) return ctx.clearResponse;
+		if (this.registry.has(token)) return this.resolveBinding(this.registry.get(token), ctx, autoDiscover);
+		if (autoDiscover && typeof token === "function") return new token();
+	}
+	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 Bind(...tokens) {
+	return ((target, propertyKeyOrContext) => {
+		if (isStandardClassContext(propertyKeyOrContext)) {
+			setClassBindingMetadata(target, tokens);
+			setStandardMetadata(propertyKeyOrContext.metadata, "__class__", { tokens });
+			return;
+		}
+		if (isStandardMethodContext(propertyKeyOrContext)) {
+			const method = propertyKeyOrContext.name;
+			const metadata = {
+				tokens,
+				method
+			};
+			setBindingMetadata(target, "__route_handler__", metadata);
+			setStandardMetadata(propertyKeyOrContext.metadata, method, metadata);
+			return;
+		}
+		if (typeof propertyKeyOrContext === "undefined") {
+			setClassBindingMetadata(target, tokens);
+			return;
+		}
+		setBindingMetadata(target, propertyKeyOrContext, {
+			tokens,
+			method: propertyKeyOrContext
+		});
+	});
+}
+function getStandardMetadata(metadata, propertyKey) {
+	const store = metadata && metadata[metadataKey];
+	if (!store) return void 0;
+	return propertyKey ? store[propertyKey] : void 0;
+}
+function setStandardMetadata(metadata, propertyKey, value) {
+	if (!metadata) return;
+	const record = metadata;
+	record[metadataKey] = record[metadataKey] ?? {};
+	record[metadataKey][propertyKey] = value;
+}
+function isStandardMethodContext(value) {
+	return Boolean(value && typeof value === "object" && value.kind === "method" && typeof value.name !== "undefined");
+}
+function isStandardClassContext(value) {
+	return Boolean(value && typeof value === "object" && value.kind === "class" && typeof value.name !== "undefined");
+}
+function setClassBindingMetadata(target, tokens) {
+	setBindingMetadata(target, "__class__", { tokens });
+	const prototype = target.prototype;
+	if (prototype) setBindingMetadata(prototype, "__class__", { tokens });
+}
+function getBindingMetadataFromTargets(targets) {
+	for (const { target, propertyKey } of targets) {
+		if (!target) continue;
+		const metadata = getBindingMetadata(target, propertyKey);
+		if (metadata) return metadata;
+		const standardMetadata = getStandardMetadata(target[Symbol.metadata], propertyKey);
+		if (standardMetadata) return standardMetadata;
+	}
+}
+function getBindingMetadata(target, propertyKey) {
+	if (propertyKey) return bindings.get(target)?.get(propertyKey);
+	return bindings.get(target)?.get("__route_handler__");
+}
+function setBindingMetadata(target, propertyKey, metadata) {
+	const map = bindings.get(target) ?? /* @__PURE__ */ new Map();
+	map.set(propertyKey, metadata);
+	bindings.set(target, map);
+}
+function getDesignParamTypes(target, propertyKey) {
+	return Reflect.getMetadata?.("design:paramtypes", target, propertyKey) ?? [];
+}
+function isClass(value) {
+	return typeof value === "function" && /^class\s/.test(Function.prototype.toString.call(value));
+}
+
+//#endregion
+Object.defineProperty(exports, 'Bind', {
+  enumerable: true,
+  get: function () {
+    return Bind;
+  }
+});
+Object.defineProperty(exports, 'Container', {
+  enumerable: true,
+  get: function () {
+    return Container;
+  }
+});
+Object.defineProperty(exports, 'Request', {
+  enumerable: true,
+  get: function () {
+    return Request;
+  }
+});
+Object.defineProperty(exports, 'Response', {
+  enumerable: true,
+  get: function () {
+    return Response;
+  }
+});
+Object.defineProperty(exports, 'getBindingMetadataFromTargets', {
+  enumerable: true,
+  get: function () {
+    return getBindingMetadataFromTargets;
+  }
+});
+Object.defineProperty(exports, 'getDesignParamTypes', {
+  enumerable: true,
+  get: function () {
+    return getDesignParamTypes;
+  }
+});
+Object.defineProperty(exports, 'getStandardMetadata', {
+  enumerable: true,
+  get: function () {
+    return getStandardMetadata;
+  }
+});

package/dist/bindings-NV0CdqGl.d.cts

@@ -0,0 +1,20 @@
+//#region src/core/bindings.d.ts
+type BindToken<T = any> = abstract new (...args: any[]) => T;
+type BindFactory<T = any> = (ctx: any) => T | Promise<T>;
+type BindValue<T = any> = T | BindFactory<T> | BindToken<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;
+};
+declare class Container {
+  private static readonly registry;
+  static bind<T>(token: BindToken<T>, value: BindValue<T>): void;
+  static unbind<T>(token: BindToken<T>): void;
+  static clear(): void;
+  static has<T>(token: BindToken<T>): boolean;
+  static resolve<T>(token: BindToken<T>, ctx: any, autoDiscover?: boolean): Promise<T | undefined>;
+  private static resolveBinding;
+}
+declare function Bind(...tokens: BindToken[]): BindDecorator;
+//#endregion
+export { BindValue as a, BindToken as i, BindDecorator as n, Container as o, BindFactory as r, Bind as t };

package/dist/core/index.cjs

@@ -1,4 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_router = require('../router-CHg0pZUO.cjs');
+const require_bindings = require('../bindings-DvV2DXWi.cjs');
+const require_router = require('../router-CU4V1kX0.cjs');
 
-exports.CoreRouter = require_router.CoreRouter;
+//#region src/core/plugins.ts
+function definePlugin(plugin) {
+	return plugin;
+}
+
+//#endregion
+exports.CoreRouter = require_router.CoreRouter;
+exports.Request = require_bindings.Request;
+exports.Response = require_bindings.Response;
+exports.definePlugin = definePlugin;

package/dist/core/index.d.cts

@@ -1,2 +1,2 @@
-import { t as CoreRouter } from "../router-CS_2XQ7I.cjs";
-export { CoreRouter };
+import { a as PluginBind, c as Request, i as ClearRouterPluginInput, n as ClearRouterPlugin, o as PluginSetupResult, r as ClearRouterPluginContext, s as definePlugin, t as CoreRouter, x as Response } from "../router-BYZmNzrZ.cjs";
+export { ClearRouterPlugin, ClearRouterPluginContext, ClearRouterPluginInput, CoreRouter, PluginBind, PluginSetupResult, Request, Response, definePlugin };

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { t as CoreRouter } from "../router-_w2VzMQF.mjs";
-export { CoreRouter };
+import { a as PluginBind, c as Request, i as ClearRouterPluginInput, n as ClearRouterPlugin, o as PluginSetupResult, r as ClearRouterPluginContext, s as definePlugin, t as CoreRouter, x as Response } from "../router-DCMtQ_Xi.mjs";
+export { ClearRouterPlugin, ClearRouterPluginContext, ClearRouterPluginInput, CoreRouter, PluginBind, PluginSetupResult, Request, Response, definePlugin };

package/dist/core/index.mjs

@@ -1,3 +1,10 @@
-import { t as CoreRouter } from "../router-BReOXz-F.mjs";
+import { o as Response, s as Request } from "../bindings-DIanvIVd.mjs";
+import { t as CoreRouter } from "../router-B3QjblRX.mjs";
 
-export { CoreRouter };
+//#region src/core/plugins.ts
+function definePlugin(plugin) {
+	return plugin;
+}
+
+//#endregion
+export { CoreRouter, Request, Response, definePlugin };

package/dist/decorators/index.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_bindings = require('../bindings-DvV2DXWi.cjs');
+
+exports.Bind = require_bindings.Bind;
+exports.Container = require_bindings.Container;

package/dist/decorators/index.d.cts

@@ -0,0 +1,2 @@
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-NV0CdqGl.cjs";
+export { Bind, type BindDecorator, type BindFactory, type BindToken, type BindValue, Container };

package/dist/decorators/index.d.mts

@@ -0,0 +1,2 @@
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-CV1e5jho.mjs";
+export { Bind, type BindDecorator, type BindFactory, type BindToken, type BindValue, Container };

package/dist/decorators/index.mjs

@@ -0,0 +1,3 @@
+import { n as Container, t as Bind } from "../bindings-DIanvIVd.mjs";
+
+export { Bind, Container };

package/dist/decorators/setup.cjs

@@ -0,0 +1,15 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_bindings = require('../bindings-DvV2DXWi.cjs');
+const require_router = require('../router-CU4V1kX0.cjs');
+require('./index.cjs');
+require("reflect-metadata");
+
+//#region src/decorators/setup.ts
+require_router.CoreRouter.configureDefaults({ container: {
+	enabled: true,
+	autoDiscover: true
+} });
+
+//#endregion
+exports.Bind = require_bindings.Bind;
+exports.Container = require_bindings.Container;

package/dist/decorators/setup.d.cts

@@ -0,0 +1,2 @@
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-NV0CdqGl.cjs";
+export { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container };

package/dist/decorators/setup.d.mts

@@ -0,0 +1,2 @@
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-CV1e5jho.mjs";
+export { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container };

package/dist/decorators/setup.mjs

@@ -0,0 +1,13 @@
+import { n as Container, t as Bind } from "../bindings-DIanvIVd.mjs";
+import { t as CoreRouter } from "../router-B3QjblRX.mjs";
+import "./index.mjs";
+import "reflect-metadata";
+
+//#region src/decorators/setup.ts
+CoreRouter.configureDefaults({ container: {
+	enabled: true,
+	autoDiscover: true
+} });
+
+//#endregion
+export { Bind, Container };