@getsoda/core 0.1.1 → 0.2.1

package/dist/logger/console-logger.js

@@ -0,0 +1,117 @@
+/**
+ * @module
+ * Logger writing to stdout and stderr, readable for people or as JSON lines.
+ *
+ * ```
+ * [Soda] 41250  - 11/14/2026, 12:22:09 AM     LOG [UsersService] User created {"id":7} +3ms
+ * {"time":"2026-11-13T21:22:09.120Z","level":"log","context":"UsersService","message":"User created","id":7}
+ * ```
+ *
+ * Like Nest's `ConsoleLogger`: the same line layout, colored by level in a
+ * terminal, with the time since the previous line; a minimum level; a JSON
+ * mode for log collectors. `error` and `fatal` go to stderr, the rest to stdout.
+ */
+import { Logger } from './logger.js';
+const SEVERITY = { verbose: 0, debug: 1, log: 2, warn: 3, error: 4, fatal: 5 };
+const color = (code) => (text) => `\u001B[${code}m${text}\u001B[0m`;
+const LEVEL_COLORS = {
+    verbose: color('96'),
+    debug: color('95'),
+    log: color('32'),
+    warn: color('33'),
+    error: color('31'),
+    fatal: color('1;31'),
+};
+const yellow = color('38;5;3');
+const plain = (text) => text;
+const dateTime = new Intl.DateTimeFormat(undefined, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+});
+const writeToConsole = (line, level) => {
+    const stream = level === 'error' || level === 'fatal' ? process.stderr : process.stdout;
+    stream.write(`${line}\n`);
+};
+const serializeError = (error) => {
+    const serialized = { name: error.name, message: error.message, stack: error.stack };
+    if (error.cause !== undefined) {
+        serialized.cause = error.cause instanceof Error ? serializeError(error.cause) : error.cause;
+    }
+    return serialized;
+};
+/**
+ * `JSON.stringify` that never throws: bigints become strings, an object met a
+ * second time (a cycle) becomes `"[Circular]"`. Errors are serialized in full
+ * (stack and cause) for JSON lines, or as `Name: message` when their stack is
+ * printed on its own lines.
+ */
+const stringify = (value, errors) => {
+    const seen = new WeakSet();
+    return JSON.stringify(value, (_key, current) => {
+        if (typeof current === 'bigint') {
+            return current.toString();
+        }
+        if (current instanceof Error) {
+            return errors === 'full' ? serializeError(current) : `${current.name}: ${current.message}`;
+        }
+        if (typeof current === 'object' && current !== null) {
+            if (seen.has(current)) {
+                return '[Circular]';
+            }
+            seen.add(current);
+        }
+        return current;
+    });
+};
+export class ConsoleLogger extends Logger {
+    #minimum;
+    #json;
+    #output;
+    #colors;
+    #prefix;
+    /** When the previous line was written, for the `+3ms` at the end of the next. */
+    #last;
+    constructor(options = {}) {
+        super();
+        this.#minimum = SEVERITY[options.level ?? 'log'];
+        this.#json = options.json === true;
+        this.#output = options.output ?? writeToConsole;
+        this.#colors = options.colors ?? (options.output === undefined && process.stdout.isTTY === true && process.env.NO_COLOR === undefined);
+        this.#prefix = options.prefix ?? 'Soda';
+    }
+    write(entry) {
+        if (SEVERITY[entry.level] < this.#minimum) {
+            return;
+        }
+        const now = Date.now();
+        this.#output(this.#json ? this.#formatJson(entry, now) : this.#formatText(entry, now), entry.level);
+        this.#last = now;
+    }
+    #formatJson(entry, now) {
+        const time = new Date(now).toISOString();
+        // Fixed fields last: data cannot overwrite them.
+        return stringify({ ...entry.data, time, level: entry.level, context: entry.context, message: entry.message }, 'full');
+    }
+    #formatText(entry, now) {
+        const level = this.#colors ? LEVEL_COLORS[entry.level] : plain;
+        const accent = this.#colors ? yellow : plain;
+        const context = entry.context === undefined ? '' : accent(`[${entry.context}] `);
+        const since = this.#last === undefined ? '' : accent(` +${now - this.#last}ms`);
+        const data = entry.data === undefined ? '' : ` ${stringify(entry.data, 'brief')}`;
+        const line = `${level(`[${this.#prefix}] ${process.pid}  - `)}${dateTime.format(now)} ${level(entry.level.toUpperCase().padStart(7))} ` +
+            `${context}${level(entry.message)}${data}${since}`;
+        let stacks = '';
+        // Stacks are read better on their own lines than inside the JSON.
+        for (const value of Object.values(entry.data ?? {})) {
+            if (value instanceof Error && value.stack !== undefined) {
+                stacks += `\n${value.stack}`;
+            }
+        }
+        return line + stacks;
+    }
+}
+//# sourceMappingURL=console-logger.js.map

