turbine-orm 0.81.0 → 0.90.0

package/dist/query/stream-idle.d.ts

@@ -0,0 +1,132 @@
+/**
+ * turbine-orm: the abandoned-stream idle guard.
+ *
+ * A cursor stream holds a checked-out connection between pulls (and, on
+ * PostgreSQL, an open transaction whose snapshot pins the xmin horizon for the
+ * whole database). A consumer that stops pulling without calling `return()`
+ * leaves the stream suspended at a `yield` forever, and a suspended generator
+ * runs no code, so nothing would ever release either. This guard is the code
+ * that runs instead: a timer that notices the consumer has asked for nothing for
+ * the configured time and closes the stream from outside.
+ *
+ * The consuming generator owns the {@link StreamIdleState}: it sets `suspended`
+ * around each yield and bumps `pulls` when the consumer resumes it. That is two
+ * writes per yield and no timer work, which is what keeps a per-row stream as
+ * cheap as before (a timer refreshed per row costs about 15% per row; a
+ * `setTimeout` per row more than doubles it).
+ *
+ * Leaf module: imports errors.ts only, so it stays in the serverless graph
+ * without pulling anything node-only.
+ */
+import { TimeoutError } from '../errors.js';
+/** The default for `streamIdleTimeoutMs` (client) and `idleTimeoutMs` (per call). */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/**
+ * How much later than the idle timeout the PostgreSQL server-side limit fires.
+ * The client timer always expires a stream first (it ticks at most every
+ * {@link MAX_TICK_MS}, half this grace), so the server limit only acts when the
+ * process has stopped running timers: frozen between serverless invocations,
+ * or an event loop blocked for longer than the grace.
+ */
+export declare const STREAM_IDLE_BACKSTOP_GRACE_MS = 10000;
+/**
+ * The largest idle timeout accepted. PostgreSQL's
+ * `idle_in_transaction_session_timeout` is a 32-bit count of milliseconds, and
+ * the backstop adds the grace to it.
+ */
+export declare const MAX_STREAM_IDLE_TIMEOUT_MS: number;
+/**
+ * Validate an idle timeout: a whole number of milliseconds from 0 (disabled)
+ * to {@link MAX_STREAM_IDLE_TIMEOUT_MS}, else E003. `undefined` means "not
+ * set here", so the caller falls back to the next level.
+ */
+export declare function resolveStreamIdleTimeout(value: unknown, name: string): number | undefined;
+/**
+ * What the generator that yields to the consumer tells the guard. Written
+ * around every yield; read by the guard's timer.
+ */
+export interface StreamIdleState {
+    /** How many times the consumer has resumed the stream. */
+    pulls: number;
+    /** The stream is suspended at a yield, waiting for the consumer to ask for more. */
+    suspended: boolean;
+    /** Rows handed to the consumer so far, for the log line. */
+    rows: number;
+    /** Set when the guard closed the stream; the next pull throws it. */
+    expired: TimeoutError | undefined;
+}
+export declare function newStreamIdleState(): StreamIdleState;
+/** The E002 the next pull on an expired stream throws. */
+export declare function streamIdleExpiredError(action: string, table: string, timeoutMs: number, unit: string): TimeoutError;
+/**
+ * The PostgreSQL server-side limit for a stream's own transaction:
+ * `idle_in_transaction_session_timeout` set to the idle timeout plus the grace,
+ * TRANSACTION-LOCAL (`set_config(..., true)`), so it ends with the stream's
+ * COMMIT and cannot reach another client through a transaction pooler.
+ *
+ * A stricter limit already in force (a role or server setting below ours) is
+ * kept, so a stream never loosens what the operator configured. The value is a
+ * validated integer, never caller text: a GUC value cannot be a bind parameter.
+ * Reading `pg_settings` rather than calling `set_config` directly also means an
+ * engine without the setting gets no row and no error.
+ */
+export declare function streamBackstopStatement(timeoutMs: number): string;
+/**
+ * The timer half of the guard. One per open cursor stream, `unref()`ed so it
+ * never keeps a process alive.
+ *
+ * It ticks every `min(timeout / 4, 5 s)`. A tick that finds the stream
+ * suspended with no pull since the previous tick counts as idle; enough idle
+ * ticks in a row to cover the timeout expire the stream, so expiry lands
+ * between 1x the timeout and the timeout plus one tick. Time Turbine spends
+ * fetching never counts, because the stream is not suspended then.
+ *
+ * With `keepalive` set (PostgreSQL, where {@link streamBackstopStatement} is
+ * in force), a tick also sends a no-op statement when the connection has been
+ * quiet for half the timeout. A consumer that pulls rows of an already-fetched
+ * batch slowly is alive while the server sees an idle transaction; without the
+ * keepalive the server limit would end a stream the consumer is still reading.
+ * The server limit therefore only fires when this timer cannot run.
+ */
+export declare class StreamIdleGuard {
+    private readonly state;
+    private readonly timeoutMs;
+    private readonly expiredError;
+    private readonly onExpire;
+    private readonly keepalive?;
+    private readonly timer;
+    private readonly idleTicksToExpire;
+    private lastPulls;
+    private idleTicks;
+    private lastStatementAt;
+    private statementsInFlight;
+    private keepaliveInFlight;
+    /** Settles once an expired stream's cleanup has run (connection released). */
+    expiry: Promise<void> | undefined;
+    constructor(state: StreamIdleState, timeoutMs: number, expiredError: () => TimeoutError, onExpire: () => Promise<void>, keepalive?: (() => Promise<unknown>) | undefined);
+    /** Bracket a statement on the stream's connection, so the keepalive knows it is busy. */
+    statementStarted(): void;
+    statementSettled(): void;
+    stop(): void;
+    private tick;
+}
+/** The connection surface a stream drives; structurally `StreamableConnection` in dialect.ts. */
+interface StreamConnection {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/**
+ * The stream's connection, as the dialect sees it, with two additions: every
+ * statement is reported to the guard (for the keepalive), and, when `backstop`
+ * is given, the dialect's own BEGIN carries {@link streamBackstopStatement} in
+ * the same simple-protocol round trip, so the limit is in force from the
+ * transaction's first statement at no extra cost. Matching the exact BEGIN text
+ * the dialect emits keeps the dialect itself unchanged; the live backstop test
+ * fails if that text ever stops matching.
+ */
+export declare function watchStreamConnection(base: StreamConnection, guard: () => StreamIdleGuard | undefined, backstop?: {
+    begin: string;
+    statement: string;
+}): StreamConnection;
+export {};

package/dist/query/stream-idle.js

@@ -0,0 +1,203 @@
+/**
+ * turbine-orm: the abandoned-stream idle guard.
+ *
+ * A cursor stream holds a checked-out connection between pulls (and, on
+ * PostgreSQL, an open transaction whose snapshot pins the xmin horizon for the
+ * whole database). A consumer that stops pulling without calling `return()`
+ * leaves the stream suspended at a `yield` forever, and a suspended generator
+ * runs no code, so nothing would ever release either. This guard is the code
+ * that runs instead: a timer that notices the consumer has asked for nothing for
+ * the configured time and closes the stream from outside.
+ *
+ * The consuming generator owns the {@link StreamIdleState}: it sets `suspended`
+ * around each yield and bumps `pulls` when the consumer resumes it. That is two
+ * writes per yield and no timer work, which is what keeps a per-row stream as
+ * cheap as before (a timer refreshed per row costs about 15% per row; a
+ * `setTimeout` per row more than doubles it).
+ *
+ * Leaf module: imports errors.ts only, so it stays in the serverless graph
+ * without pulling anything node-only.
+ */
+import { TimeoutError, ValidationError } from '../errors.js';
+/** The default for `streamIdleTimeoutMs` (client) and `idleTimeoutMs` (per call). */
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000;
+/**
+ * How much later than the idle timeout the PostgreSQL server-side limit fires.
+ * The client timer always expires a stream first (it ticks at most every
+ * {@link MAX_TICK_MS}, half this grace), so the server limit only acts when the
+ * process has stopped running timers: frozen between serverless invocations,
+ * or an event loop blocked for longer than the grace.
+ */
+export const STREAM_IDLE_BACKSTOP_GRACE_MS = 10_000;
+/**
+ * The largest idle timeout accepted. PostgreSQL's
+ * `idle_in_transaction_session_timeout` is a 32-bit count of milliseconds, and
+ * the backstop adds the grace to it.
+ */
+export const MAX_STREAM_IDLE_TIMEOUT_MS = 2_147_483_647 - STREAM_IDLE_BACKSTOP_GRACE_MS;
+/** The longest gap between two idle checks, so expiry lands within 5 s of the timeout. */
+const MAX_TICK_MS = 5_000;
+/**
+ * Validate an idle timeout: a whole number of milliseconds from 0 (disabled)
+ * to {@link MAX_STREAM_IDLE_TIMEOUT_MS}, else E003. `undefined` means "not
+ * set here", so the caller falls back to the next level.
+ */
+export function resolveStreamIdleTimeout(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > MAX_STREAM_IDLE_TIMEOUT_MS) {
+        throw new ValidationError(`Invalid ${name}: ${typeof value === 'string' ? JSON.stringify(value) : String(value)}. Expected a whole ` +
+            `number of milliseconds from 0 (no idle timeout) to ${MAX_STREAM_IDLE_TIMEOUT_MS}.`);
+    }
+    return value;
+}
+export function newStreamIdleState() {
+    return { pulls: 0, suspended: false, rows: 0, expired: undefined };
+}
+/** The E002 the next pull on an expired stream throws. */
+export function streamIdleExpiredError(action, table, timeoutMs, unit) {
+    return new TimeoutError(timeoutMs, 'Stream', {
+        message: `${action} on "${table}" was closed after ${timeoutMs} ms with no ${unit} requested: its cursor and ` +
+            `connection were released so an abandoned stream cannot hold a pooled connection and the database's ` +
+            `snapshot. Consume faster, raise streamIdleTimeoutMs (client) or idleTimeoutMs (this call), or pass 0 ` +
+            'to disable.',
+        outcome: 'not-executed',
+    });
+}
+/**
+ * The PostgreSQL server-side limit for a stream's own transaction:
+ * `idle_in_transaction_session_timeout` set to the idle timeout plus the grace,
+ * TRANSACTION-LOCAL (`set_config(..., true)`), so it ends with the stream's
+ * COMMIT and cannot reach another client through a transaction pooler.
+ *
+ * A stricter limit already in force (a role or server setting below ours) is
+ * kept, so a stream never loosens what the operator configured. The value is a
+ * validated integer, never caller text: a GUC value cannot be a bind parameter.
+ * Reading `pg_settings` rather than calling `set_config` directly also means an
+ * engine without the setting gets no row and no error.
+ */
+export function streamBackstopStatement(timeoutMs) {
+    const limit = timeoutMs + STREAM_IDLE_BACKSTOP_GRACE_MS;
+    if (!Number.isSafeInteger(limit) || limit <= STREAM_IDLE_BACKSTOP_GRACE_MS || limit > 2_147_483_647) {
+        throw new ValidationError(`Invalid stream idle timeout ${String(timeoutMs)} for the server-side limit.`);
+    }
+    return ("SELECT set_config('idle_in_transaction_session_timeout', CASE WHEN s.setting::bigint > 0 AND " +
+        `s.setting::bigint < ${limit} THEN s.setting ELSE '${limit}' END, true) FROM pg_settings s ` +
+        "WHERE s.name = 'idle_in_transaction_session_timeout'");
+}
+/**
+ * The timer half of the guard. One per open cursor stream, `unref()`ed so it
+ * never keeps a process alive.
+ *
+ * It ticks every `min(timeout / 4, 5 s)`. A tick that finds the stream
+ * suspended with no pull since the previous tick counts as idle; enough idle
+ * ticks in a row to cover the timeout expire the stream, so expiry lands
+ * between 1x the timeout and the timeout plus one tick. Time Turbine spends
+ * fetching never counts, because the stream is not suspended then.
+ *
+ * With `keepalive` set (PostgreSQL, where {@link streamBackstopStatement} is
+ * in force), a tick also sends a no-op statement when the connection has been
+ * quiet for half the timeout. A consumer that pulls rows of an already-fetched
+ * batch slowly is alive while the server sees an idle transaction; without the
+ * keepalive the server limit would end a stream the consumer is still reading.
+ * The server limit therefore only fires when this timer cannot run.
+ */
+export class StreamIdleGuard {
+    state;
+    timeoutMs;
+    expiredError;
+    onExpire;
+    keepalive;
+    timer;
+    idleTicksToExpire;
+    lastPulls;
+    idleTicks = 0;
+    lastStatementAt = Date.now();
+    statementsInFlight = 0;
+    keepaliveInFlight = false;
+    /** Settles once an expired stream's cleanup has run (connection released). */
+    expiry;
+    constructor(state, timeoutMs, expiredError, onExpire, keepalive) {
+        this.state = state;
+        this.timeoutMs = timeoutMs;
+        this.expiredError = expiredError;
+        this.onExpire = onExpire;
+        this.keepalive = keepalive;
+        const tickMs = Math.max(1, Math.min(Math.floor(timeoutMs / 4), MAX_TICK_MS));
+        this.idleTicksToExpire = Math.ceil(timeoutMs / tickMs);
+        this.lastPulls = state.pulls;
+        this.timer = setInterval(() => this.tick(), tickMs);
+        this.timer.unref?.();
+    }
+    /** Bracket a statement on the stream's connection, so the keepalive knows it is busy. */
+    statementStarted() {
+        this.statementsInFlight++;
+        this.lastStatementAt = Date.now();
+    }
+    statementSettled() {
+        this.statementsInFlight--;
+        this.lastStatementAt = Date.now();
+    }
+    stop() {
+        clearInterval(this.timer);
+    }
+    tick() {
+        if (this.expiry)
+            return;
+        if (!this.state.suspended || this.state.pulls !== this.lastPulls) {
+            this.lastPulls = this.state.pulls;
+            this.idleTicks = 0;
+        }
+        else if (++this.idleTicks >= this.idleTicksToExpire) {
+            this.stop();
+            // Set before any await, so a pull that races the cleanup already sees it.
+            this.state.expired = this.expiredError();
+            this.expiry = this.onExpire();
+            return;
+        }
+        if (this.keepalive &&
+            !this.keepaliveInFlight &&
+            this.statementsInFlight === 0 &&
+            Date.now() - this.lastStatementAt >= this.timeoutMs / 2) {
+            this.keepaliveInFlight = true;
+            this.statementStarted();
+            // A failed keepalive is not reported here: the stream's next statement
+            // meets the same broken connection and reports it with context.
+            this.keepalive()
+                .catch(() => undefined)
+                .finally(() => {
+                this.keepaliveInFlight = false;
+                this.statementSettled();
+            });
+        }
+    }
+}
+/**
+ * The stream's connection, as the dialect sees it, with two additions: every
+ * statement is reported to the guard (for the keepalive), and, when `backstop`
+ * is given, the dialect's own BEGIN carries {@link streamBackstopStatement} in
+ * the same simple-protocol round trip, so the limit is in force from the
+ * transaction's first statement at no extra cost. Matching the exact BEGIN text
+ * the dialect emits keeps the dialect itself unchanged; the live backstop test
+ * fails if that text ever stops matching.
+ */
+export function watchStreamConnection(base, guard, backstop) {
+    let backstopSent = false;
+    return {
+        query: async (text, values) => {
+            let sql = text;
+            if (backstop && !backstopSent && values === undefined && text === backstop.begin) {
+                backstopSent = true;
+                sql = `${text}; ${backstop.statement}`;
+            }
+            const g = guard();
+            g?.statementStarted();
+            try {
+                return await base.query(sql, values);
+            }
+            finally {
+                g?.statementSettled();
+            }
+        },
+    };
+}

