@smounters/imperium 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@smounters/imperium` are documented in this file.
 
+## 1.2.0 - 2026-03-30
+
+### Added
+- **Pluggable logger transports** — `LogTransport` interface, `ImperiumLogger` class, `consoleTransport()` factory.
+- **Global `onError` callback** — single error reporting point for HTTP, RPC, WebSocket, cron, and event handler errors. Integrates with Sentry, OTLP, or any custom reporter.
+- New types: `LogLevel`, `LogEntry`, `LogTransport`, `ImperiumLoggerOptions`, `ErrorContext`, `ErrorContextType`, `OnErrorCallback`.
+
+### Changed
+- `LoggerOptions` is now a union of `ImperiumLoggerOptions` (transport-based) and `TslogOptions` (legacy tslog). Auto-detected from options shape.
+- All adapters (HTTP, RPC, WS) now call `reportError()` when `onError` is configured.
+- `imperium-cron` and `imperium-events` now use `LoggerService` and `onError` instead of raw `console.error`.
+
 ## 1.1.3 - 2026-03-30
 
 ### Added

package/dist/core/container.d.ts

@@ -1,6 +1,6 @@
 import "reflect-metadata";
 import { type DependencyContainer } from "tsyringe";
-import type { Constructor, ExceptionFilterLike, GuardLike, InjectionToken, InterceptorLike, LoggerOptions, ModuleImport, PipeLike } from "../types.js";
+import type { Constructor, ExceptionFilterLike, GuardLike, InjectionToken, InterceptorLike, LoggerOptions, ModuleImport, OnErrorCallback, ErrorContext, PipeLike } from "../types.js";
 import type { ZodType, output } from "zod";
 import { type AppLogger } from "./logger.js";
 export declare class AppContainer {
@@ -27,6 +27,7 @@ export declare class AppContainer {
     private initialized;
     private closed;
     private exposeInternalErrors;
+    private onErrorCallback;
     private globalGuards;
     private globalInterceptors;
     private globalPipes;
@@ -58,6 +59,9 @@ export declare class AppContainer {
     getLogger(): AppLogger;
     setExposeInternalErrors(value: boolean): void;
     shouldExposeInternalErrors(): boolean;
+    setOnError(callback: OnErrorCallback): void;
+    getOnError(): OnErrorCallback | undefined;
+    reportError(error: unknown, context: ErrorContext): void;
     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>;

package/dist/core/container.js

@@ -507,6 +507,22 @@ export class AppContainer {
     shouldExposeInternalErrors() {
         return this.exposeInternalErrors;
     }
+    setOnError(callback) {
+        this.onErrorCallback = callback;
+    }
+    getOnError() {
+        return this.onErrorCallback;
+    }
+    reportError(error, context) {
+        if (!this.onErrorCallback)
+            return;
+        try {
+            void this.onErrorCallback(error, context);
+        }
+        catch {
+            // never let error reporter break the app
+        }
+    }
     setConfig(config) {
         this.assertRuntimeConfigMutable("config");
         this.root.registerInstance(CONFIG_TOKEN, config);

package/dist/core/imperium-logger.d.ts

@@ -0,0 +1,20 @@
+import type { ImperiumLoggerOptions } from "../types.js";
+/**
+ * Native imperium logger with pluggable transports.
+ * Drop-in replacement for tslog Logger — same method signatures.
+ */
+export declare class ImperiumLogger {
+    private readonly transports;
+    private readonly minIdx;
+    private readonly name?;
+    constructor(options?: ImperiumLoggerOptions);
+    private dispatch;
+    log(_logLevelId: number, logLevelName: string, ...args: unknown[]): void;
+    silly(...args: unknown[]): void;
+    trace(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    fatal(...args: unknown[]): void;
+}

package/dist/core/imperium-logger.js

@@ -0,0 +1,59 @@
+import { consoleTransport, levelIndex } from "./log-transport.js";
+/**
+ * Native imperium logger with pluggable transports.
+ * Drop-in replacement for tslog Logger — same method signatures.
+ */
+export class ImperiumLogger {
+    constructor(options = {}) {
+        this.transports = options.transports ?? [consoleTransport()];
+        this.minIdx = levelIndex(options.minLevel ?? "silly");
+        this.name = options.name;
+    }
+    dispatch(level, args) {
+        const idx = levelIndex(level);
+        if (idx < this.minIdx)
+            return;
+        const message = args.length > 0 && typeof args[0] === "string" ? args[0] : "";
+        const rest = typeof args[0] === "string" ? args.slice(1) : args;
+        const entry = {
+            level,
+            message,
+            args: rest,
+            timestamp: new Date(),
+            name: this.name,
+        };
+        for (const transport of this.transports) {
+            try {
+                transport.log(entry);
+            }
+            catch {
+                // never let a broken transport crash the app
+            }
+        }
+    }
+    log(_logLevelId, logLevelName, ...args) {
+        const level = logLevelName.toLowerCase();
+        this.dispatch(level, args);
+    }
+    silly(...args) {
+        this.dispatch("silly", args);
+    }
+    trace(...args) {
+        this.dispatch("trace", args);
+    }
+    debug(...args) {
+        this.dispatch("debug", args);
+    }
+    info(...args) {
+        this.dispatch("info", args);
+    }
+    warn(...args) {
+        this.dispatch("warn", args);
+    }
+    error(...args) {
+        this.dispatch("error", args);
+    }
+    fatal(...args) {
+        this.dispatch("fatal", args);
+    }
+}

package/dist/core/index.d.ts

@@ -2,4 +2,6 @@ export { Application } from "./application.js";
 export { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from "./app-tokens.js";
 export { BadRequestException, ForbiddenException, HttpException, InternalServerErrorException, NotFoundException, UnauthorizedException, } from "./errors.js";
 export { Reflector } from "./reflector.js";
+export { consoleTransport } from "./log-transport.js";
+export { ImperiumLogger } from "./imperium-logger.js";
 export type * from "../types.js";

package/dist/core/index.js

@@ -2,3 +2,5 @@ export { Application } from "./application.js";
 export { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from "./app-tokens.js";
 export { BadRequestException, ForbiddenException, HttpException, InternalServerErrorException, NotFoundException, UnauthorizedException, } from "./errors.js";
 export { Reflector } from "./reflector.js";
+export { consoleTransport } from "./log-transport.js";
+export { ImperiumLogger } from "./imperium-logger.js";

package/dist/core/log-transport.d.ts

@@ -0,0 +1,11 @@
+import type { ImperiumLoggerOptions, LogLevel, LogTransport, TslogOptions } from "../types.js";
+export declare const LOG_LEVELS: LogLevel[];
+export declare function levelIndex(level: LogLevel): number;
+export declare function isImperiumLoggerOptions(options: unknown): options is ImperiumLoggerOptions;
+export declare function isTslogOptions(options: unknown): options is TslogOptions;
+/**
+ * Built-in console transport. Writes to stdout (silly..info) and stderr (warn..fatal).
+ */
+export declare function consoleTransport(options?: {
+    minLevel?: LogLevel;
+}): LogTransport;

package/dist/core/log-transport.js

@@ -0,0 +1,51 @@
+export const LOG_LEVELS = ["silly", "trace", "debug", "info", "warn", "error", "fatal"];
+export function levelIndex(level) {
+    return LOG_LEVELS.indexOf(level);
+}
+export function isImperiumLoggerOptions(options) {
+    if (!options || typeof options !== "object") {
+        return false;
+    }
+    const obj = options;
+    // ImperiumLoggerOptions has 'transports' or 'minLevel' as LogLevel string
+    if (Array.isArray(obj.transports)) {
+        return true;
+    }
+    if (typeof obj.minLevel === "string" && LOG_LEVELS.includes(obj.minLevel)) {
+        // Could be tslog too (it also has minLevel as number), but string minLevel is ours
+        if (typeof obj.type !== "string") {
+            return true;
+        }
+    }
+    return false;
+}
+export function isTslogOptions(options) {
+    return !isImperiumLoggerOptions(options);
+}
+function formatTimestamp(date) {
+    return date.toISOString().replace("T", " ").replace("Z", "");
+}
+function formatLevel(level) {
+    return level.toUpperCase().padEnd(5);
+}
+/**
+ * Built-in console transport. Writes to stdout (silly..info) and stderr (warn..fatal).
+ */
+export function consoleTransport(options) {
+    const minIdx = levelIndex(options?.minLevel ?? "silly");
+    return {
+        log(entry) {
+            const idx = levelIndex(entry.level);
+            if (idx < minIdx)
+                return;
+            const prefix = `${formatTimestamp(entry.timestamp)} | ${formatLevel(entry.level)} |${entry.name ? ` ${entry.name} |` : ""}`;
+            const parts = [prefix, entry.message, ...entry.args];
+            if (idx >= levelIndex("warn")) {
+                console.error(...parts);
+            }
+            else {
+                console.log(...parts);
+            }
+        },
+    };
+}

package/dist/core/logger.d.ts

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

package/dist/core/logger.js

@@ -1,12 +1,17 @@
 import { Logger } from "tslog";
+import { ImperiumLogger } from "./imperium-logger.js";
+import { isImperiumLoggerOptions } from "./log-transport.js";
 export const LOGGER_TOKEN = Symbol("app:logger");
-const DEFAULT_LOGGER_OPTIONS = {
+const DEFAULT_TSLOG_OPTIONS = {
     name: "app",
     type: "pretty",
 };
 export function createLogger(options) {
+    if (options && isImperiumLoggerOptions(options)) {
+        return new ImperiumLogger(options);
+    }
     return new Logger({
-        ...DEFAULT_LOGGER_OPTIONS,
+        ...DEFAULT_TSLOG_OPTIONS,
         ...(options ?? {}),
     });
 }

package/dist/core/server.js

@@ -140,7 +140,7 @@ export async function startServer(diOrOptions, options) {
     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;
+    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, onError, config, } = serverOptions;
     if (loggerOptions !== undefined) {
         di.configureLogger(loggerOptions);
     }
@@ -148,6 +148,9 @@ export async function startServer(diOrOptions, options) {
         di.configureConfig(config.schema, config.source ?? process.env);
     }
     di.setExposeInternalErrors(exposeInternalErrors);
+    if (onError) {
+        di.setOnError(onError);
+    }
     const listenPort = resolveListenPort(port, di.getConfig());
     const healthConfig = resolveHealth(health);
     const http = hasRegisteredHttpHandlers(di);

package/dist/http/adapter.js

@@ -6,19 +6,22 @@ import { collectFiltersForHttp, collectGuardsForHttp, collectInterceptorsForHttp
 function logHttpError(app, scope, details, error) {
     try {
         scope.resolve(LoggerService).error(details, error);
-        return;
     }
     catch {
-        // fallback below
-    }
-    try {
-        app.getLogger().error(details, error);
-        return;
-    }
-    catch {
-        // final fallback
+        try {
+            app.getLogger().error(details, error);
+        }
+        catch {
+            console.error("[imperium] http_error", details, error);
+        }
     }
-    console.error("[imperium] http_error", details, error);
+    app.reportError(error, {
+        type: "http",
+        handler: details.handler,
+        controller: details.controller,
+        method: details.method,
+        url: details.url,
+    });
 }
 function resolveEnhancer(scope, enhancer) {
     if (typeof enhancer === "function") {

package/dist/rpc/adapter.js

@@ -7,19 +7,21 @@ import { collectFiltersForRpc, collectGuardsForRpc, collectInterceptorsForRpc, c
 function logRpcError(app, scope, details, error) {
     try {
         scope.resolve(LoggerService).error(details, error);
-        return;
     }
     catch {
-        // fallback below
-    }
-    try {
-        app.getLogger().error(details, error);
-        return;
-    }
-    catch {
-        // final fallback
+        try {
+            app.getLogger().error(details, error);
+        }
+        catch {
+            console.error("[imperium] rpc_error", details, error);
+        }
     }
-    console.error("[imperium] rpc_error", details, error);
+    app.reportError(error, {
+        type: "rpc",
+        handler: details.handler,
+        controller: details.controller,
+        procedure: details.procedure,
+    });
 }
 function getPayloadValue(payload, key) {
     if (!key) {

package/dist/rpc/streaming-adapter.js

@@ -7,19 +7,21 @@ import { collectFiltersForRpc, collectGuardsForRpc, collectPipesForRpc } from ".
 function logRpcError(app, scope, details, error) {
     try {
         scope.resolve(LoggerService).error(details, error);
-        return;
     }
     catch {
-        // fallback below
-    }
-    try {
-        app.getLogger().error(details, error);
-        return;
-    }
-    catch {
-        // final fallback
+        try {
+            app.getLogger().error(details, error);
+        }
+        catch {
+            console.error("[imperium] rpc_streaming_error", details, error);
+        }
     }
-    console.error("[imperium] rpc_streaming_error", details, error);
+    app.reportError(error, {
+        type: "rpc",
+        handler: details.handler,
+        controller: details.controller,
+        procedure: details.procedure,
+    });
 }
 function getPayloadValue(payload, key) {
     if (!key) {

package/dist/services/logger.service.d.ts

@@ -3,28 +3,28 @@ export declare class LoggerService {
     private readonly logger;
     constructor(logger: AppLogger);
     getRawLogger(): AppLogger;
-    log(logLevelId: number, logLevelName: string, ...args: unknown[]): ({
+    log(logLevelId: number, logLevelName: string, ...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta & import("tslog").ILogObj) | undefined;
-    silly(...args: unknown[]): ({
+    } & import("tslog").ILogObjMeta & import("tslog").ILogObj);
+    silly(...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta) | undefined;
-    trace(...args: unknown[]): ({
+    } & import("tslog").ILogObjMeta);
+    trace(...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta) | undefined;
-    debug(...args: unknown[]): ({
+    } & import("tslog").ILogObjMeta);
+    debug(...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta) | undefined;
-    info(...args: unknown[]): ({
+    } & import("tslog").ILogObjMeta);
+    info(...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta) | undefined;
-    warn(...args: unknown[]): ({
+    } & import("tslog").ILogObjMeta);
+    warn(...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta) | undefined;
-    error(...args: unknown[]): ({
+    } & import("tslog").ILogObjMeta);
+    error(...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta) | undefined;
-    fatal(...args: unknown[]): ({
+    } & import("tslog").ILogObjMeta);
+    fatal(...args: unknown[]): void | ({
         [x: string]: unknown;
-    } & import("tslog").ILogObjMeta) | undefined;
+    } & import("tslog").ILogObjMeta);
 }

package/dist/types.d.ts

@@ -4,10 +4,38 @@ import type { DependencyContainer, RegistrationOptions, InjectionToken as Tsyrin
 import type { ZodType } from "zod";
 export type Constructor<T = unknown> = new (...args: any[]) => T;
 export type ContextType = "http" | "rpc" | "ws";
-export type LoggerOptions = ISettingsParam<Record<string, unknown>>;
 export type InjectionToken<T = unknown> = TsyringeInjectionToken<T>;
 export type MetadataKey = string | symbol;
 export type ShutdownSignal = "SIGINT" | "SIGTERM";
+export type LogLevel = "silly" | "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    args: unknown[];
+    timestamp: Date;
+    name?: string;
+}
+export interface LogTransport {
+    log(entry: LogEntry): void;
+}
+/** Native imperium logger options (transport-based) */
+export interface ImperiumLoggerOptions {
+    name?: string;
+    minLevel?: LogLevel;
+    transports?: LogTransport[];
+}
+/** Legacy tslog options — still supported */
+export type TslogOptions = ISettingsParam<Record<string, unknown>>;
+/** Accepts either native imperium options or tslog settings */
+export type LoggerOptions = ImperiumLoggerOptions | TslogOptions;
+export type ErrorContextType = "http" | "rpc" | "ws" | "cron" | "events";
+export interface ErrorContext {
+    type: ErrorContextType;
+    handler?: string;
+    controller?: string;
+    [key: string]: unknown;
+}
+export type OnErrorCallback = (error: unknown, context: ErrorContext) => void | Promise<void>;
 export interface ClassProvider<T = unknown> {
     provide: InjectionToken<T>;
     useClass: Constructor<T>;
@@ -172,6 +200,7 @@ export interface ServerOptions {
     health?: boolean | HealthOptions;
     gracefulShutdown?: boolean | GracefulShutdownOptions;
     loggerOptions?: LoggerOptions;
+    onError?: OnErrorCallback;
     config?: ConfigServiceOptions;
 }
 export {};

package/dist/validation/app-config.d.ts

@@ -14,13 +14,13 @@ export declare const appConfigSchema: z.ZodObject<{
     CORS_EXPOSE_HEADERS: z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<z.ZodString>>>;
     LOG_NAME: z.ZodDefault<z.ZodString>;
     LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
-        error: "error";
+        silly: "silly";
         trace: "trace";
-        fatal: "fatal";
-        warn: "warn";
-        info: "info";
         debug: "debug";
-        silly: "silly";
+        info: "info";
+        warn: "warn";
+        error: "error";
+        fatal: "fatal";
     }>>;
     LOG_TYPE: z.ZodDefault<z.ZodEnum<{
         pretty: "pretty";

package/dist/ws/adapter.js

@@ -67,19 +67,20 @@ function buildWsContext(gateway, methodName, handler, socket, request, message)
 function logWsError(app, scope, details, error) {
     try {
         scope.resolve(LoggerService).error(details, error);
-        return;
     }
     catch {
-        // fallback
-    }
-    try {
-        app.getLogger().error(details, error);
-        return;
-    }
-    catch {
-        // final fallback
+        try {
+            app.getLogger().error(details, error);
+        }
+        catch {
+            console.error("[imperium] ws_error", details, error);
+        }
     }
-    console.error("[imperium] ws_error", details, error);
+    app.reportError(error, {
+        type: "ws",
+        handler: details.type,
+        controller: details.gateway,
+    });
 }
 export function handleWsConnection(app, gateway, socket, request) {
     const scope = app.createRequestScope(gateway);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smounters/imperium",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "NestJS-like modular DI container with unified HTTP + Connect RPC server for TypeScript",
   "keywords": [
     "di",