@zerotal/core 1.0.0

package/src/index.ts

@@ -0,0 +1,250 @@
+/**
+ * The Zerotal kernel — the IoC container, application lifecycle, HTTP router and
+ * pipeline, service providers, events, facades, and the common request helpers
+ * that every Zerotal app builds on.
+ *
+ * `@zerotal/core` is the one package every app depends on. This root entry
+ * carries only the hot, cheap kernel used across the framework — `Application`,
+ * the {@link Container}, {@link HttpContext}, the {@link Router}, middleware,
+ * providers, {@link Emitter | events}, facades, and helpers. Heavier or cohesive
+ * subsystems live behind explicit subpaths so importing the kernel never drags
+ * them in:
+ *
+ * | Subpath | What it provides |
+ * | --- | --- |
+ * | `@zerotal/core/contracts` | Interface-only seams packages implement and the kernel consumes (session, transaction, authenticatable user) |
+ * | `@zerotal/core/carbon` | Date/time via {@link Carbon} (pulls the Temporal polyfill) |
+ * | `@zerotal/core/http` | Outbound HTTP client, URL building, uploads, API resources, content negotiation |
+ * | `@zerotal/core/view` | Server-side JSX runtime + authoring helpers |
+ * | `@zerotal/core/env` | Typed environment-variable schema |
+ * | `@zerotal/core/config` | Config manager/loader + app config shapes |
+ * | `@zerotal/core/security` | `Crypt` + `Hash` |
+ * | `@zerotal/core/logger` | Structured logging (`Log`, channels) |
+ * | `@zerotal/core/lock` | Distributed locks |
+ * | `@zerotal/core/commands` | Built-in CLI commands |
+ * | `@zerotal/core/dev` | Dev-only build/reload tooling (owns `Bun.build`) |
+ * | `@zerotal/core/assets` | Asset URL helper + versioning |
+ * | `@zerotal/core/health` | Health checks |
+ * | `@zerotal/core/metrics` | HTTP request metrics |
+ *
+ * @example Bootstrap an application
+ * ```ts
+ * // bootstrap/app.ts
+ * import { Application } from "@zerotal/core";
+ * import providers from "./providers.ts";
+ *
+ * const app = Application.create({ providers, env: "web" });
+ * await app.start();
+ * ```
+ *
+ * @example Define routes and a controller
+ * ```ts
+ * import { Router } from "@zerotal/core";
+ *
+ * Router.get("/", (ctx) => ctx.html("<h1>Hello</h1>"));
+ * Router.get("/users/{id}", (ctx) => ctx.json({ id: ctx.params.id }));
+ * ```
+ *
+ * @remarks
+ * Zerotal runs on **Bun ≥ 1.1** — Node.js is not supported. The framework uses
+ * `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs
+ * throughout.
+ *
+ * @packageDocumentation
+ */
+
+// Application
+
+// Application
+export { Application, registerAppScope } from "./application/Application.ts";
+export { currentApp, tryCurrentApp, withApp } from "./application/currentApp.ts";
+export type { AuthenticatedUser } from "./auth/AuthenticatedUser.ts";
+export type {
+  WebSocketHandlers,
+  RoutingEntry,
+  RoutingConfig,
+  FileRoutingEntry,
+  FileRoutingConfig,
+  AppScopeInstaller,
+} from "./application/Application.ts";
+export { ExceptionHandler } from "./application/ExceptionHandler.ts";
+
+// Container
+export { Container } from "./container/Container.ts";
+export { ScopedResolver } from "./container/ScopedResolver.ts";
+export { inject } from "./container/inject.ts";
+export type { ContainerBindings, BindingToken, Factory } from "./container/types.ts";
+
+// Context
+export { RequestContext } from "./context/RequestContext.ts";
+
+// Pipeline
+export { HttpContext, safeRedirectPath } from "./pipeline/HttpContext.ts";
+export { currentPage, setCurrentPageResolver } from "./pipeline/currentPage.ts";
+export { pageElements } from "./helpers/pageElements.ts";
+export type { CurrentPageResolver } from "./pipeline/currentPage.ts";
+export type { ContextRegistry, ContextKey, ContextValue } from "./pipeline/ContextRegistry.ts";
+export type { CompiledDomain } from "./router/domain.ts";
+export type { RequestIPProvider } from "./pipeline/HttpContext.ts";
+export { Pipeline } from "./pipeline/Pipeline.ts";
+export type { Pipe, NextFn, HasResponse, HttpResponse } from "./pipeline/types.ts";
+
+// Provider
+export { ServiceProvider } from "./provider/ServiceProvider.ts";
+export type { AppEnvironment } from "./provider/ServiceProvider.ts";
+export type { ConcernDescriptor, ConcernContext } from "./conventions/ConventionLoader.ts";
+
+// Errors
+export {
+  ZerotalError,
+  HttpError,
+  BadRequestError,
+  NotFoundError,
+  UnauthorizedError,
+  ForbiddenError,
+  MethodNotAllowedError,
+  ConflictError,
+  GoneError,
+  UnprocessableEntityError,
+  TooManyRequestsError,
+  ServiceUnavailableError,
+  ValidationError,
+  ConfigError,
+  BindingNotFoundError,
+  ContainerLockedError,
+} from "./errors/index.ts";
+
+// Events
+export { Emitter } from "./events/Emitter.ts";
+export { EventFake } from "./events/EventFake.ts";
+export {
+  FrameworkEvents,
+  AppBooted,
+  RequestHandled,
+  RequestFailed,
+  OutgoingRequestCompleted,
+  MiddlewareSkipped,
+  CommandRan,
+} from "./events/FrameworkEvents.ts";
+export { CallQueuedListener } from "./events/CallQueuedListener.ts";
+export type { QueuedListener } from "./events/Emitter.ts";
+
+// Helpers
+export {
+  env,
+  requireEnv,
+  setAppEnv,
+  basePath,
+  Str,
+  tap,
+  tapAsync,
+  pipe,
+  pipeAsync,
+  rescue,
+  rescueSync,
+  data_get,
+} from "./helpers/index.ts";
+export { config } from "./helpers/config.ts";
+export { pluralize, singularize, snakeCase, camelCase, tableNameFor } from "./support/str.ts";
+export { deepMerge } from "./support/deepMerge.ts";
+export { safeEqual, sha256Hex, hmacHex } from "./support/crypto.ts";
+export {
+  buildCookie,
+  readCookie,
+  parseCookieHeader,
+  type CookieOptions,
+  type SameSite,
+} from "./support/cookie.ts";
+export { isDevSurfaceAllowed, devSurfacesEnabled } from "./support/env.ts";
+export { fluent, Fluent } from "./helpers/fluent.ts";
+export { collect, Collection } from "./helpers/Collection.ts";
+export {
+  ResponseBuilder,
+  RedirectBuilder,
+  MarkdownBuilder,
+  redirect,
+  redirectTo,
+  json,
+  view,
+  html,
+  markdown,
+  file,
+  abort,
+} from "./helpers/response.ts";
+export type { ControllerResponse } from "./helpers/response.ts";
+export { request } from "./helpers/request.ts";
+export { make, app } from "./helpers/make.ts";
+
+// Router
+export {
+  RouterState,
+  route,
+  ResourceRouteBuilder,
+  setImplicitModelResolver,
+} from "./router/Router.ts";
+export type {
+  RouteRegistration,
+  ViewRegistration,
+  GroupOptions,
+  RouterMacros,
+} from "./router/Router.ts";
+export type {
+  RouteDefinition,
+  HttpMethod,
+  MiddlewareClass,
+  ModelClass,
+  ModelBindingResolver,
+  ViewComponent,
+  ViewLayout,
+} from "./router/Route.ts";
+export { scanFileRoutes, registerFileRouteResolver } from "./router/FileRouter.ts";
+export type { FileRouteResolver, FileRouteContext } from "./router/FileRouter.ts";
+export type {
+  FileHandler,
+  RouteModule,
+  RouteFileMeta,
+  RouteMiddleware,
+  RouteMethodMiddleware,
+  MiddlewareModule,
+} from "./router/FileRouter.ts";
+export type { FileHandler as FileRouteHandler } from "./router/FileRouter.ts";
+
+// Command
+export { Command } from "./command/Command.ts";
+export type { ArgDef, FlagDef } from "./command/Command.ts";
+export { CommandRunner } from "./command/CommandRunner.ts";
+export { startZerotal } from "./command/startZerotal.ts";
+export type { StartZerotalOptions } from "./command/startZerotal.ts";
+
+// OutputWriter
+export { TerminalWriter, BufferWriter } from "./command/OutputWriter.ts";
+export type { OutputWriter } from "./command/OutputWriter.ts";
+
+// Facades
+export { createFacade } from "./facade/Facade.ts";
+export { App, Config, Events, Artisan } from "./facade/facades/index.ts";
+export type { ArtisanResult } from "./facade/facades/index.ts";
+
+// Middleware
+export { BaseMiddleware } from "./middleware/BaseMiddleware.ts";
+export { ThrottleMiddleware } from "./middleware/ThrottleMiddleware.ts";
+export type { ThrottleOptions } from "./middleware/ThrottleMiddleware.ts";
+export { CorsMiddleware } from "./middleware/CorsMiddleware.ts";
+export type { CorsOptions } from "./middleware/CorsMiddleware.ts";
+export { RateLimiter, LimiterDefinition } from "./middleware/RateLimiter.ts";
+export { SecureHeadersMiddleware } from "./middleware/SecureHeadersMiddleware.ts";
+export type { SecureHeadersOptions } from "./middleware/SecureHeadersMiddleware.ts";
+export { WebhookMiddleware } from "./middleware/WebhookMiddleware.ts";
+export type { WebhookOptions } from "./middleware/WebhookMiddleware.ts";
+
+// Response header helper — reconstructs (never mutates) so immutable responses are safe
+export { withHeaders } from "./http/withHeaders.ts";
+
+import { Router as _Router } from "./router/Router.ts";
+import type { RouterMacros as _RouterMacros } from "./router/Router.ts";
+
+/**
+ * The route registry, macro-aware: methods packages add via `Router.macro()`
+ * (`Router.flow`, `Router.inertia`, …) are visible to TypeScript without a cast.
+ */
+export const Router: typeof _Router & _RouterMacros = _Router as typeof _Router & _RouterMacros;

