@getsoda/core 0.2.1 → 0.3.0

package/dist/websocket/gateway.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module
+ * Serving a gateway: the handshake goes through the route pipeline (guards
+ * and exception filters of the gateway), then frames are dispatched to its
+ * `@SubscribeMessage()` methods.
+ *
+ * The protocol is the one of Nest's `WsAdapter`: text frames holding
+ * `{ "event": string, "data": any }`. Frames that are not JSON, not such an
+ * object, or name no handled event are dropped silently, as anyone can send
+ * them; errors of the gateway's own code are reported.
+ */
+import type { ControllerEntry } from '../di/index.ts';
+import type { Context } from '../http/context.ts';
+import type { FilterStep, GuardStep } from '../http/pipeline.ts';
+/** What a gateway socket carries. */
+export interface GatewaySocketData {
+    /** Context of the handshake request: what its guards set is read with `context.get(key)`. */
+    readonly context: Context;
+    /** @internal */
+    readonly gateway: GatewayRuntime;
+}
+/** A connection of a gateway: Bun's `ServerWebSocket`, with `subscribe()`, `publish()`... */
+export type GatewaySocket = Bun.ServerWebSocket<GatewaySocketData>;
+/** `handleConnection(socket)`: called when a client is connected. */
+export interface OnGatewayConnection {
+    handleConnection(socket: GatewaySocket): unknown;
+}
+/** `handleDisconnect(socket, code, reason)`: called when a connection is closed. */
+export interface OnGatewayDisconnect {
+    handleDisconnect(socket: GatewaySocket, code: number, reason: string): unknown;
+}
+/** The live part of a gateway: its sockets and handlers. */
+export declare class GatewayRuntime {
+    #private;
+    constructor(instance: object, onError: (error: unknown, req: Request) => void);
+    get events(): readonly string[];
+    open(socket: GatewaySocket): void;
+    message(socket: GatewaySocket, message: string | Buffer): void;
+    close(socket: GatewaySocket, code: number, reason: string): void;
+    /** Closes every connection, as the application shuts down. */
+    closeAll(): void;
+}
+/** Bun's handlers for every gateway of a server: each socket knows its gateway. */
+export declare const websocketHandler: Bun.WebSocketHandler<GatewaySocketData>;
+export interface GatewayParts {
+    readonly entry: ControllerEntry;
+    readonly path: string;
+    readonly guards: readonly GuardStep[];
+    readonly filters: readonly FilterStep[];
+    readonly metadata: ReadonlyMap<symbol, unknown>;
+    readonly onError: (error: unknown, req: Request) => void;
+}
+/** A gateway ready to serve: its native route and its runtime. */
+export interface BuiltGateway {
+    readonly path: string;
+    readonly runtime: GatewayRuntime;
+    /** The native route of the handshake, for `Bun.serve({ routes })`. */
+    readonly handle: (req: Bun.BunRequest, server: Bun.Server<GatewaySocketData>) => Response | undefined | Promise<Response | undefined>;
+}
+export declare const buildGateway: (parts: GatewayParts) => BuiltGateway;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/websocket/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/websocket/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,oBAAoB,CAAA;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAKhE,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,gBAAgB;IAChB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CACjC;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAA;AAElE,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAA;CACjD;AAED,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;CAC/E;AAoBD,4DAA4D;AAC5D,qBAAa,cAAc;;IAMzB,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,EAY5E;IAED,IAAI,MAAM,IAAI,SAAS,MAAM,EAAE,CAE9B;IAED,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAGhC;IAED,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB7D;IAED,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAG/D;IAED,8DAA8D;IAC9D,QAAQ,IAAI,IAAI,CAIf;CAqBF;AAkBD,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,CAAC,iBAAiB,CAIpE,CAAA;AAKD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/C,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACzD;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CACtI;AAED,eAAO,MAAM,YAAY,UAAW,YAAY,KAAG,YA2BlD,CAAA"}

