npm - @shaferllc/keel - Versions diffs - 0.59.0 → 0.68.0 - Mend

@shaferllc/keel 0.59.0 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (166) hide show

package/AGENTS.md +167 -0
package/README.md +30 -1
package/bin/keel-mcp.mjs +9 -0
package/dist/core/application.d.ts +5 -5
package/dist/core/application.js +14 -2
package/dist/core/auth.d.ts +47 -0
package/dist/core/auth.js +77 -0
package/dist/core/authorization.d.ts +9 -1
package/dist/core/authorization.js +22 -2
package/dist/core/cache.d.ts +82 -5
package/dist/core/cache.js +181 -23
package/dist/core/cli/stubs.d.ts +12 -0
package/dist/core/cli/stubs.js +120 -0
package/dist/core/container.d.ts +20 -0
package/dist/core/container.js +52 -0
package/dist/core/cors.d.ts +29 -0
package/dist/core/cors.js +72 -0
package/dist/core/crypto.d.ts +40 -4
package/dist/core/crypto.js +66 -6
package/dist/core/csrf.d.ts +25 -0
package/dist/core/csrf.js +78 -0
package/dist/core/database.d.ts +49 -4
package/dist/core/database.js +89 -21
package/dist/core/events.d.ts +129 -5
package/dist/core/events.js +165 -7
package/dist/core/health.d.ts +141 -0
package/dist/core/health.js +226 -0
package/dist/core/helpers.d.ts +15 -3
package/dist/core/helpers.js +23 -3
package/dist/core/index.d.ts +33 -18
package/dist/core/index.js +16 -8
package/dist/core/lock.d.ts +139 -0
package/dist/core/lock.js +215 -0
package/dist/core/logger.d.ts +82 -4
package/dist/core/logger.js +141 -23
package/dist/core/mail.d.ts +128 -7
package/dist/core/mail.js +264 -16
package/dist/core/model.d.ts +2 -0
package/dist/core/model.js +16 -14
package/dist/core/provider.d.ts +7 -0
package/dist/core/provider.js +7 -0
package/dist/core/queue.d.ts +134 -9
package/dist/core/queue.js +304 -14
package/dist/core/rate-limit.js +3 -0
package/dist/core/relations.js +13 -13
package/dist/core/request.d.ts +26 -0
package/dist/core/request.js +77 -0
package/dist/core/shield.d.ts +39 -0
package/dist/core/shield.js +60 -0
package/dist/core/social.d.ts +173 -0
package/dist/core/social.js +337 -0
package/dist/core/storage.d.ts +159 -6
package/dist/core/storage.js +287 -7
package/dist/core/tokens.d.ts +74 -0
package/dist/core/tokens.js +155 -0
package/dist/db/d1.d.ts +32 -0
package/dist/db/d1.js +26 -0
package/dist/db/libsql.d.ts +29 -0
package/dist/db/libsql.js +32 -0
package/dist/db/pg.d.ts +29 -0
package/dist/db/pg.js +33 -0
package/dist/mcp/server.d.ts +19 -0
package/dist/mcp/server.js +355 -0
package/docs/ai-manifest.json +2472 -0
package/docs/ai.md +128 -0
package/docs/architecture.md +331 -0
package/docs/authentication.md +453 -0
package/docs/authorization.md +167 -0
package/docs/broadcasting.md +137 -0
package/docs/broker.md +500 -0
package/docs/cache.md +558 -0
package/docs/configuration.md +311 -0
package/docs/console.md +356 -0
package/docs/container.md +467 -0
package/docs/controllers.md +265 -0
package/docs/cors.md +51 -0
package/docs/database.md +530 -0
package/docs/debugging.md +129 -0
package/docs/decorators.md +127 -0
package/docs/errors.md +395 -0
package/docs/events.md +496 -0
package/docs/examples/architecture-app.ts +27 -0
package/docs/examples/authentication.ts +61 -0
package/docs/examples/authorization.ts +79 -0
package/docs/examples/broadcasting.ts +60 -0
package/docs/examples/broker-cache-validate.ts +34 -0
package/docs/examples/broker-fault-tolerance.ts +29 -0
package/docs/examples/broker-middleware.ts +27 -0
package/docs/examples/broker.ts +203 -0
package/docs/examples/cache.ts +222 -0
package/docs/examples/configuration.ts +81 -0
package/docs/examples/container.ts +134 -0
package/docs/examples/controllers.ts +86 -0
package/docs/examples/database.ts +118 -0
package/docs/examples/debugging.ts +41 -0
package/docs/examples/decorators.ts +40 -0
package/docs/examples/errors.ts +121 -0
package/docs/examples/events.ts +204 -0
package/docs/examples/factories.ts +84 -0
package/docs/examples/hashing.ts +71 -0
package/docs/examples/health.ts +94 -0
package/docs/examples/helpers.ts +171 -0
package/docs/examples/hooks.ts +54 -0
package/docs/examples/inertia.ts +81 -0
package/docs/examples/locks.ts +120 -0
package/docs/examples/logger.ts +92 -0
package/docs/examples/mail.ts +160 -0
package/docs/examples/middleware.ts +119 -0
package/docs/examples/migrations.ts +126 -0
package/docs/examples/models.ts +239 -0
package/docs/examples/notification.ts +124 -0
package/docs/examples/providers.ts +123 -0
package/docs/examples/queues.ts +254 -0
package/docs/examples/rate-limiting.ts +42 -0
package/docs/examples/redis.ts +99 -0
package/docs/examples/request-response.ts +197 -0
package/docs/examples/routing.ts +186 -0
package/docs/examples/scheduling.ts +62 -0
package/docs/examples/sessions.ts +102 -0
package/docs/examples/static-files.ts +63 -0
package/docs/examples/storage.ts +132 -0
package/docs/examples/templates.ts +58 -0
package/docs/examples/testing.ts +66 -0
package/docs/examples/transformer.ts +141 -0
package/docs/examples/transformers.ts +49 -0
package/docs/examples/url-builder.ts +86 -0
package/docs/examples/validation.ts +102 -0
package/docs/examples/views.tsx +62 -0
package/docs/examples/vite.ts +106 -0
package/docs/factories.md +166 -0
package/docs/getting-started.md +290 -0
package/docs/hashing.md +259 -0
package/docs/health.md +225 -0
package/docs/helpers.md +347 -0
package/docs/hono.md +186 -0
package/docs/hooks.md +118 -0
package/docs/inertia.md +241 -0
package/docs/locks.md +323 -0
package/docs/logger.md +290 -0
package/docs/mail.md +678 -0
package/docs/middleware.md +425 -0
package/docs/migrations.md +476 -0
package/docs/models.md +810 -0
package/docs/notifications.md +474 -0
package/docs/providers.md +363 -0
package/docs/queues.md +679 -0
package/docs/rate-limiting.md +155 -0
package/docs/redis.md +178 -0
package/docs/request-response.md +953 -0
package/docs/routing.md +804 -0
package/docs/scheduling.md +110 -0
package/docs/security.md +85 -0
package/docs/sessions.md +354 -0
package/docs/social-auth.md +174 -0
package/docs/static-files.md +211 -0
package/docs/storage.md +450 -0
package/docs/templates.md +315 -0
package/docs/testing.md +125 -0
package/docs/transformers.md +381 -0
package/docs/url-builder.md +295 -0
package/docs/validation.md +288 -0
package/docs/views.md +267 -0
package/docs/vite.md +434 -0
package/llms-full.txt +17694 -0
package/llms.txt +116 -0
package/package.json +38 -7

