@shaferllc/keel 0.66.0 → 0.68.0

package/dist/core/lock.js

@@ -0,0 +1,215 @@
+/**
+ * Distributed locks — "only one of you may do this at a time", across processes
+ * and across nodes. The counterpart to the cache's stampede protection: that
+ * collapses concurrent work *inside one isolate*, this one coordinates work
+ * *between* them.
+ *
+ *   const [ran] = await lock("invoice:42").run(async () => charge(invoice));
+ *   if (!ran) return;   // someone else is already charging it
+ *
+ * Like every other backend in keel, the store is a small pluggable seam and the
+ * core imports no driver — `MemoryLockStore` is the built-in default (per
+ * isolate, so it's for tests and single-process apps); the locks guide has Redis
+ * and database recipes for the real thing.
+ *
+ * ## Two safety properties, both easy to get wrong
+ *
+ * **Ownership.** Every acquisition mints a random owner token, and release and
+ * extend only succeed for the owner. Without that, a lock whose TTL expired
+ * mid-work gets picked up by process B, and process A's `release()` — arriving
+ * late — would delete *B's* lock, letting a third process in. A store must
+ * compare-and-delete, not just delete.
+ *
+ * **TTL.** A lock always expires. If a holder crashes, the lock must not be held
+ * forever, so there's no "hold until released" mode. Pick a TTL longer than the
+ * work; if the work might outrun it, `extend()` from inside.
+ */
+/**
+ * An in-memory `LockStore` — the default. Per-isolate, so it coordinates
+ * *within* one process and nothing more: perfect for tests and single-process
+ * apps, useless across a cluster. Point `setLockStore()` at Redis for that.
+ */
+export class MemoryLockStore {
+    entries = new Map();
+    /** The live entry for a key, dropping it if it has expired. */
+    live(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    async acquire(key, owner, ttlMs) {
+        if (this.live(key))
+            return false;
+        this.entries.set(key, { owner, expiresAt: Date.now() + ttlMs });
+        return true;
+    }
+    async release(key, owner) {
+        const entry = this.live(key);
+        if (!entry || entry.owner !== owner)
+            return false;
+        this.entries.delete(key);
+        return true;
+    }
+    async extend(key, owner, ttlMs) {
+        const entry = this.live(key);
+        if (!entry || entry.owner !== owner)
+            return false;
+        entry.expiresAt = Date.now() + ttlMs;
+        return true;
+    }
+    async isLocked(key) {
+        return this.live(key) !== undefined;
+    }
+    async remainingTime(key) {
+        const entry = this.live(key);
+        return entry ? entry.expiresAt - Date.now() : null;
+    }
+}
+/** A lock that has expired or was never held. */
+export class LockNotHeldError extends Error {
+    constructor(key) {
+        super(`The lock "${key}" is not held by you — it expired or was released.`);
+        this.name = "LockNotHeldError";
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A random owner token. Web Crypto, so it works on Node and the edge. */
+function mintOwner() {
+    return crypto.randomUUID();
+}
+/* ---------------------------------- lock ---------------------------------- */
+export class Lock {
+    key;
+    ttlMs;
+    store;
+    /** Non-null only while this instance holds the lock. */
+    owner;
+    constructor(key, 
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    ttlMs, store, owner) {
+        this.key = key;
+        this.ttlMs = ttlMs;
+        this.store = store;
+        this.owner = owner;
+    }
+    /**
+     * Take the lock, run `fn`, and always give it back — the form you want almost
+     * every time, because the `finally` is what stops a throwing callback from
+     * leaving the lock held until its TTL runs out.
+     *
+     * Returns `[ran, result]`: `ran` is false if someone else holds it, in which
+     * case `fn` never ran.
+     *
+     *   const [ran, invoice] = await lock("invoice:42").run(() => charge(id));
+     *   if (!ran) return;   // another worker is on it
+     */
+    async run(fn, options = {}) {
+        if (!(await this.acquire(options)))
+            return [false, undefined];
+        try {
+            return [true, await fn()];
+        }
+        finally {
+            await this.release();
+        }
+    }
+    /** `run()`, but never waits: if the lock is held, give up at once. */
+    runImmediately(fn) {
+        return this.run(fn, { timeout: 0 });
+    }
+    /**
+     * Take the lock, waiting up to `timeout` for it. Returns whether we got it.
+     *
+     * Prefer `run()` — with a bare `acquire()` you own the `try/finally`, and a
+     * throw between here and `release()` leaks the lock for the rest of its TTL.
+     */
+    async acquire(options = {}) {
+        const { timeout = 0, retryDelay = 50 } = options;
+        const deadline = Date.now() + timeout;
+        const owner = mintOwner();
+        for (;;) {
+            if (await this.store.acquire(this.key, owner, this.ttlMs)) {
+                this.owner = owner;
+                return true;
+            }
+            // Wait only if there's time left to wait *and* to sleep before the deadline.
+            if (Date.now() + retryDelay >= deadline)
+                return false;
+            await sleep(retryDelay);
+        }
+    }
+    /** Take the lock only if it's free right now. */
+    acquireImmediately() {
+        return this.acquire({ timeout: 0 });
+    }
+    /** Give the lock back. A no-op if we no longer hold it (it may have expired). */
+    async release() {
+        if (!this.owner)
+            return false;
+        const released = await this.store.release(this.key, this.owner);
+        this.owner = undefined;
+        return released;
+    }
+    /**
+     * Push the expiry out — for work that might outrun the TTL. Throws
+     * `LockNotHeldError` if we've already lost it, because the alternative (a
+     * silent no-op) would let you carry on believing you hold a lock you don't.
+     */
+    async extend(ttlMs = this.ttlMs) {
+        if (!this.owner || !(await this.store.extend(this.key, this.owner, ttlMs))) {
+            this.owner = undefined;
+            throw new LockNotHeldError(this.key);
+        }
+    }
+    /** Whether *anyone* holds this key — not necessarily us. */
+    isLocked() {
+        return this.store.isLocked(this.key);
+    }
+    /** Whether we held this lock but no longer do. */
+    async isExpired() {
+        if (!this.owner)
+            return false; // never acquired — not the same as expired
+        return !(await this.store.isLocked(this.key));
+    }
+    /** Milliseconds until the lock expires, or null if nobody holds it. */
+    getRemainingTime() {
+        return this.store.remainingTime(this.key);
+    }
+    /**
+     * Freeze the lock (key, TTL, owner token) to a string, so another process can
+     * `restoreLock()` it and release or extend the *same* lock — the handoff you
+     * need when one process takes the lock and another finishes the work.
+     */
+    serialize() {
+        return JSON.stringify({ key: this.key, ttlMs: this.ttlMs, owner: this.owner });
+    }
+}
+/* --------------------------------- global --------------------------------- */
+let store = new MemoryLockStore();
+/** Register the lock store used by `lock()`. */
+export function setLockStore(next) {
+    store = next;
+    return store;
+}
+/** The active lock store. */
+export function getLockStore() {
+    return store;
+}
+/**
+ * A lock on `key`, held for `ttlMs` once acquired (default 30s).
+ *
+ *   const [ran] = await lock("invoice:42").run(() => charge(invoice));
+ */
+export function lock(key, ttlMs = 30_000) {
+    return new Lock(key, ttlMs, store);
+}
+/** Rebuild a lock from `serialize()` — same key, same TTL, same owner token. */
+export function restoreLock(serialized) {
+    const { key, ttlMs, owner } = JSON.parse(serialized);
+    return new Lock(key, ttlMs, store, owner);
+}

package/dist/core/logger.d.ts

@@ -5,8 +5,37 @@
  *
  *   logger().info("user registered", { userId: user.id });
  *   logger().error("payment failed", { orderId, error });
+ *
+ * Output goes through a `Sink` — `console` by default, but any function, so logs
+ * can go to a file, an HTTP collector, or a buffer in tests. Register extra
+ * loggers by name (`setLogger(audit, "audit")`) when a subsystem needs its own
+ * level or destination.
  */
-export type LogLevel = "debug" | "info" | "warn" | "error";
+/** Levels, quietest last. `trace` is the most verbose; `fatal` the most severe. */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/** One log event, as handed to a `Sink`. */
+export interface LogRecord {
+    level: LogLevel;
+    /** ISO 8601. */
+    time: string;
+    msg: string;
+    /** Bindings merged with the call's context, after redaction. */
+    fields: Record<string, unknown>;
+}
+/** Where log lines go. Return nothing; a sink that throws is a sink that lies. */
+export type Sink = (record: LogRecord) => void;
+export interface RedactOptions {
+    /**
+     * Field paths to redact — a top-level key (`"password"`), a dot path
+     * (`"req.headers.authorization"`), or a wildcard segment (`"*.password"`,
+     * `"user.*.token"`).
+     */
+    paths: string[];
+    /** What to replace matched values with. Default: `"[redacted]"`. */
+    censor?: string;
+    /** Delete the key outright instead of censoring it. Default: false. */
+    remove?: boolean;
+}
 export interface LoggerOptions {
     /** Minimum level to emit. Default: "info". */
     level?: LogLevel;
@@ -15,20 +44,69 @@ export interface LoggerOptions {
     /** Fields merged into every log line. */
     bindings?: Record<string, unknown>;
     /**
-     * Field paths to redact from log output — top-level keys (`"password"`) or dot
-     * paths (`"req.headers.authorization"`). Matched values become `"[redacted]"`.
+     * Field paths to redact. A `string[]` is shorthand for `{ paths }` — matched
+     * values become `"[redacted]"`.
      */
-    redact?: string[];
+    redact?: string[] | RedactOptions;
+    /** Where lines go. Default: the console (`console.log` / `.warn` / `.error`). */
+    sink?: Sink;
+    /** Silence the logger entirely — nothing is emitted, at any level. */
+    enabled?: boolean;
+}
+/** The default sink: JSON to stdout, or a pretty single line when `pretty`. */
+export declare function consoleSink(pretty?: boolean): Sink;
+/** A sink that collects records in memory — for tests. Assert on `.records`. */
+export declare class MemorySink {
+    readonly records: LogRecord[];
+    /** The sink function to hand to `LoggerOptions.sink`. */
+    readonly sink: Sink;
+    /** Records at one level. */
+    at(level: LogLevel): LogRecord[];
+    /** The messages logged, in order. */
+    messages(): string[];
+    clear(): void;
 }
 export declare class Logger {
     private options;
     private threshold;
+    private redact?;
+    private sink;
     constructor(options?: LoggerOptions);
+    /**
+     * Whether a level would be emitted. Check it before building an expensive
+     * context object — the work of assembling it happens whether or not the line
+     * is ever written.
+     *
+     *   if (logger().isLevelEnabled("debug")) {
+     *     logger().debug("state", { snapshot: expensiveSnapshot() });
+     *   }
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    /** Run `fn` only if `level` would be emitted — the callback form of the above. */
+    ifLevelEnabled(level: LogLevel, fn: (log: Logger) => void): void;
     private write;
+    trace(message: string, context?: Record<string, unknown>): void;
     debug(message: string, context?: Record<string, unknown>): void;
     info(message: string, context?: Record<string, unknown>): void;
     warn(message: string, context?: Record<string, unknown>): void;
     error(message: string, context?: Record<string, unknown>): void;
+    /** An unrecoverable failure — the loudest level. */
+    fatal(message: string, context?: Record<string, unknown>): void;
+    /** Log at a level chosen at runtime. */
+    log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
     /** A child logger with additional bound fields (e.g. a request id). */
     child(bindings: Record<string, unknown>): Logger;
 }
+/**
+ * Register a logger under a name, so a subsystem can have its own level or
+ * destination:
+ *
+ *   setLogger(new Logger({ level: "trace", sink: auditSink }), "audit");
+ *   namedLogger("audit").trace("permission granted", { userId });
+ *
+ * The default logger is the application's `Logger` singleton — resolve that with
+ * the global `logger()` helper, not this.
+ */
+export declare function setLogger(instance: Logger, name: string): Logger;
+/** A logger registered with `setLogger`. Throws for an unknown name. */
+export declare function namedLogger(name: string): Logger;

package/dist/core/logger.js

@@ -5,49 +5,135 @@
  *
  *   logger().info("user registered", { userId: user.id });
  *   logger().error("payment failed", { orderId, error });
+ *
+ * Output goes through a `Sink` — `console` by default, but any function, so logs
+ * can go to a file, an HTTP collector, or a buffer in tests. Register extra
+ * loggers by name (`setLogger(audit, "audit")`) when a subsystem needs its own
+ * level or destination.
  */
-const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const LEVELS = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60,
+};
 const REDACTED = "[redacted]";
-/** Return a copy of `obj` with `path` (dot-separated) redacted — clones only along the path. */
-function redactPath(obj, keys) {
+function normalizeRedact(redact) {
+    if (!redact)
+        return undefined;
+    const options = Array.isArray(redact) ? { paths: redact } : redact;
+    if (!options.paths.length)
+        return undefined;
+    return { paths: options.paths, censor: options.censor ?? REDACTED, remove: options.remove ?? false };
+}
+/**
+ * Return a copy of `obj` with `keys` (a split dot path) redacted. Clones only
+ * along the path, so untouched branches keep their identity. A `*` segment
+ * matches every key at that level.
+ */
+function redactPath(obj, keys, options) {
     const [head, ...rest] = keys;
-    if (head === undefined || !(head in obj))
+    if (head === undefined)
+        return obj;
+    const targets = head === "*" ? Object.keys(obj) : head in obj ? [head] : [];
+    if (!targets.length)
         return obj;
     const clone = { ...obj };
-    if (rest.length === 0) {
-        clone[head] = REDACTED;
-    }
-    else {
-        const child = clone[head];
-        if (child && typeof child === "object") {
-            clone[head] = redactPath(child, rest);
+    for (const key of targets) {
+        if (rest.length === 0) {
+            if (options.remove)
+                delete clone[key];
+            else
+                clone[key] = options.censor;
+        }
+        else {
+            const child = clone[key];
+            if (child && typeof child === "object" && !Array.isArray(child)) {
+                clone[key] = redactPath(child, rest, options);
+            }
         }
     }
     return clone;
 }
+/** The default sink: JSON to stdout, or a pretty single line when `pretty`. */
+export function consoleSink(pretty = false) {
+    return ({ level, time, msg, fields }) => {
+        const write = level === "warn"
+            ? console.warn
+            : level === "error" || level === "fatal"
+                ? console.error
+                : console.log;
+        if (pretty) {
+            const extra = Object.keys(fields).length ? " " + JSON.stringify(fields) : "";
+            write(`[${time}] ${level.toUpperCase().padEnd(5)} ${msg}${extra}`);
+        }
+        else {
+            write(JSON.stringify({ level, time, msg, ...fields }));
+        }
+    };
+}
+/** A sink that collects records in memory — for tests. Assert on `.records`. */
+export class MemorySink {
+    records = [];
+    /** The sink function to hand to `LoggerOptions.sink`. */
+    sink = (record) => {
+        this.records.push(record);
+    };
+    /** Records at one level. */
+    at(level) {
+        return this.records.filter((r) => r.level === level);
+    }
+    /** The messages logged, in order. */
+    messages() {
+        return this.records.map((r) => r.msg);
+    }
+    clear() {
+        this.records.length = 0;
+    }
+}
 export class Logger {
     options;
     threshold;
+    redact;
+    sink;
     constructor(options = {}) {
         this.options = options;
         this.threshold = LEVELS[options.level ?? "info"];
+        this.redact = normalizeRedact(options.redact);
+        this.sink = options.sink ?? consoleSink(options.pretty);
+    }
+    /**
+     * Whether a level would be emitted. Check it before building an expensive
+     * context object — the work of assembling it happens whether or not the line
+     * is ever written.
+     *
+     *   if (logger().isLevelEnabled("debug")) {
+     *     logger().debug("state", { snapshot: expensiveSnapshot() });
+     *   }
+     */
+    isLevelEnabled(level) {
+        return this.options.enabled !== false && LEVELS[level] >= this.threshold;
+    }
+    /** Run `fn` only if `level` would be emitted — the callback form of the above. */
+    ifLevelEnabled(level, fn) {
+        if (this.isLevelEnabled(level))
+            fn(this);
     }
     write(level, message, context) {
-        if (LEVELS[level] < this.threshold)
+        if (!this.isLevelEnabled(level))
             return;
-        const time = new Date().toISOString();
         let fields = { ...this.options.bindings, ...context };
-        for (const path of this.options.redact ?? []) {
-            fields = redactPath(fields, path.split("."));
-        }
-        if (this.options.pretty) {
-            const extra = Object.keys(fields).length ? " " + JSON.stringify(fields) : "";
-            const fn = level === "warn" ? console.warn : level === "error" ? console.error : console.log;
-            fn(`[${time}] ${level.toUpperCase().padEnd(5)} ${message}${extra}`);
-        }
-        else {
-            console.log(JSON.stringify({ level, time, msg: message, ...fields }));
+        if (this.redact) {
+            for (const path of this.redact.paths) {
+                fields = redactPath(fields, path.split("."), this.redact);
+            }
         }
+        this.sink({ level, time: new Date().toISOString(), msg: message, fields });
+    }
+    trace(message, context) {
+        this.write("trace", message, context);
     }
     debug(message, context) {
         this.write("debug", message, context);
@@ -61,6 +147,14 @@ export class Logger {
     error(message, context) {
         this.write("error", message, context);
     }
+    /** An unrecoverable failure — the loudest level. */
+    fatal(message, context) {
+        this.write("fatal", message, context);
+    }
+    /** Log at a level chosen at runtime. */
+    log(level, message, context) {
+        this.write(level, message, context);
+    }
     /** A child logger with additional bound fields (e.g. a request id). */
     child(bindings) {
         return new Logger({
@@ -69,3 +163,27 @@ export class Logger {
         });
     }
 }
+/* -------------------------------- registry -------------------------------- */
+const loggers = new Map();
+/**
+ * Register a logger under a name, so a subsystem can have its own level or
+ * destination:
+ *
+ *   setLogger(new Logger({ level: "trace", sink: auditSink }), "audit");
+ *   namedLogger("audit").trace("permission granted", { userId });
+ *
+ * The default logger is the application's `Logger` singleton — resolve that with
+ * the global `logger()` helper, not this.
+ */
+export function setLogger(instance, name) {
+    loggers.set(name, instance);
+    return instance;
+}
+/** A logger registered with `setLogger`. Throws for an unknown name. */
+export function namedLogger(name) {
+    const instance = loggers.get(name);
+    if (!instance) {
+        throw new Error(`No logger named "${name}". Register it with setLogger(logger, name).`);
+    }
+    return instance;
+}