@smounters/imperium 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@smounters/imperium` are documented in this file.
+
+## 0.1.0 - 2026-02-22
+
+- Initial public package setup.
+- Unified HTTP + ConnectRPC runtime on Fastify.
+- NestJS-inspired module/decorator/DI API.
+- Typed `Application` bootstrap with pre-start `configureConfig` and `configureLogger`.
+- Multi provider intent metadata (`multi`) and array resolution via `InjectAll` / `resolveAll`.
+- VitePress documentation and GitHub Pages workflow.
+- npm publish workflow with `pnpm`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CryppEX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# @smounters/imperium
+
+`@smounters/imperium` is **inspired by NestJS** and provides a modular DI-first runtime for TypeScript services using Fastify + ConnectRPC.
+
+It is designed for teams that want Nest-like architecture but with explicit control over runtime wiring and exported API surface.
+
+## Key Features
+
+- Nest-like modules and decorators (`@Module`, `@Injectable`, guards/pipes/interceptors/filters).
+- Unified HTTP + RPC server on one Fastify instance.
+- Request-scoped handler execution.
+- Typed runtime config via `zod` + `ConfigService`.
+- Built-in `LoggerService` (tslog-based).
+- Global enhancer tokens (`APP_GUARD`, `APP_PIPE`, `APP_INTERCEPTOR`, `APP_FILTER`).
+- Multi-provider array injection (`InjectAll`) and manual array resolution (`resolveAll`).
+
+## Public Imports
+
+Root import is intentionally disabled.
+
+Use subpaths only:
+
+- `@smounters/imperium/core`
+- `@smounters/imperium/decorators`
+- `@smounters/imperium/services`
+- `@smounters/imperium/pipes`
+- `@smounters/imperium/validation`
+
+## Installation
+
+```bash
+pnpm add @smounters/imperium reflect-metadata tsyringe fastify @connectrpc/connect @connectrpc/connect-fastify zod
+```
+
+TypeScript requirements:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+Entry point must import metadata:
+
+```ts
+import "reflect-metadata";
+```
+
+## Quick Start
+
+```ts
+import "reflect-metadata";
+
+import { Application } from "@smounters/imperium/core";
+import { Body, HttpController, Injectable, Module, Post } from "@smounters/imperium/decorators";
+
+@Injectable()
+class AuthService {
+  signIn(email: string) {
+    return { ok: true, email };
+  }
+}
+
+@HttpController("/auth")
+class AuthHttpController {
+  constructor(private readonly authService: AuthService) {}
+
+  @Post("/sign-in")
+  signIn(@Body("email") email: string) {
+    return this.authService.signIn(email);
+  }
+}
+
+@Module({
+  providers: [AuthService],
+  httpControllers: [AuthHttpController],
+})
+class AppModule {}
+
+const app = new Application(AppModule, {
+  host: "0.0.0.0",
+  accessLogs: true,
+});
+
+await app.start({ port: 3000 });
+```
+
+## Recommended Bootstrap Flow
+
+```ts
+import { Application } from "@smounters/imperium/core";
+import { ConfigService, LoggerService } from "@smounters/imperium/services";
+import { z } from "zod";
+
+const appConfigSchema = z.object({
+  APP_PORT: z.coerce.number().default(8000),
+  APP_GLOBAL_PREFIX: z.string().default(""),
+});
+
+type AppConfig = z.infer<typeof appConfigSchema>;
+
+const app = new Application(AppModule, {
+  host: "0.0.0.0",
+  accessLogs: true,
+});
+
+app.configureConfig(appConfigSchema, process.env);
+
+const config = app.resolve(ConfigService<AppConfig>).getAll();
+
+app.configureLogger({
+  name: "backend",
+  minLevel: 3,
+});
+
+await app.start({
+  port: config.APP_PORT,
+  prefix: config.APP_GLOBAL_PREFIX,
+});
+
+app.resolve(LoggerService).info({ event: "app.started", port: config.APP_PORT });
+```
+
+## Multi Providers
+
+```ts
+import { InjectAll, Injectable, Module } from "@smounters/imperium/decorators";
+
+const AML_RULES = Symbol("AML_RULES");
+
+@Module({
+  providers: [
+    { provide: AML_RULES, multi: true, useClass: SanctionsRule },
+    { provide: AML_RULES, multi: true, useClass: MixerRule },
+    { provide: AML_RULES, multi: true, useClass: FreshAddressRule },
+  ],
+  exports: [AML_RULES],
+})
+class AmlModule {}
+
+@Injectable()
+class AmlEngine {
+  constructor(@InjectAll(AML_RULES) private readonly rules: AmlRule[]) {}
+}
+```
+
+Manual resolution is also available:
+
+```ts
+const rules = app.resolveAll<AmlRule>(AML_RULES);
+```
+
+## HTTP and RPC
+
+Use decorators from `@smounters/imperium/decorators`:
+
+- HTTP: `HttpController`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `Body`, `Query`, `Param`, `Header`, `Req`, `Res`
+- RPC: `RpcService`, `RpcMethod`, `RpcData`, `RpcContext`, `RpcHeaders`, `RpcHeader`
+
+Imperium auto-detects registered HTTP/RPC handlers and serves both protocols from one server.
+
+## Services
+
+From `@smounters/imperium/services`:
+
+- `ConfigService`
+- `LoggerService`
+
+## Pipes and Validation
+
+- `ZodPipe` from `@smounters/imperium/pipes`
+- validation helpers from `@smounters/imperium/validation`
+  - `booleanSchema`
+  - `numberSchema`
+  - `nativeEnumSchema`
+  - `stringArraySchema`
+  - `enumArraySchema`
+
+## Error Classes
+
+From `@smounters/imperium/core`:
+
+- `HttpException`
+- `BadRequestException`
+- `UnauthorizedException`
+- `ForbiddenException`
+- `NotFoundException`
+- `InternalServerErrorException`
+
+## Documentation
+
+Full docs (VitePress) are located in:
+
+- `docs`
+
+Local docs commands:
+
+```bash
+pnpm run docs:dev
+pnpm run docs:build
+```
+
+GitHub Pages deployment is configured via `.github/workflows/publish.yml`.
+
+## Publish to npm
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm run build
+pnpm publish --access public --no-git-checks
+```
+
+Automated npm publishing workflow:
+
+- `.github/workflows/publish.yml`
+
+Required secret:
+
+- `NPM_TOKEN`
+
+## License
+
+MIT