package/docs/inertia.md ADDED Viewed

@@ -0,0 +1,241 @@
+# Inertia
+Keel ships a server-side [Inertia.js](https://inertiajs.com) adapter. Pair Keel's
+routing with an Inertia client (React, Vue, or Svelte) and render page components
+from the server without building an API — `inertia("Page", props)` returns the
+right response automatically.
+## Configure it
+Bind an `Inertia` instance in a service provider. You supply the **root view**
+(the HTML shell that embeds the page data and loads your client bundle) and an
+optional asset **version**:
+```ts
+import { ServiceProvider, singleton, Inertia, inertiaPageAttr } from "@shaferllc/keel/core";
+export class InertiaServiceProvider extends ServiceProvider {
+  register(): void {
+    singleton(
+      Inertia,
+      () =>
+        new Inertia({
+          version: "1",
+          rootView: (page) =>
+            `<!DOCTYPE html><html><head><meta charset="utf-8"></head>` +
+            `<body><div id="app" data-page="${inertiaPageAttr(page)}"></div>` +
+            `<script src="/assets/app.js"></script></body></html>`,
+        }),
+    );
+  }
+}
+```
+`inertiaPageAttr(page)` serializes and HTML-escapes the page object for the
+`data-page` attribute.
+> **The version defaults to `"1"`.** Omit it and every deploy reports the same
+> asset version — fine until you ship new assets, at which point stale clients
+> won't be told to hard-reload. Bump it (a build hash, a timestamp) whenever your
+> bundle changes so the adapter can force a full reload on mismatch.
+## Render a page
+From a controller, or straight from a route:
+```ts
+import { inertia } from "@shaferllc/keel/core";
+// controller
+show() {
+  return inertia("Users/Show", { user: getUser(param("id")) });
+}
+// brisk route
+router.on("/dashboard").renderInertia("Dashboard", { title: "Welcome" });
+```
+`inertia()` looks up the bound `Inertia` instance and delegates to its `render`.
+The component name is the client-side path Inertia resolves (e.g. `Users/Show`
+maps to your `Pages/Users/Show` component); `props` is any JSON-serializable
+object.
+> **Configure the adapter before you render.** `inertia()` throws
+> `Inertia is not configured…` if no `Inertia` instance is bound in the
+> container. Register the provider (above) during boot, before any route runs.
+## What the adapter does
+It implements the Inertia protocol for you. Every branch below is decided from
+the incoming request headers — you call `inertia("Page", props)` once and the
+adapter picks the response:
+| Situation | Response |
+|-----------|----------|
+| First visit (no `X-Inertia` header) | The full HTML document from your `rootView` (a `string`) |
+| Inertia navigation (`X-Inertia: true`) | `{ component, props, url, version }` JSON + `X-Inertia: true` and `Vary: X-Inertia` headers |
+| Asset version changed (GET) | `409` + `X-Inertia-Location` so the client hard-reloads |
+| Partial reload (`X-Inertia-Partial-Data`) | Only the requested props, for the matching component |
+The `url` embedded in the page object is the request's `pathname + search` —
+Inertia uses it to keep the browser history in sync.
+### Version mismatches
+The version check only fires on a **GET** Inertia request whose
+`X-Inertia-Version` header differs from the adapter's configured version. On a
+mismatch the adapter returns an empty `409` with `X-Inertia-Location` set to the
+current URL; the Inertia client sees the `409` and does a full page reload to
+pull fresh assets. Non-GET requests (a form POST, say) skip the check and render
+normally.
+### Partial reloads
+When the client asks for a partial reload it sends two headers:
+`X-Inertia-Partial-Component` (the component it already has mounted) and
+`X-Inertia-Partial-Data` (a comma-separated list of prop keys it wants). The
+adapter only trims props when the partial component **matches** the component
+you're rendering — so a partial reload of `Users/Index` won't accidentally
+strip props when you render `Users/Show`. Matching props are filtered down to
+the requested keys; everything else is dropped from the payload.
+```ts
+// Client requests only `notifications` for the already-mounted Dashboard.
+// The adapter sends { component: "Dashboard", props: { notifications }, ... }.
+inertia("Dashboard", { stats, notifications, activity });
+```
+> Partial reloads are an **allow-list** (the `only` mechanism). The adapter does
+> not implement Inertia's `except` variant — every listed key is kept, all others
+> are dropped.
+## The client
+The adapter is the server half. On the client, set up Inertia as usual
+(`@inertiajs/react` / `-vue` / `-svelte`) pointing at `#app`, and build your
+`app.js` bundle referenced by the root view. See
+[inertiajs.com](https://inertiajs.com) for the client setup.
+## Related
+`inertia()` resolves the `Inertia` instance from the [container](./container.md),
+so it's bound like any other [service provider](./providers.md) singleton. The
+`renderInertia` brisk-route helper lives on the [router](./routing.md).
+---
+## API reference
+### `inertia(component, props?)`
+`inertia(component: string, props?: Record<string, unknown>): Response | string`
+Renders an Inertia response for the current request using the `Inertia` instance
+bound in the container.
+```ts
+import { inertia } from "@shaferllc/keel/core";
+return inertia("Users/Show", { user });
+```
+**Notes:** `props` defaults to `{}`. Throws `Inertia is not configured…` if no
+`Inertia` instance is bound — bind one in a provider first. Returns a `string`
+(the `rootView` HTML) on a first load and a `Response` (JSON, or a `409`) on an
+Inertia navigation, so it fits anywhere a route handler can return either.
+### `inertiaPageAttr(page)`
+`inertiaPageAttr(page: InertiaPage): string`
+HTML-escapes a JSON-serialized page object for embedding in the `data-page`
+attribute of your root element.
+```ts
+`<div id="app" data-page="${inertiaPageAttr(page)}"></div>`;
+```
+**Notes:** escapes `&`, `"`, `'`, `<`, and `>` (in that order, so `&` isn't
+double-escaped). Use it only inside a double-quoted attribute in your `rootView`
+— it is the escaping counterpart the Inertia client reads back off `#app`.
+### `Inertia`
+The adapter itself. Construct one and bind it as a container singleton; the
+`inertia()` helper resolves it per request. You rarely call its methods directly
+— `inertia()` and `renderInertia()` do.
+#### `new Inertia(options)`
+`new Inertia(options: InertiaOptions)`
+Creates an adapter with a root view and an optional asset version.
+```ts
+new Inertia({
+  version: "1",
+  rootView: (page) => `<div id="app" data-page="${inertiaPageAttr(page)}"></div>`,
+});
+```
+**Notes:** `options.version` defaults to `"1"` when omitted; `options.rootView`
+is required.
+#### `render(component, props?)`
+`render(component: string, props?: Record<string, unknown>): Response | string`
+Produces the correct response for the current request: the full HTML document on
+a first visit, the page JSON on an Inertia navigation, a `409` on a version
+mismatch, or a trimmed payload for a partial reload.
+```ts
+const html = new Inertia({ rootView }).render("Dashboard", { title: "Welcome" });
+```
+**Notes:** reads the active request from `ctx()`, so call it inside a request
+(the `inertia()` helper does this for you). `props` defaults to `{}`. The JSON
+branch sets `X-Inertia: true` and `Vary: X-Inertia`; the `409` branch sets
+`X-Inertia-Location`.
+### Interfaces & types
+#### `InertiaOptions`
+```ts
+interface InertiaOptions {
+  version?: string;
+  rootView: (page: InertiaPage) => string;
+}
+```
+The constructor argument. `version` is the asset version (default `"1"`); a
+mismatch against the client's `X-Inertia-Version` forces a full reload.
+`rootView` renders the HTML shell for a first, non-XHR load — it receives the
+`InertiaPage` and must embed it (typically via `inertiaPageAttr`) so the client
+can boot.
+```ts
+const options: InertiaOptions = {
+  version: "abc123",
+  rootView: (page) =>
+    `<div id="app" data-page="${inertiaPageAttr(page)}"></div>`,
+};
+```
+#### `InertiaPage`
+```ts
+interface InertiaPage {
+  component: string;
+  props: Record<string, unknown>;
+  url: string;
+  version: string;
+}
+```
+The Inertia page object — the payload both the JSON response and the `rootView`
+receive. `component` is the page name, `props` its (possibly partial-reload
+filtered) data, `url` the request's `pathname + search`, and `version` the
+adapter's asset version. You consume it inside `rootView`; you don't build it
+yourself.

package/docs/locks.md ADDED Viewed

@@ -0,0 +1,323 @@
+# Locks
+"Only one of you may do this at a time" — across processes, across nodes.
+```ts
+import { lock } from "@shaferllc/keel/core";
+const [ran] = await lock("invoice:42").run(async () => {
+  await charge(invoice);
+});
+if (!ran) return; // another worker is already charging it
+```
+This is the counterpart to the [cache](./cache.md)'s stampede protection. That
+collapses concurrent work **inside one isolate**; a lock coordinates work
+**between** them. Reach for a lock when doing the thing twice would be *wrong* —
+charging a card, sending an invoice, running a migration — not merely wasteful.
+Like every other backend in Keel, the store is a small pluggable seam and the core
+imports no driver. `MemoryLockStore` is the default; it's per-isolate, so it
+coordinates within one process and nothing more — fine for tests and
+single-process apps, useless across a cluster. Point it at Redis for the real
+thing.
+## `run()` — the form you want
+```ts
+const [ran, result] = await lock("invoice:42").run(() => charge(invoice));
+```
+It acquires, runs, and **always** releases — the `finally` is what stops a
+throwing callback from leaving the lock held until its TTL runs out. It returns
+`[ran, result]`; `ran` is `false` if someone else holds the lock, in which case
+your callback never ran and `result` is `undefined`.
+By default it doesn't wait: if the lock is taken, it gives up immediately. To wait
+for it, pass a timeout:
+```ts
+// Wait up to 5 seconds for the lock, checking every 100ms.
+const [ran] = await lock("report").run(() => rebuild(), {
+  timeout: 5_000,
+  retryDelay: 100,
+});
+```
+`runImmediately()` is the explicit "never wait" spelling.
+## TTL and expiry
+**A lock always expires.** There's no hold-forever mode, because a holder that
+crashes would keep the lock forever and nothing would ever run again. The default
+TTL is 30 seconds:
+```ts
+lock("invoice:42");           // held for 30s once acquired
+lock("nightly-report", 300_000); // 5 minutes
+```
+Pick a TTL comfortably longer than the work. If the work might outrun it, `extend()`
+from inside:
+```ts
+await lock("import", 60_000).run(async () => {
+  for (const batch of batches) {
+    await process(batch);
+    await l.extend(); // push the expiry out another 60s
+  }
+});
+```
+`extend()` **throws** `LockNotHeldError` if you've already lost the lock. That's
+deliberate: the alternative — silently doing nothing — would let you carry on
+believing you hold a lock you don't.
+## Ownership, and why it matters
+Every acquisition mints a random owner token, and `release()`/`extend()` only
+succeed for the owner. This is not bookkeeping — it's the property that makes the
+lock correct:
+1. Process **A** takes the lock with a 30s TTL.
+2. A's work takes longer than 30s. The lock **expires**.
+3. Process **B** takes the now-free lock and starts working.
+4. A finishes and calls `release()`.
+Without ownership, A's release deletes **B's** lock, and a third process walks
+straight in while B is still working. With it, A's release is a no-op that returns
+`false`. A store must *compare-and-delete*, not just delete.
+## Manual acquisition
+`acquire()` / `release()` are there when the lock's lifetime doesn't fit a single
+callback. You own the `try/finally`:
+```ts
+const l = lock("invoice:42");
+if (!(await l.acquire({ timeout: 2_000 }))) return;
+try {
+  await charge(invoice);
+} finally {
+  await l.release(); // without this, the lock leaks for the rest of its TTL
+}
+```
+Prefer `run()`. It exists so you can't forget the `finally`.
+## Handing a lock to another process
+`serialize()` freezes the key, TTL, and **owner token** to a string.
+`restoreLock()` rebuilds it elsewhere — so one process can take the lock and
+another can release or extend the *same* lock:
+```ts
+// worker A
+const l = lock("import:99", 60_000);
+await l.acquire();
+await queue.dispatch(new FinishImport(l.serialize()));
+// worker B, later
+const l = restoreLock(serialized);
+await l.extend(60_000);
+// ...finish the work...
+await l.release();
+```
+## Inspecting a lock
+```ts
+await l.isLocked(); // does anyone hold this key? (not necessarily you)
+await l.isExpired(); // did we hold it and lose it?
+await l.getRemainingTime(); // ms until expiry, or null if unheld
+```
+## Testing
+The default `MemoryLockStore` needs no setup. Give each test a clean one so keys
+can't leak between them:
+```ts
+import { setLockStore, MemoryLockStore } from "@shaferllc/keel/core";
+beforeEach(() => setLockStore(new MemoryLockStore()));
+```
+## Writing a store
+A store is the `LockStore` interface. Implementations **must** make `acquire`
+atomic (set-if-absent) and make `release`/`extend` conditional on the owner
+matching — a store that can't do both isn't a lock, it's a suggestion.
+### Redis
+Redis gives you both: `SET key owner PX ttl NX` is an atomic set-if-absent, and a
+small Lua script makes release and extend compare-and-act. This example uses
+[ioredis](https://github.com/redis/ioredis); any client with `set` and `eval` works
+the same way.
+```ts
+import type { LockStore } from "@shaferllc/keel/core";
+import type { Redis } from "ioredis";
+// Compare-and-delete: only delete if the value still matches our owner token.
+const RELEASE = `
+  if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+  end
+  return 0
+`;
+// Compare-and-extend, same idea.
+const EXTEND = `
+  if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("pexpire", KEYS[1], ARGV[2])
+  end
+  return 0
+`;
+export const redisLockStore = (client: Redis): LockStore => ({
+  async acquire(key, owner, ttlMs) {
+    // NX = only if absent. This is the atomic bit.
+    const res = await client.set(key, owner, "PX", ttlMs, "NX");
+    return res === "OK";
+  },
+  async release(key, owner) {
+    return (await client.eval(RELEASE, 1, key, owner)) === 1;
+  },
+  async extend(key, owner, ttlMs) {
+    return (await client.eval(EXTEND, 1, key, owner, String(ttlMs))) === 1;
+  },
+  async isLocked(key) {
+    return (await client.exists(key)) === 1;
+  },
+  async remainingTime(key) {
+    const ms = await client.pttl(key);
+    return ms < 0 ? null : ms; // -1 = no expiry, -2 = no key
+  },
+});
+```
+```ts
+setLockStore(redisLockStore(client));
+```
+### Database
+A unique primary key on `key` gives you the atomicity — the insert fails if
+someone already holds it. Expired rows are treated as free.
+```sql
+CREATE TABLE locks (
+  key        TEXT PRIMARY KEY,
+  owner      TEXT NOT NULL,
+  expires_at BIGINT NOT NULL
+);
+```
+```ts
+import { connection } from "@shaferllc/keel/core";
+export const databaseLockStore = (table = "locks"): LockStore => ({
+  async acquire(key, owner, ttlMs) {
+    const now = Date.now();
+    // Clear the row first if it has expired, then insert. The PK makes the
+    // insert the atomic step: two racing writers, one unique-violation.
+    await connection().write(`DELETE FROM ${table} WHERE key = ? AND expires_at <= ?`, [key, now]);
+    try {
+      await connection().write(
+        `INSERT INTO ${table} (key, owner, expires_at) VALUES (?, ?, ?)`,
+        [key, owner, now + ttlMs],
+      );
+      return true;
+    } catch {
+      return false; // someone else holds it
+    }
+  },
+  async release(key, owner) {
+    const res = await connection().write(`DELETE FROM ${table} WHERE key = ? AND owner = ?`, [key, owner]);
+    return res.changes > 0;
+  },
+  async extend(key, owner, ttlMs) {
+    const res = await connection().write(
+      `UPDATE ${table} SET expires_at = ? WHERE key = ? AND owner = ? AND expires_at > ?`,
+      [Date.now() + ttlMs, key, owner, Date.now()],
+    );
+    return res.changes > 0;
+  },
+  async isLocked(key) {
+    const rows = await connection().select(
+      `SELECT 1 FROM ${table} WHERE key = ? AND expires_at > ?`,
+      [key, Date.now()],
+    );
+    return rows.length > 0;
+  },
+  async remainingTime(key) {
+    const rows = await connection().select(`SELECT expires_at FROM ${table} WHERE key = ?`, [key]);
+    const row = rows[0] as { expires_at: number } | undefined;
+    if (!row) return null;
+    const left = Number(row.expires_at) - Date.now();
+    return left > 0 ? left : null;
+  },
+});
+```
+Redis is the better fit if you have it — the database store pays a round trip per
+operation and needs the expired rows cleaned up.
+---
+## API reference
+### `lock(key, ttlMs?)`
+`lock(key: string, ttlMs?: number): Lock`
+A lock on `key`, held for `ttlMs` once acquired (default `30_000`).
+### `Lock`
+| Method | Signature |
+|--------|-----------|
+| `run` | `<T>(fn, options?: AcquireOptions) => Promise<[boolean, T \| undefined]>` — acquire, run, always release |
+| `runImmediately` | `<T>(fn) => Promise<[boolean, T \| undefined]>` — never waits |
+| `acquire` | `(options?: AcquireOptions) => Promise<boolean>` |
+| `acquireImmediately` | `() => Promise<boolean>` |
+| `release` | `() => Promise<boolean>` — false if we no longer hold it |
+| `extend` | `(ttlMs?) => Promise<void>` — throws `LockNotHeldError` if lost |
+| `isLocked` | `() => Promise<boolean>` — does *anyone* hold it |
+| `isExpired` | `() => Promise<boolean>` — did *we* hold it and lose it |
+| `getRemainingTime` | `() => Promise<number \| null>` — ms until expiry |
+| `serialize` | `() => string` — key + TTL + owner token |
+### `restoreLock(serialized)`
+`restoreLock(serialized: string): Lock` — rebuild a lock from `serialize()`, owner
+token and all, so another process can release or extend it.
+### `setLockStore(store)` / `getLockStore()`
+Register the store `lock()` uses, and read it back.
+### Interfaces & types
+#### `LockStore`
+`acquire(key, owner, ttlMs)` / `release(key, owner)` / `extend(key, owner, ttlMs)` /
+`isLocked(key)` / `remainingTime(key)`. `acquire` must be atomic; `release` and
+`extend` must be conditional on the owner.
+#### `AcquireOptions`
+`{ timeout?: number, retryDelay?: number }` — how long to wait for a held lock
+(default `0`, don't wait) and how often to retry (default `50`ms).
+#### `MemoryLockStore`
+The default. Per-isolate — for tests and single-process apps.
+#### `LockNotHeldError`
+Thrown by `extend()` when the lock has expired or was never acquired.