@zerotal/core 1.0.0

package/src/container/ScopedResolver.ts

@@ -0,0 +1,117 @@
+/**
+ * The request-scoped resolver: caches scoped bindings for the lifetime of a
+ * single request and reference-counts them so the cache is flushed only once
+ * every outstanding reference (including pending afterResponse hooks) is gone.
+ */
+import type { Factory } from "./types.ts";
+import type { Container } from "./Container.ts";
+import { ScopedAfterFlushError } from "../errors/ContainerErrors.ts";
+
+/**
+ * Per-request cache of scoped bindings, flushed when the last reference is released.
+ */
+export class ScopedResolver {
+  private _cache = new Map<unknown, unknown>();
+  private _pending = new Map<unknown, Promise<unknown>>();
+  private _refCount = 1; // starts at 1 — the request itself holds a reference
+  private _flushed = false;
+
+  constructor(private readonly _container?: Container) {}
+
+  /**
+   * Resolve a scoped binding, caching the instance for the rest of the request.
+   * Concurrent calls for the same token share a single in-flight promise.
+   *
+   * @throws {ScopedAfterFlushError} If the scope has already been flushed.
+   */
+  async resolve<T>(token: unknown, factory: Factory<T>): Promise<T> {
+    if (this._flushed) {
+      throw new ScopedAfterFlushError(
+        `Attempted to resolve a scoped binding after the request scope was flushed. ` +
+          `Ensure afterResponse() is called before the response pipeline resolves.`,
+      );
+    }
+
+    if (this._cache.has(token)) {
+      return this._cache.get(token) as T;
+    }
+
+    if (this._pending.has(token)) {
+      return this._pending.get(token) as Promise<T>;
+    }
+
+    const promise = Promise.resolve(factory(this._container!)).then((instance) => {
+      this._cache.set(token, instance);
+      this._pending.delete(token);
+      return instance;
+    });
+
+    this._pending.set(token, promise);
+    return promise;
+  }
+
+  // ── Reference counting ────────────────────────────────────────────────
+
+  /**
+   * Acquire a reference. Called synchronously by HttpContext.afterResponse()
+   * at registration time — before any await — so the request's finally block
+   * cannot flush the scope before the callback has a chance to run.
+   */
+  acquire(): void {
+    if (this._flushed) {
+      throw new ScopedAfterFlushError(
+        `Cannot acquire a reference on a flushed ScopedResolver. ` +
+          `afterResponse() must be called before the response pipeline resolves.`,
+      );
+    }
+    this._refCount++;
+  }
+
+  /**
+   * Release a reference. When _refCount reaches 0, _doFlush() runs.
+   * Called by afterResponse() callback finally blocks and by flush().
+   */
+  release(): void {
+    this._refCount = Math.max(0, this._refCount - 1);
+    if (this._refCount === 0) this._doFlush();
+  }
+
+  /**
+   * Called by Application.ts in the fetch handler's finally block.
+   * Releases the request's own reference (the initial 1).
+   * If afterResponse() callbacks are pending they hold their own references,
+   * so _doFlush() will not run until all of them have released.
+   */
+  flush(): void {
+    this.release();
+  }
+
+  // ── Internal cleanup ──────────────────────────────────────────────────
+  private _doFlush(): void {
+    if (this._flushed) return;
+    this._flushed = true;
+    this._cache.clear();
+    this._pending.clear();
+    // The AsyncLocalStorage entry in Container is garbage-collected automatically
+    // when the runScoped() async context exits — no manual unregistration needed.
+  }
+
+  // ── Introspection (for tests and debug logging) ───────────────────────
+
+  /** @internal The current number of outstanding references on this scope. */
+  get refCount(): number {
+    return this._refCount;
+  }
+  /** @internal Whether the scope has been flushed and can no longer resolve. */
+  get isFlushed(): boolean {
+    return this._flushed;
+  }
+  /** @internal The number of cached scoped instances. */
+  get cacheSize(): number {
+    return this._cache.size;
+  }
+  /** The root container — allows middleware to resolve non-scoped bindings. */
+  get container(): Container | undefined {
+    return this._container;
+  }
+}