package/dist/websocket/gateway.js

@@ -0,0 +1,142 @@
+/**
+ * @module
+ * Serving a gateway: the handshake goes through the route pipeline (guards
+ * and exception filters of the gateway), then frames are dispatched to its
+ * `@SubscribeMessage()` methods.
+ *
+ * The protocol is the one of Nest's `WsAdapter`: text frames holding
+ * `{ "event": string, "data": any }`. Frames that are not JSON, not such an
+ * object, or name no handled event are dropped silently, as anyone can send
+ * them; errors of the gateway's own code are reported.
+ */
+import { parseJson } from '../http/body.js';
+import { createPipeline } from '../http/pipeline.js';
+import { methodNames } from '../utils/object.js';
+import { isThenable } from '../utils/promise.js';
+import { getSubscribedEvent } from './decorators.js';
+/** Code of the close frame sent when the application shuts down. */
+const GOING_AWAY = 1001;
+/** Runs `fn`, reporting a synchronous or asynchronous failure. */
+const settle = (fn, report, then) => {
+    try {
+        const result = fn();
+        if (isThenable(result)) {
+            Promise.resolve(result).then(then, report);
+        }
+        else {
+            then?.(result);
+        }
+    }
+    catch (error) {
+        report(error);
+    }
+};
+/** The live part of a gateway: its sockets and handlers. */
+export class GatewayRuntime {
+    #instance;
+    #handlers = new Map();
+    #sockets = new Set();
+    #onError;
+    constructor(instance, onError) {
+        this.#instance = instance;
+        this.#onError = onError;
+        for (const name of methodNames(instance)) {
+            const method = this.#instance[name];
+            const event = getSubscribedEvent(method);
+            if (event !== undefined) {
+                this.#handlers.set(event, method);
+            }
+        }
+    }
+    get events() {
+        return [...this.#handlers.keys()];
+    }
+    open(socket) {
+        this.#sockets.add(socket);
+        this.#call('handleConnection', socket, [socket]);
+    }
+    message(socket, message) {
+        const frame = typeof message === 'string' ? parseFrame(message) : undefined;
+        const handler = frame === undefined ? undefined : this.#handlers.get(frame.event);
+        if (handler === undefined) {
+            return;
+        }
+        settle(() => handler.call(this.#instance, frame.data, socket), (error) => this.#onError(error, socket.data.context.req), (result) => {
+            if (result !== undefined) {
+                this.#send(socket, result);
+            }
+        });
+    }
+    close(socket, code, reason) {
+        this.#sockets.delete(socket);
+        this.#call('handleDisconnect', socket, [socket, code, reason]);
+    }
+    /** Closes every connection, as the application shuts down. */
+    closeAll() {
+        for (const socket of this.#sockets) {
+            socket.close(GOING_AWAY, 'Server shutting down');
+        }
+    }
+    #call(hook, socket, args) {
+        const fn = this.#instance[hook];
+        if (typeof fn === 'function') {
+            settle(() => fn.apply(this.#instance, args), (error) => this.#onError(error, socket.data.context.req));
+        }
+    }
+    #send(socket, value) {
+        try {
+            // JSON.stringify throws on cycles and bigints: an application error, reported.
+            socket.send(JSON.stringify(value));
+        }
+        catch (error) {
+            this.#onError(error, socket.data.context.req);
+        }
+    }
+}
+const parseFrame = (message) => {
+    let frame;
+    try {
+        frame = parseJson(message);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof frame !== 'object' || frame === null || typeof frame.event !== 'string') {
+        return undefined;
+    }
+    return frame;
+};
+/** Bun's handlers for every gateway of a server: each socket knows its gateway. */
+export const websocketHandler = {
+    open: (socket) => socket.data.gateway.open(socket),
+    message: (socket, message) => socket.data.gateway.message(socket, message),
+    close: (socket, code, reason) => socket.data.gateway.close(socket, code, reason),
+};
+/** Result of the handshake once the connection is upgraded: Bun wants no response then. */
+const UPGRADED = Symbol('upgraded');
+export const buildGateway = (parts) => {
+    const runtime = new GatewayRuntime(parts.entry.instance, parts.onError);
+    const route = { controller: parts.entry.controller, handler: 'handshake', method: 'GET', path: parts.path, metadata: parts.metadata };
+    // The pipeline is built once; the server of each request is found here.
+    const servers = new WeakMap();
+    const pipeline = createPipeline({
+        route,
+        guards: parts.guards,
+        interceptors: [],
+        filters: parts.filters,
+        invoke: (ctx) => servers.get(ctx.req).upgrade(ctx.req, { data: { context: ctx, gateway: runtime } })
+            ? UPGRADED
+            : new Response('Expected a WebSocket upgrade', { status: 426, headers: { upgrade: 'websocket' } }),
+        respond: (value) => (value === UPGRADED ? undefined : value),
+        onError: parts.onError,
+    });
+    return {
+        path: parts.path,
+        runtime,
+        handle: (req, server) => {
+            servers.set(req, server);
+            return pipeline(req, {});
+        },
+    };
+};
+//# sourceMappingURL=gateway.js.map

package/dist/websocket/gateway.js.map

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

package/dist/websocket/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @module
+ * WebSocket gateways, as in `@nestjs/websockets`.
+ */
+export { SubscribeMessage, WebSocketGateway } from './decorators.ts';
+export type { GatewaySocket, GatewaySocketData, OnGatewayConnection, OnGatewayDisconnect } from './gateway.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/websocket/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACpE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA"}

package/dist/websocket/index.js

@@ -0,0 +1,6 @@
+/**
+ * @module
+ * WebSocket gateways, as in `@nestjs/websockets`.
+ */
+export { SubscribeMessage, WebSocketGateway } from './decorators.js';
+//# sourceMappingURL=index.js.map

package/dist/websocket/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/websocket/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getsoda/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Class-based web framework for Bun: modules, dependency injection and decorators like Nest, on Bun's native router",
   "keywords": [
     "bun",
@@ -32,6 +32,14 @@
       "types": "./dist/jwt/index.d.ts",
       "default": "./dist/jwt/index.js"
     },
+    "./openapi": {
+      "types": "./dist/openapi/index.d.ts",
+      "default": "./dist/openapi/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
@@ -47,5 +55,8 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepublishOnly": "cd ../.. && bun run lint && bun run typecheck && bun run test && cd packages/core && bun run build"
+  },
+  "devDependencies": {
+    "zod": "4.6.7"
   }
 }

