@tanstack/electric-db-collection 0.1.44 → 0.2.1

package/dist/esm/sql-compiler.js

@@ -0,0 +1,151 @@
+import { serialize } from "./pg-serializer.js";
+function compileSQL(options) {
+  const { where, orderBy, limit } = options;
+  const params = [];
+  const compiledSQL = { params };
+  if (where) {
+    compiledSQL.where = compileBasicExpression(where, params);
+  }
+  if (orderBy) {
+    compiledSQL.orderBy = compileOrderBy(orderBy, params);
+  }
+  if (limit) {
+    compiledSQL.limit = limit;
+  }
+  if (!where) {
+    compiledSQL.where = `true = true`;
+  }
+  const paramsRecord = params.reduce(
+    (acc, param, index) => {
+      const serialized = serialize(param);
+      if (serialized !== ``) {
+        acc[`${index + 1}`] = serialized;
+      }
+      return acc;
+    },
+    {}
+  );
+  return {
+    ...compiledSQL,
+    params: paramsRecord
+  };
+}
+function quoteIdentifier(name) {
+  return `"${name}"`;
+}
+function compileBasicExpression(exp, params) {
+  switch (exp.type) {
+    case `val`:
+      params.push(exp.value);
+      return `$${params.length}`;
+    case `ref`:
+      if (exp.path.length !== 1) {
+        throw new Error(
+          `Compiler can't handle nested properties: ${exp.path.join(`.`)}`
+        );
+      }
+      return quoteIdentifier(exp.path[0]);
+    case `func`:
+      return compileFunction(exp, params);
+    default:
+      throw new Error(`Unknown expression type`);
+  }
+}
+function compileOrderBy(orderBy, params) {
+  const compiledOrderByClauses = orderBy.map(
+    (clause) => compileOrderByClause(clause, params)
+  );
+  return compiledOrderByClauses.join(`,`);
+}
+function compileOrderByClause(clause, params) {
+  const { expression, compareOptions } = clause;
+  let sql = compileBasicExpression(expression, params);
+  if (compareOptions.direction === `desc`) {
+    sql = `${sql} DESC`;
+  }
+  if (compareOptions.nulls === `first`) {
+    sql = `${sql} NULLS FIRST`;
+  }
+  if (compareOptions.nulls === `last`) {
+    sql = `${sql} NULLS LAST`;
+  }
+  return sql;
+}
+function compileFunction(exp, params = []) {
+  const { name, args } = exp;
+  const opName = getOpName(name);
+  const compiledArgs = args.map(
+    (arg) => compileBasicExpression(arg, params)
+  );
+  if (name === `isNull` || name === `isUndefined`) {
+    if (compiledArgs.length !== 1) {
+      throw new Error(`${name} expects 1 argument`);
+    }
+    return `${compiledArgs[0]} ${opName}`;
+  }
+  if (name === `not`) {
+    if (compiledArgs.length !== 1) {
+      throw new Error(`NOT expects 1 argument`);
+    }
+    const arg = args[0];
+    if (arg && arg.type === `func`) {
+      const funcArg = arg;
+      if (funcArg.name === `isNull` || funcArg.name === `isUndefined`) {
+        const innerArg = compileBasicExpression(funcArg.args[0], params);
+        return `${innerArg} IS NOT NULL`;
+      }
+    }
+    return `${opName} (${compiledArgs[0]})`;
+  }
+  if (isBinaryOp(name)) {
+    if ((name === `and` || name === `or`) && compiledArgs.length > 2) {
+      return compiledArgs.map((arg) => `(${arg})`).join(` ${opName} `);
+    }
+    if (compiledArgs.length !== 2) {
+      throw new Error(`Binary operator ${name} expects 2 arguments`);
+    }
+    const [lhs, rhs] = compiledArgs;
+    if (name === `in`) {
+      return `${lhs} ${opName}(${rhs})`;
+    }
+    return `${lhs} ${opName} ${rhs}`;
+  }
+  return `${opName}(${compiledArgs.join(`,`)})`;
+}
+function isBinaryOp(name) {
+  const binaryOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `in`];
+  return binaryOps.includes(name);
+}
+function getOpName(name) {
+  const opNames = {
+    eq: `=`,
+    gt: `>`,
+    gte: `>=`,
+    lt: `<`,
+    lte: `<=`,
+    add: `+`,
+    and: `AND`,
+    or: `OR`,
+    not: `NOT`,
+    isUndefined: `IS NULL`,
+    isNull: `IS NULL`,
+    in: `= ANY`,
+    // Use = ANY syntax for array parameters
+    like: `LIKE`,
+    ilike: `ILIKE`,
+    upper: `UPPER`,
+    lower: `LOWER`,
+    length: `LENGTH`,
+    concat: `CONCAT`,
+    coalesce: `COALESCE`
+  };
+  const opName = opNames[name];
+  if (!opName) {
+    throw new Error(`Unknown operator/function: ${name}`);
+  }
+  return opName;
+}
+export {
+  compileSQL
+};
+//# sourceMappingURL=sql-compiler.js.map