package/src/lock/LockManager.ts

@@ -0,0 +1,228 @@
+import type { LockDriver } from "./drivers/LockDriver.ts";
+import { LockNotAcquiredError } from "./errors.ts";
+
+/**
+ * Options controlling how {@link LockManager.block} and {@link Lock.block} wait
+ * for a busy lock.
+ *
+ * @category Acquiring
+ */
+export interface BlockOptions {
+  /**
+   * Maximum seconds to wait for the lock before throwing.
+   * Defaults to the lock TTL.
+   */
+  timeout?: number;
+
+  /**
+   * Milliseconds between polling attempts while waiting.
+   * Default: 100 ms.
+   */
+  retryDelay?: number;
+}
+
+/**
+ * A single named lock instance.
+ *
+ * Each instance holds a unique `owner` token so that release is always
+ * owner-guarded — a process that held a lock which expired cannot accidentally
+ * release the lock of a new holder that acquired it during the gap.
+ *
+ * @example
+ * ```ts
+ * const lock = manager.lock('invoice:123', 10);
+ * await lock.acquire();       // try once → returns boolean
+ * await lock.block(30);       // wait up to 30s → throws on timeout
+ * await lock.release();       // release (no-op if not acquired or expired)
+ * await lock.forceRelease();  // unconditionally remove
+ * ```
+ *
+ * @category Acquiring
+ */
+export class ManagedLock {
+  private readonly _owner: string;
+  private _acquired = false;
+
+  constructor(
+    private readonly _key: string,
+    private readonly _ttl: number,
+    private readonly _driver: LockDriver,
+  ) {
+    this._owner = crypto.randomUUID();
+  }
+
+  /**
+   * Try to acquire exactly once. Returns `true` on success. Re-acquiring while
+   * this same instance already holds the key refreshes it (returns `true`).
+   *
+   * @category Acquiring
+   */
+  async acquire(): Promise<boolean> {
+    this._acquired = await this._driver.acquire(this._key, this._owner, this._ttl);
+    return this._acquired;
+  }
+
+  /**
+   * Block until the lock can be acquired or `timeoutSeconds` elapses, polling
+   * every `retryDelayMs`.
+   *
+   * @param timeoutSeconds - Maximum seconds to wait before giving up.
+   * @param retryDelayMs - Milliseconds between acquire attempts (default 100).
+   * @throws {LockNotAcquiredError} On timeout.
+   * @category Acquiring
+   */
+  async block(timeoutSeconds: number, retryDelayMs = 100): Promise<void> {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+
+    while (true) {
+      if (await this.acquire()) return;
+      if (Date.now() >= deadline) break;
+      await Bun.sleep(retryDelayMs);
+    }
+
+    throw new LockNotAcquiredError(this._key);
+  }
+
+  /**
+   * Release the lock. Owner-guarded at the driver level, so it only removes the
+   * lock if this instance still holds it. No-op when this instance never
+   * acquired it or it already expired.
+   *
+   * @category Releasing
+   */
+  async release(): Promise<void> {
+    if (!this._acquired) return;
+    this._acquired = false;
+    await this._driver.release(this._key, this._owner);
+  }
+
+  /**
+   * Unconditionally remove the lock regardless of who holds it. Use with care —
+   * it can release a lock owned by another holder.
+   *
+   * @category Releasing
+   */
+  async forceRelease(): Promise<void> {
+    this._acquired = false;
+    await this._driver.forceRelease(this._key);
+  }
+
+  /** The logical lock name. */
+  get key(): string {
+    return this._key;
+  }
+  /** Whether this instance currently believes it holds the lock. */
+  get isAcquired(): boolean {
+    return this._acquired;
+  }
+}
+
+/**
+ * High-level entry point for distributed locking, backed by a pluggable
+ * {@link LockDriver} (memory, SQLite, or Redis).
+ *
+ * Offers three usage styles: {@link LockManager.try | try} (fail fast),
+ * {@link LockManager.block | block} (wait for the lock), and
+ * {@link LockManager.lock | lock} (a manual {@link ManagedLock} handle). Both
+ * `try` and `block` always release the lock, even when the callback throws.
+ * Normally resolved via the {@link Lock} facade rather than constructed
+ * directly.
+ *
+ * @category Acquiring
+ *
+ * @example
+ * ```ts
+ * // Fail fast: throw immediately if the lock is busy.
+ * await manager.try("invoice:123", 10, async () => {
+ *   await processInvoice(123);
+ * });
+ *
+ * // Blocking: wait up to 30s for the lock to free.
+ * await manager.block("invoice:123", 10, async () => {
+ *   await processInvoice(123);
+ * }, { timeout: 30 });
+ *
+ * // Manual, for flows that span multiple steps.
+ * const lock = manager.lock("invoice:123", 10);
+ * if (await lock.acquire()) {
+ *   try { await processInvoice(123); } finally { await lock.release(); }
+ * }
+ * ```
+ */
+export class LockManager {
+  /** @param _driver - Storage backend that performs the atomic acquire/release operations. */
+  constructor(private readonly _driver: LockDriver) {}
+
+  /**
+   * Build a named {@link ManagedLock} handle for manual acquire/release flows.
+   * Does not acquire the lock.
+   *
+   * @param key - Logical lock name.
+   * @param ttlSeconds - Time-to-live, in seconds, after which the lock auto-expires.
+   * @category Acquiring
+   */
+  lock(key: string, ttlSeconds: number): ManagedLock {
+    return new ManagedLock(key, ttlSeconds, this._driver);
+  }
+
+  /**
+   * Try to acquire the lock exactly once, execute `callback`, then release.
+   * The lock is always released — even when `callback` throws.
+   *
+   * @param key - Logical lock name.
+   * @param ttlSeconds - Lock time-to-live in seconds.
+   * @param callback - Critical section to run while the lock is held.
+   * @returns The value returned by `callback`.
+   * @throws {LockNotAcquiredError} Immediately, if the lock is already held.
+   * @category Acquiring
+   */
+  async try<T>(key: string, ttlSeconds: number, callback: () => Promise<T> | T): Promise<T> {
+    const lock = this.lock(key, ttlSeconds);
+    const acquired = await lock.acquire();
+    if (!acquired) throw new LockNotAcquiredError(key);
+    try {
+      return await callback();
+    } finally {
+      await lock.release();
+    }
+  }
+
+  /**
+   * Block until the lock can be acquired (up to `options.timeout` seconds,
+   * defaulting to `ttlSeconds`), then execute `callback` and release.
+   * The lock is always released — even when `callback` throws.
+   *
+   * @param key - Logical lock name.
+   * @param ttlSeconds - Lock time-to-live in seconds.
+   * @param callback - Critical section to run while the lock is held.
+   * @param options - Wait {@link BlockOptions.timeout | timeout} and
+   *   {@link BlockOptions.retryDelay | poll interval}.
+   * @returns The value returned by `callback`.
+   * @throws {LockNotAcquiredError} If the lock cannot be acquired before the timeout elapses.
+   * @category Acquiring
+   */
+  async block<T>(
+    key: string,
+    ttlSeconds: number,
+    callback: () => Promise<T> | T,
+    options: BlockOptions = {},
+  ): Promise<T> {
+    const lock = this.lock(key, ttlSeconds);
+    await lock.block(options.timeout ?? ttlSeconds, options.retryDelay);
+    try {
+      return await callback();
+    } finally {
+      await lock.release();
+    }
+  }
+
+  /**
+   * Release any background resources held by the underlying driver (timers, DB
+   * connections). Called by {@link LockProvider} when the application stops.
+   *
+   * @category Configuration
+   */
+  dispose(): void {
+    this._driver.dispose?.();
+  }
+}

