@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/adapter.js

@@ -0,0 +1,444 @@
+/**
+ * What a database adapter has to provide, and — just as importantly — what it
+ * is not allowed to decide.
+ *
+ * An adapter reads a dialect's catalog and runs parameterised reads. It does
+ * not build WHERE clauses from user input, does not decide what a row is
+ * called, and never returns SQL for something upstream to concatenate. Every
+ * value the user supplies reaches the database as a bound parameter, because
+ * a browsing tool that interpolates a filter into SQL is a SQL injection
+ * vulnerability with a nice front end.
+ */
+import { declaredOrder } from '../shared/schema.js';
+import { Refusal } from '../shared/refusal.js';
+import { orderClauseSql } from '../shared/filter.js';
+/* The filter, the limit policy and Refusal live in shared/, where the query
+   language and views reach them without depending on the adapters. Adapter
+   and server code keep reaching them through this contract. */
+export { ANSI_STYLE, OPS, POSTGRES_STYLE, buildWhere, } from '../shared/filter.js';
+export { DEFAULT_LIMIT, ESTIMATE_ABOVE, MAX_LIMIT, clampLimit, clampOffset, countStatement, countEachStatement, countEachRows, } from '../shared/reads.js';
+/**
+ * Whether one scan can answer every item (countEachStatement's `together`):
+ * they all read one table, and the catalog says that table holds no more
+ * rows than the bound — so reading all of it costs no more than one bounded
+ * count would. Unbounded, one scan always beats one per item.
+ */
+export function countsTogether(schema, items, limit) {
+    if (!items.every((item) => item.table === items[0]?.table))
+        return false;
+    if (limit === undefined)
+        return true;
+    const rows = schema?.tables.find((table) => table.id === items[0].table)?.approxRows;
+    return typeof rows === 'number' && rows <= limit;
+}
+export { Refusal } from '../shared/refusal.js';
+/**
+ * A read's ORDER BY, or nothing: each column by its value, or by its declared
+ * vocabulary where the catalog has one over text (shared/schema.ts
+ * `declaredOrder`), its values bound from `startIndex`. Every adapter's plain
+ * read and a scoped read say it the same way, so a list sorts alike on all
+ * three engines.
+ */
+export function orderClause(order, table, style, startIndex, quote = (column) => style.quote(column)) {
+    return orderClauseSql((order ?? []).map((o) => ({
+        expression: quote(o.column),
+        direction: o.direction,
+        declared: declaredOrder(table?.columns.find((column) => column.name === o.column)),
+    })), style, startIndex);
+}
+/* Registered, not a local symbol: a command handler catches the conflict its
+   `tx.update` threw and rethrows through the copy of tablewalk it imported,
+   which need not be this one (see businessCommandExecution.ts). */
+const conflictBrand = Symbol.for('mistri.writeConflict');
+/** A conditional update matched no row and did not apply its proposed values. */
+export class WriteConflict extends Error {
+    [conflictBrand] = true;
+    constructor() {
+        super('This record changed or was removed since it was read. Reload it and review your changes before applying them again.');
+        this.name = 'WriteConflict';
+    }
+}
+/** The native class, or a branded twin from another copy of the package. */
+export function isWriteConflict(error) {
+    return error instanceof WriteConflict || (error instanceof Error && error[conflictBrand] === true);
+}
+/** A transaction acknowledgement could not establish whether writes landed.
+ * Never inherit Refusal or driver constraint codes: callers must not turn a
+ * failed rollback of a rejected operation into permission to retry it. */
+export class TransactionOutcomeUnknown extends Error {
+    outcome = 'unknown';
+    constructor(cause) {
+        super('The transaction outcome could not be confirmed. Refresh and reconcile the records before making another change.', { cause });
+        this.name = 'TransactionOutcomeUnknown';
+    }
+}
+/**
+ * Refuse anything that is more than one statement.
+ *
+ * Not a SQL parser and not trying to be one — it answers exactly one question,
+ * "is there a second statement here", and it answers it by scanning for a
+ * semicolon that has something after it. Everything that can contain a
+ * semicolon harmlessly is skipped: quoted strings and names, line comments,
+ * block comments, and Postgres's dollar-quoted bodies, which is how a function
+ * definition carries semicolons without being several statements.
+ *
+ * Each of those is read the way the dialect's own lexer reads it, because a
+ * scanner that ends a string or a comment somewhere other than where the
+ * database does can hide a real `;`: Postgres nests block comments, honours
+ * backslash escapes in an E'…' string, and reads `x$$` as one identifier
+ * rather than an opening dollar-quote. It is not the only line: Postgres runs
+ * user text on the extended protocol (postgres.ts runSql), which carries one
+ * statement, and SQLite's prepare compiles only the first.
+ *
+ * Stacking is refused rather than truncated. Running the first half of what
+ * someone typed and discarding the rest is worse than refusing both: they
+ * asked for two things and would be told about neither.
+ *
+ * Returns null when the text is a single statement, or the reason it is not.
+ */
+export function refuseStacked(text, dialect = 'postgres') {
+    const postgres = dialect === 'postgres';
+    let i = 0;
+    const n = text.length;
+    /* A quoted run that starts at `i`, read to just past its close. A doubled
+       close is an escaped close; a backslash escapes only where the dialect
+       says so (Postgres's E'…'). Everywhere else a backslash is a character:
+       Postgres (standard-conforming strings, the default since 9.1) and SQLite
+       both read `'\'` as a one-character string, and reading it as an escape
+       would scan `'\'; drop table x; --'` as one long string. */
+    const quoted = (close, backslash) => {
+        i += 1;
+        while (i < n) {
+            if (backslash && text[i] === '\\') {
+                i += 2;
+                continue;
+            }
+            if (text[i] === close && text[i + 1] === close) {
+                i += 2;
+                continue;
+            }
+            if (text[i] === close) {
+                i += 1;
+                return;
+            }
+            i += 1;
+        }
+    };
+    while (i < n) {
+        const ch = text[i];
+        // Line comment, to end of line.
+        if (ch === '-' && text[i + 1] === '-') {
+            const nl = text.indexOf('\n', i);
+            i = nl < 0 ? n : nl + 1;
+            continue;
+        }
+        // Block comment. Postgres nests them; SQLite ends at the first close.
+        if (ch === '/' && text[i + 1] === '*') {
+            let depth = 1;
+            i += 2;
+            while (i < n && depth) {
+                if (postgres && text[i] === '/' && text[i + 1] === '*') {
+                    depth += 1;
+                    i += 2;
+                }
+                else if (text[i] === '*' && text[i + 1] === '/') {
+                    depth -= 1;
+                    i += 2;
+                }
+                else
+                    i += 1;
+            }
+            continue;
+        }
+        /* A name or keyword, read whole: `$` continues one in both dialects, so
+           the `$$` of `x$$` belongs to the name and opens nothing. */
+        IDENTIFIER.lastIndex = i;
+        const word = IDENTIFIER.exec(text)?.[0];
+        if (word) {
+            i += word.length;
+            if (postgres && (word === 'E' || word === 'e') && text[i] === "'") {
+                quoted("'", true);
+                /* A string continued on the next line is still an E'…' string. */
+                for (let more = CONTINUED.exec(text.slice(i)); more; more = CONTINUED.exec(text.slice(i))) {
+                    i += more[0].length - 1;
+                    quoted("'", true);
+                }
+            }
+            continue;
+        }
+        /* A number, read whole, so `1x$$` is the number and the name `x$$`. A
+           number directly before `$$` leaves the `$` to open a quote, as the
+           Postgres releases that still allow trailing junk read it. */
+        NUMBER.lastIndex = i;
+        const number = NUMBER.exec(text)?.[0];
+        if (number) {
+            i += number.length;
+            continue;
+        }
+        // Dollar-quoted body: $$…$$ or $tag$…$tag$. Postgres only.
+        if (ch === '$' && postgres) {
+            const tag = /^\$[A-Za-z_]\w*\$|^\$\$/.exec(text.slice(i))?.[0];
+            if (tag) {
+                const end = text.indexOf(tag, i + tag.length);
+                i = end < 0 ? n : end + tag.length;
+                continue;
+            }
+        }
+        // A backquote quotes a name in SQLite and is an operator character in Postgres.
+        if (ch === "'" || ch === '"' || (ch === '`' && !postgres)) {
+            quoted(ch, false);
+            continue;
+        }
+        if (ch === '[' && !postgres) {
+            quoted(']', false);
+            continue;
+        }
+        if (ch === ';') {
+            // A trailing semicolon is punctuation, not a second statement.
+            if (text.slice(i + 1).trim() === '')
+                return null;
+            return 'One statement at a time. Remove the semicolon and everything after it, or run them separately.';
+        }
+        i += 1;
+    }
+    return null;
+}
+/* An identifier as both dialects lex one: a letter, underscore or non-ASCII
+   character, then any of those, digits or `$`. */
+const IDENTIFIER = /[A-Za-z_\u0080-\uffff][\w$\u0080-\uffff]*/y;
+const NUMBER = /\d+(?:\.\d*)?(?:[eE][+-]?\d+)?/y;
+/* Postgres's quote continuation: a newline (and any further space or line
+   comments) between two quoted runs joins them into one string. */
+const CONTINUED = /^[ \t\f]*[\n\r](?:[ \t\n\r\f\v]|--[^\n\r]*[\n\r])*'/;
+/**
+ * Output column names, with collisions given a suffix.
+ *
+ * `SELECT id, id FROM t` names both columns `id`. Left alone, the grid draws
+ * one header twice and nothing says which value belongs to which. The suffix
+ * is the same answer `compileView` gives an explicit collision, for the same
+ * reason: one column quietly standing in for two is worse than an ugly name.
+ */
+export function dedupe(names) {
+    const seen = new Map();
+    return names.map((name) => {
+        const count = seen.get(name) ?? 0;
+        seen.set(name, count + 1);
+        return count ? `${name}_${count + 1}` : name;
+    });
+}
+/** A statement with its trailing semicolon and surrounding space removed. */
+export function trimStatement(text) {
+    /* The whitespace *before* the semicolon goes too. `select 1 ;` left a
+       trailing space, which is invisible in the editor and shows up in the
+       reported statement as a difference between what ran and what was typed. */
+    return text.trim().replace(/\s*;+\s*$/, '');
+}
+/**
+ * Wrap a statement so it cannot return more rows than asked for.
+ *
+ * `clampLimit` is the invariant everywhere else in this file, and it has no
+ * application point in a statement this process did not build — there is no
+ * request object to clamp. Wrapping is the equivalent: the database is asked
+ * for a bounded result rather than trusted to have been asked politely.
+ *
+ * One more row than the caller wanted, so "there is more than this" is known
+ * without a second query — the same trick `runView` uses.
+ *
+ * The limit is interpolated rather than bound, which is the one deliberate
+ * exception to the rule that nothing is interpolated. It is an integer this
+ * process computed from `clampLimit`, never a value that came from outside,
+ * and it is asserted to be one before it is used. Binding it would need a
+ * dialect-specific placeholder here, which is a lot of machinery to parameterise a number we
+ * chose ourselves.
+ *
+ * Not every statement can be wrapped — `EXPLAIN`, `PRAGMA`, a `WITH` that ends
+ * in `INSERT … RETURNING` — so the caller is told whether it applied and can
+ * fall back to running the statement bare and saying so.
+ */
+export function boundStatement(text, limit) {
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw new Error(`A row limit must be a positive integer, not ${String(limit)}.`);
+    }
+    /* The inner statement sits on its own line. A trailing line comment —
+       `select * from huge -- note` — would otherwise swallow the closing
+       parenthesis and the LIMIT with it, the wrap would fail to parse, and the
+       fallback ran the statement *unbounded* and materialised every row before
+       slicing. A newline ends the comment; the wrapper survives. */
+    return `SELECT * FROM (\n${trimStatement(text)}\n) AS mistri_bounded LIMIT ${limit + 1}`;
+}
+/**
+ * Refuse a statement that `EXPLAIN` would *execute* rather than plan.
+ *
+ * `EXPLAIN` is offered as the planner's account of a statement without
+ * running it. `EXPLAIN ANALYZE …` (Postgres) and the option
+ * form `EXPLAIN (ANALYZE) …` run the statement to measure it, so text that
+ * begins with `analyze` or `(` turned a plan-only tool into an execute tool.
+ * Both sit inside a read-only transaction, so no row could be written — but
+ * a `pg_sleep(60)` or a full scan runs all the same, and the contract said
+ * it would not. Leading comments are skipped so the check reads the
+ * statement, not a note above it.
+ */
+export function refuseAnalyze(text) {
+    const first = trimStatement(text).replace(/^\s*(?:--[^\n]*\n|\/\*[\s\S]*?\*\/|\s)+/g, '');
+    if (/^(?:\(|analy[sz]e\b|explain\b)/i.test(first)) {
+        return 'explain plans a statement without running it: give it the statement itself, not ' + 'an EXPLAIN, ANALYZE or (option) form.';
+    }
+    return null;
+}
+/**
+ * Whether a statement is worth trying to wrap.
+ *
+ * A conservative first token test, and deliberately not a parse. Getting this
+ * wrong in the cautious direction costs a bounded result; getting it wrong in
+ * the other direction costs a confusing syntax error from the database about a
+ * statement the user did not write. `WITH` is included because a CTE ending in
+ * a SELECT is the common case, and the wrap failing on one that does not is
+ * handled by the fallback rather than by being clever here.
+ */
+export function looksWrappable(text) {
+    const first = trimStatement(text).replace(/^\s*(?:--[^\n]*\n|\/\*[\s\S]*?\*\/|\s)+/g, '');
+    /* `(select …) union (select …)` is a SELECT too, and unwrapped it ran unbounded. */
+    return /^(?:\(|(?:select|with|table|values)\b)/i.test(first);
+}
+/**
+ * A queue of one.
+ *
+ * Every adapter here writes through a single connection, and a transaction is
+ * a span of statements on it that nothing else may enter. Node is
+ * single-threaded but `await` is not: two requests arriving together interleave
+ * at every await point, so a plain `/api/update` can land in the middle of
+ * somebody's open transaction and be rolled back with it — a write that
+ * succeeded, reported success, and then quietly did not happen.
+ *
+ * So writes queue. The cost is that two concurrent edits are applied one after
+ * the other rather than at once, which is what a single connection was always
+ * going to do anyway.
+ */
+export class Serial {
+    tail = Promise.resolve();
+    run(work) {
+        /* The chain must not break on a failure: `catch` here keeps the *queue*
+           going while the caller still gets the rejection from `next`. */
+        const next = this.tail.then(work, work);
+        this.tail = next.catch(() => { });
+        return next;
+    }
+}
+/**
+ * Drain accepted operations before commit/rollback, then refuse escaped handles.
+ *
+ * Each operation starts once every operation asked before it has settled
+ * (`run`), so a handler's statements reach the database in the order it asked
+ * them. Reads asked together — a handler's `Promise.all` — waited on each
+ * other all the same, a round trip each, though nothing in one could change
+ * what another reads. On a transaction told its writer sends together
+ * (`together`, a pipelining PostgreSQL writer), a read (`read`) starts beside
+ * the reads still in flight, in the order asked, so they leave in one flight;
+ * it still waits for every write asked before it, and every write waits for
+ * every read before it. Only operations in flight together overlap: one
+ * awaited before the next is asked is answered before the next starts.
+ *
+ * What a caller hears is unchanged. Each operation settles in the order asked,
+ * after the ones before it, and the first failure in that order is every later
+ * operation's failure, whether the later one had started or not — a read that
+ * ran beside a failed one is answered with that failure, never its own rows —
+ * and finish() rethrows it. Elsewhere `read` is `run`.
+ */
+export class TransactionOperations {
+    together;
+    active = true;
+    failure;
+    /** Settles once every operation asked so far has: where the next write starts, and where each one settles. */
+    settled = Promise.resolve();
+    /** Settles once the last operation that was not a read has: where a read starts, beside the reads after it. */
+    written = Promise.resolve();
+    constructor(together = false) {
+        this.together = together;
+    }
+    run(work) {
+        return this.enqueue(work, false);
+    }
+    /** A read: it changes nothing another operation reads, so on a transaction that sends together it starts beside reads in flight. */
+    read(work) {
+        return this.enqueue(work, this.together);
+    }
+    enqueue(work, beside) {
+        if (!this.active)
+            return Promise.reject(new Refusal('This transaction is no longer active.'));
+        const before = this.settled;
+        const ran = (beside ? this.written : before).then(() => {
+            // Some engine errors roll back the transaction themselves. Running a
+            // later queued write (including a receipt) could then autocommit it.
+            if (this.failure)
+                throw this.failure.error;
+            return work();
+        });
+        // Settled in the order asked: a failure before this one is this one's, and this one's is recorded only in its turn.
+        const result = ran.then((value) => before.then(() => {
+            if (this.failure)
+                throw this.failure.error;
+            return value;
+        }), (error) => before.then(() => {
+            if (this.failure)
+                throw this.failure.error;
+            this.failure = { error };
+            throw error;
+        }));
+        this.settled = result.catch(() => { });
+        if (!beside)
+            this.written = this.settled;
+        // Fire-and-forget failures are still observed and rethrown by finish().
+        void result.catch(() => { });
+        return result;
+    }
+    async finish() {
+        this.active = false;
+        await this.settled;
+        if (this.failure)
+            throw this.failure.error;
+    }
+}
+/** Capture before queue waits, including failures: a caught malformed lock must
+ * still poison the owning transaction just like a failed database operation. */
+export function queueRecordLock(operations, input, work) {
+    let request;
+    let invalid;
+    try {
+        const data = (value) => {
+            if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+                throw new Refusal('Malformed record lock request.');
+            const entries = Reflect.ownKeys(value).map((key) => {
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (typeof key !== 'string' || !descriptor.enumerable || !('value' in descriptor))
+                    throw new Refusal('Malformed record lock request.');
+                return [key, descriptor.value];
+            });
+            return Object.fromEntries(entries);
+        };
+        const root = data(input);
+        if (typeof root.table !== 'string' || !root.table.length)
+            throw new Refusal('Malformed record lock table.');
+        const key = data(root.key);
+        if (!Object.keys(key).length ||
+            Object.values(key).some((value) => typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value))))
+            throw new Refusal('Malformed record lock key.');
+        request = { table: root.table, key: key };
+    }
+    catch (error) {
+        invalid = { error };
+    }
+    return operations.run(() => {
+        if (invalid)
+            throw invalid.error;
+        return work(request);
+    });
+}
+/** Catalog-attested complete key only; callers supply the writer's metadata. */
+export function recordLockFilter(request, primary) {
+    if (!primary.length)
+        throw new Refusal(`${request.table} has no primary key, so no single row can be identified.`);
+    if (Object.keys(request.key).length !== primary.length || primary.some((column) => !Object.hasOwn(request.key, column))) {
+        throw new Refusal(`Locking ${request.table} needs exactly its primary key (${primary.join(', ')}).`);
+    }
+    return { groups: [primary.map((column) => ({ column, op: '=', value: request.key[column] }))] };
+}

