@shaferllc/keel 0.59.0 → 0.68.0

package/dist/core/index.d.ts

@@ -4,35 +4,46 @@ export type { Token, Constructor, Factory } from "./container.js";
 export { Application } from "./application.js";
 export type { BootOptions, LifecycleHook, Configurator } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, alias, swap, restore, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
-export type { LogLevel, LoggerOptions } from "./logger.js";
+export { consoleSink, MemorySink, setLogger, namedLogger } from "./logger.js";
+export type { LogLevel, LoggerOptions, LogRecord, Sink, RedactOptions } from "./logger.js";
 export { requestLogger, requestLog } from "./request-logger.js";
 export type { RequestLoggerOptions } from "./request-logger.js";
-export { Events } from "./events.js";
-export type { Listener } from "./events.js";
+export { Events, EventBuffer } from "./events.js";
+export type { Listener, AnyListener, ErrorHandler, EventsList, EventName, PayloadOf, RecordedEvent, } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
-export type { CacheStore } from "./cache.js";
+export type { CacheStore, RememberOptions, PutOptions } from "./cache.js";
 export { serveStatic } from "./static.js";
 export type { StaticOptions } from "./static.js";
-export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
-export type { Disk, Contents } from "./storage.js";
+export { lock, restoreLock, setLockStore, getLockStore, Lock, MemoryLockStore, LockNotHeldError, } from "./lock.js";
+export type { LockStore, AcquireOptions } from "./lock.js";
+export { health, healthCheck, check, Result, BaseCheck, HealthChecks, DatabaseCheck, RedisCheck, CacheCheck, } from "./health.js";
+export type { HealthStatus, HealthReport, CheckReport, HealthCheckOptions, } from "./health.js";
+export { Storage, FakeStorage, MemoryDisk, storage, setDisk, fakeDisk, restoreDisk, serveStorage, signStorageUrl, verifyStorageUrl, contentTypeFor, } from "./storage.js";
+export type { Disk, Contents, FileVisibility, WriteOptions, FileMetadata, SignedFileOptions, SignedUploadOptions, ServeStorageOptions, } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption, jwt } from "./crypto.js";
-export type { JwtPayload, JwtSignOptions, JwtVerifyOptions } from "./crypto.js";
+export type { JwtPayload, JwtSignOptions, JwtVerifyOptions, EncryptOptions } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
 export type { RateLimiterOptions } from "./rate-limit.js";
-export { db, setConnection, QueryBuilder } from "./database.js";
-export type { Connection, WriteResult, Row, Dialect, Operator, Paginated } from "./database.js";
+export { cors } from "./cors.js";
+export type { CorsOptions } from "./cors.js";
+export { securityHeaders } from "./shield.js";
+export type { SecurityHeadersOptions, HstsOptions } from "./shield.js";
+export { csrf, csrfToken, csrfField } from "./csrf.js";
+export type { CsrfOptions } from "./csrf.js";
+export { db, connection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, QueryBuilder, } from "./database.js";
+export type { Connection, ConnectionHandle, WriteResult, Row, Dialect, Operator, Paginated } from "./database.js";
 export { Model } from "./model.js";
 export type { CastType, Casts } from "./casts.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
 export type { Definition } from "./factory.js";