package/src/lock/config.ts

@@ -0,0 +1,49 @@
+import { deepMerge } from "../support/deepMerge.ts";
+
+/**
+ * Full shape of the `lock` config namespace, as produced by {@link LockConfig}.
+ * Selects the storage backend and driver-specific options.
+ *
+ * @category Configuration
+ */
+export interface LockConfigShape {
+  /** Storage backend. Default: `'memory'` */
+  driver: "memory" | "sqlite" | "redis";
+
+  /** Key prefix prepended to every lock key. Default: `'zerotal_lock:'` */
+  prefix: string;
+
+  /** SQLite-specific options. */
+  sqlite: {
+    /** Path to the SQLite file. Use `':memory:'` for in-process storage. */
+    path: string;
+  };
+}
+
+const defaults: LockConfigShape = {
+  driver: "memory",
+  prefix: "zerotal_lock:",
+  sqlite: { path: ":memory:" },
+};
+
+/**
+ * Create a typed {@link LockConfigShape} with defaults applied (memory driver,
+ * `zerotal_lock:` prefix, in-memory SQLite path).
+ *
+ * @param options - Partial overrides deep-merged over the defaults.
+ * @returns The resolved lock config.
+ * @category Configuration
+ *
+ * @example
+ * ```ts
+ * // config/lock.ts
+ * import { LockConfig } from '@zerotal/core/lock';
+ * export default LockConfig({ driver: 'redis' });
+ * ```
+ */
+export function LockConfig(options: Partial<LockConfigShape> = {}): LockConfigShape {
+  return deepMerge(defaults, options);
+}
+
+// The `lock` config namespace is registered directly on core's ConfigRegistry
+// (see src/config/registry.ts) since lock ships as part of core.