package/dist/logger/console-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-logger.js","sourceRoot":"","sources":["../../src/logger/console-logger.ts"],"names":[],"mappings":"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"}

package/dist/logger/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module
+ * Logging: the `Logger` contract and token, and the console implementation.
+ */
+export { ConsoleLogger } from './console-logger.ts';
+export type { ConsoleLoggerOptions } from './console-logger.ts';
+export { LOG_LEVELS, Logger, SilentLogger } from './logger.ts';
+export type { LogData, LogEntry, LogLevel } from './logger.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC9D,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA"}

package/dist/logger/index.js

@@ -0,0 +1,7 @@
+/**
+ * @module
+ * Logging: the `Logger` contract and token, and the console implementation.
+ */
+export { ConsoleLogger } from './console-logger.js';
+export { LOG_LEVELS, Logger, SilentLogger } from './logger.js';
+//# sourceMappingURL=index.js.map

package/dist/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA"}

package/dist/logger/logger.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module
+ * The logger contract.
+ *
+ * `Logger` is both the type and the DI token: the application provides one
+ * (a `ConsoleLogger` unless told otherwise) and any class injects it.
+ *
+ * ```ts
+ * class UsersService {
+ *   readonly #logger = inject(Logger).child('UsersService')
+ *
+ *   create(user: User) {
+ *     this.#logger.log('User created', { id: user.id })
+ *   }
+ * }
+ * ```
+ *
+ * Levels are Nest's. Unlike Nest's `Logger`, it is not a static global: each
+ * application has its own, and tests replace it with `overrides`.
+ */
+/** Levels, from the most to the least verbose. */
+export declare const LOG_LEVELS: readonly ['verbose', 'debug', 'log', 'warn', 'error', 'fatal'];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+/** Structured data of an entry; `Error` values are serialized with their stack and cause. */
+export type LogData = Readonly<Record<string, unknown>>;
+/**
+ * One log entry, as a `Logger` implementation receives it.
+ */
+export interface LogEntry {
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly data: LogData | undefined;
+    /** Where it comes from, as given to `child()`. */
+    readonly context: string | undefined;
+}
+/**
+ * A logger. Implementations only write entries; levels and contexts are handled here.
+ */
+export declare abstract class Logger {
+    /** Writes one entry. Called for every level: filtering is up to the implementation. */
+    abstract write(entry: LogEntry): void;
+    verbose(message: string, data?: LogData): void;
+    debug(message: string, data?: LogData): void;
+    log(message: string, data?: LogData): void;
+    warn(message: string, data?: LogData): void;
+    error(message: string, data?: LogData): void;
+    fatal(message: string, data?: LogData): void;
+    /** A logger writing through this one, with `context` on every entry. */
+    child(context: string): Logger;
+}
+/** A logger that writes nothing: `createApp(AppModule, { logger: false })`. */
+export declare class SilentLogger extends Logger {
+    write(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,kDAAkD;AAClD,eAAO,MAAM,UAAU,YAAI,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAA;AAExF,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAElD,6FAA6F;AAC7F,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IAClC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED;;GAEG;AACH,8BAAsB,MAAM;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAA;IAErC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAE7C;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAE3C;IAED,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAEzC;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAE1C;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAE3C;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAE3C;IAED,wEAAwE;IACxE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7B;CACF;AAiBD,+EAA+E;AAC/E,qBAAa,YAAa,SAAQ,MAAM;IACtC,KAAK,IAAI,IAAI,CAAG;CACjB"}

package/dist/logger/logger.js

@@ -0,0 +1,66 @@
+/**
+ * @module
+ * The logger contract.
+ *
+ * `Logger` is both the type and the DI token: the application provides one
+ * (a `ConsoleLogger` unless told otherwise) and any class injects it.
+ *
+ * ```ts
+ * class UsersService {
+ *   readonly #logger = inject(Logger).child('UsersService')
+ *
+ *   create(user: User) {
+ *     this.#logger.log('User created', { id: user.id })
+ *   }
+ * }
+ * ```
+ *
+ * Levels are Nest's. Unlike Nest's `Logger`, it is not a static global: each
+ * application has its own, and tests replace it with `overrides`.
+ */
+/** Levels, from the most to the least verbose. */
+export const LOG_LEVELS = ['verbose', 'debug', 'log', 'warn', 'error', 'fatal'];
+/**
+ * A logger. Implementations only write entries; levels and contexts are handled here.
+ */
+export class Logger {
+    verbose(message, data) {
+        this.write({ level: 'verbose', message, data, context: undefined });
+    }
+    debug(message, data) {
+        this.write({ level: 'debug', message, data, context: undefined });
+    }
+    log(message, data) {
+        this.write({ level: 'log', message, data, context: undefined });
+    }
+    warn(message, data) {
+        this.write({ level: 'warn', message, data, context: undefined });
+    }
+    error(message, data) {
+        this.write({ level: 'error', message, data, context: undefined });
+    }
+    fatal(message, data) {
+        this.write({ level: 'fatal', message, data, context: undefined });
+    }
+    /** A logger writing through this one, with `context` on every entry. */
+    child(context) {
+        return new ContextLogger(this, context);
+    }
+}
+class ContextLogger extends Logger {
+    #parent;
+    #context;
+    constructor(parent, context) {
+        super();
+        this.#parent = parent;
+        this.#context = context;
+    }
+    write(entry) {
+        this.#parent.write({ ...entry, context: this.#context });
+    }
+}
+/** A logger that writes nothing: `createApp(AppModule, { logger: false })`. */
+export class SilentLogger extends Logger {
+    write() { }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAA;AAkBxF;;GAEG;AACH,MAAM,OAAgB,MAAM;IAI1B,OAAO,CAAC,OAAe,EAAE,IAAc;QACrC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACrE,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,GAAG,CAAC,OAAe,EAAE,IAAc;QACjC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACjE,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,OAAe;QACnB,OAAO,IAAI,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACzC,CAAC;CACF;AAED,MAAM,aAAc,SAAQ,MAAM;IACvB,OAAO,CAAQ;IACf,QAAQ,CAAQ;IAEzB,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,KAAe;QACnB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC1D,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,YAAa,SAAQ,MAAM;IACtC,KAAK,KAAU,CAAC;CACjB"}

package/dist/routing/types.d.ts

@@ -30,7 +30,7 @@ export type Params = Record<string, string>;
  *
  * `params` may be the very object Bun put on `req.params`: treat it as read-only.
  */
-export type Handler = (req: Request, params: Params) => Response | Promise<Response>;
+export type Handler = (req: Bun.BunRequest, params: Params) => Response | Promise<Response>;
 /**
  * Route definition.
  *

package/dist/routing/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAQ,CAAA;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,SAAU,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE3C;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEpF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClE,oFAAoF;IACpF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC9C,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC/D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAQ,CAAA;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,SAAU,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE3C;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE3F;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClE,oFAAoF;IACpF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC9C,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC/D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getsoda/core",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Class-based web framework for Bun: modules, dependency injection and decorators like Nest, on Bun's native router",
   "keywords": [
     "bun",
@@ -28,6 +28,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./jwt": {
+      "types": "./dist/jwt/index.d.ts",
+      "default": "./dist/jwt/index.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
@@ -42,16 +46,6 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "typecheck": "bun check",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "test": "bun test",
-    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build"
-  },
-  "devDependencies": {
-    "@stylistic/eslint-plugin": "5.10.0",
-    "@types/bun": "latest",
-    "oxlint": "1.93.0",
-    "typescript": "7.0.2"
+    "prepublishOnly": "cd ../.. && bun run lint && bun run typecheck && bun run test && cd packages/core && bun run build"
   }
 }

package/src/app/app.ts

@@ -19,11 +19,14 @@
  * are being destroyed; here they cannot.
  */
 
-import { createContainer } from '../di/index.ts'
+import { createContainer, provide } from '../di/index.ts'
 import type { Container, ContainerOptions, ModuleImport } from '../di/index.ts'
 import { destroyAll, initializeAll } from '../di/lifecycle.ts'
 import { buildRoutes } from '../http/index.ts'
-import type { ControllerRoutesOptions } from '../http/index.ts'
+import type { ControllerRoutesOptions, MappedController, Middleware } from '../http/index.ts'
+import { errorResponse } from '../http/exceptions.ts'
+import { applyMiddleware, resolveMiddleware } from '../http/middleware.ts'
+import { ConsoleLogger, Logger, SilentLogger } from '../logger/index.ts'
 import { compileRoutes } from '../routing/index.ts'
 import type { CompiledRoutes, CompileOptions } from '../routing/index.ts'
 import { release, takeOver } from './hot.ts'
@@ -31,7 +34,18 @@ import { release, takeOver } from './hot.ts'
 /**
  * Options of `createApp`.
  */
-export interface AppOptions extends ContainerOptions, ControllerRoutesOptions, CompileOptions {}
+export interface AppOptions extends ContainerOptions, ControllerRoutesOptions, CompileOptions {
+  /**
+   * Middleware run around every request, before routing (404 and preflights
+   * included), first one outermost: `[cors(), requestId]`.
+   */
+  readonly middleware?: readonly Middleware[]
+  /**
+   * Logger of the application, injectable everywhere as `inject(Logger)`.
+   * Defaults to a `ConsoleLogger`; `false` writes nothing.
+   */
+  readonly logger?: Logger | false
+}
 
 /**
  * Where to listen. `port: 0` picks a free port.
@@ -39,6 +53,11 @@ export interface AppOptions extends ContainerOptions, ControllerRoutesOptions, C
 export interface ListenOptions {
   readonly port?: number
   readonly hostname?: string
+  /**
+   * Largest request body accepted, in bytes; bigger ones are refused before any
+   * handler runs. Bun's default is 128 MiB.
+   */
+  readonly maxRequestBodySize?: number
 }
 
 /** Signals `enableShutdownSignals()` listens to by default. */
@@ -80,11 +99,13 @@ class Application implements App {
   #closing: Promise<void> | undefined
   readonly #enhancers: readonly unknown[]
   readonly #signals = new Map<NodeJS.Signals, () => void>()
+  readonly #logger: Logger
 
-  constructor(container: Container, routes: CompiledRoutes, enhancers: readonly unknown[]) {
+  constructor(container: Container, routes: CompiledRoutes, enhancers: readonly unknown[], logger: Logger) {
     this.container = container
     this.routes = routes
     this.#enhancers = enhancers
+    this.#logger = logger
   }
 
   get server(): Bun.Server<undefined> | undefined {
@@ -100,9 +121,9 @@ class Application implements App {
       throw new Error(`The application already listens on ${this.#server.url.href}`)
     }
 
-    const { port = 0, hostname } = typeof options === 'number' ? { port: options } : options
+    const { port = 0, hostname, maxRequestBodySize } = typeof options === 'number' ? { port: options } : options
 
-    const server = Bun.serve({ port, hostname, ...this.routes })
+    const server = Bun.serve({ port, hostname, maxRequestBodySize, ...this.routes })
 
     this.#server = server
 
@@ -110,6 +131,8 @@ class Application implements App {
       await takeOver(server.port, this)
     }
 
+    this.#logger.log(`Listening on ${server.url.href}`)
+
     return server
   }
 
@@ -151,7 +174,7 @@ class Application implements App {
             process.kill(process.pid, signal)
           },
           (error: unknown) => {
-            console.error('Error during shutdown', error)
+            this.#logger.fatal('Shutdown failed', { error })
             process.exit(1)
           }
         )
@@ -222,6 +245,24 @@ const destroyEverything = async (enhancers: readonly unknown[], container: Conta
   }
 }
 
+/** What Nest logs at startup: the modules, then each controller and its routes. */
+const logStartup = (logger: Logger, container: Container, controllers: readonly MappedController[]): void => {
+  const modules = logger.child('Container')
+  const routes = logger.child('Routes')
+
+  for (const module of container.modules) {
+    modules.log(`${module.name} dependencies initialized`)
+  }
+
+  for (const { controller, path, routes: mapped } of controllers) {
+    routes.log(`${controller.name} {${path}}:`)
+
+    for (const route of mapped) {
+      routes.log(`Mapped {${route.path}, ${route.method}} route`)
+    }
+  }
+}
+
 /**
  * Creates the container and the routes, and runs every `onInit` hook.
  *
@@ -230,16 +271,39 @@ const destroyEverything = async (enhancers: readonly unknown[], container: Conta
  * error first, as `createContainer` does.
  */
 export const createApp = async (root: ModuleImport, options: AppOptions = {}): Promise<App> => {
-  const container = await createContainer(root, options)
-  let enhancers: readonly unknown[] = []
+  const logger = options.logger === false ? new SilentLogger() : (options.logger ?? new ConsoleLogger())
+  const own = logger.child('Soda')
+  const onError =
+    options.onError ??
+    ((error: unknown, req: Request) =>
+      own.error('Unhandled error while handling a request', { error, method: req.method, url: req.url }))
 
-  try {
-    const built = buildRoutes(container, options)
+  own.log('Starting application')
+
+  const container = await createContainer(root, {
+    ...options,
+    providers: [...(options.providers ?? []), provide(Logger, { useValue: logger })],
+  })
+  const enhancers: unknown[] = []
 
-    enhancers = built.enhancers
+  try {
+    // Middleware first: it wraps everything, so it is initialized first and destroyed last.
+    const middleware = resolveMiddleware(options.middleware ?? [], (fn) => container.runInContext(fn), (instance) => {
+      enhancers.push(instance)
+    })
+    const built = buildRoutes(container, { ...options, onError })
+
+    logStartup(logger, container, built.controllers)
+    enhancers.push(...built.enhancers)
     await initializeAll(enhancers)
+    own.log('Application started')
+
+    const compiled = compileRoutes(built.routes, options)
+    const routes = applyMiddleware(middleware, compiled.routes, compiled.fetch, (error, req) =>
+      errorResponse(error, (unknown) => onError(unknown, req))
+    )
 
-    return new Application(container, compileRoutes(built.routes, options), enhancers)
+    return new Application(container, routes, enhancers, own)
   } catch (error) {
     try {
       await destroyEverything(enhancers, container)

package/src/di/container.ts

@@ -19,11 +19,13 @@
 import { isThenable } from '../utils/promise.ts'
 import { runInContext } from './context.ts'
 import type { InjectionContext } from './context.ts'
-import type { ModuleClass, ModuleImport } from './decorators.ts'
+import { Module } from './decorators.ts'
+import type { DynamicModule, ModuleClass, ModuleImport } from './decorators.ts'
 import { DiError } from './errors.ts'
 import { buildGraph } from './graph.ts'
 import type { ModuleGraph, ModuleNode, ProviderNode } from './graph.ts'
 import { destroyAll, initializeAll } from './lifecycle.ts'
+import { isProviderRecord } from './provider.ts'
 import type { Provider, ProviderDefinition } from './provider.ts'
 import { tokenName } from './token.ts'
 import type { Constructor, Token } from './token.ts'
@@ -43,6 +45,25 @@ export interface ContainerOptions {
    * ```
    */
   readonly overrides?: readonly Provider[]
+  /**
+   * Providers visible in every module, as if exported by a global module:
+   * what the application itself provides, such as its `Logger`.
+   */
+  readonly providers?: readonly Provider[]
+}
+
+/** Module holding `ContainerOptions.providers`. */
+@Module({})
+class ContainerProvidersModule {}
+
+const providersModule = (providers: readonly Provider[]): DynamicModule => {
+  const exports: Token<unknown>[] = []
+
+  for (const provider of providers) {
+    exports.push(isProviderRecord(provider) ? provider.token : provider)
+  }
+
+  return { module: ContainerProvidersModule, providers, exports, global: true }
 }
 
 /**
@@ -81,6 +102,8 @@ export interface Container {
   runInContext<R>(fn: () => R, options?: ResolveOptions): R
   /** Every controller, in module order. */
   readonly controllers: readonly ControllerEntry[]
+  /** Every module, imports before importers. */
+  readonly modules: readonly ModuleClass[]
   /**
    * Calls `onDestroy` in reverse creation order, then releases every instance.
    * Calling it again, even from an `onDestroy` hook, returns the same promise.
@@ -398,6 +421,18 @@ class StartedContainer implements Container {
     this.controllers = controllers
   }
 
+  get modules(): readonly ModuleClass[] {
+    const modules: ModuleClass[] = []
+
+    for (const node of this.#graph.modules) {
+      if (node.moduleClass !== ContainerProvidersModule) {
+        modules.push(node.moduleClass)
+      }
+    }
+
+    return modules
+  }
+
   get<T>(token: Token<T>, options?: ResolveOptions & { readonly optional?: false }): T
   get<T>(token: Token<T>, options: ResolveOptions & { readonly optional: true }): T | undefined
   get<T>(token: Token<T>, options: ResolveOptions & { readonly optional?: boolean } = {}): T | undefined {
@@ -524,7 +559,8 @@ const createAll = async (graph: ModuleGraph, resolver: Resolver): Promise<Contro
  * hooks fail too, everything is rethrown as one `AggregateError`, startup error first.
  */
 export const createContainer = async (root: ModuleImport, options: ContainerOptions = {}): Promise<Container> => {
-  const graph = await buildGraph(root, options.overrides ?? [])
+  const providers = options.providers ?? []
+  const graph = await buildGraph(root, options.overrides ?? [], providers.length > 0 ? [providersModule(providers)] : [])
   const resolver = new Resolver(graph)
 
   try {

package/src/di/graph.ts

@@ -139,7 +139,17 @@ class GraphBuilder {
     }
   }
 
-  async build(root: ModuleImport): Promise<ModuleGraph> {
+  /**
+   * `globals` are global modules added next to `root` (the container's own
+   * providers); they are created first, before anything that may inject them.
+   */
+  async build(root: ModuleImport, globals: readonly ModuleImport[]): Promise<ModuleGraph> {
+    const globalNodes: ModuleNode[] = []
+
+    for (let i = 0, len = globals.length; i < len; i++) {
+      globalNodes.push(await this.#module(globals[i], 'createContainer()', i))
+    }
+
     const rootNode = await this.#module(root, 'createContainer()', 0)
 
     // The queue grows while modules are read: breadth-first over imports.
@@ -149,8 +159,8 @@ class GraphBuilder {
 
     this.#assertReplacementsUsed()
 
-    const modules = orderModules(rootNode)
-    const globals: ModuleNode[] = []
+    const modules = orderModules([...globalNodes, rootNode])
+    const globalModules: ModuleNode[] = []
     const providers: ProviderNode[] = []
     const controllers: ProviderNode[] = []
 
@@ -160,14 +170,14 @@ class GraphBuilder {
       assertExportsProvided(node)
 
       if (node.global) {
-        globals.push(node)
+        globalModules.push(node)
       }
 
       providers.push(...node.providers.values())
       controllers.push(...node.controllers)
     }
 
-    return { root: rootNode, modules, globals, providers, controllers }
+    return { root: rootNode, modules, globals: globalModules, providers, controllers }
   }
 
   /** Node for an `imports` entry, created on first sight. */
@@ -320,8 +330,8 @@ const assertExportsProvided = (node: ModuleNode): void => {
   }
 }
 
-/** Modules reachable from `root`, each after the modules it imports. */
-const orderModules = (root: ModuleNode): ModuleNode[] => {
+/** Modules reachable from `roots`, each after the modules it imports. */
+const orderModules = (roots: readonly ModuleNode[]): ModuleNode[] => {
   const ordered: ModuleNode[] = []
   const visited = new Set<ModuleNode>()
 
@@ -339,15 +349,20 @@ const orderModules = (root: ModuleNode): ModuleNode[] => {
     ordered.push(node)
   }
 
-  visit(root)
+  for (const root of roots) {
+    visit(root)
+  }
 
   return ordered
 }
 
 /**
- * Builds the module graph rooted at `root`.
+ * Builds the module graph rooted at `root`, with `globals` as extra global modules.
  *
  * `overrides` replace the provider of their token in every module providing it (for tests).
  */
-export const buildGraph = (root: ModuleImport, overrides: readonly Provider[]): Promise<ModuleGraph> =>
-  new GraphBuilder(overrides).build(root)
+export const buildGraph = (
+  root: ModuleImport,
+  overrides: readonly Provider[],
+  globals: readonly ModuleImport[] = []
+): Promise<ModuleGraph> => new GraphBuilder(overrides).build(root, globals)