package/src/container/index.ts

@@ -0,0 +1,32 @@
+/**
+ * The IoC container and its supporting types: the {@link Container} that
+ * registers and resolves bindings (transient, singleton, scoped, value) with
+ * auto-wiring and cycle detection, the per-request {@link ScopedResolver}, the
+ * `@inject`/`deps` helpers for declaring constructor dependencies, and the
+ * {@link ContextualBindingBuilder} for consumer-specific overrides.
+ *
+ * @example
+ * ```ts
+ * import { Container, inject } from "@zerotal/core";
+ *
+ * class Logger {}
+ *
+ * @inject(Logger)
+ * class UserService {
+ *   constructor(private log: Logger) {}
+ * }
+ *
+ * const container = Container.createEmpty();
+ * container.singleton(Logger, () => new Logger());
+ *
+ * // UserService is auto-wired from its @inject() dependencies.
+ * const users = await container.make(UserService);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { Container } from "./Container.ts";
+export { ScopedResolver } from "./ScopedResolver.ts";
+export { inject, injectRegistry } from "./inject.ts";
+export { ContextualBindingBuilder } from "./ContextualBindingBuilder.ts";
+export type { ContainerBindings, BindingToken, Binding, Factory, BindingKind } from "./types.ts";

package/src/container/inject.ts

@@ -0,0 +1,55 @@
+/**
+ * TC39 standard ES decorators for dependency injection.
+ * No reflect-metadata. No external packages.
+ *
+ * Pass the dependency tokens straight to the decorator — they are auto-wired
+ * into the constructor in order:
+ *
+ *   @inject(Db, Cache)
+ *   class UserService {
+ *     constructor(private db: SQL, private cache: CacheManager) {}
+ *   }
+ *
+ * Tokens may be classes, abstract classes, or registry keys. Because standard
+ * decorators expose no runtime parameter types, the tokens must be listed
+ * explicitly (there is no reflect-metadata inference).
+ */
+
+import type { BindingToken } from "./types.ts";
+
+/**
+ * Module-level registry: constructor → ordered dependency tokens.
+ *
+ * @internal Populated by {@link inject} and read by the container during
+ * auto-wiring; not part of the public API.
+ */
+export const injectRegistry = new Map<Function, BindingToken[]>();
+
+/**
+ * Mark a class for auto-wiring by the container, declaring its constructor
+ * dependencies in order. `@inject()` with no tokens marks a class with a
+ * no-argument constructor for auto-wiring.
+ *
+ * @example
+ * ```ts
+ * @inject(Db, Cache)
+ * class UserService {
+ *   constructor(private db: SQL, private cache: CacheManager) {}
+ * }
+ *
+ * // The container builds the dependencies and injects them in order:
+ * const users = await container.make(UserService);
+ * ```
+ */
+export function inject(...tokens: BindingToken[]) {
+  // `args: any[]` (the codebase's standard Constructor shape) keeps the target
+  // assignable from classes with typed constructors — `unknown[]` would fail the
+  // constructor-parameter contravariance check at the decoration site.
+  return function (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any — decorator target must accept any class shape
+    target: new (...args: any[]) => unknown,
+    _context: ClassDecoratorContext,
+  ): void {
+    injectRegistry.set(target, tokens);
+  };
+}

package/src/container/types.ts

