@smounters/imperium 1.0.0

package/dist/core/errors.d.ts

@@ -0,0 +1,31 @@
+import { ConnectError } from "@connectrpc/connect";
+export declare class HttpException extends Error {
+    readonly status: number;
+    readonly response?: unknown | undefined;
+    constructor(status: number, message: string, response?: unknown | undefined);
+    getResponse(): unknown;
+}
+export declare class BadRequestException extends HttpException {
+    constructor(message?: string, response?: unknown);
+}
+export declare class UnauthorizedException extends HttpException {
+    constructor(message?: string, response?: unknown);
+}
+export declare class ForbiddenException extends HttpException {
+    constructor(message?: string, response?: unknown);
+}
+export declare class NotFoundException extends HttpException {
+    constructor(message?: string, response?: unknown);
+}
+export declare class InternalServerErrorException extends HttpException {
+    constructor(message?: string, response?: unknown);
+}
+interface ErrorMappingOptions {
+    exposeInternalErrors?: boolean;
+}
+export declare function toHttpError(error: unknown, options?: ErrorMappingOptions): {
+    status: number;
+    body: unknown;
+};
+export declare function toConnectError(error: unknown, options?: ErrorMappingOptions): ConnectError;
+export {};

package/dist/core/errors.js

@@ -0,0 +1,169 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+export class HttpException extends Error {
+    constructor(status, message, response) {
+        super(message);
+        this.status = status;
+        this.response = response;
+        this.name = new.target.name;
+    }
+    getResponse() {
+        if (this.response !== undefined) {
+            return this.response;
+        }
+        return {
+            statusCode: this.status,
+            message: this.message,
+            error: this.name,
+        };
+    }
+}
+export class BadRequestException extends HttpException {
+    constructor(message = "Bad Request", response) {
+        super(400, message, response);
+    }
+}
+export class UnauthorizedException extends HttpException {
+    constructor(message = "Unauthorized", response) {
+        super(401, message, response);
+    }
+}
+export class ForbiddenException extends HttpException {
+    constructor(message = "Forbidden", response) {
+        super(403, message, response);
+    }
+}
+export class NotFoundException extends HttpException {
+    constructor(message = "Not Found", response) {
+        super(404, message, response);
+    }
+}
+export class InternalServerErrorException extends HttpException {
+    constructor(message = "Internal Server Error", response) {
+        super(500, message, response);
+    }
+}
+function internalErrorMessage(error, options) {
+    if (options?.exposeInternalErrors && error.message.trim().length > 0) {
+        return error.message;
+    }
+    return "Internal Server Error";
+}
+function connectCodeToHttpStatus(code) {
+    switch (code) {
+        case Code.Canceled:
+            return 499;
+        case Code.Unknown:
+            return 500;
+        case Code.InvalidArgument:
+            return 400;
+        case Code.DeadlineExceeded:
+            return 504;
+        case Code.NotFound:
+            return 404;
+        case Code.AlreadyExists:
+            return 409;
+        case Code.PermissionDenied:
+            return 403;
+        case Code.ResourceExhausted:
+            return 429;
+        case Code.FailedPrecondition:
+            return 412;
+        case Code.Aborted:
+            return 409;
+        case Code.OutOfRange:
+            return 400;
+        case Code.Unimplemented:
+            return 501;
+        case Code.Internal:
+            return 500;
+        case Code.Unavailable:
+            return 503;
+        case Code.DataLoss:
+            return 500;
+        case Code.Unauthenticated:
+            return 401;
+        default:
+            return 500;
+    }
+}
+function httpStatusToConnectCode(status) {
+    if (status === 400)
+        return Code.InvalidArgument;
+    if (status === 401)
+        return Code.Unauthenticated;
+    if (status === 403)
+        return Code.PermissionDenied;
+    if (status === 404)
+        return Code.NotFound;
+    if (status === 409)
+        return Code.Aborted;
+    if (status === 412)
+        return Code.FailedPrecondition;
+    if (status === 429)
+        return Code.ResourceExhausted;
+    if (status === 499)
+        return Code.Canceled;
+    if (status === 501)
+        return Code.Unimplemented;
+    if (status === 503)
+        return Code.Unavailable;
+    if (status === 504)
+        return Code.DeadlineExceeded;
+    return Code.Internal;
+}
+export function toHttpError(error, options) {
+    if (error instanceof HttpException) {
+        return {
+            status: error.status,
+            body: error.getResponse(),
+        };
+    }
+    if (error instanceof ConnectError) {
+        const status = connectCodeToHttpStatus(error.code);
+        const isInternal = status >= 500;
+        return {
+            status,
+            body: {
+                statusCode: status,
+                message: isInternal ? internalErrorMessage(error, options) : error.message,
+                code: error.code,
+            },
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            status: 500,
+            body: {
+                statusCode: 500,
+                message: internalErrorMessage(error, options),
+                error: error.name,
+            },
+        };
+    }
+    return {
+        status: 500,
+        body: {
+            statusCode: 500,
+            message: "Internal Server Error",
+        },
+    };
+}
+export function toConnectError(error, options) {
+    if (error instanceof ConnectError) {
+        if (error.code === Code.Internal && !options?.exposeInternalErrors) {
+            return new ConnectError("Internal Server Error", error.code);
+        }
+        return error;
+    }
+    if (error instanceof HttpException) {
+        const code = httpStatusToConnectCode(error.status);
+        if (code === Code.Internal && !options?.exposeInternalErrors) {
+            return new ConnectError("Internal Server Error", code);
+        }
+        return new ConnectError(error.message, code);
+    }
+    if (error instanceof Error) {
+        return new ConnectError(internalErrorMessage(error, options), Code.Internal);
+    }
+    return new ConnectError("Internal Server Error", Code.Internal);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+export { Application } from "./application";
+export { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from "./app-tokens";
+export { BadRequestException, ForbiddenException, HttpException, InternalServerErrorException, NotFoundException, UnauthorizedException, } from "./errors";
+export { Reflector } from "./reflector";
+export type * from "../types";

package/dist/core/index.js

@@ -0,0 +1,4 @@
+export { Application } from "./application";
+export { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from "./app-tokens";
+export { BadRequestException, ForbiddenException, HttpException, InternalServerErrorException, NotFoundException, UnauthorizedException, } from "./errors";
+export { Reflector } from "./reflector";

package/dist/core/logger.d.ts

@@ -0,0 +1,7 @@
+import { Logger } from "tslog";
+import type { LoggerOptions } from "../types";
+type LoggerPayload = Record<string, unknown>;
+export type AppLogger = Logger<LoggerPayload>;
+export declare const LOGGER_TOKEN: unique symbol;
+export declare function createLogger(options?: LoggerOptions): AppLogger;
+export {};

package/dist/core/logger.js

@@ -0,0 +1,12 @@
+import { Logger } from "tslog";
+export const LOGGER_TOKEN = Symbol("app:logger");
+const DEFAULT_LOGGER_OPTIONS = {
+    name: "app",
+    type: "pretty",
+};
+export function createLogger(options) {
+    return new Logger({
+        ...DEFAULT_LOGGER_OPTIONS,
+        ...(options ?? {}),
+    });
+}

package/dist/core/reflector.d.ts

@@ -0,0 +1,9 @@
+import "reflect-metadata";
+import type { MetadataKey } from "../types";
+type MetadataTarget = object | Function | undefined;
+export declare class Reflector {
+    get<T = unknown>(metadataKey: MetadataKey, target: MetadataTarget): T | undefined;
+    getAllAndOverride<T = unknown>(metadataKey: MetadataKey, targets: MetadataTarget[]): T | undefined;
+    getAllAndMerge<T = unknown[]>(metadataKey: MetadataKey, targets: MetadataTarget[]): T;
+}
+export {};

package/dist/core/reflector.js

@@ -0,0 +1,39 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import "reflect-metadata";
+import { Injectable } from "../decorators/di.decorators";
+let Reflector = class Reflector {
+    get(metadataKey, target) {
+        if (!target) {
+            return undefined;
+        }
+        return Reflect.getMetadata(metadataKey, target);
+    }
+    getAllAndOverride(metadataKey, targets) {
+        for (const target of targets) {
+            const value = this.get(metadataKey, target);
+            if (value !== undefined) {
+                return value;
+            }
+        }
+        return undefined;
+    }
+    getAllAndMerge(metadataKey, targets) {
+        const result = [];
+        for (const target of targets) {
+            const value = this.get(metadataKey, target);
+            if (Array.isArray(value)) {
+                result.push(...value);
+            }
+        }
+        return result;
+    }
+};
+Reflector = __decorate([
+    Injectable()
+], Reflector);
+export { Reflector };

package/dist/core/server.d.ts

@@ -0,0 +1,10 @@
+import "reflect-metadata";
+import { type FastifyInstance } from "fastify";
+import type { ServerOptions } from "../types";
+import { AppContainer } from "./container";
+type LegacyServerOptions = ServerOptions & {
+    di: AppContainer;
+};
+export declare function startServer(di: AppContainer, options: ServerOptions): Promise<FastifyInstance>;
+export declare function startServer(options: LegacyServerOptions): Promise<FastifyInstance>;
+export {};

package/dist/core/server.js

@@ -0,0 +1,296 @@
+import "reflect-metadata";
+import { fastifyConnectPlugin } from "@connectrpc/connect-fastify";
+import fastifyCors from "@fastify/cors";
+import Fastify from "fastify";
+import { HTTP_ROUTES_KEY } from "../decorators/http.decorators";
+import { RPC_METHODS_KEY, RPC_SERVICE_KEY } from "../decorators/rpc.decorators";
+import { registerHttpRoutes } from "../http";
+import { buildConnectRoutes } from "../rpc";
+import { AppContainer } from "./container";
+function normalizePrefix(prefix) {
+    if (!prefix) {
+        return "";
+    }
+    const trimmed = prefix.trim();
+    if (trimmed.length === 0 || trimmed === "/") {
+        return "";
+    }
+    const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    if (withLeadingSlash.length > 1 && withLeadingSlash.endsWith("/")) {
+        return withLeadingSlash.slice(0, -1);
+    }
+    return withLeadingSlash;
+}
+function mergePrefixes(...prefixes) {
+    const normalized = prefixes.map((prefix) => normalizePrefix(prefix)).filter((prefix) => prefix.length > 0);
+    return normalized.join("");
+}
+function hasRegisteredHttpHandlers(di) {
+    for (const controller of di.getHttpControllers()) {
+        const routes = Reflect.getMetadata(HTTP_ROUTES_KEY, controller);
+        if ((routes?.length ?? 0) > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasRegisteredRpcHandlers(di) {
+    for (const controller of di.getControllers()) {
+        const service = Reflect.getMetadata(RPC_SERVICE_KEY, controller);
+        if (!service) {
+            continue;
+        }
+        const methods = Reflect.getMetadata(RPC_METHODS_KEY, controller);
+        if ((methods?.length ?? 0) > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+function isValidPort(port) {
+    return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+function resolveListenPort(port, config) {
+    if (typeof port === "number" && isValidPort(port)) {
+        return port;
+    }
+    const configPort = config.APP_PORT;
+    if (typeof configPort === "number" && isValidPort(configPort)) {
+        return configPort;
+    }
+    if (typeof configPort === "string") {
+        const normalized = configPort.trim();
+        if (normalized.length > 0) {
+            const parsed = Number(normalized);
+            if (isValidPort(parsed)) {
+                return parsed;
+            }
+        }
+    }
+    throw new Error("Server port is invalid. Provide options.port or APP_PORT in range 1..65535.");
+}
+function resolveCors(options) {
+    if (options === undefined || options === false) {
+        return { enabled: false, options: {} };
+    }
+    if (options === true) {
+        return { enabled: true, options: {} };
+    }
+    const { enabled = true, ...corsOptions } = options;
+    return { enabled, options: corsOptions };
+}
+function resolveHealth(options) {
+    const defaults = {
+        enabled: false,
+        path: "/health",
+    };
+    if (options === undefined || options === false) {
+        return defaults;
+    }
+    if (options === true) {
+        return {
+            ...defaults,
+            enabled: true,
+        };
+    }
+    return {
+        enabled: options.enabled ?? true,
+        path: normalizePrefix(options.path) || defaults.path,
+        check: options.check,
+    };
+}
+function normalizeHealthResult(result) {
+    if (typeof result === "boolean") {
+        return { ok: result };
+    }
+    return {
+        ok: result.ok,
+        details: result.details,
+    };
+}
+async function runHealthCheck(check, exposeInternalErrors, logger, path) {
+    if (!check) {
+        return { ok: true };
+    }
+    try {
+        const result = await check();
+        return normalizeHealthResult(result);
+    }
+    catch (error) {
+        logger.error({
+            type: "health_check_error",
+            path,
+        }, error);
+        if (exposeInternalErrors && error instanceof Error) {
+            return {
+                ok: false,
+                details: {
+                    message: error.message,
+                    error: error.name,
+                },
+            };
+        }
+        return { ok: false };
+    }
+}
+export async function startServer(diOrOptions, options) {
+    const di = diOrOptions instanceof AppContainer ? diOrOptions : diOrOptions.di;
+    const serverOptions = diOrOptions instanceof AppContainer ? options : diOrOptions;
+    if (!serverOptions) {
+        throw new Error("Server options are required");
+    }
+    const { port, host = "0.0.0.0", prefix, httpPrefix, rpcPrefix, trustProxy, requestTimeout, connectionTimeout, keepAliveTimeout, bodyLimit, routerOptions, maxParamLength: legacyMaxParamLength, pluginTimeout, accessLogs = false, exposeInternalErrors = false, cors, health, loggerOptions, config, } = serverOptions;
+    if (loggerOptions !== undefined) {
+        di.configureLogger(loggerOptions);
+    }
+    if (config) {
+        di.configureConfig(config.schema, config.source ?? process.env);
+    }
+    di.setExposeInternalErrors(exposeInternalErrors);
+    const listenPort = resolveListenPort(port, di.getConfig());
+    const healthConfig = resolveHealth(health);
+    const http = hasRegisteredHttpHandlers(di);
+    const rpc = hasRegisteredRpcHandlers(di);
+    if (!http && !rpc && !healthConfig.enabled) {
+        throw new Error("No handlers found for HTTP or RPC. Register controllers in @Module().");
+    }
+    let server;
+    try {
+        await di.init();
+        const resolvedRouterOptions = legacyMaxParamLength === undefined
+            ? routerOptions
+            : {
+                ...(routerOptions ?? {}),
+                maxParamLength: legacyMaxParamLength,
+            };
+        server = Fastify({
+            logger: false,
+            trustProxy,
+            requestTimeout,
+            connectionTimeout,
+            keepAliveTimeout,
+            bodyLimit,
+            pluginTimeout,
+            ...(resolvedRouterOptions ? { routerOptions: resolvedRouterOptions } : {}),
+        });
+        const appLogger = di.getLogger();
+        const corsConfig = resolveCors(cors);
+        const effectiveHttpPrefix = mergePrefixes(prefix, httpPrefix);
+        const effectiveRpcPrefix = mergePrefixes(prefix, rpcPrefix);
+        server.addHook("onRequest", async (req) => {
+            const request = req;
+            request.requestStartAt = Date.now();
+        });
+        server.addHook("onResponse", async (req, reply) => {
+            const request = req;
+            const startedAt = request.requestStartAt ?? Date.now();
+            if (accessLogs) {
+                appLogger.info({
+                    type: "access",
+                    method: req.method,
+                    url: req.url,
+                    statusCode: reply.statusCode,
+                    durationMs: Date.now() - startedAt,
+                    ip: req.ip,
+                });
+            }
+            if (request.diScope) {
+                try {
+                    await di.disposeRequestScope(request.diScope);
+                }
+                catch (error) {
+                    appLogger.error({
+                        type: "request_scope_dispose_error",
+                        method: req.method,
+                        url: req.url,
+                    }, error);
+                }
+                finally {
+                    request.diScope = undefined;
+                }
+            }
+        });
+        server.addHook("onRequestAbort", async (req) => {
+            const request = req;
+            if (request.diScope) {
+                try {
+                    await di.disposeRequestScope(request.diScope);
+                }
+                catch (error) {
+                    appLogger.error({
+                        type: "request_scope_abort_dispose_error",
+                        method: req.method,
+                        url: req.url,
+                    }, error);
+                }
+                finally {
+                    request.diScope = undefined;
+                }
+            }
+        });
+        server.addHook("onClose", async () => {
+            await di.close("server.close");
+        });
+        if (corsConfig.enabled) {
+            await server.register(fastifyCors, corsConfig.options);
+        }
+        if (healthConfig.enabled) {
+            const healthUrl = mergePrefixes(effectiveHttpPrefix, healthConfig.path);
+            server.get(healthUrl || "/", async (_req, reply) => {
+                const result = await runHealthCheck(healthConfig.check, exposeInternalErrors, appLogger, healthUrl || "/");
+                reply.status(result.ok ? 200 : 503).send({
+                    status: result.ok ? "ok" : "error",
+                    type: "health",
+                    ...(result.details !== undefined ? { details: result.details } : {}),
+                });
+            });
+        }
+        if (http) {
+            registerHttpRoutes(server, di, effectiveHttpPrefix);
+        }
+        if (rpc) {
+            await server.register(fastifyConnectPlugin, {
+                prefix: effectiveRpcPrefix,
+                routes: buildConnectRoutes(di),
+            });
+        }
+        await server.listen({ port: listenPort, host });
+        return server;
+    }
+    catch (error) {
+        const logger = (() => {
+            try {
+                return di.getLogger();
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (logger) {
+            logger.error({
+                type: "server_start_failed",
+                host,
+                port: listenPort,
+            }, error);
+        }
+        if (server) {
+            try {
+                await server.close();
+            }
+            catch (closeError) {
+                if (logger) {
+                    logger.error({ type: "server_start_cleanup_error", stage: "server.close" }, closeError);
+                }
+            }
+        }
+        try {
+            await di.close("server.start_failed");
+        }
+        catch (closeError) {
+            if (logger) {
+                logger.error({ type: "server_start_cleanup_error", stage: "di.close" }, closeError);
+            }
+        }
+        throw error;
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface HttpRouteMeta {
+    method: HttpMethod;
+    path: string;
+    handlerName: string;
+}
+export type HttpParamSource = "body" | "query" | "param" | "header" | "req" | "res";
+export interface HttpParamMeta {
+    index: number;
+    source: HttpParamSource;
+    key?: string;
+}
+export type RpcParamSource = "data" | "context" | "headers" | "header";
+export interface RpcParamMeta {
+    index: number;
+    source: RpcParamSource;
+    key?: string;
+}
+export type RpcServiceDescriptor = Parameters<ConnectRouter["service"]>[0];
+export type RpcMethodDescriptor = Parameters<ConnectRouter["rpc"]>[0];
+export interface RpcMethodMeta {
+    method: RpcMethodDescriptor;
+    handlerName: string;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/decorators/di.decorators.d.ts

@@ -0,0 +1,10 @@
+import "reflect-metadata";
+import { inject, injectAll, injectable, Lifecycle } from "tsyringe";
+import type { InjectionToken, ModuleMeta } from "../types";
+export declare const MODULE_KEY: unique symbol;
+export declare function Module(meta: ModuleMeta): ClassDecorator;
+export declare const Injectable: typeof injectable;
+export declare const Inject: typeof inject;
+export declare const InjectAll: typeof injectAll;
+export declare const Scope: typeof Lifecycle;
+export declare function Optional(token: InjectionToken<unknown>): ParameterDecorator;

package/dist/decorators/di.decorators.js

@@ -0,0 +1,15 @@
+import "reflect-metadata";
+import { inject, injectAll, injectable, Lifecycle } from "tsyringe";
+export const MODULE_KEY = Symbol("module");
+export function Module(meta) {
+    return (target) => {
+        Reflect.defineMetadata(MODULE_KEY, meta, target);
+    };
+}
+export const Injectable = injectable;
+export const Inject = inject;
+export const InjectAll = injectAll;
+export const Scope = Lifecycle;
+export function Optional(token) {
+    return inject(token, { isOptional: true });
+}

package/dist/decorators/filters.decorators.d.ts

@@ -0,0 +1,6 @@
+import "reflect-metadata";
+import type { Constructor, ExceptionFilterLike } from "../types";
+export declare const FILTERS_KEY: unique symbol;
+export declare const CATCH_EXCEPTIONS_KEY: unique symbol;
+export declare function UseFilters(...filters: ExceptionFilterLike[]): ClassDecorator & MethodDecorator;
+export declare function Catch(...exceptions: Constructor[]): ClassDecorator;

package/dist/decorators/filters.decorators.js

@@ -0,0 +1,16 @@
+import "reflect-metadata";
+import { Injectable } from "./di.decorators";
+import { appendArrayMetadata } from "./metadata.decorators";
+export const FILTERS_KEY = Symbol("filters");
+export const CATCH_EXCEPTIONS_KEY = Symbol("filter:exceptions");
+export function UseFilters(...filters) {
+    return (target, propertyKey) => {
+        appendArrayMetadata(FILTERS_KEY, filters, target, propertyKey);
+    };
+}
+export function Catch(...exceptions) {
+    return (target) => {
+        Injectable()(target);
+        Reflect.defineMetadata(CATCH_EXCEPTIONS_KEY, exceptions, target);
+    };
+}

package/dist/decorators/guards.decorators.d.ts

@@ -0,0 +1,4 @@
+import "reflect-metadata";
+import type { GuardLike } from "../types";
+export declare const GUARDS_KEY: unique symbol;
+export declare function UseGuards(...guards: GuardLike[]): ClassDecorator & MethodDecorator;