@aponiajs/common 0.0.0

package/README.md

@@ -0,0 +1,8 @@
+# @aponiajs/common
+
+Platform-neutral decorators and public contracts for Aponia modules,
+controllers, routes, and dependency injection.
+
+The public application authoring API includes `@Module()`, `@Controller()`,
+HTTP method decorators, `@Injectable()`, and `@Inject()`. This package does not
+depend on Elysia, Bun runtime APIs, or another Aponia package.

package/dist/index.d.mts

@@ -0,0 +1,169 @@
+import "reflect-metadata";
+//#region src/token.d.ts
+declare const tokenType: unique symbol;
+type Constructor<T, TArguments extends readonly unknown[] = readonly unknown[]> = new (...arguments_: TArguments) => T;
+type ClassToken<T> = abstract new (...arguments_: never[]) => T;
+interface InjectionToken<T> {
+  readonly id: symbol;
+  readonly description: string;
+  readonly [tokenType]?: T;
+}
+type Token<T> = ClassToken<T> | InjectionToken<T>;
+type TokenValue<TToken> = TToken extends Token<infer TValue> ? TValue : never;
+type TokenValues<TTokens extends readonly Token<unknown>[]> = { readonly [TIndex in keyof TTokens]: TokenValue<TTokens[TIndex]>; };
+declare function createToken<T>(description: string): InjectionToken<T>;
+declare function tokenName(token: Token<unknown>): string;
+//#endregion
+//#region src/controller.d.ts
+interface ControllerDefinition {
+  readonly kind: string;
+  readonly token: Token<unknown>;
+  readonly inject: readonly Token<unknown>[];
+  readonly useClass: Constructor<unknown, never[]>;
+}
+//#endregion
+//#region src/provider.d.ts
+type ProviderScope = "singleton";
+interface ProviderBase<T> {
+  readonly provide: Token<T>;
+  readonly scope?: ProviderScope;
+}
+interface ValueProvider<T> extends ProviderBase<T> {
+  readonly kind: "value";
+  readonly useValue: T;
+}
+interface FactoryProvider<T, TDependencies extends readonly Token<unknown>[] = readonly Token<unknown>[]> extends ProviderBase<T> {
+  readonly kind: "factory";
+  readonly inject: TDependencies;
+  readonly useFactory: (...dependencies: TokenValues<TDependencies>) => T;
+}
+interface ClassProvider<T, TDependencies extends readonly Token<unknown>[] = readonly Token<unknown>[]> extends ProviderBase<T> {
+  readonly kind: "class";
+  readonly inject: TDependencies;
+  readonly useClass: Constructor<T, TokenValues<TDependencies>>;
+}
+interface AliasProvider<T> extends ProviderBase<T> {
+  readonly kind: "alias";
+  readonly useExisting: Token<T>;
+}
+type Provider = {
+  readonly kind: "value";
+  readonly provide: Token<unknown>;
+  readonly useValue: unknown;
+} | {
+  readonly kind: "factory";
+  readonly provide: Token<unknown>;
+  readonly inject: readonly Token<unknown>[];
+  readonly useFactory: (...dependencies: never[]) => unknown;
+} | {
+  readonly kind: "class";
+  readonly provide: Token<unknown>;
+  readonly inject: readonly Token<unknown>[];
+  readonly useClass: Constructor<unknown, never[]>;
+} | {
+  readonly kind: "alias";
+  readonly provide: Token<unknown>;
+  readonly useExisting: Token<unknown>;
+};
+declare function provideValue<T>(provide: Token<T>, useValue: T): ValueProvider<T>;
+declare function provideFactory<T, const TDependencies extends readonly Token<unknown>[]>(provide: Token<T>, inject: TDependencies, useFactory: (...dependencies: TokenValues<TDependencies>) => T): FactoryProvider<T, TDependencies>;
+declare function provideClass<T, const TDependencies extends readonly Token<unknown>[]>(useClass: ClassToken<T> & Constructor<T, TokenValues<TDependencies>>, inject: TDependencies): ClassProvider<T, TDependencies>;
+declare function provideAlias<T>(provide: Token<T>, useExisting: Token<T>): AliasProvider<T>;
+//#endregion
+//#region src/module.d.ts
+interface ModuleDefinition {
+  readonly id: string;
+  readonly imports: readonly ModuleDefinition[];
+  readonly controllers: readonly ControllerDefinition[];
+  readonly providers: readonly Provider[];
+  readonly exports: readonly Token<unknown>[];
+}
+interface ModuleOptions {
+  readonly id: string;
+  readonly imports?: readonly ModuleDefinition[];
+  readonly controllers?: readonly ControllerDefinition[];
+  readonly providers?: readonly Provider[];
+  readonly exports?: readonly Token<unknown>[];
+}
+declare function defineModule<const TOptions extends ModuleOptions>(options: TOptions): ModuleDefinition & TOptions;
+//#endregion
+//#region src/decorators.d.ts
+type ModuleClass = ClassToken<unknown>;
+type ModuleImport = ModuleClass | ModuleDefinition;
+type ModuleProvider = ClassToken<unknown> | Provider;
+interface ModuleMetadata {
+  readonly imports?: readonly ModuleImport[];
+  readonly controllers?: readonly ClassToken<unknown>[];
+  readonly providers?: readonly ModuleProvider[];
+  readonly exports?: readonly Token<unknown>[];
+}
+interface ControllerMetadata {
+  readonly path: string;
+}
+type RequestMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+interface RouteMetadata {
+  readonly method: RequestMethod;
+  readonly path: string;
+  readonly propertyKey: string | symbol;
+}
+declare function Module(metadata: ModuleMetadata): ClassDecorator;
+declare function Injectable(): ClassDecorator;
+declare function Controller(path?: string): ClassDecorator;
+declare function Inject(token: Token<unknown>): ParameterDecorator;
+declare const Delete: (path?: string) => MethodDecorator;
+declare const Get: (path?: string) => MethodDecorator;
+declare const Patch: (path?: string) => MethodDecorator;
+declare const Post: (path?: string) => MethodDecorator;
+declare const Put: (path?: string) => MethodDecorator;
+declare function getModuleMetadata(target: ModuleClass): Readonly<ModuleMetadata> | undefined;
+declare function getControllerMetadata(target: ClassToken<unknown>): Readonly<ControllerMetadata> | undefined;
+declare function getRouteMetadata(target: ClassToken<unknown>): readonly RouteMetadata[];
+declare function getConstructorDependencies(target: ClassToken<unknown>): readonly Token<unknown>[];
+//#endregion
+//#region src/error.d.ts
+type AponiaErrorCode = "MODULE_CYCLE" | "DUPLICATE_MODULE" | "DUPLICATE_PROVIDER" | "INVALID_EXPORT" | "AMBIGUOUS_PROVIDER" | "MISSING_PROVIDER" | "PROVIDER_CYCLE" | "INVALID_CONTROLLER" | "INVALID_MODULE" | "APPLICATION_NOT_LISTENING" | "UNSUPPORTED_CONTROLLER";
+declare class AponiaError extends Error {
+  readonly code: AponiaErrorCode;
+  readonly details: Readonly<Record<string, unknown>>;
+  constructor(code: AponiaErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+//#endregion
+//#region src/logger.d.ts
+type LogLevel = "fatal" | "error" | "warn" | "log" | "debug" | "verbose";
+interface LoggerService {
+  log(message: unknown, ...optionalParameters: unknown[]): void;
+  fatal(message: unknown, ...optionalParameters: unknown[]): void;
+  error(message: unknown, ...optionalParameters: unknown[]): void;
+  warn(message: unknown, ...optionalParameters: unknown[]): void;
+  debug?(message: unknown, ...optionalParameters: unknown[]): void;
+  verbose?(message: unknown, ...optionalParameters: unknown[]): void;
+}
+interface ConsoleLoggerOptions {
+  readonly logLevels?: readonly LogLevel[];
+  readonly timestamp?: boolean;
+  readonly prefix?: string;
+  readonly json?: boolean;
+  readonly colors?: boolean;
+  readonly context?: string;
+  readonly compact?: boolean | number;
+  readonly depth?: number;
+}
+declare class ConsoleLogger implements LoggerService {
+  #private;
+  static lastTimestampAt: number | undefined;
+  constructor();
+  constructor(context: string, options?: ConsoleLoggerOptions);
+  constructor(options: ConsoleLoggerOptions);
+  setContext(context: string): void;
+  resetContext(): void;
+  isLevelEnabled(level: LogLevel): boolean;
+  log(message: unknown, ...optionalParameters: unknown[]): void;
+  fatal(message: unknown, ...optionalParameters: unknown[]): void;
+  error(message: unknown, ...optionalParameters: unknown[]): void;
+  warn(message: unknown, ...optionalParameters: unknown[]): void;
+  debug(message: unknown, ...optionalParameters: unknown[]): void;
+  verbose(message: unknown, ...optionalParameters: unknown[]): void;
+}
+declare class Logger extends ConsoleLogger {}
+//#endregion
+export { type AliasProvider, AponiaError, type AponiaErrorCode, type ClassProvider, type ClassToken, ConsoleLogger, type ConsoleLoggerOptions, type Constructor, Controller, type ControllerDefinition, type ControllerMetadata, Delete, type FactoryProvider, Get, Inject, Injectable, type InjectionToken, type LogLevel, Logger, type LoggerService, Module, type ModuleClass, type ModuleDefinition, type ModuleImport, type ModuleMetadata, type ModuleOptions, type ModuleProvider, Patch, Post, type Provider, type ProviderScope, Put, type RequestMethod, type RouteMetadata, type Token, type TokenValue, type TokenValues, type ValueProvider, createToken, defineModule, getConstructorDependencies, getControllerMetadata, getModuleMetadata, getRouteMetadata, provideAlias, provideClass, provideFactory, provideValue, tokenName };

package/dist/index.mjs

@@ -0,0 +1,257 @@
+import "reflect-metadata";
+import { inspect } from "node:util";
+//#region src/decorators.ts
+const modules = /* @__PURE__ */ new WeakMap();
+const controllers = /* @__PURE__ */ new WeakMap();
+const routes = /* @__PURE__ */ new WeakMap();
+const injectedTokens = /* @__PURE__ */ new WeakMap();
+function Module(metadata) {
+	const normalized = Object.freeze({
+		imports: Object.freeze([...metadata.imports ?? []]),
+		controllers: Object.freeze([...metadata.controllers ?? []]),
+		providers: Object.freeze([...metadata.providers ?? []]),
+		exports: Object.freeze([...metadata.exports ?? []])
+	});
+	return (target) => {
+		modules.set(target, normalized);
+	};
+}
+function Injectable() {
+	return () => {};
+}
+function Controller(path = "") {
+	return (target) => {
+		controllers.set(target, Object.freeze({ path }));
+	};
+}
+function Inject(token) {
+	return (target, _propertyKey, parameterIndex) => {
+		const constructor = typeof target === "function" ? target : target.constructor;
+		const parameters = injectedTokens.get(constructor) ?? /* @__PURE__ */ new Map();
+		parameters.set(parameterIndex, token);
+		injectedTokens.set(constructor, parameters);
+	};
+}
+const Delete = createRouteDecorator("DELETE");
+const Get = createRouteDecorator("GET");
+const Patch = createRouteDecorator("PATCH");
+const Post = createRouteDecorator("POST");
+const Put = createRouteDecorator("PUT");
+function getModuleMetadata(target) {
+	return modules.get(target);
+}
+function getControllerMetadata(target) {
+	return controllers.get(target);
+}
+function getRouteMetadata(target) {
+	return Object.freeze([...routes.get(target.prototype) ?? []]);
+}
+function getConstructorDependencies(target) {
+	const reflected = Reflect.getMetadata("design:paramtypes", target) ?? [];
+	const explicit = injectedTokens.get(target);
+	const explicitLength = explicit ? Math.max(0, ...[...explicit.keys()].map((index) => index + 1)) : 0;
+	const length = Math.max(reflected.length, explicitLength);
+	return Object.freeze(Array.from({ length }, (_, index) => explicit?.get(index) ?? asToken(reflected[index], target)));
+}
+function createRouteDecorator(method) {
+	return (path = "") => (target, propertyKey) => {
+		const controllerRoutes = routes.get(target) ?? [];
+		controllerRoutes.push(Object.freeze({
+			method,
+			path,
+			propertyKey
+		}));
+		routes.set(target, controllerRoutes);
+	};
+}
+function asToken(value, target) {
+	if (typeof value === "function") return value;
+	throw new TypeError(`Cannot resolve a constructor dependency for "${target.name}". Use @Inject(token) for non-class tokens.`);
+}
+//#endregion
+//#region src/error.ts
+var AponiaError = class extends Error {
+	code;
+	details;
+	constructor(code, message, details = {}) {
+		super(message);
+		this.name = "AponiaError";
+		this.code = code;
+		this.details = Object.freeze({ ...details });
+	}
+};
+//#endregion
+//#region src/logger.ts
+const logLevelOrder = [
+	"fatal",
+	"error",
+	"warn",
+	"log",
+	"debug",
+	"verbose"
+];
+const colorByLevel = {
+	fatal: 31,
+	error: 31,
+	warn: 33,
+	log: 32,
+	debug: 35,
+	verbose: 36
+};
+var ConsoleLogger = class ConsoleLogger {
+	static lastTimestampAt;
+	#options;
+	#originalContext;
+	#context;
+	constructor(contextOrOptions = {}, options = {}) {
+		const context = typeof contextOrOptions === "string" ? contextOrOptions : contextOrOptions.context;
+		const suppliedOptions = typeof contextOrOptions === "string" ? options : contextOrOptions;
+		const json = suppliedOptions.json ?? false;
+		this.#context = context ?? "";
+		this.#originalContext = this.#context;
+		this.#options = {
+			...suppliedOptions,
+			colors: suppliedOptions.colors ?? !json,
+			json,
+			prefix: suppliedOptions.prefix ?? "Aponia",
+			timestamp: suppliedOptions.timestamp ?? false
+		};
+	}
+	setContext(context) {
+		this.#context = context;
+	}
+	resetContext() {
+		this.#context = this.#originalContext;
+	}
+	isLevelEnabled(level) {
+		const configured = this.#options.logLevels;
+		if (!configured) return true;
+		if (configured.length === 0) return false;
+		const maximumLevel = Math.max(...configured.map((item) => logLevelOrder.indexOf(item)));
+		return logLevelOrder.indexOf(level) <= maximumLevel;
+	}
+	log(message, ...optionalParameters) {
+		this.#print("log", message, optionalParameters);
+	}
+	fatal(message, ...optionalParameters) {
+		this.#print("fatal", message, optionalParameters);
+	}
+	error(message, ...optionalParameters) {
+		this.#print("error", message, optionalParameters);
+	}
+	warn(message, ...optionalParameters) {
+		this.#print("warn", message, optionalParameters);
+	}
+	debug(message, ...optionalParameters) {
+		this.#print("debug", message, optionalParameters);
+	}
+	verbose(message, ...optionalParameters) {
+		this.#print("verbose", message, optionalParameters);
+	}
+	#print(level, message, optionalParameters) {
+		if (!this.isLevelEnabled(level)) return;
+		const context = typeof optionalParameters.at(-1) === "string" ? optionalParameters.at(-1) : this.#context;
+		const timestamp = Date.now();
+		const timestampDifference = this.#timestampDifference(timestamp);
+		const output = this.#options.json ? this.#formatJson(level, message, context, timestamp) : this.#formatText(level, message, context, timestampDifference);
+		process[level === "error" || level === "fatal" ? "stderr" : "stdout"].write(`${output}\n`);
+	}
+	#formatJson(level, message, context, timestamp) {
+		return JSON.stringify({
+			level,
+			pid: process.pid,
+			timestamp,
+			message,
+			...context ? { context } : {}
+		});
+	}
+	#formatText(level, message, context, timestampDifference) {
+		return `${this.#colorize(`[${this.#options.prefix}] ${process.pid} -`, level)} ${new Intl.DateTimeFormat(void 0, {
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "numeric",
+			minute: "2-digit",
+			second: "2-digit"
+		}).format(Date.now())} ${this.#colorize(level.toUpperCase().padStart(7, " "), level)} ${context ? `${this.#ansi(`[${context}]`, 33)} ` : ""}${this.#colorize(this.#stringify(message), level)}${timestampDifference ? this.#ansi(timestampDifference, 33) : timestampDifference}`;
+	}
+	#timestampDifference(timestamp) {
+		const previousTimestamp = ConsoleLogger.lastTimestampAt;
+		ConsoleLogger.lastTimestampAt = timestamp;
+		return previousTimestamp && this.#options.timestamp ? ` +${timestamp - previousTimestamp}ms` : "";
+	}
+	#stringify(message) {
+		if (typeof message === "string") return message;
+		if (typeof message === "function") return message.name || message.toString();
+		return inspect(message, {
+			colors: this.#options.colors,
+			compact: this.#options.compact ?? true,
+			depth: this.#options.depth ?? 5,
+			breakLength: Number.POSITIVE_INFINITY
+		});
+	}
+	#colorize(message, level) {
+		return this.#ansi(message, colorByLevel[level]);
+	}
+	#ansi(message, color) {
+		return this.#options.colors ? `\u001B[${color}m${message}\u001B[0m` : message;
+	}
+};
+var Logger = class extends ConsoleLogger {};
+//#endregion
+//#region src/module.ts
+function defineModule(options) {
+	return Object.freeze({
+		...options,
+		imports: Object.freeze([...options.imports ?? []]),
+		controllers: Object.freeze([...options.controllers ?? []]),
+		providers: Object.freeze([...options.providers ?? []]),
+		exports: Object.freeze([...options.exports ?? []])
+	});
+}
+//#endregion
+//#region src/provider.ts
+function provideValue(provide, useValue) {
+	return Object.freeze({
+		kind: "value",
+		provide,
+		useValue
+	});
+}
+function provideFactory(provide, inject, useFactory) {
+	return Object.freeze({
+		kind: "factory",
+		provide,
+		inject,
+		useFactory
+	});
+}
+function provideClass(useClass, inject) {
+	return Object.freeze({
+		kind: "class",
+		provide: useClass,
+		inject,
+		useClass
+	});
+}
+function provideAlias(provide, useExisting) {
+	return Object.freeze({
+		kind: "alias",
+		provide,
+		useExisting
+	});
+}
+//#endregion
+//#region src/token.ts
+function createToken(description) {
+	return Object.freeze({
+		id: Symbol(description),
+		description
+	});
+}
+function tokenName(token) {
+	if (typeof token === "function") return token.name || "<anonymous class>";
+	return token.description;
+}
+//#endregion
+export { AponiaError, ConsoleLogger, Controller, Delete, Get, Inject, Injectable, Logger, Module, Patch, Post, Put, createToken, defineModule, getConstructorDependencies, getControllerMetadata, getModuleMetadata, getRouteMetadata, provideAlias, provideClass, provideFactory, provideValue, tokenName };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@aponiajs/common",
+  "version": "0.0.0",
+  "description": "Platform-neutral contracts for Aponia modules and dependency injection.",
+  "homepage": "https://github.com/aponiajs/aponiajs#readme",
+  "bugs": {
+    "url": "https://github.com/aponiajs/aponiajs/issues"
+  },
+  "license": "MIT",
+  "author": "AponiaJS contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aponiajs/aponiajs.git",
+    "directory": "packages/common"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bunx --bun vp pack",
+    "dev": "bunx --bun vp pack --watch",
+    "test": "bun test",
+    "test:vite-plus": "vp test",
+    "check": "bunx --bun vp check",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2"
+  }
+}