package/src/app/app.ts

@@ -22,13 +22,15 @@
 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 { buildRoutes, ControllerError, ROUTES } 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 type { CompiledRoutes, CompileOptions, NativeHandler } from '../routing/index.ts'
+import { websocketHandler } from '../websocket/gateway.ts'
+import type { BuiltGateway, GatewaySocketData } from '../websocket/gateway.ts'
 import { release, takeOver } from './hot.ts'
 
 /**
@@ -68,16 +70,16 @@ const DEFAULT_SIGNALS: readonly NodeJS.Signals[] = ['SIGTERM', 'SIGINT']
  */
 export interface App {
   readonly container: Container
-  /** Routes for `Bun.serve()`, when serving them yourself instead of calling `listen()`. */
-  readonly routes: CompiledRoutes
+  /** Routes (and WebSocket handlers) for `Bun.serve()`, when serving them yourself instead of calling `listen()`. */
+  readonly routes: ServeRoutes
   /** The server once `listen()` resolved. */
-  readonly server: Bun.Server<undefined> | undefined
+  readonly server: Bun.Server<GatewaySocketData> | undefined
   /**
    * Starts serving. Under `bun --hot`, a new version of the application
    * listening on the same port takes the server over from the previous one,
    * which is then destroyed (its server is not stopped: it is shared).
    */
-  listen(options?: number | ListenOptions): Promise<Bun.Server<undefined>>
+  listen(options?: number | ListenOptions): Promise<Bun.Server<GatewaySocketData>>
   /**
    * Graceful shutdown: refuses new requests, waits for those in flight, then
    * runs `onDestroy` hooks. Safe to call more than once, even from a hook.
@@ -92,27 +94,35 @@ export interface App {
 
 class Application implements App {
   readonly container: Container
-  readonly routes: CompiledRoutes
-  #server: Bun.Server<undefined> | undefined
+  readonly routes: ServeRoutes
+  #server: Bun.Server<GatewaySocketData> | undefined
   /** Set when a new version took the server over: it must not be stopped. */
   #handedOver = false
   #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[], logger: Logger) {
+  readonly #gateways: readonly BuiltGateway[]
+
+  constructor(
+    container: Container,
+    routes: ServeRoutes,
+    gateways: readonly BuiltGateway[],
+    enhancers: readonly unknown[],
+    logger: Logger
+  ) {
     this.container = container
     this.routes = routes
+    this.#gateways = gateways
     this.#enhancers = enhancers
     this.#logger = logger
   }
 
-  get server(): Bun.Server<undefined> | undefined {
+  get server(): Bun.Server<GatewaySocketData> | undefined {
     return this.#server
   }
 
-  async listen(options: number | ListenOptions = {}): Promise<Bun.Server<undefined>> {
+  async listen(options: number | ListenOptions = {}): Promise<Bun.Server<GatewaySocketData>> {
     if (this.#closing !== undefined) {
       throw new Error('Cannot listen: the application is closed')
     }
@@ -191,6 +201,11 @@ class Application implements App {
     const server = this.#server
 
     try {
+      // Open sockets would keep stop() waiting; under --hot, clients reconnect to the new version.
+      for (const gateway of this.#gateways) {
+        gateway.runtime.closeAll()
+      }
+
       if (server !== undefined && !this.#handedOver) {
         await server.stop()
       }
@@ -245,8 +260,37 @@ const destroyEverything = async (enhancers: readonly unknown[], container: Conta
   }
 }
 
+/**
+ * Routes and WebSocket handlers for `Bun.serve()`: the handshakes of gateways
+ * are native routes of their own, outside middleware, as an upgrade returns no response.
+ */
+export interface ServeRoutes {
+  readonly routes: Record<string, NativeHandler | BuiltGateway['handle']>
+  readonly fetch: CompiledRoutes['fetch']
+  readonly websocket: Bun.WebSocketHandler<GatewaySocketData>
+}
+
+const withGateways = (compiled: CompiledRoutes, gateways: readonly BuiltGateway[]): ServeRoutes => {
+  const routes: ServeRoutes['routes'] = { ...compiled.routes }
+
+  for (const gateway of gateways) {
+    if (Object.hasOwn(routes, gateway.path)) {
+      throw new ControllerError('DUPLICATE_ROUTE', `The WebSocket gateway on ${gateway.path} has the path of another gateway or route`)
+    }
+
+    routes[gateway.path] = gateway.handle
+  }
+
+  return { routes, fetch: compiled.fetch, websocket: websocketHandler }
+}
+
 /** What Nest logs at startup: the modules, then each controller and its routes. */
-const logStartup = (logger: Logger, container: Container, controllers: readonly MappedController[]): void => {
+const logStartup = (
+  logger: Logger,
+  container: Container,
+  controllers: readonly MappedController[],
+  gateways: readonly BuiltGateway[]
+): void => {
   const modules = logger.child('Container')
   const routes = logger.child('Routes')
 
@@ -257,10 +301,14 @@ const logStartup = (logger: Logger, container: Container, controllers: readonly
   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`)
+    for (const { info } of mapped) {
+      routes.log(`Mapped {${info.path}, ${info.method}} route`)
     }
   }
+
+  for (const gateway of gateways) {
+    routes.log(`WebSocket gateway {${gateway.path}}, events: ${gateway.runtime.events.join(', ') || 'none'}`)
+  }
 }
 
 /**
@@ -280,9 +328,11 @@ export const createApp = async (root: ModuleImport, options: AppOptions = {}): P
 
   own.log('Starting application')
 
+  // Filled once the routes are built; read by what describes them (OpenAPI).
+  const registry: { controllers: readonly MappedController[] } = { controllers: [] }
   const container = await createContainer(root, {
     ...options,
-    providers: [...(options.providers ?? []), provide(Logger, { useValue: logger })],
+    providers: [...(options.providers ?? []), provide(Logger, { useValue: logger }), provide(ROUTES, { useValue: registry })],
   })
   const enhancers: unknown[] = []
 
@@ -293,7 +343,8 @@ export const createApp = async (root: ModuleImport, options: AppOptions = {}): P
     })
     const built = buildRoutes(container, { ...options, onError })
 
-    logStartup(logger, container, built.controllers)
+    registry.controllers = built.controllers
+    logStartup(logger, container, built.controllers, built.gateways)
     enhancers.push(...built.enhancers)
     await initializeAll(enhancers)
     own.log('Application started')
@@ -303,7 +354,7 @@ export const createApp = async (root: ModuleImport, options: AppOptions = {}): P
       errorResponse(error, (unknown) => onError(unknown, req))
     )
 
-    return new Application(container, routes, enhancers, own)
+    return new Application(container, withGateways(routes, built.gateways), built.gateways, enhancers, own)
   } catch (error) {
     try {
       await destroyEverything(enhancers, container)

package/src/app/index.ts

@@ -4,4 +4,4 @@
  */
 
 export { createApp } from './app.ts'
-export type { App, AppOptions, ListenOptions } from './app.ts'
+export type { App, AppOptions, ListenOptions, ServeRoutes } from './app.ts'

package/src/config/config.ts

@@ -0,0 +1,90 @@
+/**
+ * @module
+ * Configuration typed by a schema and validated at startup.
+ *
+ * What `@nestjs/config` does with `registerAs()` and a `validationSchema`,
+ * typed by the schema instead of read with string keys. Bun already loads
+ * `.env`, `.env.local` and `.env.<NODE_ENV>` into `process.env`.
+ *
+ * ```ts
+ * export const AppConfig = defineConfig('app', z.object({
+ *   PORT: z.coerce.number().default(3000),
+ *   JWT_SECRET: z.string().min(32),
+ * }))
+ *
+ * @Module({ imports: [ConfigModule.forRoot({ load: [AppConfig], global: true })] })
+ * class AppModule {}
+ *
+ * class AuthService {
+ *   readonly #config = inject(AppConfig) // { PORT: number; JWT_SECRET: string }
+ * }
+ * ```
+ */
+
+import { InjectionToken } from '../di/token.ts'
+import { formatIssues } from '../http/schema.ts'
+import type { InferOutput, StandardSchemaV1 } from '../http/schema.ts'
+import { hideFrameworkFrames } from '../utils/errors.ts'
+
+/** Environment variables, as in `process.env`. */
+export type Environment = Readonly<Record<string, string | undefined>>
+
+/** A configuration that does not match its schema; `issues` lists every problem. */
+export class ConfigError extends Error {
+  override readonly name = 'ConfigError'
+
+  constructor(
+    readonly config: string,
+    readonly issues: readonly string[]
+  ) {
+    super(`Invalid configuration "${config}":\n  ${issues.join('\n  ')}`)
+    hideFrameworkFrames(this)
+  }
+}
+
+/**
+ * A configuration, and the DI token of its value: `inject(AppConfig)`.
+ * `ConfigModule.forRoot()` loads it at startup; `load()` works without DI.
+ */
+export class Config<T> extends InjectionToken<T> {
+  readonly #schema: StandardSchemaV1<unknown, T>
+  readonly #source: (env: Environment) => unknown
+
+  constructor(name: string, schema: StandardSchemaV1<unknown, T>, source: (env: Environment) => unknown) {
+    super(name)
+    this.#schema = schema
+    this.#source = source
+  }
+
+  /** The value read from `env` and validated; throws a {@link ConfigError} listing every issue. */
+  async load(env: Environment = process.env): Promise<T> {
+    const result = await this.#schema['~standard'].validate(this.#source(env))
+
+    if (result.issues !== undefined) {
+      throw new ConfigError(this.description, formatIssues(result.issues, ''))
+    }
+
+    return result.value
+  }
+
+  override toString(): string {
+    return `Config(${this.description})`
+  }
+}
+
+/**
+ * Defines a configuration validated by `schema`. Its input is the environment,
+ * or what `source` builds from it, for a nested configuration:
+ *
+ * ```ts
+ * const DatabaseConfig = defineConfig('database', DatabaseSchema, (env) => ({
+ *   url: env.DATABASE_URL,
+ *   pool: { max: env.DATABASE_POOL_MAX },
+ * }))
+ * ```
+ */
+export const defineConfig = <S extends StandardSchemaV1>(
+  name: string,
+  schema: S,
+  source: (env: Environment) => unknown = (env) => env
+): Config<InferOutput<S>> => new Config(name, schema as StandardSchemaV1<unknown, InferOutput<S>>, source)

package/src/config/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module
+ * Configuration typed by a schema and validated at startup.
+ */
+
+export { Config, ConfigError, defineConfig } from './config.ts'
+export type { Environment } from './config.ts'
+export { ConfigModule } from './module.ts'
+export type { ConfigModuleOptions } from './module.ts'

package/src/config/module.ts

@@ -0,0 +1,40 @@
+/**
+ * @module
+ * `ConfigModule`: loads configurations at startup, like `ConfigModule.forRoot()` of `@nestjs/config`.
+ */
+
+import { Module, provide } from '../di/index.ts'
+import type { DynamicModule } from '../di/index.ts'
+import type { Config, Environment } from './config.ts'
+
+export interface ConfigModuleOptions {
+  /** Configurations to load and provide. */
+  readonly load: readonly Config<unknown>[]
+  /** Makes them injectable in every module. Defaults to `false`, as in Nest. */
+  readonly global?: boolean
+  /** Where variables come from, read when the container starts. Defaults to `process.env`. */
+  readonly env?: Environment
+}
+
+/**
+ * ```ts
+ * @Module({ imports: [ConfigModule.forRoot({ load: [AppConfig, DatabaseConfig], global: true })] })
+ * class AppModule {}
+ * ```
+ *
+ * Each configuration is loaded when the container starts; an invalid one
+ * fails the startup with a `ConfigError` listing all its issues. Tests
+ * replace a value with `overrides: [provide(AppConfig, { useValue })]`, and
+ * the replaced configuration is not loaded.
+ */
+@Module({})
+export class ConfigModule {
+  static forRoot(options: ConfigModuleOptions): DynamicModule {
+    return {
+      module: ConfigModule,
+      global: options.global ?? false,
+      providers: options.load.map((config) => provide(config, { useFactory: () => config.load(options.env) })),
+      exports: options.load,
+    }
+  }
+}

package/src/di/errors.ts

@@ -3,6 +3,8 @@
  * Errors raised by the dependency injection container.
  */
 
+import { hideFrameworkFrames } from '../utils/errors.ts'
+
 /**
  * Reason of a `DiError`.
  *
@@ -42,5 +44,6 @@ export class DiError extends Error {
     message: string
   ) {
     super(message)
+    hideFrameworkFrames(this)
   }
 }