@minnowdb/core 0.7.5 → 0.7.8

package/dist/engine/batch.d.ts

@@ -31,5 +31,18 @@ export interface ColumnarBatch {
 }
 /** What `insertBatch` and `upsertBatch` take: rows, or columns for a bulk load. */
 export type InsertBatchInput = readonly BatchRow[] | ColumnarBatch;
+/**
+ * `ColumnarBatch` as the schema-typed overloads hand it to the erased implementation: a column
+ * vector or omission mask may be `undefined`, meaning that column is not in the batch. Only the
+ * type is looser — `toColumnarBatch` drops such entries, so nothing downstream sees them.
+ */
+export interface ColumnarBatchLike {
+    readonly columns: Readonly<Record<string, readonly BatchValue[] | undefined>>;
+    readonly omitted?: Readonly<Record<string, readonly boolean[] | undefined>>;
+    readonly rowCount?: number;
+}
+export type InsertBatchInputLike = readonly BatchRow[] | ColumnarBatchLike;
+/** The entries of a per-column record whose vector is present. */
+export declare function definedVectors<T>(vectors: Readonly<Record<string, T | undefined>>): Record<string, T>;
 /** Pivots rows into the engine's columnar form; a columnar batch passes straight through. */
-export declare function toColumnarBatch(input: InsertBatchInput): ColumnarBatch;
+export declare function toColumnarBatch(input: InsertBatchInputLike): ColumnarBatch;

package/dist/engine/batch.js

@@ -1,9 +1,29 @@
+function definedVectors(vectors) {
+  const defined = {};
+  for (const [name, vector] of Object.entries(vectors)) {
+    if (vector !== void 0)
+      defined[name] = vector;
+  }
+  return defined;
+}
+function hasUndefinedVector(vectors) {
+  return Object.values(vectors).includes(void 0);
+}
 function isColumnarBatch(input) {
   return !Array.isArray(input);
 }
 function toColumnarBatch(input) {
-  if (isColumnarBatch(input))
-    return input;
+  if (isColumnarBatch(input)) {
+    const columnsComplete = !hasUndefinedVector(input.columns);
+    const omittedComplete = input.omitted === void 0 || !hasUndefinedVector(input.omitted);
+    if (columnsComplete && omittedComplete)
+      return input;
+    return {
+      columns: definedVectors(input.columns),
+      ...input.omitted === void 0 ? {} : { omitted: definedVectors(input.omitted) },
+      ...input.rowCount === void 0 ? {} : { rowCount: input.rowCount }
+    };
+  }
   if (input.length === 0)
     throw new TypeError("A batch needs at least one row");
   const columnsByName = /* @__PURE__ */ new Map();
@@ -36,5 +56,6 @@ function toColumnarBatch(input) {
   };
 }
 export {
+  definedVectors,
   toColumnarBatch
 };

package/dist/engine/buffered-writer.d.ts