package/dist/core/app-tokens.d.ts

@@ -0,0 +1,5 @@
+import type { ExceptionFilterLike, GuardLike, InjectionToken, InterceptorLike, PipeLike } from "../types";
+export declare const APP_GUARD: InjectionToken<GuardLike>;
+export declare const APP_INTERCEPTOR: InjectionToken<InterceptorLike>;
+export declare const APP_PIPE: InjectionToken<PipeLike>;
+export declare const APP_FILTER: InjectionToken<ExceptionFilterLike>;

package/dist/core/app-tokens.js

@@ -0,0 +1,4 @@
+export const APP_GUARD = Symbol("app:guard");
+export const APP_INTERCEPTOR = Symbol("app:interceptor");
+export const APP_PIPE = Symbol("app:pipe");
+export const APP_FILTER = Symbol("app:filter");

package/dist/core/application.d.ts

@@ -0,0 +1,34 @@
+import type { FastifyInstance } from "fastify";
+import type { InjectionToken, LoggerOptions, ModuleImport, ServerOptions } from "../types";
+import type { ZodType, output } from "zod";
+import { AppContainer } from "./container";
+export declare class Application {
+    private static readonly DEFAULT_SHUTDOWN_SIGNALS;
+    private static readonly DEFAULT_SHUTDOWN_TIMEOUT_MS;
+    private readonly moduleImport;
+    private readonly di;
+    private options;
+    private readonly signalHandlers;
+    private moduleLoaded;
+    private loggerConfiguredExplicitly;
+    private server;
+    private startPromise;
+    private shutdownInProgress;
+    constructor(moduleClass: ModuleImport, options?: ServerOptions);
+    getContainer(): AppContainer;
+    resolve<T>(token: InjectionToken<T>): T;
+    resolveAll<T>(token: InjectionToken<T>): T[];
+    getServerOptions(): Readonly<ServerOptions>;
+    setServerOptions(options: ServerOptions): this;
+    configureLogger(options?: LoggerOptions): this;
+    configureConfig<TSchema extends ZodType>(schema: TSchema, source?: unknown): output<TSchema>;
+    getServer(): FastifyInstance;
+    start(options?: ServerOptions): Promise<FastifyInstance>;
+    close(signal?: string): Promise<void>;
+    private resolveGracefulShutdownOptions;
+    private installSignalHandlers;
+    private removeSignalHandlers;
+    private handleShutdownSignal;
+    private assertConfigurable;
+    private ensureModuleLoaded;
+}