package/dist/query/table-client.d.ts

@@ -0,0 +1,101 @@
+/**
+ * turbine-orm, the table accessor contract.
+ *
+ * `db.users` is a `QueryInterface` on the SQL engines and a `PowqlInterface` on
+ * PowDB. The second is a parallel class, not a subclass, so without a shared
+ * type the compiler cannot see a method one engine has and the other lacks, and
+ * the user meets it as `TypeError: ... is not a function` at run time.
+ *
+ * {@link TableClient} is that shared type. It is DERIVED from QueryInterface
+ * (a `Pick` of the classified methods), so the SQL builder stays the one source
+ * of truth for every signature, and `PowqlInterface implements TableClient`
+ * makes a missing or mismatched method a build error.
+ *
+ * Type-only imports: this module emits {@link TABLE_METHODS} and nothing else,
+ * so it adds no edge to the import graph.
+ */
+import type { QueryInterface } from './builder.js';
+import type { DefaultInputTypes, TableInputTypes } from './types.js';
+/**
+ * How a table method is routed.
+ *
+ * - `read`: may be served by a read replica (`READ_OPERATIONS` in client.ts is
+ *   derived from these).
+ * - `write`: always runs on the primary.
+ * - `deferred`: returns a `DeferredQuery` for `db.pipeline()` /
+ *   `$transaction([...])` without running anything.
+ * - `primary`: anything else on the accessor; runs on the primary.
+ */
+export type TableMethodKind = 'read' | 'write' | 'deferred' | 'primary';
+/**
+ * Every public method of a table accessor, with its routing class.
+ *
+ * `satisfies` refuses a key QueryInterface does not have; the exhaustiveness
+ * check below refuses a QueryInterface member missing from here.
+ */
+export declare const TABLE_METHODS: {
+    readonly findMany: "read";
+    readonly findFirst: "read";
+    readonly findFirstOrThrow: "read";
+    readonly findUnique: "read";
+    readonly findUniqueOrThrow: "read";
+    readonly count: "read";
+    readonly aggregate: "read";
+    readonly groupBy: "read";
+    readonly findManyStream: "read";
+    readonly findManyStreamBatches: "read";
+    readonly explain: "primary";
+    readonly cacheStats: "primary";
+    readonly create: "write";
+    readonly createMany: "write";
+    readonly update: "write";
+    readonly updateMany: "write";
+    readonly delete: "write";
+    readonly deleteMany: "write";
+    readonly upsert: "write";
+    readonly buildFindMany: "deferred";
+    readonly buildFindFirst: "deferred";
+    readonly buildFindFirstOrThrow: "deferred";
+    readonly buildFindUnique: "deferred";
+    readonly buildFindUniqueOrThrow: "deferred";
+    readonly buildCount: "deferred";
+    readonly buildAggregate: "deferred";
+    readonly buildGroupBy: "deferred";
+    readonly buildCreate: "deferred";
+    readonly buildCreateMany: "deferred";
+    readonly buildUpdate: "deferred";
+    readonly buildUpdateMany: "deferred";
+    readonly buildDelete: "deferred";
+    readonly buildDeleteMany: "deferred";
+    readonly buildUpsert: "deferred";
+};
+/** A method name in the table accessor contract. */
+export type TableMethod = keyof typeof TABLE_METHODS;
+/**
+ * Public QueryInterface members that are SQL-engine internals (cache
+ * fingerprinting, the upsert lookup decision, a test hook), deliberately
+ * outside the accessor contract, so PowDB need not implement them.
+ */
+export type SqlInternalMember = 'collectWhereParams' | 'fingerprintWhere' | 'withFingerprint' | 'upsertNeedsLookup' | 'resetUnlimitedWarnings';
+/** Public QueryInterface members classified neither as a table method nor as internal. */
+type Unclassified = Exclude<keyof QueryInterface<object>, TableMethod | SqlInternalMember>;
+/**
+ * Fails the build, naming the member, when QueryInterface gains a public
+ * member nobody classified: add it to TABLE_METHODS (and to PowqlInterface) or
+ * to SqlInternalMember.
+ */
+type AssertEveryMemberClassified<U extends never> = U;
+export type EveryQueryInterfaceMemberClassified = AssertEveryMemberClassified<Unclassified>;
+/** The table accessor contract every engine's accessor class implements. */
+export type TableClient<T extends object, R extends object = {}, M extends TableInputTypes = DefaultInputTypes<T, R>> = Pick<QueryInterface<T, R, M>, TableMethod>;
+/**
+ * View a factory-built accessor as the `QueryInterface` the client's public
+ * `table()` type names.
+ *
+ * Sound because the exhaustiveness check above guarantees `TableClient` holds
+ * every public QueryInterface member except the SQL internals, which nothing
+ * outside the SQL builder reaches through an accessor without first checking
+ * the member exists. The cast hides only private members.
+ */
+export declare function asQueryInterface<T extends object>(client: TableClient<T>): QueryInterface<T>;
+export {};

