@voltro/database 0.24.0 → 0.25.0

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'`,
@@ -2215,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;
@@ -2664,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.
@@ -3373,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 {
@@ -3849,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`.
@@ -4810,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
@@ -5923,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
@@ -5970,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