@@ -1,4 +1,4 @@
-import type { BatchValue } from "./batch.js";
+import type { BatchRow } from "./batch.js";
 import type { InsertBatchResult, MinnowDatabase, UpsertBatchResult } from "./database.js";
 export interface BufferedWriterOptions {
     mode?: "insert" | "upsert";
@@ -26,15 +26,18 @@ export interface LifecycleFlushOptions {
 }
 /** Maximum accepted `add()` calls that have not completed. Callers must await for backpressure. */
 export declare const MAX_BUFFERED_WRITER_PENDING_ADDS = 64;
-/** Batches row-oriented writes by row count, estimated bytes, or age. */
-export declare class BufferedTableWriter {
+/**
+ * Batches row-oriented writes by row count, estimated bytes, or age. `TRow` is the declared
+ * table's insert row when the database that opened the writer carries a schema.
+ */
+export declare class BufferedTableWriter<TRow extends BatchRow = BatchRow> {
     #private;
     private readonly database;
     private readonly tableName;
     constructor(database: MinnowDatabase, tableName: string, options?: BufferedWriterOptions);
     get pendingRowCount(): number;
     get estimatedBytes(): number;
-    add(row: Readonly<Record<string, BatchValue>>): Promise<BufferedFlushResult | undefined>;
+    add(row: TRow): Promise<BufferedFlushResult | undefined>;
     flush(): Promise<BufferedFlushResult | undefined>;
     requestFlush(): void;
     close(): Promise<BufferedFlushResult | undefined>;

package/dist/engine/client.d.ts

@@ -1,10 +1,10 @@
 import { type CompactionJobRecord, type GarbageCollectionJobRecord, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult } from "../storage/types.js";
-import { type BatchRow, type InsertBatchInput } from "./batch.js";
+import { type BatchRow } from "./batch.js";
 import type { Catalog } from "./catalog.js";
-import type { BatchValue, BufferPoolStats, StagedWriteResult, BufferedFlushResult, BufferedWriterOptions, CancelCompactionJobResult, CollectGarbageOptions, CollectGarbageStepOptions, CompactTableOptions, CompactTableResult, CompactTableStepOptions, CompactionJobProgress, CreateTableInput, DatabaseRow, MigrateOptions, DeleteBatchInput, DeleteBatchResult, ExecuteOptions, ExecuteResult, GarbageCollectionProgress, GarbageCollectionResult, MaintenanceStatus, InsertBatchResult, QueryOptions, QueryExecutionStats, QueryCursorOptions, QuerySpillCleanupOptions, QuerySpillCleanupResult, ReadTableOptions, RunStatementOptions, SnapshotExportOptions, SnapshotImportOptions, TableDefinition, UpdateBatchInput, UpdateBatchResult, UpsertBatchResult, UpsertOptions, VisibleSegmentPage, VisibleSegmentPageOptions } from "./database.js";
+import type { BufferPoolStats, StagedWriteResult, StagedUpsertResult, BufferedFlushResult, BufferedWriterOptions, CancelCompactionJobResult, CollectGarbageOptions, CollectGarbageStepOptions, CompactTableOptions, CompactTableResult, CompactTableStepOptions, CompactionJobProgress, CreateTableInput, MigrateOptions, DeleteBatchResult, ExecuteOptions, ExecuteResult, GarbageCollectionProgress, GarbageCollectionResult, MaintenanceStatus, InsertBatchResult, QueryOptions, QueryExecutionStats, QueryCursorOptions, QuerySpillCleanupOptions, QuerySpillCleanupResult, RunStatementOptions, SnapshotExportOptions, SnapshotImportOptions, TableDefinition, UpdateBatchResult, UpsertBatchResult, VisibleSegmentPage, VisibleSegmentPageOptions } from "./database.js";
 import type { LiveQueryInput, LiveQueryInvalidation, LiveQueryObserveOptions, LiveQueryStats, LiveQuerySubscribeOptions } from "./live.js";
 import type { CompiledQuery, CompiledStatement, QueryResult, QueryValue } from "./query.js";
-import type { AnyTable, SchemaDefinition } from "./schema.js";
+import type { AnySchema, UntypedSchema, AnyTable, BatchColumnName, BatchDeleteInput, BatchInsertInput, BatchInsertRow, BatchKeyValue, BatchReadOptions, BatchReadRow, BatchUpdateChanges, BatchUpdateInput, BatchUpsertOptions, SchemaDefinition, TableName } from "./schema.js";
 import { type WireMigrationStep } from "./schema-wire.js";
 import type { StoreDescriptor, WireDatabaseOptions } from "./worker-host.js";
 /**
@@ -31,7 +31,13 @@ export interface ClientTransport {
     removeEventListener?(type: "error" | "messageerror", listener: () => void): void;
     terminate?(): void;
 }
-export interface MinnowDatabaseClientOptions {
+export interface MinnowDatabaseClientOptions<TSchema extends AnySchema = UntypedSchema> {
+    /**
+     * The schema this database is declared against. It types every batch method by table name and
+     * is what a bare `migrate()` applies. It stays on the main thread: the worker learns the
+     * schema from `migrate()`, not from construction.
+     */
+    schema?: TSchema;
     /**
      * Defaults to `{ kind: "indexeddb", name: "minnow" }`. The `opfs` kind selects
      * `OpfsBlockStore`, which needs the worker to be a dedicated worker (it always is with
@@ -71,9 +77,9 @@ interface RpcCallControls {
     signal?: AbortSignal | undefined;
     onStats?: ((stats: QueryExecutionStats) => void) | undefined;
 }
-export declare class MinnowDatabaseClient {
+export declare class MinnowDatabaseClient<TSchema extends AnySchema = UntypedSchema> {
     #private;
-    constructor(transport: ClientTransport, options?: MinnowDatabaseClientOptions);
+    constructor(transport: ClientTransport, options?: MinnowDatabaseClientOptions<TSchema>);
     /** Resolves once the worker has opened the store and constructed the database. */
     ready(): Promise<void>;
     createTable(input: CreateTableInput): Promise<void>;
@@ -103,17 +109,28 @@ export declare class MinnowDatabaseClient {
     /** The published catalog; see `MinnowDatabase.introspect()`. */
     introspect(): Promise<Catalog>;
     listTables(): Promise<TableDefinition[]>;
-    migrate(definition: SchemaDefinition<readonly AnyTable[]>, options?: MigrateOptions): Promise<ClientMigrationResult>;
-    insertBatch(tableName: string, input: InsertBatchInput): Promise<InsertBatchResult>;
-    insert(tableName: string, row: BatchRow): Promise<InsertBatchResult>;
-    upsertBatch(tableName: string, input: InsertBatchInput, options?: UpsertOptions): Promise<UpsertBatchResult>;
-    upsert(tableName: string, row: BatchRow, options?: UpsertOptions): Promise<UpsertBatchResult>;
-    updateBatch(tableName: string, input: UpdateBatchInput): Promise<UpdateBatchResult>;
-    update(tableName: string, key: Exclude<BatchValue, null>, changes: Readonly<Record<string, BatchValue>>): Promise<UpdateBatchResult>;
-    deleteBatch(tableName: string, input: DeleteBatchInput): Promise<DeleteBatchResult>;
-    delete(tableName: string, key: Exclude<BatchValue, null>): Promise<DeleteBatchResult>;
-    bufferedWriter(tableName: string, options?: BufferedWriterOptions): ClientBufferedWriter;
-    readTable(tableName: string, versionOrOptions?: number | ReadTableOptions): Promise<DatabaseRow[]>;
+    /**
+     * Brings storage in line with a schema declaration. With no argument it applies the schema the
+     * client was constructed with.
+     */
+    migrate(definition?: SchemaDefinition<readonly AnyTable[]> | undefined, options?: MigrateOptions): Promise<ClientMigrationResult>;
+    insertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>): Promise<InsertBatchResult>;
+    insert<TName extends TableName<TSchema>>(tableName: TName, row: BatchInsertRow<TSchema, TName>): Promise<InsertBatchResult>;
+    upsertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>, options?: BatchUpsertOptions<TSchema, TName>): Promise<UpsertBatchResult>;
+    upsert<TName extends TableName<TSchema>>(tableName: TName, row: BatchInsertRow<TSchema, TName>, options?: BatchUpsertOptions<TSchema, TName>): Promise<UpsertBatchResult>;
+    updateBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchUpdateInput<TSchema, TName>): Promise<UpdateBatchResult>;
+    /**
+     * Changes one row by the table's unique key. An explicitly `undefined` change leaves that
+     * column untouched, so a patch spread from optional fields needs no filtering first.
+     */
+    update<TName extends TableName<TSchema>>(tableName: TName, key: BatchKeyValue<TSchema, TName>, changes: BatchUpdateChanges<TSchema, TName>): Promise<UpdateBatchResult>;
+    deleteBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchDeleteInput<TSchema, TName>): Promise<DeleteBatchResult>;
+    delete<TName extends TableName<TSchema>>(tableName: TName, key: BatchKeyValue<TSchema, TName>): Promise<DeleteBatchResult>;
+    bufferedWriter<TName extends TableName<TSchema>>(tableName: TName, options?: BufferedWriterOptions): ClientBufferedWriter<BatchInsertRow<TSchema, TName>>;
+    readTable<TName extends TableName<TSchema>, const TColumns extends ReadonlyArray<BatchColumnName<TSchema, TName>>>(tableName: TName, options: BatchReadOptions<TSchema, TName, TColumns> & {
+        readonly columns: TColumns;
+    }): Promise<Array<Pick<BatchReadRow<TSchema, TName>, TColumns[number]>>>;
+    readTable<TName extends TableName<TSchema>>(tableName: TName, versionOrOptions?: number | BatchReadOptions<TSchema, TName>): Promise<Array<BatchReadRow<TSchema, TName>>>;
     /**
      * Results cross the channel as one array per column (typed arrays for numbers, booleans, and
      * datetimes) and are rebuilt into row objects here; see `result-wire.ts`.
@@ -142,7 +159,7 @@ export declare class MinnowDatabaseClient {
      * transaction and publishes as one atomic commit when the callback returns; an error
      * aborts the scope with nothing published.
      */