package/dist/adapters/cache/cacheStore.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Somewhere to keep a value for a while: in this process by default, in a
+ * Valkey cache when the config names one, so every instance of a deployment
+ * shares it.
+ *
+ * Never a source of truth. Everything here is a copy or a count that is
+ * allowed to vanish — a cached API answer, a rate-limit window — so every
+ * write carries a time to live (there is no "forever"), a read that cannot
+ * reach the cache is a miss, and a write that cannot is dropped. The one
+ * caller that must know the difference, the rate limiter, is told through
+ * `incr`, which throws `CacheUnavailable` rather than inventing a count.
+ */
+import { type RespClient } from './resp.js';
+export { CacheUnavailable } from './resp.js';
+export interface CacheStore {
+    readonly kind: 'memory' | 'valkey';
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * Count one under `key`. A new key starts a window of `ttlMs`; the answer is
+     * the count within it and the milliseconds it has left. Throws
+     * CacheUnavailable when the count cannot be kept.
+     */
+    incr(key: string, ttlMs: number): Promise<{
+        count: number;
+        ttlMs: number;
+    }>;
+    close(): Promise<void>;
+}
+/**
+ * The process's own cache: a Map in least-recently-used order, bounded, so a
+ * stream of distinct keys (an API's pages, a flood of client addresses) cannot
+ * grow it without end. Expiry is read, not scheduled: no timers to clean up.
+ */
+export declare class MemoryCacheStore implements CacheStore {
+    private readonly maxEntries;
+    private readonly now;
+    readonly kind: 'memory';
+    private readonly entries;
+    constructor(maxEntries?: number, now?: () => number);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    incr(key: string, ttlMs: number): Promise<{
+        count: number;
+        ttlMs: number;
+    }>;
+    close(): Promise<void>;
+    /** How many entries are held; tests read it. */
+    get size(): number;
+    private live;
+    private trim;
+}
+/**
+ * A Valkey cache shared by every instance. `onUnavailable` hears each
+ * outage's reason — the server logs it once — while reads carry on as misses.
+ */
+export declare class ValkeyCacheStore implements CacheStore {
+    private readonly client;
+    private readonly onUnavailable;
+    readonly kind: 'valkey';
+    constructor(client: RespClient, onUnavailable?: (message: string) => void);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    incr(key: string, ttlMs: number): Promise<{
+        count: number;
+        ttlMs: number;
+    }>;
+    close(): Promise<void>;
+    private unavailable;
+}
+/** The same store under a key prefix: `tw:<app>:http:<connection>:`, say. */
+export declare function scopedCache(store: CacheStore, prefix: string): CacheStore;