@@ -0,0 +1,71 @@
+/**
+ * The IoC container's type vocabulary: binding tokens, factory functions, the
+ * discriminated union of binding descriptors, and the typed binding registry
+ * that other packages extend through declaration merging.
+ */
+import type { Container } from "./Container.ts";
+
+// ── Binding token types ───────────────────────────────────────────────────
+
+// `args: any[]` (the codebase's standard Constructor shape) lets classes with
+// typed constructors be used as tokens — `unknown[]` fails constructor-parameter
+// contravariance at the call site (e.g. `App.make(ServiceWithCtorDeps)`).
+/* eslint-disable @typescript-eslint/no-explicit-any -- token types must accept any class shape */
+/** A concrete class usable as a container token. */
+export type ClassToken<T> = new (...args: any[]) => T;
+/** An abstract class usable as a container token. */
+export type AbstractToken<T> = abstract new (...args: any[]) => T;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+/** Any value that can identify a binding: a class, an abstract class, or a registry key. */
+export type BindingToken<T = unknown> = ClassToken<T> | AbstractToken<T> | keyof ContainerBindings;
+
+/** Builds an instance for a binding; may resolve asynchronously. */
+export type Factory<T> = (container: Container) => T | Promise<T>;
+
+/** The four binding lifetimes the container supports. */
+export type BindingKind = "transient" | "singleton" | "scoped" | "value";
+
+/** A binding that runs its factory on every resolution. */
+export interface TransientBinding<T> {
+  kind: "transient";
+  factory: Factory<T>;
+}
+
+/** A binding resolved once and cached for the process lifetime. */
+export interface SingletonBinding<T> {
+  kind: "singleton";
+  factory: Factory<T>;
+  instance: T | undefined;
+  resolved: boolean;
+}
+
+/** A binding resolved once per request scope. */
+export interface ScopedBinding<T> {
+  kind: "scoped";
+  factory: Factory<T>;
+}
+
+/** A binding backed by an already-constructed value. */
+export interface ValueBinding<T> {
+  kind: "value";
+  instance: T;
+}
+
+/** The discriminated union of all binding descriptors, keyed by `kind`. */
+export type Binding<T> =
+  TransientBinding<T> | SingletonBinding<T> | ScopedBinding<T> | ValueBinding<T>;
+
+/**
+ * The typed registry of well-known container bindings.
+ *
+ * Third-party packages extend this via declaration merging:
+ *   declare module '@zerotal/core' { interface ContainerBindings { 'db': SQL } }
+ */
+export interface ContainerBindings {
+  config: import("../config/ConfigManager.ts").ConfigManager;
+  events: import("../events/Emitter.ts").Emitter;
+  commands: import("../command/CommandRunner.ts").CommandRunner;
+  lock: import("../lock/LockManager.ts").LockManager;
+  log: import("../logger/LogManager.ts").LogManager;
+}

package/src/context/RequestContext.ts

@@ -0,0 +1,91 @@
+/**
+ * Ambient access to the current request's `HttpContext` through
+ * AsyncLocalStorage, so deeply nested code can reach the request without it
+ * being threaded through every call.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import type { TransactionContext } from "../contracts/index.ts";
+import { ContextOutsideRequestError } from "../errors/index.ts";
+
+// One ALS instance for the entire process lifetime.
+const storage = new AsyncLocalStorage<HttpContext>();
+
+/**
+ * Static accessor for the request-scoped `HttpContext` stored in AsyncLocalStorage.
+ *
+ * @remarks
+ * A boundary is opened once per request via {@link RequestContext.run} (in the
+ * `Bun.serve()` fetch handler). Inside it, any code — however deeply nested —
+ * reaches the current request with {@link RequestContext.get} (throws off-request)
+ * or {@link RequestContext.tryGet} (returns `undefined` off-request).
+ *
+ * @example
+ * ```ts
+ * const ctx = RequestContext.tryGet();
+ * if (ctx) console.log(`handling ${ctx.request.url}`);
+ * ```
+ */
+export class RequestContext {
+  // ── Entry point ───────────────────────────────────────────────────────
+  /**
+   * Establish a per-request ALS boundary.
+   *
+   * MUST be called at the very top of the Bun.serve() fetch handler —
+   * synchronously, before any await — to avoid the Bun #24199 edge case
+   * where ALS context is lost if await happens before run() is called.
+   *
+   * The callback runs inside the boundary. Everything called from within
+   * the callback (including deeply nested async code) can access ctx via
+   * RequestContext.get() with no argument passing.
+   */
+  static run<T>(ctx: HttpContext, callback: () => T): T {
+    return storage.run(ctx, callback);
+  }
+
+  // ── Accessors ─────────────────────────────────────────────────────────
+
+  /**
+   * Returns the current HttpContext. Throws if called outside a request.
+   *
+   * @throws {ContextOutsideRequestError} When called outside a request boundary opened by {@link RequestContext.run}.
+   */
+  static get(): HttpContext {
+    const ctx = storage.getStore();
+    if (!ctx) throw new ContextOutsideRequestError();
+    return ctx;
+  }
+
+  /**
+   * Returns the current HttpContext or undefined.
+   * Use this for code that runs in both request and non-request contexts
+   * (CLI commands, queue workers, scheduled jobs).
+   */
+  static tryGet(): HttpContext | undefined {
+    return storage.getStore();
+  }
+
+  // ── Typed shortcuts — facades use these ──────────────────────────────
+
+  /** The current request. Throws if called outside a request. */
+  static request(): Request {
+    return this.get().request;
+  }
+  /** The current request's unique id. Throws if called outside a request. */
+  static requestId(): string {
+    return this.get().requestId;
+  }
+  /** Elapsed milliseconds since the current request started. Throws if outside a request. */
+  static took(): number {
+    return this.get().took;
+  }
+  /** The current request's locale, defaulting to `"en"`. Throws if outside a request. */
+  static locale(): string {
+    return this.get().locale ?? "en";
+  }
+
+  /** The active database transaction for the current request, or `undefined`. */
+  static transaction(): TransactionContext | undefined {
+    return this.tryGet()?._transaction;
+  }
+}