package/dist/esm/sql-compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-compiler.js","sources":["../../src/sql-compiler.ts"],"sourcesContent":["import { serialize } from \"./pg-serializer\"\nimport type { SubsetParams } from \"@electric-sql/client\"\nimport type { IR, LoadSubsetOptions } from \"@tanstack/db\"\n\nexport type CompiledSqlRecord = Omit<SubsetParams, `params`> & {\n  params?: Array<unknown>\n}\n\nexport function compileSQL<T>(options: LoadSubsetOptions): SubsetParams {\n  const { where, orderBy, limit } = options\n\n  const params: Array<T> = []\n  const compiledSQL: CompiledSqlRecord = { params }\n\n  if (where) {\n    // TODO: this only works when the where expression's PropRefs directly reference a column of the collection\n    //       doesn't work if it goes through aliases because then we need to know the entire query to be able to follow the reference until the base collection (cf. followRef function)\n    compiledSQL.where = compileBasicExpression(where, params)\n  }\n\n  if (orderBy) {\n    compiledSQL.orderBy = compileOrderBy(orderBy, params)\n  }\n\n  if (limit) {\n    compiledSQL.limit = limit\n  }\n\n  // WORKAROUND for Electric bug: Empty subset requests don't load data\n  // Add dummy \"true = true\" predicate when there's no where clause\n  // This is always true so doesn't filter data, just tricks Electric into loading\n  if (!where) {\n    compiledSQL.where = `true = true`\n  }\n\n  // Serialize the values in the params array into PG formatted strings\n  // and transform the array into a Record<string, string>\n  const paramsRecord = params.reduce(\n    (acc, param, index) => {\n      const serialized = serialize(param)\n      // Only include non-empty values in params\n      // Empty strings from null/undefined should be omitted\n      if (serialized !== ``) {\n        acc[`${index + 1}`] = serialized\n      }\n      return acc\n    },\n    {} as Record<string, string>\n  )\n\n  return {\n    ...compiledSQL,\n    params: paramsRecord,\n  }\n}\n\n/**\n * Quote PostgreSQL identifiers to handle mixed case column names correctly.\n * Electric/Postgres requires quotes for case-sensitive identifiers.\n * @param name - The identifier to quote\n * @returns The quoted identifier\n */\nfunction quoteIdentifier(name: string): string {\n  return `\"${name}\"`\n}\n\n/**\n * Compiles the expression to a SQL string and mutates the params array with the values.\n * @param exp - The expression to compile\n * @param params - The params array\n * @returns The compiled SQL string\n */\nfunction compileBasicExpression(\n  exp: IR.BasicExpression<unknown>,\n  params: Array<unknown>\n): string {\n  switch (exp.type) {\n    case `val`:\n      params.push(exp.value)\n      return `$${params.length}`\n    case `ref`:\n      // TODO: doesn't yet support JSON(B) values which could be accessed with nested props\n      if (exp.path.length !== 1) {\n        throw new Error(\n          `Compiler can't handle nested properties: ${exp.path.join(`.`)}`\n        )\n      }\n      return quoteIdentifier(exp.path[0]!)\n    case `func`:\n      return compileFunction(exp, params)\n    default:\n      throw new Error(`Unknown expression type`)\n  }\n}\n\nfunction compileOrderBy(orderBy: IR.OrderBy, params: Array<unknown>): string {\n  const compiledOrderByClauses = orderBy.map((clause: IR.OrderByClause) =>\n    compileOrderByClause(clause, params)\n  )\n  return compiledOrderByClauses.join(`,`)\n}\n\nfunction compileOrderByClause(\n  clause: IR.OrderByClause,\n  params: Array<unknown>\n): string {\n  // FIXME: We should handle stringSort and locale.\n  //        Correctly supporting them is tricky as it depends on Postgres' collation\n  const { expression, compareOptions } = clause\n  let sql = compileBasicExpression(expression, params)\n\n  if (compareOptions.direction === `desc`) {\n    sql = `${sql} DESC`\n  }\n\n  if (compareOptions.nulls === `first`) {\n    sql = `${sql} NULLS FIRST`\n  }\n\n  if (compareOptions.nulls === `last`) {\n    sql = `${sql} NULLS LAST`\n  }\n\n  return sql\n}\n\nfunction compileFunction(\n  exp: IR.Func<unknown>,\n  params: Array<unknown> = []\n): string {\n  const { name, args } = exp\n\n  const opName = getOpName(name)\n\n  const compiledArgs = args.map((arg: IR.BasicExpression) =>\n    compileBasicExpression(arg, params)\n  )\n\n  // Special case for IS NULL / IS NOT NULL - these are postfix operators\n  if (name === `isNull` || name === `isUndefined`) {\n    if (compiledArgs.length !== 1) {\n      throw new Error(`${name} expects 1 argument`)\n    }\n    return `${compiledArgs[0]} ${opName}`\n  }\n\n  // Special case for NOT - unary prefix operator\n  if (name === `not`) {\n    if (compiledArgs.length !== 1) {\n      throw new Error(`NOT expects 1 argument`)\n    }\n    // Check if the argument is IS NULL to generate IS NOT NULL\n    const arg = args[0]\n    if (arg && arg.type === `func`) {\n      const funcArg = arg\n      if (funcArg.name === `isNull` || funcArg.name === `isUndefined`) {\n        const innerArg = compileBasicExpression(funcArg.args[0]!, params)\n        return `${innerArg} IS NOT NULL`\n      }\n    }\n    return `${opName} (${compiledArgs[0]})`\n  }\n\n  if (isBinaryOp(name)) {\n    // Special handling for AND/OR which can be variadic\n    if ((name === `and` || name === `or`) && compiledArgs.length > 2) {\n      // Chain multiple arguments: (a AND b AND c) or (a OR b OR c)\n      return compiledArgs.map((arg) => `(${arg})`).join(` ${opName} `)\n    }\n\n    if (compiledArgs.length !== 2) {\n      throw new Error(`Binary operator ${name} expects 2 arguments`)\n    }\n    const [lhs, rhs] = compiledArgs\n    // Special case for = ANY operator which needs parentheses around the array parameter\n    if (name === `in`) {\n      return `${lhs} ${opName}(${rhs})`\n    }\n    return `${lhs} ${opName} ${rhs}`\n  }\n\n  return `${opName}(${compiledArgs.join(`,`)})`\n}\n\nfunction isBinaryOp(name: string): boolean {\n  const binaryOps = [`eq`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `in`]\n  return binaryOps.includes(name)\n}\n\nfunction getOpName(name: string): string {\n  const opNames = {\n    eq: `=`,\n    gt: `>`,\n    gte: `>=`,\n    lt: `<`,\n    lte: `<=`,\n    add: `+`,\n    and: `AND`,\n    or: `OR`,\n    not: `NOT`,\n    isUndefined: `IS NULL`,\n    isNull: `IS NULL`,\n    in: `= ANY`, // Use = ANY syntax for array parameters\n    like: `LIKE`,\n    ilike: `ILIKE`,\n    upper: `UPPER`,\n    lower: `LOWER`,\n    length: `LENGTH`,\n    concat: `CONCAT`,\n    coalesce: `COALESCE`,\n  }\n\n  const opName = opNames[name as keyof typeof opNames]\n\n  if (!opName) {\n    throw new Error(`Unknown operator/function: ${name}`)\n  }\n\n  return opName\n}\n"],"names":[],"mappings":";AAQO,SAAS,WAAc,SAA0C;AACtE,QAAM,EAAE,OAAO,SAAS,MAAA,IAAU;AAElC,QAAM,SAAmB,CAAA;AACzB,QAAM,cAAiC,EAAE,OAAA;AAEzC,MAAI,OAAO;AAGT,gBAAY,QAAQ,uBAAuB,OAAO,MAAM;AAAA,EAC1D;AAEA,MAAI,SAAS;AACX,gBAAY,UAAU,eAAe,SAAS,MAAM;AAAA,EACtD;AAEA,MAAI,OAAO;AACT,gBAAY,QAAQ;AAAA,EACtB;AAKA,MAAI,CAAC,OAAO;AACV,gBAAY,QAAQ;AAAA,EACtB;AAIA,QAAM,eAAe,OAAO;AAAA,IAC1B,CAAC,KAAK,OAAO,UAAU;AACrB,YAAM,aAAa,UAAU,KAAK;AAGlC,UAAI,eAAe,IAAI;AACrB,YAAI,GAAG,QAAQ,CAAC,EAAE,IAAI;AAAA,MACxB;AACA,aAAO;AAAA,IACT;AAAA,IACA,CAAA;AAAA,EAAC;AAGH,SAAO;AAAA,IACL,GAAG;AAAA,IACH,QAAQ;AAAA,EAAA;AAEZ;AAQA,SAAS,gBAAgB,MAAsB;AAC7C,SAAO,IAAI,IAAI;AACjB;AAQA,SAAS,uBACP,KACA,QACQ;AACR,UAAQ,IAAI,MAAA;AAAA,IACV,KAAK;AACH,aAAO,KAAK,IAAI,KAAK;AACrB,aAAO,IAAI,OAAO,MAAM;AAAA,IAC1B,KAAK;AAEH,UAAI,IAAI,KAAK,WAAW,GAAG;AACzB,cAAM,IAAI;AAAA,UACR,4CAA4C,IAAI,KAAK,KAAK,GAAG,CAAC;AAAA,QAAA;AAAA,MAElE;AACA,aAAO,gBAAgB,IAAI,KAAK,CAAC,CAAE;AAAA,IACrC,KAAK;AACH,aAAO,gBAAgB,KAAK,MAAM;AAAA,IACpC;AACE,YAAM,IAAI,MAAM,yBAAyB;AAAA,EAAA;AAE/C;AAEA,SAAS,eAAe,SAAqB,QAAgC;AAC3E,QAAM,yBAAyB,QAAQ;AAAA,IAAI,CAAC,WAC1C,qBAAqB,QAAQ,MAAM;AAAA,EAAA;AAErC,SAAO,uBAAuB,KAAK,GAAG;AACxC;AAEA,SAAS,qBACP,QACA,QACQ;AAGR,QAAM,EAAE,YAAY,eAAA,IAAmB;AACvC,MAAI,MAAM,uBAAuB,YAAY,MAAM;AAEnD,MAAI,eAAe,cAAc,QAAQ;AACvC,UAAM,GAAG,GAAG;AAAA,EACd;AAEA,MAAI,eAAe,UAAU,SAAS;AACpC,UAAM,GAAG,GAAG;AAAA,EACd;AAEA,MAAI,eAAe,UAAU,QAAQ;AACnC,UAAM,GAAG,GAAG;AAAA,EACd;AAEA,SAAO;AACT;AAEA,SAAS,gBACP,KACA,SAAyB,IACjB;AACR,QAAM,EAAE,MAAM,KAAA,IAAS;AAEvB,QAAM,SAAS,UAAU,IAAI;AAE7B,QAAM,eAAe,KAAK;AAAA,IAAI,CAAC,QAC7B,uBAAuB,KAAK,MAAM;AAAA,EAAA;AAIpC,MAAI,SAAS,YAAY,SAAS,eAAe;AAC/C,QAAI,aAAa,WAAW,GAAG;AAC7B,YAAM,IAAI,MAAM,GAAG,IAAI,qBAAqB;AAAA,IAC9C;AACA,WAAO,GAAG,aAAa,CAAC,CAAC,IAAI,MAAM;AAAA,EACrC;AAGA,MAAI,SAAS,OAAO;AAClB,QAAI,aAAa,WAAW,GAAG;AAC7B,YAAM,IAAI,MAAM,wBAAwB;AAAA,IAC1C;AAEA,UAAM,MAAM,KAAK,CAAC;AAClB,QAAI,OAAO,IAAI,SAAS,QAAQ;AAC9B,YAAM,UAAU;AAChB,UAAI,QAAQ,SAAS,YAAY,QAAQ,SAAS,eAAe;AAC/D,cAAM,WAAW,uBAAuB,QAAQ,KAAK,CAAC,GAAI,MAAM;AAChE,eAAO,GAAG,QAAQ;AAAA,MACpB;AAAA,IACF;AACA,WAAO,GAAG,MAAM,KAAK,aAAa,CAAC,CAAC;AAAA,EACtC;AAEA,MAAI,WAAW,IAAI,GAAG;AAEpB,SAAK,SAAS,SAAS,SAAS,SAAS,aAAa,SAAS,GAAG;AAEhE,aAAO,aAAa,IAAI,CAAC,QAAQ,IAAI,GAAG,GAAG,EAAE,KAAK,IAAI,MAAM,GAAG;AAAA,IACjE;AAEA,QAAI,aAAa,WAAW,GAAG;AAC7B,YAAM,IAAI,MAAM,mBAAmB,IAAI,sBAAsB;AAAA,IAC/D;AACA,UAAM,CAAC,KAAK,GAAG,IAAI;AAEnB,QAAI,SAAS,MAAM;AACjB,aAAO,GAAG,GAAG,IAAI,MAAM,IAAI,GAAG;AAAA,IAChC;AACA,WAAO,GAAG,GAAG,IAAI,MAAM,IAAI,GAAG;AAAA,EAChC;AAEA,SAAO,GAAG,MAAM,IAAI,aAAa,KAAK,GAAG,CAAC;AAC5C;AAEA,SAAS,WAAW,MAAuB;AACzC,QAAM,YAAY,CAAC,MAAM,MAAM,OAAO,MAAM,OAAO,OAAO,MAAM,IAAI;AACpE,SAAO,UAAU,SAAS,IAAI;AAChC;AAEA,SAAS,UAAU,MAAsB;AACvC,QAAM,UAAU;AAAA,IACd,IAAI;AAAA,IACJ,IAAI;AAAA,IACJ,KAAK;AAAA,IACL,IAAI;AAAA,IACJ,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,IACL,IAAI;AAAA,IACJ,KAAK;AAAA,IACL,aAAa;AAAA,IACb,QAAQ;AAAA,IACR,IAAI;AAAA;AAAA,IACJ,MAAM;AAAA,IACN,OAAO;AAAA,IACP,OAAO;AAAA,IACP,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,UAAU;AAAA,EAAA;AAGZ,QAAM,SAAS,QAAQ,IAA4B;AAEnD,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI,MAAM,8BAA8B,IAAI,EAAE;AAAA,EACtD;AAEA,SAAO;AACT;"}

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@tanstack/electric-db-collection",
   "description": "ElectricSQL collection for TanStack DB",
