@voltro/database 0.23.0 → 0.25.0

package/dist/{frameworkLiveTables-BvPIm2cD.js → frameworkLiveTables-BQwB8K6R.js}

@@ -32,6 +32,15 @@ var r = (e) => {
 			serverOnly: !0
 		});
 	}
+	version() {
+		if (this.rejectIfRaw("version"), this.definition.type !== "integer") throw Error(`.version() requires an integer() column (got ${this.definition.type}). The store increments it, so it has to be a number — and a timestamp version reintroduces exactly the clock problem optimistic locking exists to avoid: two writes in the same millisecond are indistinguishable, and replica clocks disagree.`);
+		return new e({
+			...this.definition,
+			versionColumn: !0,
+			hasDefault: !0,
+			defaultValue: 1
+		});
+	}
 	sensitive(t) {
 		return new e({
 			...this.definition,

package/dist/index.d.ts

@@ -670,6 +670,34 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault e
      * neither.)
      */
     serverOnly(): this;
+    /**
+     * Mark this column as the row's OPTIMISTIC-CONCURRENCY version.
+     *
+     * ```ts
+     * table('documents', { id: id(), title: text(), version: integer().version() })
+     * ```
+     *
+     * From then on the store increments it on every update, and an update that
+     * carries `expectedVersion` fails with a typed `VersionConflict` when the row
+     * has moved on. That is the whole feature, and the reason it is a COLUMN
+     * marker rather than a table mixin is that only the author knows which column
+     * (if any) their schema already uses for this — several apps arrive with one.
+     *
+     * WHAT IT REPLACES. Nothing, which is the point: today the second of two
+     * concurrent writers wins silently. `updatedAt` is the obvious substitute and
+     * it does not work — same-millisecond writes are indistinguishable and replica
+     * clocks disagree, so a comparison that looks correct in a test loses rows
+     * under load. An integer the DATABASE owns has neither problem.
+     *
+     * WHAT IT DOES NOT DO. It is not a history: it records that a row changed, not
+     * what it changed to. For that use `plugin-versioning`. It is also not a
+     * distributed lock — a conflicting write is REPORTED, never queued or merged,
+     * because merging two intents is a decision only the application can make.
+     *
+     * Must be an `integer()`. A `text()` version cannot be incremented and a
+     * `timestamp()` one reintroduces the clock, so both fail at declaration.
+     */
+    version(): this;
     /**
      * Classify this column as SENSITIVE — it holds personal / sensitive data of
      * `class` (`'email'`, `'fullName'`, `'phone'`, `'address'`, `'secret'`, …).
@@ -1112,6 +1140,23 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
      * COSTS is per command — see `serverOnly()` below for the matrix.
      */
     readonly serverOnly?: boolean;
+    /**
+     * Optimistic-concurrency marker, set by `.version()`.
+     *
+     * The column the store INCREMENTS on every update, and the one an update may
+     * carry an expectation of. Two clients that read the same row and both write
+     * it are the normal case, not an exotic one — and without this the second
+     * write silently wins, which is the shape of every "my change disappeared"
+     * report ever filed.
+     *
+     * A TIMESTAMP cannot do this job. Two writes in the same millisecond are
+     * indistinguishable, and across replicas the clocks disagree; this repo has
+     * already lost rows to exactly that (an analytics sink dropped 7 of 40 events
+     * written in the same millisecond as the query bounding them). A monotonic
+     * integer has neither problem, and it also answers the other half of the
+     * question — which of two copies is NEWER — without consulting a clock.
+     */
+    readonly versionColumn?: boolean;
     /**
      * Data-sensitivity classification, set by `.sensitive(class)`. Declares that
      * this column holds personal / sensitive data of a given CLASS (`'email'`,
@@ -1404,6 +1449,31 @@ export declare interface ConnectionConfig {
      */
     readonly ssl?: boolean;
     readonly maxConnections?: number;
+    /**
+     * Per-statement timeout in ms — a runaway query (missing index, cartesian
+     * join) is aborted instead of holding a pooled connection forever, which under
+     * load exhausts the pool and stalls the whole app. Applied at the CONNECTION
+     * level so every query is bounded (no per-call opt-in). Env `DB_STATEMENT_TIMEOUT_MS`.
+     * Runtime-path only — the migration path (`voltro db apply`) deliberately does
+     * NOT read this, so a long backfill / index build is never cancelled by the app
+     * query ceiling.
+     *
+     * **Wired for postgres only** (the default dialect), enforced server-side via
+     * node-postgres' `statement_timeout` pool option — a runaway query is cancelled
+     * with SQLSTATE 57014, not merely disconnected. Every OTHER dialect currently
+     * ACCEPTS the field but IGNORES it, and the honest reasons differ:
+     *   - **mssql** — `@effect/sql-mssql` exposes only `connectTimeout` (connection
+     *     establishment), not tedious's per-request `requestTimeout`; mapping this
+     *     onto `connectTimeout` would bound the wrong phase, so it is left unwired
+     *     rather than wrong.
+     *   - **mysql/mariadb** — the server's `max_execution_time` bounds SELECTs only
+     *     (writes run unbounded), so a connection-level setting would be a partial,
+     *     misleading guarantee; not wired in V1.
+     *   - **sqlite** — in-process, one connection, no pool to exhaust; nothing to
+     *     protect.
+     * Unset (or any non-postgres dialect) = no timeout — behaviour is unchanged.
+     */
+    readonly statementTimeoutMs?: number;
     /**
      * Postgres only: the schema the app's tables live in, pinned as the
      * connection `search_path` (env `DB_SCHEMA`). When set, EVERY pooled
@@ -2190,6 +2260,35 @@ export declare interface ExistsPredicate {
     readonly subquery: QueryDescriptor;
 }
 
+/**
+ * Add `expiresAt` — after that instant the row is invisible to reads.
+ *
+ * ```ts
+ * table('inviteLinks', { id: id(), email: text() }).with(expires())
+ *
+ * await ctx.store.insert('inviteLinks', {
+ *   email, expiresAt: new Date(Date.now() + 24 * 3_600_000),
+ * })
+ * ```
+ *
+ * `expiresAt` is NULLABLE and null means never — so adding the mixin to an
+ * existing table does not make its rows vanish, and a row that should outlive
+ * the others simply leaves it unset. A non-null default would have been the
+ * tidier API and the wrong one: it would turn "I added a mixin" into "I set an
+ * expiry on every existing row".
+ *
+ * Reads filter it out on EVERY dialect from the moment it passes; the physical
+ * delete is a postgres-only sweep. Read the header before relying on the second
+ * half — an expired row is INVISIBLE everywhere and still PRESENT on four of
+ * five dialects, which is the right trade and a surprising one.
+ *
+ * Opt out for a deliberate read of expired rows the same way soft-delete does:
+ * `ctx.store.select('inviteLinks').includeExpired()`.
+ */
+export declare const expires: () => MixinDefinition<{
+    readonly expiresAt: ColumnDefinition<Date | null, "timestamp", boolean>;
+}>;
+
 /** The cipher the store middleware injects. Operates on opaque strings. */
 export declare interface FieldCipher {
     readonly encrypt: (plaintext: string) => string;
@@ -2639,6 +2738,16 @@ export declare type InferRowFromFields<F extends Record<string, ColumnDefinition
 /** Row type for a view — mirrors `InferRow` for tables. */
 export declare type InferViewRow<V> = V extends View<string, infer F> ? InferRowFromFields<F> : never;
 
+/**
+ * The version a freshly-inserted row starts at.
+ *
+ * 1 rather than 0 so that "has this row ever been written?" and "what version is
+ * it?" are never the same question — a 0 reads as absent in too many places
+ * (`if (row.version)`), and a version that is falsy on a real row is a trap
+ * waiting for the first person who writes that check.
+ */
+export declare const INITIAL_VERSION = 1;
+
 /**
  * Insert a row, typed against the table: the payload must carry every required
  * column (NOT NULL, no default, not auto-filled) or it is a compile error.
@@ -3348,6 +3457,26 @@ export declare const planNeonBranchProvision: (branchId: string, options?: NeonB
  *  never delete a non-branch; idempotent on the executor side. */
 export declare const planNeonBranchTeardown: (branchId: string) => ReadonlyArray<BranchStep>;
 
+/**
+ * The version an UPDATE must write, and the guard it must carry.
+ *
+ * Returns `undefined` when the table has no version column, so a store's fast
+ * path is a single check and an app that does not use the feature pays nothing.
+ *
+ * `expected` is read from the PATCH rather than passed separately, because the
+ * alternative — a second argument on every store method — is a change every
+ * caller has to make and most would skip. Putting it in the patch means the
+ * caller who cares opts in at the one call site that cares.
+ */
+export declare const planVersionedUpdate: (input: {
+    readonly versionColumn: string | undefined;
+    readonly patch: Readonly<Record<string, unknown>>;
+}) => {
+    readonly nextVersion: number | undefined;
+    readonly expected: number | undefined;
+    readonly patch: Record<string, unknown>;
+};
+
 export declare type Predicate = PredicateLeaf | AndPredicate | OrPredicate | NotPredicate | SubqueryInPredicate | ExistsPredicate;
 
 export declare interface PredicateLeaf {
@@ -3824,6 +3953,10 @@ export declare interface QueryDescriptor<R = Row> {
      * (storeMiddleware read path + reactive-query finalize) honors.
      */
     readonly includeDeleted?: boolean;
+    /** Opt OUT of the `expires()` read filter — a deliberate read of expired
+     *  rows (an admin view, a grace-period check). Same shape and same posture as
+     *  `includeDeleted`. */
+    readonly includeExpired?: boolean;
     /**
      * Opt OUT of the runtime's automatic tenant scope on `tenant()` tables.
      * Set by `.unscoped()`. Honored by the runtime, same as `includeDeleted`.
@@ -4785,6 +4918,20 @@ export declare const setResidencyConfig: (config: ResidencyConfig) => ResidencyC
  */
 export declare const settleTransactionExit: <A>(exit: Exit.Exit<A, unknown>) => A;
 
+/**
+ * Decide the outcome of a versioned update from what the row actually held.
+ *
+ * Separated from the SQL so every store shares the DECISION and only the
+ * statement differs. `current` is the row's version before the write, or `null`
+ * when the row is gone.
+ */
+export declare const settleVersionedUpdate: (input: {
+    readonly table: string;
+    readonly id: string;
+    readonly expected: number | undefined;
+    readonly current: number | null;
+}) => VersionConflict | undefined;
+
 /**
  * PostGIS spatial-distance clause carried on a {@link QueryDescriptor}.
  * Drives a `ST_Distance` projected column (distance-as-a-value) and/or a
@@ -5898,6 +6045,34 @@ export declare interface VectorOptions {
     readonly precision?: 'float32' | 'half';
 }
 
+/** The column marked `.version()`, or `undefined` when a table has none. */
+export declare const versionColumnOf: (columns: Readonly<Record<string, {
+    readonly definition?: {
+        readonly versionColumn?: boolean;
+    };
+}>>) => string | undefined;
+
+/**
+ * A write lost the race.
+ *
+ * Carries both numbers because "someone else changed it" is not actionable and
+ * "you had 3, it is now 7" is: four intervening writes is a different situation
+ * from one, and a UI can say so.
+ */
+export declare class VersionConflict extends VersionConflict_base {
+}
+
+declare const VersionConflict_base: Schema.TaggedErrorClass<VersionConflict, "VersionConflict", {
+    readonly _tag: Schema.tag<"VersionConflict">;
+} & {
+    table: typeof Schema.String;
+    id: typeof Schema.String;
+    /** What the caller believed the row was at. */
+    expected: typeof Schema.Number;
+    /** What it is actually at. `null` when the row is gone entirely. */
+    actual: Schema.NullOr<typeof Schema.Number>;
+}>;
+
 /**
  * A read-only SQL view descriptor. Structurally a `TableLike` (carries
  * `tableName` + `fields`) so the query builder + row decoder + by-name
@@ -5945,6 +6120,9 @@ export declare const view: <const Name extends string, const Input extends Field
  */
 export declare const viewSql: (v: View<string, Record<string, ColumnDefinition<unknown>>>, dialect: DialectId, schema?: string | null) => string;
 
+/** Stable mixin id — the runtime keys read-filtering off it. */
+export declare const VOLTRO_EXPIRES_MIXIN_ID = "voltro/expires";
+
 /**
  * `_voltro_api_keys` — first-class API key management. Only the SHA-256 HASH
  * of a key is stored (`hashedKey`, unique); the raw token is shown once at