package/src/contracts/auth.ts

@@ -0,0 +1,24 @@
+/**
+ * The authenticatable-user contract — the identity of "the current user" as the
+ * kernel and first-party packages refer to it, with **no** commitment to any
+ * particular User model or ORM.
+ *
+ * It is intentionally empty. An application makes it concrete by merging its own
+ * User type in, which flows through every core surface that speaks of the
+ * authenticated user (`ctx.user`, the `Auth` facade, policies):
+ *
+ * @example
+ * ```ts
+ * // app/models/User.ts
+ * declare module "@zerotal/core/contracts" {
+ *   interface AuthenticatableUser extends User {}
+ * }
+ * ```
+ *
+ * @remarks
+ * The `AuthenticatedUser` interface exported from `@zerotal/core` extends this,
+ * so augmenting either interface resolves to the same shape.
+ *
+ * @category Contracts
+ */
+export interface AuthenticatableUser {}

package/src/contracts/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `@zerotal/core/contracts` — the framework's interface layer.
+ *
+ * Every type here is **pure surface**: zero runtime code, and this subtree
+ * imports nothing from the rest of core. Its job is to break the duck-typing at
+ * the seams between the kernel and its satellite packages. Core consumes a
+ * contract; a package (or a third-party alternative) implements it; neither
+ * needs to import the other.
+ *
+ * | Contract | Kernel use | Implemented by |
+ * | --- | --- | --- |
+ * | {@link SessionContract} | `ctx.session`, `ctx.flash()` / `flashed()` | `@zerotal/session` |
+ * | {@link TransactionContext} | `ctx._transaction`, `RequestContext.transaction()` | `@zerotal/orm` |
+ * | {@link AuthenticatableUser} | the current-user identity | the app's User model |
+ *
+ * A package wires in by implementing the contract and merging into a registry —
+ * never by reaching into an untyped side channel on `HttpContext`.
+ *
+ * @packageDocumentation
+ */
+export type { SessionContract } from "./session.ts";
+export type { TransactionContext } from "./transaction.ts";
+export type { AuthenticatableUser } from "./auth.ts";

package/src/contracts/session.ts