-export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
-export type { Message, Transport, MailerOptions, FetchTransportOptions } from "./mail.js";
-export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
-export type { Dispatchable, JobOptions, QueueDriver, Drainable, QueuedJob } from "./queue.js";
+export { Mailer, FakeMailer, PendingMail, BaseMail, SendMailJob, ArrayTransport, LogTransport, fetchTransport, mail, mailer, send, sendLater, setMailer, getMailer, fakeMail, restoreMail, } from "./mail.js";
+export type { Message, Transport, MailerOptions, FetchTransportOptions, Attachment, RecordedMail, } from "./mail.js";
+export { Job, Queue, FakeQueue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, fakeQueue, restoreQueue, exponentialBackoff, linearBackoff, fixedBackoff, noBackoff, } from "./queue.js";
+export type { Dispatchable, JobOptions, JobContext, JobClass, QueueDriver, Drainable, QueuedJob, FailedJob, Backoff, } from "./queue.js";
 export { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
 export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
 export type { Broadcaster, Subscriber, ChannelAuthorizer } from "./broadcasting.js";
@@ -63,10 +74,14 @@ export { validate, validateRequest, validated } from "./validation.js";
 export type { Schema, RequestSchemas } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
 export type { SessionOptions } from "./session.js";
-export { Auth, auth, authGuard, bearerAuth, setUserProvider } from "./auth.js";
-export type { UserProvider } from "./auth.js";
-export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
-export type { GateCallback, BeforeCallback } from "./authorization.js";
+export { Auth, auth, authGuard, bearerAuth, basicAuth, tokenAuth, token, tokenCan, setUserProvider } from "./auth.js";
+export type { UserProvider, BasicVerifier } from "./auth.js";
+export { createToken, verifyToken, revokeToken, revokeTokens, listTokens, tokenAllows, tokenDenies, setTokensTable, } from "./tokens.js";
+export type { AccessToken, CreateTokenOptions, IssuedToken } from "./tokens.js";
+export { social, github, google, discord, oauthDriver, oauthState, OAuthDriver, OAuthError, twitter, oauth1Driver, oauth1Signature, OAuth1Driver, } from "./social.js";
+export type { SocialUser, OAuthToken, OAuthConfig, ProviderSpec, RedirectOptions, OAuth1Config, OAuth1Token, OAuth1ProviderSpec, } from "./social.js";
+export { define, policy, gateBefore, gateAfter, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
+export type { GateCallback, BeforeCallback, AfterCallback } from "./authorization.js";
 export { Transformer } from "./transformer.js";
 export type { Attributes, DocumentOptions } from "./transformer.js";
 export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";

package/dist/core/index.js

@@ -2,22 +2,28 @@
 export { Container } from "./container.js";
 export { Application } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, alias, swap, restore, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
+export { consoleSink, MemorySink, setLogger, namedLogger } from "./logger.js";
 export { requestLogger, requestLog } from "./request-logger.js";
-export { Events } from "./events.js";
+export { Events, EventBuffer } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
 export { serveStatic } from "./static.js";
-export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
+export { lock, restoreLock, setLockStore, getLockStore, Lock, MemoryLockStore, LockNotHeldError, } from "./lock.js";
+export { health, healthCheck, check, Result, BaseCheck, HealthChecks, DatabaseCheck, RedisCheck, CacheCheck, } from "./health.js";
+export { Storage, FakeStorage, MemoryDisk, storage, setDisk, fakeDisk, restoreDisk, serveStorage, signStorageUrl, verifyStorageUrl, contentTypeFor, } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption, jwt } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
-export { db, setConnection, QueryBuilder } from "./database.js";
+export { cors } from "./cors.js";
+export { securityHeaders } from "./shield.js";
+export { csrf, csrfToken, csrfField } from "./csrf.js";
+export { db, connection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, QueryBuilder, } from "./database.js";
 export { Model } from "./model.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
-export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
-export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
+export { Mailer, FakeMailer, PendingMail, BaseMail, SendMailJob, ArrayTransport, LogTransport, fetchTransport, mail, mailer, send, sendLater, setMailer, getMailer, fakeMail, restoreMail, } from "./mail.js";
+export { Job, Queue, FakeQueue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, fakeQueue, restoreQueue, exponentialBackoff, linearBackoff, fixedBackoff, noBackoff, } from "./queue.js";
 export { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
 export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
 export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.js";
@@ -35,8 +41,10 @@ export { TestClient, TestResponse, testClient } from "./testing.js";
 export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
 export { validate, validateRequest, validated } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
-export { Auth, auth, authGuard, bearerAuth, setUserProvider } from "./auth.js";
-export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
+export { Auth, auth, authGuard, bearerAuth, basicAuth, tokenAuth, token, tokenCan, setUserProvider } from "./auth.js";
+export { createToken, verifyToken, revokeToken, revokeTokens, listTokens, tokenAllows, tokenDenies, setTokensTable, } from "./tokens.js";
+export { social, github, google, discord, oauthDriver, oauthState, OAuthDriver, OAuthError, twitter, oauth1Driver, oauth1Signature, OAuth1Driver, } from "./social.js";
+export { define, policy, gateBefore, gateAfter, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
 export { Transformer } from "./transformer.js";
 export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";
 export { Vite, viteTags, viteAsset, viteReactRefresh } from "./vite.js";

package/dist/core/lock.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+/**
+ * The bridge to a lock backend.
+ *
+ * Every method is keyed by `owner` for the reason above: implementations MUST
+ * make `acquire` atomic (set-if-absent) and `release`/`extend` conditional on
+ * the owner matching. A store that can't do that isn't a lock.
+ */
+export interface LockStore {
+    /** Set the key if absent. Returns whether this owner got it. Must be atomic. */
+    acquire(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Delete the key only if `owner` still holds it. Returns whether it did. */
+    release(key: string, owner: string): Promise<boolean>;
+    /** Push the expiry out, only if `owner` still holds it. */
+    extend(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Whether anyone currently holds the key. */
+    isLocked(key: string): Promise<boolean>;
+    /** Milliseconds until the key expires, or null if nobody holds it. */
+    remainingTime(key: string): Promise<number | null>;
+}
+/**
+ * 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 declare class MemoryLockStore implements LockStore {
+    private entries;
+    /** The live entry for a key, dropping it if it has expired. */
+    private live;
+    acquire(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    release(key: string, owner: string): Promise<boolean>;
+    extend(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    isLocked(key: string): Promise<boolean>;
+    remainingTime(key: string): Promise<number | null>;
+}
+export interface AcquireOptions {
+    /**
+     * Give up after this many milliseconds of waiting. Default: 0 — don't wait at
+     * all, fail immediately if the lock is held.
+     */
+    timeout?: number;
+    /** Milliseconds between attempts while waiting. Default: 50. */
+    retryDelay?: number;
+}
+/** A lock that has expired or was never held. */
+export declare class LockNotHeldError extends Error {
+    constructor(key: string);
+}
+export declare class Lock {
+    readonly key: string;
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    readonly ttlMs: number;
+    private store;
+    /** Non-null only while this instance holds the lock. */
+    private owner?;
+    constructor(key: string, 
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    ttlMs: number, store: LockStore, owner?: string);
+    /**
+     * 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
+     */
+    run<T>(fn: () => Promise<T> | T, options?: AcquireOptions): Promise<[boolean, T | undefined]>;
+    /** `run()`, but never waits: if the lock is held, give up at once. */
+    runImmediately<T>(fn: () => Promise<T> | T): Promise<[boolean, T | undefined]>;
+    /**
+     * 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.
+     */
+    acquire(options?: AcquireOptions): Promise<boolean>;
+    /** Take the lock only if it's free right now. */
+    acquireImmediately(): Promise<boolean>;
+    /** Give the lock back. A no-op if we no longer hold it (it may have expired). */
+    release(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    extend(ttlMs?: number): Promise<void>;
+    /** Whether *anyone* holds this key — not necessarily us. */
+    isLocked(): Promise<boolean>;
+    /** Whether we held this lock but no longer do. */
+    isExpired(): Promise<boolean>;
+    /** Milliseconds until the lock expires, or null if nobody holds it. */
+    getRemainingTime(): Promise<number | null>;
+    /**
+     * 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(): string;
+}
+/** Register the lock store used by `lock()`. */
+export declare function setLockStore(next: LockStore): LockStore;
+/** The active lock store. */
+export declare function getLockStore(): LockStore;
+/**
+ * A lock on `key`, held for `ttlMs` once acquired (default 30s).
+ *
+ *   const [ran] = await lock("invoice:42").run(() => charge(invoice));
+ */
+export declare function lock(key: string, ttlMs?: number): Lock;
+/** Rebuild a lock from `serialize()` — same key, same TTL, same owner token. */
+export declare function restoreLock(serialized: string): Lock;

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;