-  "version": "0.1.44",
+  "version": "0.2.1",
   "dependencies": {
-    "@electric-sql/client": "^1.1.0",
+    "@electric-sql/client": "^1.1.4",
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/store": "^0.8.0",
     "debug": "^4.4.3",
-    "@tanstack/db": "0.4.20"
+    "@tanstack/db": "0.5.1"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",
-    "@vitest/coverage-istanbul": "^3.2.4"
+    "@types/pg": "^8.15.6",
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "pg": "^8.16.3"
   },
   "exports": {
     ".": {
@@ -53,6 +55,7 @@
     "build": "vite build",
     "dev": "vite build --watch",
     "lint": "eslint . --fix",
-    "test": "npx vitest --run"
+    "test": "npx vitest run",
+    "test:e2e": "npx vitest run --config vitest.e2e.config.ts"
   }
 }

package/src/electric.ts

@@ -6,18 +6,22 @@ import {
 } from "@electric-sql/client"
 import { Store } from "@tanstack/store"
 import DebugModule from "debug"
+import { DeduplicatedLoadSubset } from "@tanstack/db"
 import {
   ExpectedNumberInAwaitTxIdError,
   StreamAbortedError,
   TimeoutWaitingForMatchError,
   TimeoutWaitingForTxIdError,
 } from "./errors"