@@ -0,0 +1,70 @@
+/**
+ * The session contract — the interface the kernel consumes so that
+ * `HttpContext.flash()` / `flashed()` and any session-aware code depend on a
+ * *shape*, never on `@zerotal/session`.
+ *
+ * `@zerotal/session` provides the implementation (`SessionManager` is what
+ * lands on `ctx.session`; `SessionAccessor` backs the `Session` facade). A third
+ * party can ship an alternative store and satisfy the same contract, and core is
+ * none the wiser.
+ *
+ * @remarks
+ * This file has **zero** runtime code and imports nothing — it is pure type
+ * surface. The extension point is an interface the compiler enforces, so a
+ * miswired implementation is a build error rather than a runtime surprise.
+ *
+ * @category Contracts
+ */
+export interface SessionContract {
+  /**
+   * The current session ID.
+   */
+  id(): string;
+
+  /**
+   * Read the value stored under `key`, or `undefined` if absent.
+   *
+   * Returns `unknown` — the caller asserts the stored shape. Higher-level
+   * surfaces (the `Session` facade, `ctx.session` helpers) layer a generic
+   * `<T>` cast on top.
+   */
+  get(key: string): unknown;
+
+  /**
+   * Read the value under `key` and remove it in one step ("read once").
+   * Returns the stored value, or `undefined` if absent.
+   */
+  pull(key: string): unknown;
+
+  /**
+   * Store `value` under `key`, overwriting any existing entry.
+   */
+  set(key: string, value: unknown): void;
+
+  /**
+   * Report whether `key` is present in the session.
+   */
+  has(key: string): boolean;
+
+  /**
+   * Remove a single value from the session.
+   */
+  forget(key: string): void;
+
+  /**
+   * Remove every value from the session. The session ID is left unchanged.
+   */
+  flush(): void;
+
+  /**
+   * Store a value that survives for exactly one subsequent request.
+   * Backs `ctx.flash()`.
+   */
+  flash(key: string, value: unknown): void;
+
+  /**
+   * Issue a fresh session ID while preserving the current session data.
+   * Call on any privilege change (login) to defend against session fixation.
+   */
+  regenerate(): void;
+}

package/src/contracts/transaction.ts

@@ -0,0 +1,26 @@
+/**
+ * The database-transaction contract — the opaque handle the kernel *carries*
+ * for a request or scope without depending on `@zerotal/orm`.
+ *
+ * `HttpContext._transaction` and `RequestContext.transaction()` are typed as
+ * this so the ORM can stash the active connection on the request and read it
+ * back, while core never learns what a `Bun.sql` connection actually is. The
+ * ORM's `SQLInstance` is a structural supertype of this — it adds `begin()` /
+ * `end()` — so assigning one here is checked, not cast.
+ *
+ * @remarks
+ * Core only ever *holds* the value; it never calls it. The single call
+ * signature is enough to make the carried value type-safe while leaving the
+ * full query API to the ORM, which narrows back to `SQLInstance` at its own
+ * boundary.
+ *
+ * @category Contracts
+ */
+export interface TransactionContext {
+  /**
+   * Run a query via a tagged template. Present so the contract is a genuine
+   * SQL-connection shape rather than an empty marker; the ORM's connection type
+   * is assignable to it.
+   */
+  <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+}

package/src/conventions/ConventionLoader.ts

