@zerotal/core 1.0.0

package/src/lock/drivers/SqliteLockDriver.ts

@@ -0,0 +1,85 @@
+import { Database } from "bun:sqlite";
+import type { LockDriver } from "./LockDriver.ts";
+
+/**
+ * SQLite-backed lock driver.
+ *
+ * Suitable for single-server deployments that need locks to survive process
+ * restarts. Backed by `bun:sqlite` — fully synchronous under the hood so
+ * every acquire/release is a single atomic statement.
+ *
+ * Use `:memory:` as the path for in-process persistence across tests
+ * without touching the filesystem.
+ *
+ * @category Configuration
+ */
+export class SqliteLockDriver implements LockDriver {
+  private readonly _db: Database;
+
+  constructor(path = ":memory:") {
+    this._db = new Database(path);
+    this._db.exec(`
+      CREATE TABLE IF NOT EXISTS zerotal_locks (
+        key        TEXT    PRIMARY KEY,
+        owner      TEXT    NOT NULL,
+        expires_at INTEGER NOT NULL
+      )
+    `);
+  }
+
+  async acquire(key: string, owner: string, ttlSeconds: number): Promise<boolean> {
+    const now = Date.now();
+    const expiresAt = now + ttlSeconds * 1000;
+
+    // Purge any expired record for this key so INSERT can succeed
+    this._db.prepare("DELETE FROM zerotal_locks WHERE key = ? AND expires_at <= ?").run(key, now);
+
+    // If the lock is already held by this owner, refresh the TTL
+    const existing = this._db
+      .prepare<{ owner: string }, string>("SELECT owner FROM zerotal_locks WHERE key = ?")
+      .get(key);
+
+    if (existing) {
+      if (existing.owner === owner) {
+        this._db
+          .prepare("UPDATE zerotal_locks SET expires_at = ? WHERE key = ?")
+          .run(expiresAt, key);
+        return true;
+      }
+      return false; // held by another owner
+    }
+
+    try {
+      this._db
+        .prepare("INSERT INTO zerotal_locks (key, owner, expires_at) VALUES (?, ?, ?)")
+        .run(key, owner, expiresAt);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async release(key: string, owner: string): Promise<boolean> {
+    const result = this._db
+      .prepare("DELETE FROM zerotal_locks WHERE key = ? AND owner = ?")
+      .run(key, owner);
+    return result.changes > 0;
+  }
+
+  async forceRelease(key: string): Promise<void> {
+    this._db.prepare("DELETE FROM zerotal_locks WHERE key = ?").run(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const row = this._db
+      .prepare<{ 1: number }, [string, number]>(
+        "SELECT 1 FROM zerotal_locks WHERE key = ? AND expires_at > ?",
+      )
+      .get(key, Date.now());
+    return row !== null;
+  }
+
+  dispose(): void {
+    this._db.close();
+  }
+}

package/src/lock/errors.ts

@@ -0,0 +1,20 @@
+import { ZerotalError } from "../errors/index.ts";
+
+/**
+ * Thrown when a lock cannot be acquired: immediately by
+ * {@link LockManager.try | try}/{@link Lock.try | Lock.try} when the key is
+ * busy, or by {@link LockManager.block | block}/{@link Lock.block | Lock.block}
+ * when the wait timeout elapses. Carries the contended {@link key} and maps to
+ * HTTP 409 (code `E_LOCK_NOT_ACQUIRED`).
+ *
+ * @category Acquiring
+ */
+export class LockNotAcquiredError extends ZerotalError {
+  /** The lock key that could not be acquired. */
+  readonly key: string;
+
+  constructor(key: string) {
+    super(`[Zerotal Lock] Could not acquire lock for key: "${key}"`, "E_LOCK_NOT_ACQUIRED", 409);
+    this.key = key;
+  }
+}

package/src/lock/facades/Lock.ts

@@ -0,0 +1,114 @@
+import { currentApp } from "../../application/currentApp.ts";
+import { ZerotalError } from "../../errors/index.ts";
+import type { LockManager, ManagedLock, BlockOptions } from "../LockManager.ts";
+import { LockNotAcquiredError } from "../errors.ts";
+
+/**
+ * Resolve the live LockManager from the application container on every call.
+ * The container is the single source of truth — the facade caches nothing and
+ * holds no module-level state.
+ */
+function _manager(): LockManager {
+  try {
+    return currentApp().container.makeSync("lock");
+  } catch {
+    throw new ZerotalError(
+      "[Zerotal Lock] Lock facade unavailable — register LockProvider in your application.",
+      "E_LOCK_FACADE_UNAVAILABLE",
+      500,
+    );
+  }
+}
+
+/**
+ * Static facade over the container-bound {@link LockManager}.
+ *
+ * Resolves the live `lock` singleton on every call and forwards to the
+ * manager, so it exposes the same three usage styles: {@link Lock.try | try}
+ * (fail fast), {@link Lock.block | block} (wait for the lock), and
+ * {@link Lock.make | make} (a manual {@link ManagedLock} handle). Requires
+ * {@link LockProvider} to be registered.
+ *
+ * @category Acquiring
+ *
+ * @example
+ * ```ts
+ * // Fail-fast — throws immediately if the lock is busy
+ * await Lock.try('invoice:123', 10, async () => {
+ *   await processInvoice(123);
+ * });
+ *
+ * // Blocking — waits up to 30s for the lock
+ * await Lock.block('invoice:123', 10, async () => {
+ *   await processInvoice(123);
+ * }, { timeout: 30 });
+ *
+ * // Manual handle for complex flows
+ * const handle = Lock.make('payment:456', 15);
+ * if (await handle.acquire()) {
+ *   try {
+ *     await capturePayment(456);
+ *   } finally {
+ *     await handle.release();
+ *   }
+ * }
+ * ```
+ */
+export class Lock {
+  /**
+   * Create a named lock handle for manual acquire/release flows.
+   * Does NOT acquire the lock — call `.acquire()` or `.block()` explicitly.
+   *
+   * @param key - Logical lock name.
+   * @param ttlSeconds - Lock time-to-live in seconds.
+   * @throws {ZerotalError} (code `E_LOCK_FACADE_UNAVAILABLE`) if {@link LockProvider} is not registered.
+   * @category Acquiring
+   */
+  static make(key: string, ttlSeconds: number): ManagedLock {
+    return _manager().lock(key, ttlSeconds);
+  }
+
+  /**
+   * Acquire the lock exactly once, run `callback`, then release — always,
+   * even if `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 busy.
+   * @category Acquiring
+   */
+  static async try<T>(key: string, ttlSeconds: number, callback: () => Promise<T> | T): Promise<T> {
+    return _manager().try(key, ttlSeconds, callback);
+  }
+
+  /**
+   * Wait until the lock is free (up to `options.timeout` seconds), run
+   * `callback`, then release — always, even if `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 poll interval.
+   * @returns The value returned by `callback`.
+   * @throws {LockNotAcquiredError} If the timeout elapses before the lock is acquired.
+   * @category Acquiring
+   */
+  static async block<T>(
+    key: string,
+    ttlSeconds: number,
+    callback: () => Promise<T> | T,
+    options?: BlockOptions,
+  ): Promise<T> {
+    return _manager().block(key, ttlSeconds, callback, options);
+  }
+
+  /**
+   * The {@link LockNotAcquiredError} class, re-exported for convenience in
+   * `catch` blocks (`err instanceof Lock.NotAcquired`).
+   *
+   * @category Acquiring
+   */
+  static readonly NotAcquired = LockNotAcquiredError;
+}

package/src/lock/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Distributed mutual-exclusion locks for Zerotal applications.
+ *
+ * A named lock guarantees that at most one holder runs a critical section at a
+ * time — across processes and servers when backed by the Redis or SQLite
+ * driver, or in-process with the default memory driver. Every lock carries a
+ * TTL so a crashed holder cannot deadlock the key, and release is owner-guarded
+ * so a holder whose lock already expired can never release a newer holder's
+ * lock. Reach the container-bound manager through the {@link Lock} facade;
+ * configure the backend with {@link LockConfig}.
+ *
+ * @example
+ * ```ts
+ * import { Lock } from "@zerotal/core/lock";
+ *
+ * // Fail fast: throw LockNotAcquiredError immediately if the key is busy.
+ * await Lock.try("invoice:123", 10, async () => {
+ *   await processInvoice(123);
+ * });
+ *
+ * // Blocking: wait up to 30s for the key to free, holding it for 10s (TTL).
+ * await Lock.block("invoice:123", 10, async () => {
+ *   await processInvoice(123);
+ * }, { timeout: 30 });
+ *
+ * // Manual handle for flows that span multiple steps.
+ * const handle = Lock.make("payment:456", 15);
+ * if (await handle.acquire()) {
+ *   try {
+ *     await capturePayment(456);
+ *   } finally {
+ *     await handle.release();
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { LockManager, ManagedLock } from "./LockManager.ts";
+export type { BlockOptions } from "./LockManager.ts";
+
+export { Lock } from "./facades/Lock.ts";
+export { LockProvider } from "../provider/LockProvider.ts";
+export { LockConfig } from "./config.ts";
+export type { LockConfigShape } from "./config.ts";
+export { LockNotAcquiredError } from "./errors.ts";
+
+// Drivers — exported for custom driver registration and direct instantiation
+export type { LockDriver } from "./drivers/LockDriver.ts";
+export { MemoryLockDriver } from "./drivers/MemoryLockDriver.ts";
+export { SqliteLockDriver } from "./drivers/SqliteLockDriver.ts";
+export { RedisLockDriver } from "./drivers/RedisLockDriver.ts";

package/src/logger/Log.ts

@@ -0,0 +1,35 @@
+import { createFacade } from "../facade/Facade.ts";
+
+/**
+ * Static facade over the container-bound {@link LogManager}.
+ *
+ * Every access resolves the live `log` singleton, so `Log` exposes the full
+ * {@link LogManager} surface: the five level methods
+ * ({@link LogManager.debug | debug}/{@link LogManager.info | info}/
+ * {@link LogManager.warn | warn}/{@link LogManager.error | error}/
+ * {@link LogManager.fatal | fatal}) on the default channel, plus
+ * {@link LogManager.channel | channel} and
+ * {@link LogManager.withContext | withContext}. Available after the application
+ * has booted (the facade throws if accessed at module scope before boot).
+ *
+ * @category Logging
+ *
+ * @example
+ * ```ts
+ * import { Log } from "@zerotal/core/logger";
+ *
+ * // Level + structured context.
+ * Log.info("Order placed", { orderId: 99, total: 42.5 });
+ *
+ * // Attach an error — its message and stack are captured onto the entry.
+ * Log.error("Charge failed", { orderId: 99 }, err);
+ *
+ * // Contextual logging: shared fields merged into every subsequent entry.
+ * const scoped = Log.withContext({ tenant: "acme" });
+ * scoped.warn("Quota nearly exhausted", { pct: 92 });
+ *
+ * // Target a specific configured channel.
+ * Log.channel("daily").info("Persisted to today's rotating file");
+ * ```
+ */
+export const Log = createFacade("log");