package/dist/core/application.js

@@ -0,0 +1,252 @@
+import { AppContainer } from "./container";
+import { startServer } from "./server";
+export class Application {
+    static { this.DEFAULT_SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"]; }
+    static { this.DEFAULT_SHUTDOWN_TIMEOUT_MS = 15_000; }
+    constructor(moduleClass, options = {}) {
+        this.signalHandlers = new Map();
+        this.moduleLoaded = false;
+        this.loggerConfiguredExplicitly = false;
+        this.server = null;
+        this.startPromise = null;
+        this.shutdownInProgress = false;
+        this.moduleImport = moduleClass;
+        this.di = new AppContainer();
+        this.options = options;
+    }
+    getContainer() {
+        return this.di;
+    }
+    resolve(token) {
+        try {
+            return this.di.resolve(token);
+        }
+        catch (initialError) {
+            if (!this.moduleLoaded) {
+                this.ensureModuleLoaded();
+                return this.di.resolve(token);
+            }
+            throw initialError;
+        }
+    }
+    resolveAll(token) {
+        try {
+            return this.di.resolveAll(token);
+        }
+        catch (initialError) {
+            if (!this.moduleLoaded) {
+                this.ensureModuleLoaded();
+                return this.di.resolveAll(token);
+            }
+            throw initialError;
+        }
+    }
+    getServerOptions() {
+        return { ...this.options };
+    }
+    setServerOptions(options) {
+        this.assertConfigurable("set server options");
+        this.options = {
+            ...this.options,
+            ...options,
+        };
+        return this;
+    }
+    configureLogger(options) {
+        this.assertConfigurable("configure logger");
+        this.di.configureLogger(options);
+        this.loggerConfiguredExplicitly = true;
+        return this;
+    }
+    configureConfig(schema, source = process.env) {
+        this.assertConfigurable("configure config");
+        return this.di.configureConfig(schema, source);
+    }
+    getServer() {
+        if (!this.server) {
+            throw new Error("Application is not started");
+        }
+        return this.server;
+    }
+    async start(options = {}) {
+        if (this.server) {
+            return this.server;
+        }
+        if (this.startPromise) {
+            return this.startPromise;
+        }
+        const resolvedOptions = {
+            ...this.options,
+            ...options,
+        };
+        this.options = resolvedOptions;
+        const startOptions = this.loggerConfiguredExplicitly && resolvedOptions.loggerOptions !== undefined
+            ? {
+                ...resolvedOptions,
+                loggerOptions: undefined,
+            }
+            : resolvedOptions;
+        this.startPromise = (async () => {
+            this.ensureModuleLoaded();
+            const server = await startServer(this.di, startOptions);
+            this.server = server;
+            this.installSignalHandlers(startOptions);
+            return server;
+        })();
+        try {
+            return await this.startPromise;
+        }
+        finally {
+            this.startPromise = null;
+        }
+    }
+    async close(signal = "application.close") {
+        if (this.startPromise && !this.server) {
+            try {
+                await this.startPromise;
+            }
+            catch {
+                // Ignore startup failures here: startServer() already performs cleanup.
+            }
+        }
+        if (this.server) {
+            const server = this.server;
+            try {
+                await server.close();
+                this.server = null;
+                this.removeSignalHandlers();
+                return;
+            }
+            catch (error) {
+                this.server = server;
+                throw error;
+            }
+        }
+        await this.di.close(signal);
+        this.removeSignalHandlers();
+    }
+    resolveGracefulShutdownOptions(serverOptions) {
+        const raw = serverOptions.gracefulShutdown;
+        if (raw === false) {
+            return {
+                enabled: false,
+                signals: Application.DEFAULT_SHUTDOWN_SIGNALS,
+                timeoutMs: Application.DEFAULT_SHUTDOWN_TIMEOUT_MS,
+                forceExitOnFailure: false,
+            };
+        }
+        if (raw === undefined || raw === true) {
+            return {
+                enabled: true,
+                signals: Application.DEFAULT_SHUTDOWN_SIGNALS,
+                timeoutMs: Application.DEFAULT_SHUTDOWN_TIMEOUT_MS,
+                forceExitOnFailure: false,
+            };
+        }
+        const options = raw;
+        const timeoutMs = typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+            ? options.timeoutMs
+            : Application.DEFAULT_SHUTDOWN_TIMEOUT_MS;
+        return {
+            enabled: options.enabled ?? true,
+            signals: options.signals?.length ? options.signals : Application.DEFAULT_SHUTDOWN_SIGNALS,
+            timeoutMs,
+            forceExitOnFailure: options.forceExitOnFailure ?? false,
+        };
+    }
+    installSignalHandlers(serverOptions) {
+        if (this.signalHandlers.size > 0) {
+            return;
+        }
+        const shutdown = this.resolveGracefulShutdownOptions(serverOptions);
+        if (!shutdown.enabled) {
+            return;
+        }
+        for (const signal of shutdown.signals) {
+            const handler = () => {
+                void this.handleShutdownSignal(signal, shutdown.timeoutMs, shutdown.forceExitOnFailure);
+            };
+            process.on(signal, handler);
+            this.signalHandlers.set(signal, handler);
+        }
+    }
+    removeSignalHandlers() {
+        if (this.signalHandlers.size === 0) {
+            return;
+        }
+        for (const [signal, handler] of this.signalHandlers) {
+            if (typeof process.off === "function") {
+                process.off(signal, handler);
+            }
+            else {
+                process.removeListener(signal, handler);
+            }
+        }
+        this.signalHandlers.clear();
+    }
+    async handleShutdownSignal(signal, timeoutMs, forceExitOnFailure) {
+        if (this.shutdownInProgress) {
+            return;
+        }
+        this.shutdownInProgress = true;
+        const logger = this.di.getLogger();
+        let timeoutId;
+        let shutdownFailed = false;
+        logger.info({
+            type: "shutdown",
+            stage: "received",
+            signal,
+            timeoutMs,
+            forceExitOnFailure,
+        });
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+                reject(new Error(`Graceful shutdown timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            if (typeof timeoutId.unref === "function") {
+                timeoutId.unref();
+            }
+        });
+        try {
+            await Promise.race([this.close(`signal:${signal}`), timeoutPromise]);
+            logger.info({
+                type: "shutdown",
+                stage: "completed",
+                signal,
+            });
+        }
+        catch (error) {
+            shutdownFailed = true;
+            logger.error({
+                type: "shutdown",
+                stage: "failed",
+                signal,
+                forceExitOnFailure,
+            }, error);
+            process.exitCode = 1;
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            if (shutdownFailed) {
+                if (forceExitOnFailure) {
+                    process.exit(1);
+                }
+                this.shutdownInProgress = false;
+            }
+        }
+    }
+    assertConfigurable(action) {
+        if (this.server || this.startPromise) {
+            throw new Error(`Cannot ${action} after application start`);
+        }
+    }
+    ensureModuleLoaded() {
+        if (this.moduleLoaded) {
+            return;
+        }
+        this.di.loadModule(this.moduleImport);
+        this.moduleLoaded = true;
+    }
+}

package/dist/core/config.d.ts

@@ -0,0 +1 @@
+export declare const CONFIG_TOKEN: unique symbol;

package/dist/core/config.js

@@ -0,0 +1 @@
+export const CONFIG_TOKEN = Symbol("app:config");

package/dist/core/container.d.ts

@@ -0,0 +1,76 @@
+import "reflect-metadata";
+import { type DependencyContainer } from "tsyringe";
+import type { Constructor, ExceptionFilterLike, GuardLike, InjectionToken, InterceptorLike, LoggerOptions, ModuleImport, PipeLike } from "../types";
+import type { ZodType, output } from "zod";
+import { type AppLogger } from "./logger";
+export declare class AppContainer {
+    private readonly root;
+    private readonly loadedModules;
+    private readonly dynamicModuleSignatures;
+    private readonly globalExportOwners;
+    private readonly loadingModules;
+    private readonly rpcControllerSet;
+    private readonly httpControllerSet;
+    private readonly rpcControllerModules;
+    private readonly httpControllerModules;
+    private readonly lifecycleTargets;
+    private readonly requestScopeOwners;
+    private readonly requestScopeLinkedScopes;
+    private readonly requestContextStorage;
+    private rootModuleRef;
+    private controllers;
+    private httpControllers;
+    private lifecycleInstances;
+    private initialized;
+    private closed;
+    private exposeInternalErrors;
+    private globalGuards;
+    private globalInterceptors;
+    private globalPipes;
+    private globalFilters;
+    constructor();
+    private addLifecycleTarget;
+    private getLifecycleInstances;
+    private normalizeModuleImport;
+    private readModuleMetadata;
+    private mergeModuleMetadata;
+    private collectProviderTokens;
+    private linkImportedExports;
+    private resolveAppEnhancerInstance;
+    private registerAppEnhancerProvider;
+    private registerProvider;
+    private resolveModuleExports;
+    private registerGlobalExports;
+    private resolveControllerModule;
+    private getOrCreateLinkedScopes;
+    private getModuleScopeForRequest;
+    private resolveTokenFromModuleScope;
+    private assertRuntimeConfigMutable;
+    private loadModuleRef;
+    loadModule(moduleImport: ModuleImport): void;
+    resolve<T>(token: InjectionToken<T>): T;
+    resolveAll<T>(token: InjectionToken<T>): T[];
+    setLogger(logger: AppLogger): void;
+    configureLogger(options?: LoggerOptions): AppLogger;
+    getLogger(): AppLogger;
+    setExposeInternalErrors(value: boolean): void;
+    shouldExposeInternalErrors(): boolean;
+    setConfig<TConfig extends Record<string, unknown>>(config: TConfig): void;
+    configureConfig<TSchema extends ZodType>(schema: TSchema, source?: unknown): output<TSchema>;
+    getConfig<TConfig extends Record<string, unknown> = Record<string, unknown>>(): Readonly<TConfig>;
+    init(): Promise<void>;
+    close(signal?: string): Promise<void>;
+    runInRequestScope<T>(scope: DependencyContainer, execute: () => Promise<T> | T): Promise<T>;
+    disposeRequestScope(scope: DependencyContainer): Promise<void>;
+    createRequestScope(controller?: Constructor): DependencyContainer;
+    getControllers(): Constructor[];
+    getHttpControllers(): Constructor[];
+    setGlobalGuards(guards: GuardLike[]): void;
+    getGlobalGuards(): GuardLike[];
+    setGlobalInterceptors(inters: InterceptorLike[]): void;
+    getGlobalInterceptors(): InterceptorLike[];
+    setGlobalPipes(pipes: PipeLike[]): void;
+    getGlobalPipes(): PipeLike[];
+    setGlobalFilters(filters: ExceptionFilterLike[]): void;
+    getGlobalFilters(): ExceptionFilterLike[];
+}