@@ -0,0 +1,128 @@
+/**
+ * Convention-based auto-registration: at boot it scans well-known `app/*`
+ * directories, imports each file, and lets a "concern descriptor" register the
+ * relevant exports (models, observers, listeners, …). Packages contribute
+ * descriptors via `app.registerConcern(...)`, so core depends on neither orm nor auth.
+ */
+
+// Dev/test glob the filesystem; production can ship a generated manifest (see
+// `manifest` in config) to avoid runtime scanning — same idea as the jobs barrel.
+
+import type { Application } from "../application/Application.ts";
+import type { AppEnvironment } from "../provider/ServiceProvider.ts";
+import { frameworkLog } from "../logger/frameworkLog.ts";
+
+/** The context a concern receives while registering discovered modules. */
+export interface ConcernContext {
+  app: Application;
+  env: AppEnvironment;
+  /** Resolve a container binding synchronously, or undefined if not bound. */
+  resolve<T = unknown>(token: string): T | undefined;
+}
+
+/** Describes one auto-registration concern: where to scan and how to register what it finds. */
+export interface ConcernDescriptor {
+  /** Identifier, e.g. "models". Used as the config key for path overrides. */
+  name: string;
+  /** Lower runs first (models=10, observers=20, policies=30, listeners=40, …). */
+  order: number;
+  /** App-relative directory to scan, e.g. "app/models". Omit for one-shot concerns. */
+  dir?: string;
+  /** Environments this concern runs in. Default: all. */
+  envs?: AppEnvironment[];
+  /** Register the relevant exports from one discovered module. */
+  register?(exports: Record<string, unknown>, ctx: ConcernContext): void | Promise<void>;
+  /** One-shot hook run once after this concern's files (or instead of scanning). */
+  run?(ctx: ConcernContext): void | Promise<void>;
+}
+
+/** Options controlling a single {@link runConventions} pass. */
+export interface RunConventionsOptions {
+  root: string;
+  env: AppEnvironment;
+  /** Per-concern directory overrides (config `discovery.paths`). */
+  paths?: Record<string, string>;
+  ctx: ConcernContext;
+}
+
+function _shouldSkip(relativePath: string): boolean {
+  const file = relativePath.split("/").at(-1) ?? "";
+  return (
+    file.startsWith("_") ||
+    file.endsWith(".test.ts") ||
+    file.endsWith(".test.tsx") ||
+    file.endsWith(".spec.ts") ||
+    file.endsWith(".d.ts")
+  );
+}
+
+async function _scanDir(absoluteDirectory: string): Promise<string[]> {
+  // glob.scan yields nothing for a missing directory; the try/catch is belt-and-suspenders.
+  try {
+    const glob = new Bun.Glob("**/*.{ts,tsx}");
+    return await Array.fromAsync(glob.scan({ cwd: absoluteDirectory, onlyFiles: true }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scan a directory, import each non-skipped file, and hand the module to `onModule`. Shared by the
+ * concern loop and by the early provider/middleware discovery in Application. Import/handler
+ * errors are logged and skipped so one bad file can't abort boot.
+ */
+export async function importConventionModules(
+  absoluteDirectory: string,
+  label: string,
+  onModule: (module: Record<string, unknown>, file: string) => void | Promise<void>,
+): Promise<void> {
+  for (const file of await _scanDir(absoluteDirectory)) {
+    if (_shouldSkip(file)) continue;
+    try {
+      const loadedModule = (await import(`${absoluteDirectory}/${file}`)) as Record<
+        string,
+        unknown
+      >;
+      await onModule(loadedModule, file);
+    } catch (error) {
+      frameworkLog("app").error(`${label} discovery failed for ${file}`, { file }, error);
+    }
+  }
+}
+
+/**
+ * Run all concern descriptors in `order`. For each concern with a `dir`, scan + import each
+ * file and call `register(module)`. For each concern with `run`, call it once afterward.
+ * Import/registration errors are logged and skipped so one bad file can't abort boot.
+ */
+export async function runConventions(
+  concerns: ConcernDescriptor[],
+  options: RunConventionsOptions,
+): Promise<void> {
+  const orderedConcerns = [...concerns].sort((first, second) => first.order - second.order);
+  for (const concern of orderedConcerns) {
+    if (concern.envs && !concern.envs.includes(options.env)) continue;
+
+    if (concern.dir && concern.register) {
+      const relativeDirectory = options.paths?.[concern.name] ?? concern.dir;
+      const register = concern.register;
+      await importConventionModules(
+        `${options.root}/${relativeDirectory}`,
+        `convention "${concern.name}"`,
+        (loadedModule) => register(loadedModule, options.ctx),
+      );
+    }
+
+    if (concern.run) {
+      try {
+        await concern.run(options.ctx);
+      } catch (error) {
+        frameworkLog("app").error(
+          `Convention "${concern.name}" run hook failed`,
+          { convention: concern.name },
+          error,
+        );
+      }
+    }
+  }
+}