-    write<T>(action: (session: ClientWriteSession) => Promise<T>): Promise<{
+    write<T>(action: (session: ClientWriteSession<TSchema>) => Promise<T>): Promise<{
         result: T;
         version: number | null;
     }>;
@@ -205,14 +222,14 @@ export declare class MinnowDatabaseClient {
  * consistent with each other for the lifetime of the callback.
  */
 /** The scope handed to the client `write()`; mirrors the in-worker WriteSession. */
-export interface ClientWriteSession {
+export interface ClientWriteSession<TSchema extends AnySchema = UntypedSchema> {
     /** Read-your-writes: observes the pre-scope snapshot plus everything staged so far. */
     query(sql: string, options?: QueryOptions): Promise<QueryResult>;
     execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
-    insertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
-    upsertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
-    updateBatch(tableName: string, input: UpdateBatchInput): Promise<StagedWriteResult>;
-    deleteBatch(tableName: string, input: DeleteBatchInput): Promise<StagedWriteResult>;
+    insertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>): Promise<StagedWriteResult>;
+    upsertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>, options?: BatchUpsertOptions<TSchema, TName>): Promise<StagedUpsertResult>;
+    updateBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchUpdateInput<TSchema, TName>): Promise<StagedWriteResult>;
+    deleteBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchDeleteInput<TSchema, TName>): Promise<StagedWriteResult>;
 }
 export interface ClientSnapshotSession {
     /** The pinned manifest version; null only on a database with no commits yet. */
@@ -223,12 +240,12 @@ export interface ClientSnapshotSession {
  * Proxy of a worker-side BufferedTableWriter. The age timer runs on the worker's clock, and
  * onError fires for background flush failures exactly as in-worker — delivered as an event.
  */
-export declare class ClientBufferedWriter {
+export declare class ClientBufferedWriter<TRow extends BatchRow = BatchRow> {
     #private;
     private readonly client;
     private readonly handleId;
     constructor(client: MinnowDatabaseClient, handleId: string, created: Promise<unknown>);
-    add(row: Readonly<Record<string, BatchValue>>): Promise<BufferedFlushResult | undefined>;
+    add(row: TRow): Promise<BufferedFlushResult | undefined>;
     flush(): Promise<BufferedFlushResult | undefined>;
     /** Fire-and-forget: flush failures surface through onError, matching the in-worker contract. */
     requestFlush(): void;

package/dist/engine/client.js

@@ -1,7 +1,7 @@
 import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, PostingBuildConflictError, SnapshotManifestMissingError, SnapshotImportConflictError, SchemaConflictError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, StorageCorruptionError, StorageFormatVersionError, OpfsUncertainOutcomeError } from "../storage/types.js";
 import { MAX_SNAPSHOT_STREAM_CHUNK_BYTES } from "../storage/snapshot.js";
 import { parseRpcResponse, MAX_DATABASE_RPC_IN_FLIGHT, protocolVersion } from "../worker-protocol/index.js";
-import { toColumnarBatch } from "./batch.js";
+import { definedVectors, toColumnarBatch } from "./batch.js";
 import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, DatabaseReadBacklogError, LiveQueryLimitError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
 import { QueryMemoryBudgetError } from "./memory.js";
 import { decodeQueryResult } from "./result-wire.js";
@@ -92,6 +92,10 @@ function rehydrateResponseError(payload) {
   return rehydrateError(candidate);
 }
 class MinnowDatabaseClient {
+  #schema;
+  get #erased() {
+    return this;
+  }
   #transport;
   #pending = /* @__PURE__ */ new Map();
   #events = /* @__PURE__ */ new Map();
@@ -109,6 +113,7 @@ class MinnowDatabaseClient {
     this.#fail(new Error("A database worker message could not be deserialized"));
   };
   constructor(transport, options = {}) {
+    this.#schema = options.schema;
     this.#transport = transport;
     transport.addEventListener("message", this.#onMessage);
     transport.addEventListener("error", this.#onError);
@@ -165,7 +170,10 @@ class MinnowDatabaseClient {
   async listTables() {
     return await this.#call("listTables", []);
   }
-  async migrate(definition, options = {}) {
+  async migrate(definition = this.#schema, options = {}) {
+    if (definition === void 0) {
+      throw new TypeError("migrate() needs a schema: pass a definition, or construct the client with { schema }");
+    }
     return await this.#call("migrate", [
       serializeSchema(definition),
       options
@@ -186,10 +194,12 @@ class MinnowDatabaseClient {
     return await this.#call("upsert", [tableName, row, options]);
   }
   async updateBatch(tableName, input) {
-    return await this.#call("updateBatch", [tableName, input]);
+    const wire = { keys: input.keys, changes: definedVectors(input.changes) };
+    return await this.#call("updateBatch", [tableName, wire]);
   }
   async update(tableName, key, changes) {
-    return await this.#call("update", [tableName, key, changes]);
+    const present = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== void 0));
+    return await this.#call("update", [tableName, key, present]);
   }
   async deleteBatch(tableName, input) {
     return await this.#call("deleteBatch", [tableName, input]);
@@ -204,7 +214,7 @@ class MinnowDatabaseClient {
       ...onError === void 0 ? {} : { onError }
     });
     const created = this.#call("bufferedWriter", [handleId, tableName, wireOptions]);
-    return new ClientBufferedWriter(this, handleId, created);
+    return new ClientBufferedWriter(this.#erased, handleId, created);
   }
   async readTable(tableName, versionOrOptions) {
     return decodeQueryResult(await this.#call("readTable", versionOrOptions === void 0 ? [tableName] : [tableName, versionOrOptions])).rows;
@@ -290,7 +300,12 @@ class MinnowDatabaseClient {
   }
   async write(action) {
     const opened = await this.#call("writeOpen", []);
-    const stage = (op, tableName, input) => this._invoke(opened.handleId, "stage", [op, tableName, input]);
+    const stage = (op, tableName, input, options) => this._invoke(opened.handleId, "stage", [
+      op,
+      tableName,
+      input,
+      options
+    ]);
     const session = {
       query: async (sql, options = {}) => {
         const { signal, onStats, ...wireOptions } = options;
@@ -298,7 +313,7 @@ class MinnowDatabaseClient {
       },
       execute: (sql, params) => this._invoke(opened.handleId, "execute", params === void 0 ? [sql] : [sql, params]),
       insertBatch: (tableName, input) => stage("insertBatch", tableName, input),
-      upsertBatch: (tableName, input) => stage("upsertBatch", tableName, input),
+      upsertBatch: (tableName, input, options) => stage("upsertBatch", tableName, input, options),
       updateBatch: (tableName, input) => stage("updateBatch", tableName, input),
       deleteBatch: (tableName, input) => stage("deleteBatch", tableName, input)
     };
@@ -419,7 +434,7 @@ class MinnowDatabaseClient {
   liveQueries(options = {}) {
     const handleId = crypto.randomUUID();
     const created = this.#call("liveQueries", [handleId, options]);
-    return new ClientLiveQuerySet(this, handleId, created);
+    return new ClientLiveQuerySet(this.#erased, handleId, created);
   }
   async listVisibleSegmentPage(tableName, options) {
     return await this.#call("listVisibleSegmentPage", options === void 0 ? [tableName] : [tableName, options]);

package/dist/engine/database.d.ts

@@ -1,4 +1,4 @@
-import { type BatchRow, type BatchValue, type InsertBatchInput } from "./batch.js";
+import { type BatchValue } from "./batch.js";
 import { BufferedTableWriter, type BufferedWriterOptions } from "./buffered-writer.js";
 export { attachLifecycleFlush, BufferedTableWriter, MAX_BUFFERED_WRITER_PENDING_ADDS, type BufferedFlushResult, type BufferedWriterOptions, type LifecycleDocumentTarget, type LifecycleFlushOptions, type LifecycleFlushRequester, type LifecyclePageTarget, } from "./buffered-writer.js";
 import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
@@ -9,7 +9,7 @@ import type { SnapshotExportProgress, SnapshotLoadProgress } from "../storage/sn
 import { type ComparisonOperator, type CompiledQuery, type CompiledStatement, type ForeignKeyDefinition, type QueryResult, type QueryRow, type QueryValue, type UniqueConstraintDefinition } from "./query.js";
 import { LiveQuerySet, type LiveQuerySetOptions } from "./live.js";
 import { type Catalog } from "./catalog.js";
-import { type AnyTable, type MigrationStep, type SchemaDefinition } from "./schema.js";
+import { type AnySchema, type UntypedSchema, type AnyTable, type BatchColumnName, type BatchDeleteInput, type BatchInsertInput, type BatchInsertRow, type BatchKeyValue, type BatchReadOptions, type BatchReadRow, type BatchUpdateChanges, type BatchUpdateInput, type BatchUpsertOptions, type MigrationStep, type SchemaDefinition, type TableName } from "./schema.js";
 /** Nested SQL savepoints and their total cloned transaction state are both hard bounded. */
 export declare const MAX_TRANSACTION_SAVEPOINTS = 64;
 export declare const MAX_TRANSACTION_SAVEPOINT_BYTES: number;
@@ -95,6 +95,7 @@ export interface UpsertBatchResult extends Omit<InsertBatchResult, "segmentId">
     requestedRowCount: number;
     insertedRowCount: number;
     updatedRowCount: number;
+    /** Input rows rejected by `conflictWhere`; always 0 without it. */
     skippedRowCount: number;
 }
 export interface UpsertConflictWhere {
@@ -174,6 +175,10 @@ export interface StagedWriteResult {
     /** Values filled by defaults or auto-increment while the rows were staged. */
     generatedColumns?: Record<string, QueryValue[]>;
 }
+export interface StagedUpsertResult extends StagedWriteResult {
+    /** Input rows rejected by `conflictWhere`; always 0 without it. */
+    skippedRowCount: number;
+}
 /**
  * The scope handed to `write()`: every mutation stages into one transaction and publishes
  * as one commit — all of it or none of it, in every tab. Reads observe the pre-scope snapshot
@@ -185,7 +190,7 @@ export interface StagedWriteResult {
  * caught the original error. A mutation that fails validation before registering anything
  * leaves the scope usable.
  */
-export interface WriteSession {
+export interface WriteSession<TSchema extends AnySchema = UntypedSchema> {
     /**
      * Read-your-writes: the query observes the pre-scope snapshot PLUS everything this scope
      * has staged so far, ordered after all committed data — without publishing anything.
@@ -193,10 +198,10 @@ export interface WriteSession {
     query(sql: string, options?: QueryOptions): Promise<QueryResult>;
     /** Runs a SELECT, INSERT, UPDATE, or DELETE inside this write scope. */
     execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
-    insertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
-    upsertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
-    updateBatch(tableName: string, input: UpdateBatchInput): Promise<StagedWriteResult>;
-    deleteBatch(tableName: string, input: DeleteBatchInput): Promise<StagedWriteResult>;
+    insertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>): Promise<StagedWriteResult>;
+    upsertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>, options?: BatchUpsertOptions<TSchema, TName>): Promise<StagedUpsertResult>;
+    updateBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchUpdateInput<TSchema, TName>): Promise<StagedWriteResult>;
+    deleteBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchDeleteInput<TSchema, TName>): Promise<StagedWriteResult>;
 }
 /** What one statement's execution cost, reported by the engine that ran it. */
 export interface QueryExecutionStats {
@@ -440,7 +445,13 @@ export interface TableDefinition {
 }
 export type DatabaseRow = Record<string, Exclude<BatchValue, null> | null>;
 export { CompactionBacklogError, CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, TableInUseError, UniqueConstraintError, VisibleSegmentCursorStaleError, };
-export interface MinnowDatabaseOptions {
+export interface MinnowDatabaseOptions<TSchema extends AnySchema = UntypedSchema> {
+    /**
+     * The schema this database is declared against. It types every batch method by table name —
+     * rows, keys, update changes, `conflictWhere`, `readTable` results — and is what a bare
+     * `migrate()` applies. Without it the batch API addresses tables by plain string, as SQL does.
+     */
+    schema?: TSchema;
     /**
      * Block codec for newly written blocks; defaults to "gzip", which is also what compaction
      * rewrites to, so a table's blocks are encoded the same way however they got there.
@@ -699,10 +710,10 @@ export interface SnapshotImportOptions {
     /** Cancels transfer and atomically removes this caller's staged import. */
     signal?: AbortSignal;
 }
-export declare class MinnowDatabase {
+export declare class MinnowDatabase<TSchema extends AnySchema = UntypedSchema> {
     #private;
     private readonly store;
-    constructor(store: BlockStore, options?: MinnowDatabaseOptions);
+    constructor(store: BlockStore, options?: MinnowDatabaseOptions<TSchema>);
     /**
      * Stops timers and background scheduling, rolls back an abandoned statement transaction,
      * closes live-query resources, releases the engine's reader lease, and drops resident caches.
@@ -754,17 +765,24 @@ export declare class MinnowDatabase {
     dropTable(tableName: string, options?: {
         ifExists?: boolean;
     }): Promise<boolean>;
-    insertBatch(tableName: string, input: InsertBatchInput): Promise<InsertBatchResult>;
-    insert(tableName: string, row: BatchRow): Promise<InsertBatchResult>;
-    upsertBatch(tableName: string, input: InsertBatchInput, options?: UpsertOptions): Promise<UpsertBatchResult>;
-    upsert(tableName: string, row: BatchRow, options?: UpsertOptions): Promise<UpsertBatchResult>;
-    updateBatch(tableName: string, input: UpdateBatchInput): Promise<UpdateBatchResult>;
-    update(tableName: string, key: Exclude<BatchValue, null>, changes: Readonly<Record<string, BatchValue>>): Promise<UpdateBatchResult>;
+    insertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>): Promise<InsertBatchResult>;
+    insert<TName extends TableName<TSchema>>(tableName: TName, row: BatchInsertRow<TSchema, TName>): Promise<InsertBatchResult>;
+    upsertBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchInsertInput<TSchema, TName>, options?: BatchUpsertOptions<TSchema, TName>): Promise<UpsertBatchResult>;
+    upsert<TName extends TableName<TSchema>>(tableName: TName, row: BatchInsertRow<TSchema, TName>, options?: BatchUpsertOptions<TSchema, TName>): Promise<UpsertBatchResult>;
+    updateBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchUpdateInput<TSchema, TName>): Promise<UpdateBatchResult>;
+    /**
+     * Changes one row by the table's unique key. An explicitly `undefined` change leaves that
+     * column untouched, so a patch spread from optional fields needs no filtering first.
+     */
+    update<TName extends TableName<TSchema>>(tableName: TName, key: BatchKeyValue<TSchema, TName>, changes: BatchUpdateChanges<TSchema, TName>): Promise<UpdateBatchResult>;
     /** Deletes one row by the table's unique key. */
-    delete(tableName: string, key: Exclude<BatchValue, null>): Promise<DeleteBatchResult>;
-    deleteBatch(tableName: string, input: DeleteBatchInput): Promise<DeleteBatchResult>;
-    bufferedWriter(tableName: string, options?: BufferedWriterOptions): BufferedTableWriter;
-    readTable(tableName: string, versionOrOptions?: number | ReadTableOptions): Promise<DatabaseRow[]>;
+    delete<TName extends TableName<TSchema>>(tableName: TName, key: BatchKeyValue<TSchema, TName>): Promise<DeleteBatchResult>;
+    deleteBatch<TName extends TableName<TSchema>>(tableName: TName, input: BatchDeleteInput<TSchema, TName>): Promise<DeleteBatchResult>;
+    bufferedWriter<TName extends TableName<TSchema>>(tableName: TName, options?: BufferedWriterOptions): BufferedTableWriter<BatchInsertRow<TSchema, TName>>;
+    readTable<TName extends TableName<TSchema>, const TColumns extends ReadonlyArray<BatchColumnName<TSchema, TName>>>(tableName: TName, options: BatchReadOptions<TSchema, TName, TColumns> & {
+        readonly columns: TColumns;
+    }): Promise<Array<Pick<BatchReadRow<TSchema, TName>, TColumns[number]>>>;
+    readTable<TName extends TableName<TSchema>>(tableName: TName, versionOrOptions?: number | BatchReadOptions<TSchema, TName>): Promise<Array<BatchReadRow<TSchema, TName>>>;
     /**
      * Runs the callback against one pinned manifest version: every query inside the scope
      * observes the same committed state, however many commits land meanwhile. This is the
@@ -807,7 +825,7 @@ export declare class MinnowDatabase {
      * compaction landing mid-scope never fails it. An error thrown by the callback aborts the
      * scope with nothing published. A scope that stages nothing publishes nothing.
      */
-    write<T>(action: (session: WriteSession) => Promise<T>): Promise<{
+    write<T>(action: (session: WriteSession<TSchema>) => Promise<T>): Promise<{
         result: T;
         version: number | null;
     }>;
@@ -824,7 +842,11 @@ export declare class MinnowDatabase {
      * steps — and every catalog alteration is one atomic compare-and-swap, so a concurrent
      * migrator fails explicitly with a conflict instead of interleaving.
      */
-    migrate(definition: SchemaDefinition<readonly AnyTable[]>, options?: MigrateOptions): Promise<MigrateResult>;
+    /**
+     * Brings storage in line with a schema declaration. With no argument it applies the schema the
+     * database was constructed with.
+     */
+    migrate(definition?: SchemaDefinition<readonly AnyTable[]> | undefined, options?: MigrateOptions): Promise<MigrateResult>;
     /**
      * Renders the optimized logical plan for a SELECT statement plus the physical strategy notes
      * the prepared execution would choose, without executing it.