package/src/lock/drivers/LockDriver.ts

@@ -0,0 +1,32 @@
+/**
+ * Contract for lock storage backends.
+ *
+ * Every method must be atomic at the driver level. The `owner` parameter
+ * prevents a process from releasing a lock it no longer holds (e.g. if the
+ * TTL expired and another process re-acquired).
+ *
+ * @category Configuration
+ */
+export interface LockDriver {
+  /**
+   * Try to acquire the lock. Returns `true` when acquired, `false` if already
+   * held by another owner and not yet expired.
+   */
+  acquire(key: string, owner: string, ttlSeconds: number): Promise<boolean>;
+
+  /**
+   * Release the lock only if the caller is still the owner.
+   * Returns `true` when released, `false` if the lock was held by someone else
+   * (e.g. TTL expired and another process re-acquired).
+   */
+  release(key: string, owner: string): Promise<boolean>;
+
+  /** Unconditionally delete the lock regardless of owner. */
+  forceRelease(key: string): Promise<void>;
+
+  /** Returns `true` if the lock is currently held (not expired). */
+  exists(key: string): Promise<boolean>;
+
+  /** Release background resources (timers, DB connections). */
+  dispose?(): void;
+}

package/src/lock/drivers/MemoryLockDriver.ts

@@ -0,0 +1,52 @@
+import type { LockDriver } from "./LockDriver.ts";
+
+interface LockRecord {
+  owner: string;
+  expiresAt: number; // Date.now() ms
+}
+
+/**
+ * In-process lock driver backed by a plain Map.
+ *
+ * Suitable for single-instance servers and tests. Not safe across
+ * processes or server restarts — use the Redis or SQLite driver for
+ * distributed / persistent locks.
+ *
+ * @category Configuration
+ */
+export class MemoryLockDriver implements LockDriver {
+  private readonly _store = new Map<string, LockRecord>();
+
+  async acquire(key: string, owner: string, ttlSeconds: number): Promise<boolean> {
+    const now = Date.now();
+    const existing = this._store.get(key);
+
+    if (existing && now < existing.expiresAt) {
+      return existing.owner === owner; // re-entrant for same owner
+    }
+
+    this._store.set(key, { owner, expiresAt: now + ttlSeconds * 1000 });
+    return true;
+  }
+
+  async release(key: string, owner: string): Promise<boolean> {
+    const existing = this._store.get(key);
+    if (!existing || existing.owner !== owner) return false;
+    this._store.delete(key);
+    return true;
+  }
+
+  async forceRelease(key: string): Promise<void> {
+    this._store.delete(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const existing = this._store.get(key);
+    return !!existing && Date.now() < existing.expiresAt;
+  }
+
+  /** Flush all locks — useful in tests. */
+  flush(): void {
+    this._store.clear();
+  }
+}

package/src/lock/drivers/RedisLockDriver.ts

@@ -0,0 +1,58 @@
+import { redis } from "bun";
+import type { LockDriver } from "./LockDriver.ts";
+
+// Lua script: delete the key only if the caller is still the owner.
+// Evaluated atomically by Redis — no race between GET and DEL.
+const RELEASE_SCRIPT = `
+if redis.call('get', KEYS[1]) == ARGV[1] then
+  return redis.call('del', KEYS[1])
+else
+  return 0
+end
+`;
+
+/**
+ * Redis-backed distributed lock driver.
+ *
+ * Uses `SET key owner NX EX ttl` for atomic acquisition and a Lua script
+ * for owner-guarded release. Safe across multiple server instances.
+ *
+ * Requires Bun's built-in Redis client (available when the REDIS_URL
+ * environment variable is set or via the global `redis` export from `bun`).
+ *
+ * @category Configuration
+ */
+export class RedisLockDriver implements LockDriver {
+  constructor(private readonly _prefix: string = "zerotal_lock:") {}
+
+  private _key(key: string): string {
+    return this._prefix + key;
+  }
+
+  async acquire(key: string, owner: string, ttlSeconds: number): Promise<boolean> {
+    const result = await redis.set(this._key(key), owner, "NX", "EX", String(ttlSeconds));
+    if (result !== null) return true;
+
+    // Re-entrant: allow the same owner to refresh its own lock
+    const current = await redis.get(this._key(key));
+    if (current === owner) {
+      await redis.expire(this._key(key), ttlSeconds);
+      return true;
+    }
+
+    return false;
+  }
+
+  async release(key: string, owner: string): Promise<boolean> {
+    const deleted = await redis.send("EVAL", [RELEASE_SCRIPT, "1", this._key(key), owner]);
+    return deleted === 1;
+  }
+
+  async forceRelease(key: string): Promise<void> {
+    await redis.del(this._key(key));
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return redis.exists(this._key(key));
+  }
+}