@smounters/imperium 1.1.0 → 1.1.1

package/README.md

@@ -1,41 +1,24 @@
 # @smounters/imperium
 
-`@smounters/imperium` is **inspired by NestJS** and provides a modular DI-first runtime for TypeScript services using Fastify + ConnectRPC + WebSocket.
+NestJS-inspired modular DI framework for TypeScript services. Unified HTTP + ConnectRPC + WebSocket server on a single Fastify instance.
 
-It is designed for teams that want Nest-like architecture but with explicit control over runtime wiring and exported API surface.
+## Features
 
-## Key Features
+- **Module system** with `@Module`, `@Injectable`, guards, pipes, interceptors, filters
+- **HTTP controllers** with `@HttpController`, `@Get`, `@Post`, `@Body`, `@Query`, `@Param`
+- **ConnectRPC** with `@RpcService`, `@RpcMethod` (unary + server streaming)
+- **WebSocket gateway** with `@WsGateway`, `@WsHandler`, message routing, lifecycle hooks
+- **Request-scoped DI** via AsyncLocalStorage (tsyringe-based)
+- **Typed config** via Zod + `ConfigService`
+- **Structured logging** via tslog + `LoggerService`
 
-- Nest-like modules and decorators (`@Module`, `@Injectable`, guards/pipes/interceptors/filters).
-- Unified HTTP + RPC + WebSocket server on one Fastify instance.
-- Server streaming RPC via `async function*` (delivered as SSE in browsers).
-- WebSocket gateway with message routing, lifecycle hooks, and guards at connection time.
-- 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`
-- `@smounters/imperium/ws`
-
-## Installation
+## Install
 
 ```bash
-pnpm add @smounters/imperium reflect-metadata tsyringe fastify @connectrpc/connect @connectrpc/connect-fastify zod
+pnpm add @smounters/imperium reflect-metadata tsyringe fastify @connectrpc/connect @connectrpc/connect-fastify zod tslog
 ```
 
-TypeScript requirements:
+TypeScript config requires:
 
 ```json
 {
@@ -46,220 +29,78 @@ TypeScript requirements:
 }
 ```
 
-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 };
+class GreetService {
+  greet(name: string) {
+    return { message: `Hello, ${name}` };
   }
 }
 
-@HttpController("/auth")
-class AuthHttpController {
-  constructor(private readonly authService: AuthService) {}
+@HttpController("/api")
+class ApiController {
+  constructor(private readonly greetService: GreetService) {}
 
-  @Post("/sign-in")
-  signIn(@Body("email") email: string) {
-    return this.authService.signIn(email);
+  @Post("/greet")
+  greet(@Body("name") name: string) {
+    return this.greetService.greet(name);
   }
 }
 
 @Module({
-  providers: [AuthService],
-  httpControllers: [AuthHttpController],
+  providers: [GreetService],
+  httpControllers: [ApiController],
 })
 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 { appConfigSchema, type AppConfig } from "@smounters/imperium/validation";
-
-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 });
+await new Application(AppModule).start({ port: 3000 });
 ```
 
-If your app needs extra config fields, extend the exported base schema:
-
-```ts
-import { appConfigSchema } from "@smounters/imperium/validation";
-import { z } from "zod";
-
-const projectConfigSchema = appConfigSchema.extend({
-  REDIS_URL: z.url(),
-});
-```
-
-## 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`, `RpcAbortSignal`
-- WebSocket: `WsGateway`, `WsHandler`, `WsConnection`, `WsMessage`, `WsRequest`
-
-Imperium auto-detects registered HTTP/RPC/WebSocket handlers and serves all protocols from one server.
-
 ## WebSocket
 
 ```ts
-import { WsGateway, WsHandler, WsConnection, WsMessage, Module } from "@smounters/imperium/decorators";
+import { WsGateway, WsHandler, WsConnection, WsMessage } from "@smounters/imperium/decorators";
 import type { WsGatewayLifecycle } from "@smounters/imperium/ws";
 import type { WebSocket } from "@fastify/websocket";
 
 @WsGateway("/ws")
-class ChatGateway implements WsGatewayLifecycle {
+class EventsGateway implements WsGatewayLifecycle {
   private clients = new Set<WebSocket>();
 
   onConnection(socket: WebSocket) { this.clients.add(socket); }
   onDisconnect(socket: WebSocket) { this.clients.delete(socket); }
 
-  @WsHandler("message")
-  onMessage(@WsConnection() ws: WebSocket, @WsMessage() data: { text: string }) {
-    const msg = JSON.stringify({ type: "message", data });
-    for (const client of this.clients) {
-      if (client.readyState === 1) client.send(msg);
-    }
+  @WsHandler("ping")
+  onPing(@WsConnection() ws: WebSocket) {
+    ws.send(JSON.stringify({ type: "pong" }));
   }
 }
-
-@Module({ providers: [ChatGateway] })
-class AppModule {}
 ```
 
 Requires optional peer dependency: `pnpm add @fastify/websocket`
 