package/dist/adapters/cache/cacheStore.js

@@ -0,0 +1,160 @@
+/**
+ * Somewhere to keep a value for a while: in this process by default, in a
+ * Valkey cache when the config names one, so every instance of a deployment
+ * shares it.
+ *
+ * Never a source of truth. Everything here is a copy or a count that is
+ * allowed to vanish — a cached API answer, a rate-limit window — so every
+ * write carries a time to live (there is no "forever"), a read that cannot
+ * reach the cache is a miss, and a write that cannot is dropped. The one
+ * caller that must know the difference, the rate limiter, is told through
+ * `incr`, which throws `CacheUnavailable` rather than inventing a count.
+ */
+import { CacheUnavailable, RespReplyError } from './resp.js';
+export { CacheUnavailable } from './resp.js';
+/* Thirty days: a copy kept longer than that is a copy nobody meant to keep. */
+const MAX_TTL_MS = 30 * 24 * 3_600_000;
+function assertTtl(ttlMs) {
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 1 || ttlMs > MAX_TTL_MS) {
+        throw new Error(`A cached value needs a time to live between 1 ms and 30 days; ${ttlMs} is not one.`);
+    }
+}
+/**
+ * The process's own cache: a Map in least-recently-used order, bounded, so a
+ * stream of distinct keys (an API's pages, a flood of client addresses) cannot
+ * grow it without end. Expiry is read, not scheduled: no timers to clean up.
+ */
+export class MemoryCacheStore {
+    maxEntries;
+    now;
+    kind = 'memory';
+    entries = new Map();
+    constructor(maxEntries = 10_000, now = Date.now) {
+        this.maxEntries = maxEntries;
+        this.now = now;
+    }
+    async get(key) {
+        const entry = this.live(key);
+        if (!entry)
+            return undefined;
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    async set(key, value, ttlMs) {
+        assertTtl(ttlMs);
+        this.entries.delete(key);
+        this.entries.set(key, { value, expires: this.now() + ttlMs });
+        this.trim();
+    }
+    async delete(key) {
+        this.entries.delete(key);
+    }
+    async incr(key, ttlMs) {
+        assertTtl(ttlMs);
+        const entry = this.live(key);
+        const now = this.now();
+        const next = entry ? { value: String(Number(entry.value) + 1), expires: entry.expires } : { value: '1', expires: now + ttlMs };
+        this.entries.delete(key);
+        this.entries.set(key, next);
+        this.trim();
+        return { count: Number(next.value), ttlMs: next.expires - now };
+    }
+    async close() {
+        this.entries.clear();
+    }
+    /** How many entries are held; tests read it. */
+    get size() {
+        return this.entries.size;
+    }
+    live(key) {
+        const entry = this.entries.get(key);
+        if (entry && entry.expires <= this.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    trim() {
+        while (this.entries.size > this.maxEntries)
+            this.entries.delete(this.entries.keys().next().value);
+    }
+}
+/* One round trip, and atomic: a window that is counted is a window that
+   expires, even if this process stops between the two steps. */
+const COUNT_IN_WINDOW = `local n = redis.call('INCR', KEYS[1])
+if n == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local t = redis.call('PTTL', KEYS[1])
+if t < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) t = tonumber(ARGV[1]) end
+return {n, t}`;
+/**
+ * A Valkey cache shared by every instance. `onUnavailable` hears each
+ * outage's reason — the server logs it once — while reads carry on as misses.
+ */
+export class ValkeyCacheStore {
+    client;
+    onUnavailable;
+    kind = 'valkey';
+    constructor(client, onUnavailable = () => { }) {
+        this.client = client;
+        this.onUnavailable = onUnavailable;
+    }
+    async get(key) {
+        try {
+            const value = await this.client.command('GET', key);
+            return typeof value === 'string' ? value : undefined;
+        }
+        catch (error) {
+            this.unavailable(error);
+            return undefined;
+        }
+    }
+    async set(key, value, ttlMs) {
+        assertTtl(ttlMs);
+        try {
+            await this.client.command('SET', key, value, 'PX', ttlMs);
+        }
+        catch (error) {
+            this.unavailable(error);
+        }
+    }
+    async delete(key) {
+        try {
+            await this.client.command('DEL', key);
+        }
+        catch (error) {
+            this.unavailable(error);
+        }
+    }
+    async incr(key, ttlMs) {
+        assertTtl(ttlMs);
+        let reply;
+        try {
+            reply = await this.client.command('EVAL', COUNT_IN_WINDOW, 1, key, ttlMs);
+        }
+        catch (error) {
+            this.unavailable(error);
+            throw error instanceof CacheUnavailable ? error : new CacheUnavailable('the cache refused a count.');
+        }
+        if (!Array.isArray(reply) || typeof reply[0] !== 'number' || typeof reply[1] !== 'number')
+            throw new CacheUnavailable('the cache answered a count in an unexpected shape.');
+        return { count: reply[0], ttlMs: reply[1] };
+    }
+    async close() {
+        await this.client.close();
+    }
+    unavailable(error) {
+        this.onUnavailable(error instanceof CacheUnavailable || error instanceof RespReplyError ? error.message : 'the cache failed.');
+    }
+}
+/** The same store under a key prefix: `tw:<app>:http:<connection>:`, say. */
+export function scopedCache(store, prefix) {
+    return {
+        kind: store.kind,
+        get: (key) => store.get(prefix + key),
+        set: (key, value, ttlMs) => store.set(prefix + key, value, ttlMs),
+        delete: (key) => store.delete(prefix + key),
+        incr: (key, ttlMs) => store.incr(prefix + key, ttlMs),
+        close: () => store.close(),
+    };
+}