package/dist/query/table-client.js

@@ -0,0 +1,70 @@
+/**
+ * turbine-orm, the table accessor contract.
+ *
+ * `db.users` is a `QueryInterface` on the SQL engines and a `PowqlInterface` on
+ * PowDB. The second is a parallel class, not a subclass, so without a shared
+ * type the compiler cannot see a method one engine has and the other lacks, and
+ * the user meets it as `TypeError: ... is not a function` at run time.
+ *
+ * {@link TableClient} is that shared type. It is DERIVED from QueryInterface
+ * (a `Pick` of the classified methods), so the SQL builder stays the one source
+ * of truth for every signature, and `PowqlInterface implements TableClient`
+ * makes a missing or mismatched method a build error.
+ *
+ * Type-only imports: this module emits {@link TABLE_METHODS} and nothing else,
+ * so it adds no edge to the import graph.
+ */
+/**
+ * Every public method of a table accessor, with its routing class.
+ *
+ * `satisfies` refuses a key QueryInterface does not have; the exhaustiveness
+ * check below refuses a QueryInterface member missing from here.
+ */
+export const TABLE_METHODS = {
+    findMany: 'read',
+    findFirst: 'read',
+    findFirstOrThrow: 'read',
+    findUnique: 'read',
+    findUniqueOrThrow: 'read',
+    count: 'read',
+    aggregate: 'read',
+    groupBy: 'read',
+    findManyStream: 'read',
+    findManyStreamBatches: 'read',
+    explain: 'primary',
+    cacheStats: 'primary',
+    create: 'write',
+    createMany: 'write',
+    update: 'write',
+    updateMany: 'write',
+    delete: 'write',
+    deleteMany: 'write',
+    upsert: 'write',
+    buildFindMany: 'deferred',
+    buildFindFirst: 'deferred',
+    buildFindFirstOrThrow: 'deferred',
+    buildFindUnique: 'deferred',
+    buildFindUniqueOrThrow: 'deferred',
+    buildCount: 'deferred',
+    buildAggregate: 'deferred',
+    buildGroupBy: 'deferred',
+    buildCreate: 'deferred',
+    buildCreateMany: 'deferred',
+    buildUpdate: 'deferred',
+    buildUpdateMany: 'deferred',
+    buildDelete: 'deferred',
+    buildDeleteMany: 'deferred',
+    buildUpsert: 'deferred',
+};
+/**
+ * View a factory-built accessor as the `QueryInterface` the client's public
+ * `table()` type names.
+ *
+ * Sound because the exhaustiveness check above guarantees `TableClient` holds
+ * every public QueryInterface member except the SQL internals, which nothing
+ * outside the SQL builder reaches through an accessor without first checking
+ * the member exists. The cast hides only private members.
+ */
+export function asQueryInterface(client) {
+    return client;
+}