-## Services
-
-From `@smounters/imperium/services`:
-
-- `ConfigService`
-- `LoggerService`
-
-## Pipes and Validation
-
-- `ZodPipe` from `@smounters/imperium/pipes`
-- validation helpers from `@smounters/imperium/validation`
-  - `appConfigSchema`
-  - `AppConfig`
-  - `booleanSchema`
-  - `numberSchema`
-  - `nativeEnumSchema`
-  - `stringArraySchema`
-  - `enumArraySchema`
-
-## Error Classes
-
-From `@smounters/imperium/core`:
+## Import Paths
 
-- `HttpException`
-- `BadRequestException`
-- `UnauthorizedException`
-- `ForbiddenException`
-- `NotFoundException`
-- `InternalServerErrorException`
+No root import. Use subpaths:
 
-## 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
+```ts
+import { Application } from "@smounters/imperium/core";
+import { Module, Injectable, HttpController, Get } from "@smounters/imperium/decorators";
+import { ConfigService, LoggerService } from "@smounters/imperium/services";
+import { ZodPipe } from "@smounters/imperium/pipes";
+import { appConfigSchema } from "@smounters/imperium/validation";
+import { registerWsGateways } from "@smounters/imperium/ws";
 ```
 
-Automated npm publishing workflow:
-
-- `.github/workflows/publish.yml`
-
-Required secret:
+## Documentation
 
