@voltro/database 0.69.1 → 0.71.0

package/dist/{frameworkLiveTables-CWbTSnjk.js → frameworkLiveTables-D53uncZH.js}

@@ -800,11 +800,11 @@ var me = () => new s({
 }, qe = (e) => e === "sqlite" || e === "turso", Je = (e) => e === "mysql" || e === "mariadb", R = (e, t) => {
 	switch (t) {
 		case "mysql":
-		case "mariadb": return `\`${e}\``;
-		case "mssql": return `[${e}]`;
+		case "mariadb": return `\`${e.replace(/`/g, "``")}\``;
+		case "mssql": return `[${e.replace(/\]/g, "]]")}]`;
 		case "postgres":
 		case "sqlite":
-		case "turso": return `"${e}"`;
+		case "turso": return `"${e.replace(/"/g, "\"\"")}"`;
 	}
 }, Ye = 1e4, z = Symbol.for("@voltro/database/tableRegistry"), B = globalThis, V = B[z] ?? (B[z] = /* @__PURE__ */ new Map()), H = (e) => {
 	let t = V.get(e.tableName);

package/dist/index.d.ts

@@ -1825,6 +1825,9 @@ export declare const columnsPerRow: (rows: ReadonlyArray<Record<string, unknown>
 
 export declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
 
+/** Exact comparison of fixed-point decimal strings, without a floating-point conversion. */
+export declare const compareDecimal: (left: unknown, right: unknown) => number | null;
+
 /**
  * Try to compile a `QueryDescriptor` with `eager` populated into a
  * single-roundtrip JSON-agg query for the given dialect.
@@ -2392,12 +2395,28 @@ export declare interface DataStore {
     insertIgnore(table: string, row: Row, options: {
         conflictColumns: ReadonlyArray<string>;
     }): Promise<Row>;
+    /**
+     * `insertIgnore`, plus the one thing it cannot report: whether the row was
+     * INSERTED or already there.
+     *
+     * The store's actual insert decision supplies the outcome, including for
+     * caller-supplied and database-generated IDs. A pre-read or comparison of
+     * IDs cannot establish which concurrent caller inserted. Every raw store,
+     * namespace view and transaction view implements this method; wrappers
+     * preserve its outcome while encoding/decoding the row. Inside a transaction
+     * the result is provisional until commit. The typed helper is
+     * `insertIgnoreRowOutcome`.
+     */
+    insertIgnoreWithOutcome(table: string, row: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<InsertIgnoreResult>;
     /**
      * Run `work` inside a transaction. ALL `insert/update/delete` calls
      * made via `work`'s store reference (passed as argument) are:
      *
      *   - atomic — the dialect's native BEGIN/COMMIT/ROLLBACK wraps the
-     *     writes; the memory store serialises trivially.
+     *     writes; memory validates snapshot read/write-table revisions before
+     *     committing and retries conflicting attempts with a fresh snapshot.
      *   - delta-deferred — ChangeEvents queue inside the transaction and
      *     are emitted ONLY after a successful commit. A throw triggers
      *     rollback AND drops every queued event so no subscriber ever
@@ -2405,6 +2424,10 @@ export declare interface DataStore {
      *
      * Reads (`query()`) inside the transaction see the in-flight write
      * set (read-your-own-writes within the transaction).
+     * Transient contention can replay the whole callback (at most four attempts,
+     * exponential delay starting at 10 ms). Do not perform external side effects
+     * in the callback. Memory validation is table-granular and process-local;
+     * `forUpdate` does not acquire a blocking row lock there.
      *
      * `transactional()` MUST NOT be nested — nested invocations throw to
      * surface design mistakes (transactions are atomic units, not
@@ -3368,7 +3391,7 @@ declare type EmptyMerge = unknown;
 export declare const encodeFieldValue: (cipher: FieldCipher, value: unknown, binding?: FieldBinding) => string;
 
 /**
- * Serialize a row's json()/array() cells to JSON strings so they can be
+ * Serialize selected json()/array()/vector() cells to JSON strings so they can be
  * bound as scalar SQL parameters. Symmetric to `decodeRowsFromSchema`.
  * No-op for tables with no json/array columns (cost: one map build +
  * a per-cell type lookup). Unknown tables pass through unchanged.
@@ -3438,7 +3461,9 @@ export declare const eq: <RowOf = Record<string, unknown>, K extends keyof RowOf
  *  explicit `ESCAPE '\'` clause at the call site. */
 export declare const escapeLike: (value: string) => string;
 
-export declare const evaluatePredicate: (predicate: Predicate, row: Row | null, subqueries?: SubqueryResults | null) => boolean;
+export declare const evaluatePredicate: (predicate: Predicate, row: Row | null, subqueries?: SubqueryResults | null, columns?: Readonly<Record<string, {
+    readonly type: string;
+}>>) => boolean;
 
 /** `EXCEPT` — rows in the FIRST input not present in any subsequent input. */
 export declare const except: (...queries: ReadonlyArray<QueryWithDescriptorAny>) => Query<Row, string>;
@@ -3726,7 +3751,7 @@ export declare const formatSubjectGraph: (graph: SubjectGraph) => string;
  */
 export declare const FRAMEWORK_LIVE_TABLES: ReadonlySet<string>;
 
-export declare const frameworkTables: readonly [TableLike, TableLike, TableLike];
+export declare const frameworkTables: readonly [SchemaTable, SchemaTable, SchemaTable];
 
 declare type FullTextIndexMeta = {
     readonly name: string;
@@ -4003,14 +4028,14 @@ export declare interface IndexKindOptions {
          *   - `'inner'`  → `vector_ip_ops` (negative inner product)
          * The opclass MUST match the metric the query orders by, or the
          * index can't accelerate the search. Set `opclass` directly only to
-         * override the mapping (e.g. `halfvec_cosine_ops`).
+         * override the mapping. Half-precision columns select `halfvec_*` automatically.
          */
         readonly distance?: VectorDistance;
         /**
          * pgvector opclass token spliced into `USING hnsw (col <opclass>)`.
-         * When unset, derived from `distance` (default `vector_cosine_ops`).
-         * Set explicitly to override (e.g. `'halfvec_cosine_ops'` for a
-         * `vector(n, { precision: 'half' })` column).
+         * When unset, derived from `distance` and the column's precision
+         * (default `vector_cosine_ops`, or `halfvec_cosine_ops` for half precision).
+         * An explicit override is an unquoted, optionally schema-qualified identifier.
          */
         readonly opclass?: string;
     };
@@ -4071,6 +4096,36 @@ export declare type InferViewRow<V> = V extends View<string, infer F> ? InferRow
  */
 export declare const INITIAL_VERSION = 1;
 
+/** What an `insertIgnoreWithOutcome` did, beside the row it hands back. */
+export declare interface InsertIgnoreResult {
+    readonly row: Row;
+    /** `'ignored'` means a row already existed for the conflict key; it is the
+     *  row returned, untouched. */
+    readonly outcome: 'inserted' | 'ignored';
+}
+
+/**
+ * `insertIgnore`, plus whether the row was INSERTED or was already there.
+ *
+ * `insertIgnore` returns the existing row on the ignore path, and that row is
+ * indistinguishable from one it just wrote. The native store's insert
+ * decision supplies the outcome; wrappers preserve it without a pre-read.
+ *
+ *     const { row, outcome } = await insertIgnoreRowOutcome(ctx.store, actors, actor, {
+ *       conflictColumns: ['id'],
+ *     })
+ *     if (outcome === 'inserted') planted++
+ *
+ * Caller-supplied and database-assigned IDs obey the same contract. Inside
+ * a transaction the decision becomes durable only when that transaction commits.
+ */
+export declare const insertIgnoreRowOutcome: <T extends AnyTable>(store: TypedInsertIgnoreOutcomeStore, table: T, row: InferInsertRow<T>, options: {
+    readonly conflictColumns: ReadonlyArray<keyof InferRow<T> & string>;
+}) => Promise<{
+    readonly row: InferRow<T>;
+    readonly outcome: "inserted" | "ignored";
+}>;
+
 /**
  * Insert MANY rows, typed against the table — `insertRow`'s batch, and nothing
  * else: it forwards to `store.insertMany` unchanged, so the chunking, the
@@ -6011,9 +6066,8 @@ declare interface QueryWithDescriptorAny {
  *                         in ANSI_QUOTES mode)
  *   - mssql:              `[name]` (T-SQL bracketed identifier)
  *
- * Identifier names in the schema DSL are restricted to
- * `[a-zA-Z][a-zA-Z0-9_]*`, so the inner quote character never needs
- * escaping — but the dialect MUST match the engine to avoid syntax errors.
+ * Catalog-derived identifiers can contain quote characters even when the
+ * schema DSL restricts its own names. Escape them at this shared boundary.
  */
 export declare const quoteIdent: (name: string, dialect: DialectId) => string;
 
@@ -8144,6 +8198,9 @@ export declare interface TransactionalViewHandle {
  */
 export declare type TransactionConnectionContext = Context.Tag.Service<typeof TransactionConnection>;
 
+/** Shared bounded contention policy, including stores without a SQL connection. */
+export declare const transactionRetrySchedule: (isRetryable: (error: unknown) => boolean) => Schedule.Schedule<number, unknown, never>;
+
 /** Turso's MVCC conflicts arrive as messages, not codes. */
 export declare const TURSO_TRANSIENT_MESSAGE: RegExp;
 
@@ -8167,6 +8224,16 @@ export declare interface TxnRecorderPort {
     readonly maxOf: TxnMaxOf;
 }
 
+/** The minimal store surface `insertIgnoreRowOutcome` needs. */
+export declare interface TypedInsertIgnoreOutcomeStore {
+    readonly insertIgnoreWithOutcome: (table: string, row: Row, options: {
+        readonly conflictColumns: ReadonlyArray<string>;
+    }) => Promise<{
+        readonly row: Row;
+        readonly outcome: 'inserted' | 'ignored';
+    }>;
+}
+
 /** The minimal store surface `insertManyRows` needs. */
 export declare interface TypedInsertManyStore {
     readonly insertMany: (table: string, rows: ReadonlyArray<Row>) => Promise<ReadonlyArray<Row>>;
@@ -8598,7 +8665,7 @@ export declare const VOLTRO_LOCAL_FIRST_MIXIN_ID: "voltro/localFirst";
  * app (empty unless `apiKeys` is enabled in app.config). See
  * `@voltro/runtime`'s `ApiKeyService`.
  */
-export declare const _voltroApiKeysTable: TableLike;
+export declare const _voltroApiKeysTable: SchemaTable;
 
 export declare const _voltroCdcOffsetsTable: TableLike;
 
@@ -8632,7 +8699,7 @@ export declare const _voltroDataTransfersTable: TableLike;
  * a record dropped while still inside that window lets the duplicate request it
  * exists to stop execute a second time.
  */
-export declare const _voltroIdempotencyTable: TableLike;
+export declare const _voltroIdempotencyTable: SchemaTable;
 
 /**
  * `_voltro_kv` — the durable key-value store behind `ctx.kv` / the `Kv`
@@ -8643,7 +8710,7 @@ export declare const _voltroIdempotencyTable: TableLike;
  * evicted for capacity — they live until deleted or their TTL lapses. Created
  * for every sql app (empty unless `ctx.kv` is used).
  */
-export declare const _voltroKvTable: TableLike;
+export declare const _voltroKvTable: SchemaTable;
 
 /**
  * `_voltro_migration_plans` — one row per declarative-diff plan
@@ -8661,7 +8728,7 @@ export declare const _voltroKvTable: TableLike;
  * the escape-hatch for split/merge/data-move migrations the diff can't
  * infer.
  */
-export declare const _voltroMigrationPlansTable: TableLike;
+export declare const _voltroMigrationPlansTable: SchemaTable;
 
 /**
  * `_voltro_migrations` — one row per migration file. Created by the
@@ -8669,7 +8736,7 @@ export declare const _voltroMigrationPlansTable: TableLike;
  * as each migration's lifecycle progresses (pending → running → applied
  * | failed | reverted).
  */
-export declare const _voltroMigrationsTable: TableLike;
+export declare const _voltroMigrationsTable: SchemaTable;
 
 export declare const _voltroMssqlCdcOffsetsTable: TableLike;
 
@@ -8718,7 +8785,7 @@ export declare const _voltroReplaceInProgressTable: TableLike;
  * writing a full subscription list here every heartbeat would be write
  * amplification for state nobody is reading.
  */
-export declare const _voltroReplicaObservationsTable: TableLike;
+export declare const _voltroReplicaObservationsTable: SchemaTable;
 
 /**
  * `_voltro_seeds` — one row per registered seed. Written to by the
@@ -8726,7 +8793,7 @@ export declare const _voltroReplicaObservationsTable: TableLike;
  * seeds re-run when the fingerprint changes; the `lastRun*` fields
  * capture the most recent execution (history lives in the audit log).
  */
-export declare const _voltroSeedsTable: TableLike;
+export declare const _voltroSeedsTable: SchemaTable;
 
 export declare const walkLeaves: (predicate: Predicate, conjunctive?: boolean) => Generator<PredicateLeafWithContext>;