@voltro/database 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -424,6 +424,10 @@ export declare interface CdcConfig {
     readonly keepAliveInitialDelayMs?: number;
 }
 
+/** Maximum `onChange` listeners a DataStore's change bus accepts before Node
+ *  warns. See this file's header for why it is 512 and why it is not `0`. */
+export declare const CHANGE_LISTENER_CEILING = 512;
+
 /**
  * A row-change event emitted by the data store (in-memory) or the CDC
  * consumer (Postgres logical replication). Drives the reactive engine.
@@ -1452,7 +1456,10 @@ export declare interface DataStore {
      * mutation.
      */
     transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
-    /** Subscribe to row-change events. Returns an unsubscribe function. */
+    /** Subscribe to row-change events. Returns an unsubscribe function.
+     *
+     *  See `CHANGE_LISTENER_CEILING` for why an EventEmitter-backed
+     *  implementation must raise its listener limit before binding. */
     onChange(listener: (event: ChangeEvent) => void): () => void;
     /**
      * Inject a ChangeEvent that originated OUTSIDE this process — the
@@ -3800,6 +3807,16 @@ declare interface QueryWithDescriptorAny {
  */
 export declare const quoteIdent: (name: string, dialect: DialectId) => string;
 
+/** Raise a change bus's listener limit to `CHANGE_LISTENER_CEILING`.
+ *
+ *  Structurally typed rather than taking a `node:events` EventEmitter — this
+ *  package is browser-safe and must not import `node:*`. Every dialect store
+ *  calls this on the emitter it ends up using (its own or an injected shared
+ *  one) before any listener binds. */
+export declare const raiseChangeListenerCeiling: (bus: {
+    setMaxListeners: (n: number) => unknown;
+}) => void;
+
 export declare const rank: (alias?: string) => WindowBuilder;
 
 /**
@@ -4262,12 +4279,45 @@ export declare interface SeedStepResult {
     readonly rowsTouched?: number;
 }
 
+/**
+ * The store a seed step gets.
+ *
+ * **Reads are unscoped and include soft-deleted rows**, by construction rather
+ * than by flag: a seed runs at boot with no request and no subject, so there is
+ * no tenant to filter by and nothing applies the `deletedAt IS NULL` predicate.
+ * A restore therefore sees the whole table, which is what a restore needs — and
+ * why there is no `.unscoped()` / `.withDeleted()` to reach for here. If a seed
+ * wants only one tenant's rows, it says so in its own predicate.
+ */
 export declare interface SeedStore {
+    /** Full descriptor read — `order` / `take` / `skip` / `projection` are
+     *  accepted so a large restore can page and sort rather than pulling every
+     *  row of every table into memory. */
     query(descriptor: {
         table: string;
         predicate?: Predicate;
+        order?: ReadonlyArray<{
+            column: string;
+            direction: 'asc' | 'desc';
+        }>;
+        take?: number;
+        skip?: number;
+        projection?: ReadonlyArray<string>;
     }): Promise<ReadonlyArray<Record<string, unknown>>>;
     insert(table: string, row: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Insert, or do nothing when a row already conflicts on `conflictColumns`.
+     *
+     * The primitive an idempotent restore is actually built on: `upsertByUnique`
+     * costs a read per row and OVERWRITES what it finds, which is wrong when the
+     * live row is newer than the snapshot. This is one statement per row and
+     * leaves an existing row alone. Reported by a consumer restoring 1361 rows
+     * across 167 tables in multiple passes for FK order — with only
+     * `upsertByUnique` available, every pass re-read and re-wrote everything.
+     */
+    insertIgnore(table: string, row: Record<string, unknown>, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<Record<string, unknown>>;
     update(table: string, primaryKey: string, patch: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     delete(table: string, primaryKey: string): Promise<boolean>;
 }
@@ -4395,6 +4445,25 @@ export declare interface SqlDialect {
     readonly retryFilter: (error: unknown) => RetryDecision;
 }
 
+/**
+ * Fill `row.id` from the table's declared scheme when it is absent.
+ *
+ * Three behaviours worth stating, because each has bitten somewhere:
+ *
+ *   - an explicit id is NEVER overwritten (tests pin deterministic ids, and
+ *     signup self-stamps before a subject exists);
+ *   - a `numeric` scheme DELETES the key instead of generating, so the
+ *     dialect's SERIAL / AUTO_INCREMENT / IDENTITY fires and the store's
+ *     RETURNING path hands the assigned value back;
+ *   - an UNREGISTERED table is left alone. The row is passed through
+ *     untouched rather than guessed at — a table we do not know is one whose
+ *     id column we cannot reason about.
+ */
+export declare const stampGeneratedId: <T extends Record<string, unknown>>(table: string, row: T) => T;
+
+/** `stampGeneratedId` over a batch. */
+export declare const stampGeneratedIds: <T extends Record<string, unknown>>(table: string, rows: ReadonlyArray<T>) => ReadonlyArray<T>;
+
 /**
  * Stream every row of a table as a lazy `Stream<Row>`, keyset-paginated so
  * memory stays flat regardless of table size. Backpressure is inherent: a