-- `NPM_TOKEN`
+Full guide and API reference: **[smounters.github.io/imperium](https://smounters.github.io/imperium/)**
 
 ## License
 

package/dist/core/container.js

@@ -229,7 +229,7 @@ export class AppContainer {
             return provider.useValue;
         }
         if ("useFactory" in provider) {
-            return provider.useFactory(moduleRef.container);
+            return (provider).useFactory(moduleRef.container);
         }
         if ("useExisting" in provider) {
             return moduleRef.container.resolve(provider.useExisting);
@@ -281,7 +281,7 @@ export class AppContainer {
         }
         if ("useFactory" in provider) {
             moduleRef.container.register(provider.provide, {
-                useFactory: (dc) => provider.useFactory(dc),
+                useFactory: (dc) => (provider).useFactory(dc),
             });
             return;
         }
@@ -467,9 +467,7 @@ export class AppContainer {
     }
     loadModule(moduleImport) {
         const moduleRef = this.loadModuleRef(moduleImport);
-        if (!this.rootModuleRef) {
-            this.rootModuleRef = moduleRef;
-        }
+        this.rootModuleRef ??= moduleRef;
     }
     resolve(token) {
         if (this.root.isRegistered(token, false)) {

package/dist/core/server.js

@@ -179,9 +179,10 @@ export async function startServer(diOrOptions, options) {
         const corsConfig = resolveCors(cors);
         const effectiveHttpPrefix = mergePrefixes(prefix, httpPrefix);
         const effectiveRpcPrefix = mergePrefixes(prefix, rpcPrefix);
-        server.addHook("onRequest", async (req) => {
+        server.addHook("onRequest", (req, _reply, done) => {
             const request = req;
             request.requestStartAt = Date.now();
+            done();
         });
         server.addHook("onResponse", async (req, reply) => {
             const request = req;

package/dist/types.d.ts

@@ -39,8 +39,7 @@ interface BaseModuleMeta {
     exports?: InjectionToken[];
     global?: boolean;
 }
-export interface ModuleMeta extends BaseModuleMeta {
-}
+export type ModuleMeta = BaseModuleMeta;
 export interface DynamicModule extends BaseModuleMeta {
     module: Constructor;
     id?: string;
@@ -70,9 +69,9 @@ export interface RpcArgumentsHost {
     getContext<T = unknown>(): T | undefined;
 }
 export interface WsArgumentsHost {
-    getSocket<T = unknown>(): T | undefined;
+    getSocket(): unknown;
     getRequest(): FastifyRequest | undefined;
-    getMessage<T = unknown>(): T | undefined;
+    getMessage(): unknown;
 }
 export interface BaseContext {
     type: ContextType;
@@ -115,7 +114,7 @@ export interface PipeTransform<TIn = unknown, TOut = unknown> {
 }
 export type PipeLike = Constructor<PipeTransform> | PipeTransform;
 export interface ExceptionFilter<T = unknown> {
-    catch(exception: T, ctx: BaseContext): Promise<unknown> | unknown;
+    catch(exception: T, ctx: BaseContext): unknown;
 }
 export type ExceptionFilterLike = Constructor<ExceptionFilter> | ExceptionFilter;
 export interface ConfigServiceOptions<TSchema extends ZodType = ZodType> {
@@ -124,7 +123,7 @@ export interface ConfigServiceOptions<TSchema extends ZodType = ZodType> {
 }
 export interface CorsOptions {
     enabled?: boolean;
-    origin?: string | boolean | RegExp | Array<string | boolean | RegExp>;
+    origin?: string | boolean | RegExp | (string | boolean | RegExp)[];
     credentials?: boolean;
     exposedHeaders?: string | string[];
     allowedHeaders?: string | string[];

package/dist/ws/adapter.js

@@ -104,9 +104,9 @@ export function handleWsConnection(app, gateway, socket, request) {
         }
         // Route messages to handlers
         socket.on("message", (raw) => {
-            (async () => {
+            void (async () => {
                 try {
-                    const msg = JSON.parse(raw.toString());
+                    const msg = JSON.parse(String(raw));
                     const handler = handlers.find((h) => h.messageType === msg.type);
                     if (!handler) {
                         return;
@@ -125,7 +125,7 @@ export function handleWsConnection(app, gateway, socket, request) {
         });
         // Cleanup on disconnect
         socket.on("close", () => {
-            (async () => {
+            void (async () => {
                 try {
                     if (typeof instance.onDisconnect === "function") {
                         await instance.onDisconnect(socket);
@@ -162,6 +162,7 @@ export function handleWsConnection(app, gateway, socket, request) {
         catch {
             // socket may already be closed
         }
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
         app.disposeRequestScope(scope).catch(() => { });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smounters/imperium",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "NestJS-like modular DI container with unified HTTP + Connect RPC server for TypeScript",
   "keywords": [
     "di",
@@ -64,6 +64,8 @@
     "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "clean": "rm -rf dist",
     "docs:dev": "pnpm exec vitepress dev docs",
     "docs:build": "pnpm exec vitepress build docs",
@@ -91,11 +93,11 @@
   "devDependencies": {
     "@connectrpc/connect": "^2.1.1",
     "@connectrpc/connect-fastify": "^2.1.1",
+    "@eslint/js": "^10.0.1",
     "@fastify/cors": "^11.2.0",
     "@fastify/websocket": "^11.2.0",
     "@types/node": "^25.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.2",
-    "@typescript-eslint/parser": "^8.57.2",
+    "@types/ws": "^8.18.1",
     "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "fastify": "^5.8.4",
@@ -104,7 +106,11 @@
     "tslog": "^4.10.2",
     "tsyringe": "^4.10.0",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.3",
     "vitepress": "^1.6.4",
+    "vitest": "^4.1.2",
+    "ws": "^8.20.0",
     "zod": "^4.3.6"
   }
 }