+import { compileSQL } from "./sql-compiler"
 import type {
   BaseCollectionConfig,
   CollectionConfig,
   DeleteMutationFnParams,
   InsertMutationFnParams,
+  LoadSubsetOptions,
   SyncConfig,
+  SyncMode,
   UpdateMutationFnParams,
   UtilsRecord,
 } from "@tanstack/db"
@@ -52,10 +56,16 @@ export type MatchFunction<T extends Row<unknown>> = (
 /**
  * Matching strategies for Electric synchronization
  * Handlers can return:
- * - Txid strategy: { txid: number | number[] } (recommended)
+ * - Txid strategy: { txid: number | number[], timeout?: number } (recommended)
  * - Void (no return value) - mutation completes without waiting
+ *
+ * The optional timeout property specifies how long to wait for the txid(s) in milliseconds.
+ * If not specified, defaults to 5000ms.
  */
-export type MatchingStrategy = { txid: Txid | Array<Txid> } | void
+export type MatchingStrategy = {
+  txid: Txid | Array<Txid>
+  timeout?: number
+} | void
 
 /**
  * Type representing a snapshot end message
@@ -72,6 +82,24 @@ type InferSchemaOutput<T> = T extends StandardSchemaV1
     : Record<string, unknown>
   : Record<string, unknown>
 
+/**
+ * The mode of sync to use for the collection.
+ * @default `eager`
+ * @description
+ * - `eager`:
+ *   - syncs all data immediately on preload
+ *   - collection will be marked as ready once the sync is complete
+ *   - there is no incremental sync
+ * - `on-demand`:
+ *   - syncs data in incremental snapshots when the collection is queried
+ *   - collection will be marked as ready immediately after the first snapshot is synced
+ * - `progressive`:
+ *   - syncs all data for the collection in the background
+ *   - uses incremental snapshots during the initial sync to provide a fast path to the data required for queries
+ *   - collection will be marked as ready once the full sync is complete
+ */
+export type ElectricSyncMode = SyncMode | `progressive`
+
 /**
  * Configuration interface for Electric collection options
  * @template T - The type of items in the collection
@@ -82,17 +110,18 @@ export interface ElectricCollectionConfig<
   TSchema extends StandardSchemaV1 = never,
 > extends Omit<
     BaseCollectionConfig<T, string | number, TSchema, UtilsRecord, any>,
-    `onInsert` | `onUpdate` | `onDelete`
+    `onInsert` | `onUpdate` | `onDelete` | `syncMode`
   > {
   /**
    * Configuration options for the ElectricSQL ShapeStream
    */
   shapeOptions: ShapeStreamOptions<GetExtensions<T>>
+  syncMode?: ElectricSyncMode
 
   /**
    * Optional asynchronous handler function called before an insert operation
    * @param params Object containing transaction and collection information
-   * @returns Promise resolving to { txid } or void
+   * @returns Promise resolving to { txid, timeout? } or void
    * @example
    * // Basic Electric insert handler with txid (recommended)
    * onInsert: async ({ transaction }) => {
@@ -104,6 +133,16 @@ export interface ElectricCollectionConfig<
    * }
    *
    * @example
+   * // Insert handler with custom timeout
+   * onInsert: async ({ transaction }) => {
+   *   const newItem = transaction.mutations[0].modified
+   *   const result = await api.todos.create({
+   *     data: newItem
+   *   })
+   *   return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
+   * }
+   *
+   * @example
    * // Insert handler with multiple items - return array of txids
    * onInsert: async ({ transaction }) => {
    *   const items = transaction.mutations.map(m => m.modified)
@@ -130,7 +169,7 @@ export interface ElectricCollectionConfig<
   /**
    * Optional asynchronous handler function called before an update operation
    * @param params Object containing transaction and collection information
-   * @returns Promise resolving to { txid } or void
+   * @returns Promise resolving to { txid, timeout? } or void
    * @example
    * // Basic Electric update handler with txid (recommended)
    * onUpdate: async ({ transaction }) => {
@@ -159,7 +198,7 @@ export interface ElectricCollectionConfig<
   /**
    * Optional asynchronous handler function called before a delete operation
    * @param params Object containing transaction and collection information
-   * @returns Promise resolving to { txid } or void
+   * @returns Promise resolving to { txid, timeout? } or void
    * @example
    * // Basic Electric delete handler with txid (recommended)
    * onDelete: async ({ transaction }) => {
@@ -281,6 +320,9 @@ export function electricCollectionOptions(
 } {
   const seenTxids = new Store<Set<Txid>>(new Set([]))
   const seenSnapshots = new Store<Array<PostgresSnapshot>>([])
+  const internalSyncMode = config.syncMode ?? `eager`
+  const finalSyncMode =
+    internalSyncMode === `progressive` ? `on-demand` : internalSyncMode
   const pendingMatches = new Store<
     Map<
       string,
@@ -331,6 +373,7 @@ export function electricCollectionOptions(
   const sync = createElectricSync<any>(config.shapeOptions, {
     seenTxids,
     seenSnapshots,
+    syncMode: internalSyncMode,
     pendingMatches,
     currentBatchMessages,
     removePendingMatches,
@@ -504,11 +547,12 @@ export function electricCollectionOptions(
   ): Promise<void> => {
     // Only wait if result contains txid
     if (result && `txid` in result) {
+      const timeout = result.timeout
       // Handle both single txid and array of txids
       if (Array.isArray(result.txid)) {
-        await Promise.all(result.txid.map(awaitTxId))
+        await Promise.all(result.txid.map((txid) => awaitTxId(txid, timeout)))
       } else {
-        await awaitTxId(result.txid)
+        await awaitTxId(result.txid, timeout)
       }
     }
     // If result is void/undefined, don't wait - mutation completes immediately
@@ -550,6 +594,7 @@ export function electricCollectionOptions(
 
   return {
     ...restConfig,
+    syncMode: finalSyncMode,
     sync,
     onInsert: wrappedOnInsert,
     onUpdate: wrappedOnUpdate,
@@ -567,6 +612,7 @@ export function electricCollectionOptions(
 function createElectricSync<T extends Row<unknown>>(
   shapeOptions: ShapeStreamOptions<GetExtensions<T>>,
   options: {
+    syncMode: ElectricSyncMode
     seenTxids: Store<Set<Txid>>
     seenSnapshots: Store<Array<PostgresSnapshot>>
     pendingMatches: Store<
@@ -590,6 +636,7 @@ function createElectricSync<T extends Row<unknown>>(
   const {
     seenTxids,
     seenSnapshots,
+    syncMode,
     pendingMatches,
     currentBatchMessages,
     removePendingMatches,
@@ -653,6 +700,12 @@ function createElectricSync<T extends Row<unknown>>(
 
       const stream = new ShapeStream({
         ...shapeOptions,
+        // In on-demand mode, we only want to sync changes, so we set the log to `changes_only`
+        log: syncMode === `on-demand` ? `changes_only` : undefined,
+        // In on-demand mode, we only need the changes from the point of time the collection was created
+        // so we default to `now` when there is no saved offset.
+        offset:
+          shapeOptions.offset ?? (syncMode === `on-demand` ? `now` : undefined),
         signal: abortController.signal,
         onError: (errorParams) => {
           // Just immediately mark ready if there's an error to avoid blocking
@@ -679,9 +732,28 @@ function createElectricSync<T extends Row<unknown>>(
       let transactionStarted = false
       const newTxids = new Set<Txid>()
       const newSnapshots: Array<PostgresSnapshot> = []
+      let hasReceivedUpToDate = false // Track if we've completed initial sync in progressive mode
+
+      // Create deduplicated loadSubset wrapper for non-eager modes
+      // This prevents redundant snapshot requests when multiple concurrent
+      // live queries request overlapping or subset predicates
+      const loadSubsetDedupe =
+        syncMode === `eager`
+          ? null
+          : new DeduplicatedLoadSubset({
+              loadSubset: async (opts: LoadSubsetOptions) => {
+                // In progressive mode, stop requesting snapshots once full sync is complete
+                if (syncMode === `progressive` && hasReceivedUpToDate) {
+                  return
+                }
+                const snapshotParams = compileSQL<T>(opts)
+                await stream.requestSnapshot(snapshotParams)
+              },
+            })
 
       unsubscribeStream = stream.subscribe((messages: Array<Message<T>>) => {
         let hasUpToDate = false
+        let hasSnapshotEnd = false
 
         for (const message of messages) {
           // Add message to current batch buffer (for race condition handling)
@@ -746,6 +818,7 @@ function createElectricSync<T extends Row<unknown>>(
             })
           } else if (isSnapshotEndMessage(message)) {
             newSnapshots.push(parseSnapshotMessage(message))
+            hasSnapshotEnd = true
           } else if (isUpToDateMessage(message)) {
             hasUpToDate = true
           } else if (isMustRefetchMessage(message)) {
@@ -761,12 +834,18 @@ function createElectricSync<T extends Row<unknown>>(
 
             truncate()
 
-            // Reset hasUpToDate so we continue accumulating changes until next up-to-date
+            // Reset the loadSubset deduplication state since we're starting fresh
+            // This ensures that previously loaded predicates don't prevent refetching after truncate
+            loadSubsetDedupe?.reset()
+
+            // Reset flags so we continue accumulating changes until next up-to-date
             hasUpToDate = false
+            hasSnapshotEnd = false
+            hasReceivedUpToDate = false // Reset for progressive mode - we're starting a new sync
           }
         }
 
-        if (hasUpToDate) {
+        if (hasUpToDate || hasSnapshotEnd) {
           // Clear the current batch buffer since we're now up-to-date
           currentBatchMessages.setState(() => [])
 
@@ -776,8 +855,15 @@ function createElectricSync<T extends Row<unknown>>(
             transactionStarted = false
           }
 
-          // Mark the collection as ready now that sync is up to date
-          markReady()
+          if (hasUpToDate || (hasSnapshotEnd && syncMode === `on-demand`)) {
+            // Mark the collection as ready now that sync is up to date
+            markReady()
+          }
+
+          // Track that we've received the first up-to-date for progressive mode
+          if (hasUpToDate) {
+            hasReceivedUpToDate = true
+          }
 
           // Always commit txids when we receive up-to-date, regardless of transaction state
           seenTxids.setState((currentTxids) => {
@@ -811,12 +897,18 @@ function createElectricSync<T extends Row<unknown>>(
         }
       })
 
-      // Return the unsubscribe function
-      return () => {
-        // Unsubscribe from the stream
-        unsubscribeStream()
-        // Abort the abort controller to stop the stream
-        abortController.abort()
+      // Return the deduplicated loadSubset if available (on-demand or progressive mode)
+      // The loadSubset method is auto-bound, so it can be safely returned directly
+      return {
+        loadSubset: loadSubsetDedupe?.loadSubset,
+        cleanup: () => {
+          // Unsubscribe from the stream
+          unsubscribeStream()
+          // Abort the abort controller to stop the stream
+          abortController.abort()
+          // Reset deduplication tracking so collection can load fresh data if restarted
+          loadSubsetDedupe?.reset()
+        },
       }
     },
     // Expose the getSyncMetadata function

package/src/pg-serializer.ts

@@ -0,0 +1,58 @@
+/**
+ * Serialize values for Electric SQL subset parameters.
+ *
+ * IMPORTANT: Electric expects RAW values, NOT SQL-formatted literals.
+ * Electric handles all type casting and escaping on the server side.
+ * The params Record<string, string> contains the actual values as strings,
+ * and Electric will parse/cast them based on the column type in the WHERE clause.
+ *
+ * @param value - The value to serialize
+ * @returns The raw value as a string (no SQL formatting/quoting)
+ */
+export function serialize(value: unknown): string {
+  // Handle null/undefined - return empty string
+  // Electric interprets empty string as NULL in typed column context
+  if (value === null || value === undefined) {
+    return ``
+  }
+
+  // Handle strings - return as-is (NO quotes, Electric handles escaping)
+  if (typeof value === `string`) {
+    return value
+  }
+
+  // Handle numbers - convert to string
+  if (typeof value === `number`) {
+    return value.toString()
+  }
+
+  // Handle booleans - return as lowercase string
+  if (typeof value === `boolean`) {
+    return value ? `true` : `false`
+  }
+
+  // Handle dates - return ISO format (NO quotes)
+  if (value instanceof Date) {
+    return value.toISOString()
+  }
+
+  // Handle arrays - for = ANY() operator, serialize as Postgres array literal
+  // Format: {val1,val2,val3} with proper escaping
+  if (Array.isArray(value)) {
+    // Postgres array literal format uses curly braces
+    const elements = value.map((item) => {
+      if (item === null || item === undefined) {
+        return `NULL`
+      }
+      if (typeof item === `string`) {
+        // Escape quotes and backslashes for Postgres array literals
+        const escaped = item.replace(/\\/g, `\\\\`).replace(/"/g, `\\"`)
+        return `"${escaped}"`
+      }
+      return serialize(item)
+    })
+    return `{${elements.join(`,`)}}`
+  }
+
+  throw new Error(`Cannot serialize value: ${JSON.stringify(value)}`)
+}