@tanstack/powersync-db-collection 0.0.0 → 0.1.1

package/dist/cjs/helpers.d.cts

@@ -0,0 +1,70 @@
+import { DiffTriggerOperation, BaseColumnType, ExtractColumnValueType, Table } from '@powersync/common';
+/**
+ * All PowerSync table records include a UUID `id` column.
+ */
+export type PowerSyncRecord = {
+    id: string;
+    [key: string]: unknown;
+};
+/**
+ * Utility type: If T includes null, also allow undefined (to support optional fields in insert/update operations).
+ * PowerSync records are typically typed as `string | null`, where insert
+ * and update operations may also allow not specifying a value at all (optional).
+ */
+type WithUndefinedIfNull<T> = null extends T ? T | undefined : T;
+type OptionalIfUndefined<T> = {
+    [K in keyof T as undefined extends T[K] ? K : never]?: T[K];
+} & {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+};
+/**
+ * Provides the base column types for a table. This excludes the `id` column.
+ */
+export type ExtractedTableColumns<TTable extends Table> = {
+    [K in keyof TTable[`columnMap`]]: ExtractColumnValueType<TTable[`columnMap`][K]>;
+};
+/**
+ * Utility type that extracts the typed structure of a table based on its column definitions.
+ * Maps each column to its corresponding TypeScript type using ExtractColumnValueType.
+ *
+ * @template TTable - The PowerSync table definition
+ * @example
+ * ```typescript
+ * const table = new Table({
+ *   name: column.text,
+ *   age: column.integer
+ * })
+ * type TableType = ExtractedTable<typeof table>
+ * // Results in: { id: string, name: string | null, age: number | null }
+ * ```
+ */
+export type ExtractedTable<TTable extends Table> = ExtractedTableColumns<TTable> & {
+    id: string;
+};
+export type OptionalExtractedTable<TTable extends Table> = OptionalIfUndefined<{
+    [K in keyof TTable[`columnMap`]]: WithUndefinedIfNull<ExtractColumnValueType<TTable[`columnMap`][K]>>;
+}> & {
+    id: string;
+};
+/**
+ * Maps the schema of TTable to a type which
+ * requires the keys be equal, but the values can have any value type.
+ */
+export type AnyTableColumnType<TTable extends Table> = {
+    [K in keyof TTable[`columnMap`]]: any;
+} & {
+    id: string;
+};
+export declare function asPowerSyncRecord(record: any): PowerSyncRecord;
+export type MapBaseColumnType<TOutput> = {
+    [Key in keyof TOutput]: BaseColumnType<any>;
+};
+/**
+ * Maps {@link DiffTriggerOperation} to TanstackDB operations
+ */
+export declare function mapOperation(operation: DiffTriggerOperation): "insert" | "update" | "delete";
+/**
+ * Maps TanstackDB operations to  {@link DiffTriggerOperation}
+ */
+export declare function mapOperationToPowerSync(operation: string): DiffTriggerOperation;
+export {};

package/dist/cjs/index.cjs

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const definitions = require("./definitions.cjs");
+const powersync = require("./powersync.cjs");
+const PowerSyncTransactor = require("./PowerSyncTransactor.cjs");
+exports.DEFAULT_BATCH_SIZE = definitions.DEFAULT_BATCH_SIZE;
+exports.powerSyncCollectionOptions = powersync.powerSyncCollectionOptions;
+exports.PowerSyncTransactor = PowerSyncTransactor.PowerSyncTransactor;
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -0,0 +1,3 @@
+export * from './definitions.cjs';
+export * from './powersync.cjs';
+export * from './PowerSyncTransactor.cjs';

package/dist/cjs/powersync.cjs

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const common = require("@powersync/common");
+const PendingOperationStore = require("./PendingOperationStore.cjs");
+const PowerSyncTransactor = require("./PowerSyncTransactor.cjs");
+const definitions = require("./definitions.cjs");
+const helpers = require("./helpers.cjs");
+const schema = require("./schema.cjs");
+const serialization = require("./serialization.cjs");
+function powerSyncCollectionOptions(config) {
+  const {
+    database,
+    table,
+    schema: inputSchema,
+    syncBatchSize = definitions.DEFAULT_BATCH_SIZE,
+    ...restConfig
+  } = config;
+  const deserializationSchema = `deserializationSchema` in config ? config.deserializationSchema : null;
+  const serializer = `serializer` in config ? config.serializer : void 0;
+  const onDeserializationError = `onDeserializationError` in config ? config.onDeserializationError : void 0;
+  const { viewName } = table;
+  const deserializeSyncRow = (value) => {
+    const validationSchema = deserializationSchema || schema$1;
+    const validation = validationSchema[`~standard`].validate(value);
+    if (`value` in validation) {
+      return validation.value;
+    } else if (`issues` in validation) {
+      const issueMessage = `Failed to validate incoming data for ${viewName}. Issues: ${validation.issues.map((issue) => `${issue.path} - ${issue.message}`)}`;
+      database.logger.error(issueMessage);
+      onDeserializationError(validation);
+      throw new Error(issueMessage);
+    } else {
+      const unknownErrorMessage = `Unknown deserialization error for ${viewName}`;
+      database.logger.error(unknownErrorMessage);
+      onDeserializationError({ issues: [{ message: unknownErrorMessage }] });
+      throw new Error(unknownErrorMessage);
+    }
+  };
+  const schema$1 = inputSchema ?? schema.convertTableToSchema(table);
+  const pendingOperationStore = PendingOperationStore.PendingOperationStore.GLOBAL;
+  const trackedTableName = `__${viewName}_tracking_${Math.floor(
+    Math.random() * 4294967295
+  ).toString(16).padStart(8, `0`)}`;
+  const transactor = new PowerSyncTransactor.PowerSyncTransactor({
+    database
+  });
+  const sync = {
+    sync: (params) => {
+      const { begin, write, commit, markReady } = params;
+      const abortController = new AbortController();
+      async function start() {
+        database.logger.info(
+          `Sync is starting for ${viewName} into ${trackedTableName}`
+        );
+        database.onChangeWithCallback(
+          {
+            onChange: async () => {
+              await database.writeTransaction(async (context) => {
+                begin();
+                const operations = await context.getAll(
+                  `SELECT * FROM ${trackedTableName} ORDER BY timestamp ASC`
+                );
+                const pendingOperations = [];
+                for (const op of operations) {
+                  const { id, operation, timestamp, value } = op;
+                  const parsedValue = deserializeSyncRow({
+                    id,
+                    ...JSON.parse(value)
+                  });
+                  const parsedPreviousValue = op.operation == common.DiffTriggerOperation.UPDATE ? deserializeSyncRow({
+                    id,
+                    ...JSON.parse(op.previous_value)
+                  }) : void 0;
+                  write({
+                    type: helpers.mapOperation(operation),
+                    value: parsedValue,
+                    previousValue: parsedPreviousValue
+                  });
+                  pendingOperations.push({
+                    id,
+                    operation,
+                    timestamp,
+                    tableName: viewName
+                  });
+                }
+                await context.execute(`DELETE FROM ${trackedTableName}`);
+                commit();
+                pendingOperationStore.resolvePendingFor(pendingOperations);
+              }).catch((error) => {
+                database.logger.error(
+                  `An error has been detected in the sync handler`,
+                  error
+                );
+              });
+            }
+          },
+          {
+            signal: abortController.signal,
+            triggerImmediate: false,
+            tables: [trackedTableName]
+          }
+        );
+        const disposeTracking = await database.triggers.createDiffTrigger({
+          source: viewName,
+          destination: trackedTableName,
+          when: {
+            [common.DiffTriggerOperation.INSERT]: `TRUE`,
+            [common.DiffTriggerOperation.UPDATE]: `TRUE`,
+            [common.DiffTriggerOperation.DELETE]: `TRUE`
+          },
+          hooks: {
+            beforeCreate: async (context) => {
+              let currentBatchCount = syncBatchSize;
+              let cursor = 0;
+              while (currentBatchCount == syncBatchSize) {
+                begin();
+                const batchItems = await context.getAll(
+                  common.sanitizeSQL`SELECT * FROM ${viewName} LIMIT ? OFFSET ?`,
+                  [syncBatchSize, cursor]
+                );
+                currentBatchCount = batchItems.length;
+                cursor += currentBatchCount;
+                for (const row of batchItems) {
+                  write({
+                    type: `insert`,
+                    value: deserializeSyncRow(row)
+                  });
+                }
+                commit();
+              }
+              markReady();
+              database.logger.info(
+                `Sync is ready for ${viewName} into ${trackedTableName}`
+              );
+            }
+          }
+        });
+        if (abortController.signal.aborted) {
+          await disposeTracking();
+        } else {
+          abortController.signal.addEventListener(
+            `abort`,
+            () => {
+              disposeTracking();
+            },
+            { once: true }
+          );
+        }
+      }
+      start().catch(
+        (error) => database.logger.error(
+          `Could not start syncing process for ${viewName} into ${trackedTableName}`,
+          error
+        )
+      );
+      return () => {
+        database.logger.info(
+          `Sync has been stopped for ${viewName} into ${trackedTableName}`
+        );
+        abortController.abort();
+      };
+    },
+    // Expose the getSyncMetadata function
+    getSyncMetadata: void 0
+  };
+  const getKey = (record) => helpers.asPowerSyncRecord(record).id;
+  const outputConfig = {
+    ...restConfig,
+    schema: schema$1,
+    getKey,
+    // Syncing should start immediately since we need to monitor the changes for mutations
+    startSync: true,
+    sync,
+    onInsert: async (params) => {
+      return await transactor.applyTransaction(params.transaction);
+    },
+    onUpdate: async (params) => {
+      return await transactor.applyTransaction(params.transaction);
+    },
+    onDelete: async (params) => {
+      return await transactor.applyTransaction(params.transaction);
+    },
+    utils: {
+      getMeta: () => ({
+        tableName: viewName,
+        trackedTableName,
+        serializeValue: (value) => serialization.serializeForSQLite(
+          value,
+          // This is required by the input generic
+          table,
+          // Coerce serializer to the shape that corresponds to the Table constructed from OutputType
+          serializer
+        )
+      })
+    }
+  };
+  return outputConfig;
+}
+exports.powerSyncCollectionOptions = powerSyncCollectionOptions;
+//# sourceMappingURL=powersync.cjs.map

package/dist/cjs/powersync.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"powersync.cjs","sources":["../../src/powersync.ts"],"sourcesContent":["import { DiffTriggerOperation, sanitizeSQL } from \"@powersync/common\"\nimport { PendingOperationStore } from \"./PendingOperationStore\"\nimport { PowerSyncTransactor } from \"./PowerSyncTransactor\"\nimport { DEFAULT_BATCH_SIZE } from \"./definitions\"\nimport { asPowerSyncRecord, mapOperation } from \"./helpers\"\nimport { convertTableToSchema } from \"./schema\"\nimport { serializeForSQLite } from \"./serialization\"\nimport type {\n  AnyTableColumnType,\n  ExtractedTable,\n  ExtractedTableColumns,\n  MapBaseColumnType,\n  OptionalExtractedTable,\n} from \"./helpers\"\nimport type {\n  BasePowerSyncCollectionConfig,\n  ConfigWithArbitraryCollectionTypes,\n  ConfigWithSQLiteInputType,\n  ConfigWithSQLiteTypes,\n  CustomSQLiteSerializer,\n  EnhancedPowerSyncCollectionConfig,\n  InferPowerSyncOutputType,\n  PowerSyncCollectionConfig,\n  PowerSyncCollectionUtils,\n} from \"./definitions\"\nimport type { PendingOperation } from \"./PendingOperationStore\"\nimport type { SyncConfig } from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { Table, TriggerDiffRecord } from \"@powersync/common\"\n\n/**\n * Creates PowerSync collection options for use with a standard Collection.\n *\n * @template TTable - The SQLite-based typing\n * @template TSchema - The validation schema type (optionally supports a custom input type)\n * @param config - Configuration options for the PowerSync collection\n * @returns Collection options with utilities\n */\n\n// Overload 1: No schema is provided\n\n/**\n * Creates a PowerSync collection configuration with basic default validation.\n * Input and Output types are the SQLite column types.\n *\n * @example\n * ```typescript\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *   }),\n * })\n *\n * type Document = (typeof APP_SCHEMA)[\"types\"][\"documents\"]\n *\n * const db = new PowerSyncDatabase({\n *   database: {\n *     dbFilename: \"test.sqlite\",\n *   },\n *   schema: APP_SCHEMA,\n * })\n *\n * const collection = createCollection(\n *   powerSyncCollectionOptions({\n *     database: db,\n *     table: APP_SCHEMA.props.documents\n *   })\n * )\n * ```\n */\nexport function powerSyncCollectionOptions<TTable extends Table = Table>(\n  config: BasePowerSyncCollectionConfig<TTable, never> & ConfigWithSQLiteTypes\n): EnhancedPowerSyncCollectionConfig<\n  TTable,\n  OptionalExtractedTable<TTable>,\n  never\n>\n\n// Overload 2: Schema is provided and the TInput matches SQLite types.\n\n/**\n * Creates a PowerSync collection configuration with schema validation.\n *\n * The input types satisfy the SQLite column types.\n *\n * The output types are defined by the provided schema. This schema can enforce additional\n * validation or type transforms.\n * Arbitrary output typed mutations are encoded to SQLite for persistence. We provide a basic standard\n * serialization implementation to serialize column values. Custom or advanced types require providing additional\n * serializer specifications. Partial column overrides can be supplied to `serializer`.\n *\n * @example\n * ```typescript\n * import { z } from \"zod\"\n *\n * // The PowerSync SQLite schema\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *     // Dates are stored as ISO date strings in SQLite\n *     created_at: column.text\n *   }),\n * })\n *\n * // Advanced Zod validations. The output type of this schema\n * // is constrained to the SQLite schema of APP_SCHEMA\n * const schema = z.object({\n *   id: z.string(),\n *   // Notice that `name` is not nullable (is required) here and it has additional validation\n *   name: z.string().min(3, { message: \"Should be at least 3 characters\" }).nullable(),\n *   // The input type is still the SQLite string type. While collections will output smart Date instances.\n *   created_at: z.string().transform(val => new Date(val))\n * })\n *\n * const collection = createCollection(\n *   powerSyncCollectionOptions({\n *     database: db,\n *     table: APP_SCHEMA.props.documents,\n *     schema,\n *     serializer: {\n *        // The default is toISOString, this is just to demonstrate custom overrides\n *        created_at: (outputValue) => outputValue.toISOString(),\n *     },\n *   })\n * )\n * ```\n */\nexport function powerSyncCollectionOptions<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // TInput is the SQLite types. We can use the supplied schema to validate sync input\n    OptionalExtractedTable<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n>(\n  config: BasePowerSyncCollectionConfig<TTable, TSchema> &\n    ConfigWithSQLiteInputType<TTable, TSchema>\n): EnhancedPowerSyncCollectionConfig<\n  TTable,\n  InferPowerSyncOutputType<TTable, TSchema>,\n  TSchema\n> & {\n  schema: TSchema\n}\n\n// Overload 3: Schema is provided with arbitrary TInput and TOutput\n/**\n * Creates a PowerSync collection configuration with schema validation.\n *\n * The input types are not linked to the internal SQLite table types. This can\n * give greater flexibility, e.g. by accepting rich types as input for `insert` or `update` operations.\n * An additional `deserializationSchema` is required in order to process incoming SQLite updates to the output type.\n *\n * The output types are defined by the provided schema. This schema can enforce additional\n * validation or type transforms.\n * Arbitrary output typed mutations are encoded to SQLite for persistence. We provide a basic standard\n * serialization implementation to serialize column values. Custom or advanced types require providing additional\n * serializer specifications. Partial column overrides can be supplied to `serializer`.\n *\n * @example\n * ```typescript\n * import { z } from \"zod\"\n *\n * // The PowerSync SQLite schema\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *     // Booleans are represented as integers in SQLite\n *     is_active: column.integer\n *   }),\n * })\n *\n * // Advanced Zod validations.\n * // We accept boolean values as input for operations and expose Booleans in query results\n * const schema = z.object({\n *   id: z.string(),\n *   isActive: z.boolean(), // TInput and TOutput are boolean\n * })\n *\n * // The deserializationSchema converts the SQLite synced INTEGER (0/1) values to booleans.\n * const deserializationSchema = z.object({\n *   id: z.string(),\n *   isActive: z.number().nullable().transform((val) => val == null ? true : val > 0),\n * })\n *\n * const collection = createCollection(\n *   powerSyncCollectionOptions({\n *     database: db,\n *     table: APP_SCHEMA.props.documents,\n *     schema,\n *     deserializationSchema,\n *   })\n * )\n * ```\n */\nexport function powerSyncCollectionOptions<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // The input and output must have the same keys, the value types can be arbitrary\n    AnyTableColumnType<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n>(\n  config: BasePowerSyncCollectionConfig<TTable, TSchema> &\n    ConfigWithArbitraryCollectionTypes<TTable, TSchema>\n): EnhancedPowerSyncCollectionConfig<\n  TTable,\n  InferPowerSyncOutputType<TTable, TSchema>,\n  TSchema\n> & {\n  utils: PowerSyncCollectionUtils<TTable>\n  schema: TSchema\n}\n\n/**\n * Implementation of powerSyncCollectionOptions that handles both schema and non-schema configurations.\n */\n\nexport function powerSyncCollectionOptions<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<any> = never,\n>(config: PowerSyncCollectionConfig<TTable, TSchema>) {\n  const {\n    database,\n    table,\n    schema: inputSchema,\n    syncBatchSize = DEFAULT_BATCH_SIZE,\n    ...restConfig\n  } = config\n\n  const deserializationSchema =\n    `deserializationSchema` in config ? config.deserializationSchema : null\n  const serializer = `serializer` in config ? config.serializer : undefined\n  const onDeserializationError =\n    `onDeserializationError` in config\n      ? config.onDeserializationError\n      : undefined\n\n  // The SQLite table type\n  type TableType = ExtractedTable<TTable>\n\n  // The collection output type\n  type OutputType = InferPowerSyncOutputType<TTable, TSchema>\n\n  const { viewName } = table\n\n  /**\n   * Deserializes data from the incoming sync stream\n   */\n  const deserializeSyncRow = (value: TableType): OutputType => {\n    const validationSchema = deserializationSchema || schema\n    const validation = validationSchema[`~standard`].validate(value)\n    if (`value` in validation) {\n      return validation.value\n    } else if (`issues` in validation) {\n      const issueMessage = `Failed to validate incoming data for ${viewName}. Issues: ${validation.issues.map((issue) => `${issue.path} - ${issue.message}`)}`\n      database.logger.error(issueMessage)\n      onDeserializationError!(validation)\n      throw new Error(issueMessage)\n    } else {\n      const unknownErrorMessage = `Unknown deserialization error for ${viewName}`\n      database.logger.error(unknownErrorMessage)\n      onDeserializationError!({ issues: [{ message: unknownErrorMessage }] })\n      throw new Error(unknownErrorMessage)\n    }\n  }\n\n  // We can do basic runtime validations for columns if not explicit schema has been provided\n  const schema = inputSchema ?? (convertTableToSchema(table) as TSchema)\n  /**\n   * The onInsert, onUpdate, and onDelete handlers should only return\n   * after we have written the changes to TanStack DB.\n   * We currently only write to TanStack DB from a diff trigger.\n   * We wait for the diff trigger to observe the change,\n   * and only then return from the on[X] handlers.\n   * This ensures that when the transaction is reported as\n   * complete to the caller, the in-memory state is already\n   * consistent with the database.\n   */\n  const pendingOperationStore = PendingOperationStore.GLOBAL\n  // Keep the tracked table unique in case of multiple tabs.\n  const trackedTableName = `__${viewName}_tracking_${Math.floor(\n    Math.random() * 0xffffffff\n  )\n    .toString(16)\n    .padStart(8, `0`)}`\n\n  const transactor = new PowerSyncTransactor({\n    database,\n  })\n\n  /**\n   * \"sync\"\n   * Notice that this describes the Sync between the local SQLite table\n   * and the in-memory tanstack-db collection.\n   */\n  const sync: SyncConfig<OutputType, string> = {\n    sync: (params) => {\n      const { begin, write, commit, markReady } = params\n      const abortController = new AbortController()\n\n      // The sync function needs to be synchronous\n      async function start() {\n        database.logger.info(\n          `Sync is starting for ${viewName} into ${trackedTableName}`\n        )\n        database.onChangeWithCallback(\n          {\n            onChange: async () => {\n              await database\n                .writeTransaction(async (context) => {\n                  begin()\n                  const operations = await context.getAll<TriggerDiffRecord>(\n                    `SELECT * FROM ${trackedTableName} ORDER BY timestamp ASC`\n                  )\n                  const pendingOperations: Array<PendingOperation> = []\n\n                  for (const op of operations) {\n                    const { id, operation, timestamp, value } = op\n                    const parsedValue = deserializeSyncRow({\n                      id,\n                      ...JSON.parse(value),\n                    })\n                    const parsedPreviousValue =\n                      op.operation == DiffTriggerOperation.UPDATE\n                        ? deserializeSyncRow({\n                            id,\n                            ...JSON.parse(op.previous_value),\n                          })\n                        : undefined\n                    write({\n                      type: mapOperation(operation),\n                      value: parsedValue,\n                      previousValue: parsedPreviousValue,\n                    })\n                    pendingOperations.push({\n                      id,\n                      operation,\n                      timestamp,\n                      tableName: viewName,\n                    })\n                  }\n\n                  // clear the current operations\n                  await context.execute(`DELETE FROM ${trackedTableName}`)\n\n                  commit()\n                  pendingOperationStore.resolvePendingFor(pendingOperations)\n                })\n                .catch((error) => {\n                  database.logger.error(\n                    `An error has been detected in the sync handler`,\n                    error\n                  )\n                })\n            },\n          },\n          {\n            signal: abortController.signal,\n            triggerImmediate: false,\n            tables: [trackedTableName],\n          }\n        )\n\n        const disposeTracking = await database.triggers.createDiffTrigger({\n          source: viewName,\n          destination: trackedTableName,\n          when: {\n            [DiffTriggerOperation.INSERT]: `TRUE`,\n            [DiffTriggerOperation.UPDATE]: `TRUE`,\n            [DiffTriggerOperation.DELETE]: `TRUE`,\n          },\n          hooks: {\n            beforeCreate: async (context) => {\n              let currentBatchCount = syncBatchSize\n              let cursor = 0\n              while (currentBatchCount == syncBatchSize) {\n                begin()\n                const batchItems = await context.getAll<TableType>(\n                  sanitizeSQL`SELECT * FROM ${viewName} LIMIT ? OFFSET ?`,\n                  [syncBatchSize, cursor]\n                )\n                currentBatchCount = batchItems.length\n                cursor += currentBatchCount\n                for (const row of batchItems) {\n                  write({\n                    type: `insert`,\n                    value: deserializeSyncRow(row),\n                  })\n                }\n                commit()\n              }\n              markReady()\n              database.logger.info(\n                `Sync is ready for ${viewName} into ${trackedTableName}`\n              )\n            },\n          },\n        })\n\n        // If the abort controller was aborted while processing the request above\n        if (abortController.signal.aborted) {\n          await disposeTracking()\n        } else {\n          abortController.signal.addEventListener(\n            `abort`,\n            () => {\n              disposeTracking()\n            },\n            { once: true }\n          )\n        }\n      }\n\n      start().catch((error) =>\n        database.logger.error(\n          `Could not start syncing process for ${viewName} into ${trackedTableName}`,\n          error\n        )\n      )\n\n      return () => {\n        database.logger.info(\n          `Sync has been stopped for ${viewName} into ${trackedTableName}`\n        )\n        abortController.abort()\n      }\n    },\n    // Expose the getSyncMetadata function\n    getSyncMetadata: undefined,\n  }\n\n  const getKey = (record: OutputType) => asPowerSyncRecord(record).id\n\n  const outputConfig: EnhancedPowerSyncCollectionConfig<\n    TTable,\n    OutputType,\n    TSchema\n  > = {\n    ...restConfig,\n    schema,\n    getKey,\n    // Syncing should start immediately since we need to monitor the changes for mutations\n    startSync: true,\n    sync,\n    onInsert: async (params) => {\n      // The transaction here should only ever contain a single insert mutation\n      return await transactor.applyTransaction(params.transaction)\n    },\n    onUpdate: async (params) => {\n      // The transaction here should only ever contain a single update mutation\n      return await transactor.applyTransaction(params.transaction)\n    },\n    onDelete: async (params) => {\n      // The transaction here should only ever contain a single delete mutation\n      return await transactor.applyTransaction(params.transaction)\n    },\n    utils: {\n      getMeta: () => ({\n        tableName: viewName,\n        trackedTableName,\n        serializeValue: (value) =>\n          serializeForSQLite(\n            value,\n            // This is required by the input generic\n            table as Table<\n              MapBaseColumnType<InferPowerSyncOutputType<TTable, TSchema>>\n            >,\n            // Coerce serializer to the shape that corresponds to the Table constructed from OutputType\n            serializer as CustomSQLiteSerializer<\n              OutputType,\n              ExtractedTableColumns<Table<MapBaseColumnType<OutputType>>>\n            >\n          ),\n      }),\n    },\n  }\n  return outputConfig\n}\n"],"names":["DEFAULT_BATCH_SIZE","schema","convertTableToSchema","PendingOperationStore","PowerSyncTransactor","DiffTriggerOperation","mapOperation","sanitizeSQL","asPowerSyncRecord","serializeForSQLite"],"mappings":"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"}

package/dist/cjs/powersync.d.cts

@@ -0,0 +1,145 @@
+import { AnyTableColumnType, OptionalExtractedTable } from './helpers.cjs';
+import { BasePowerSyncCollectionConfig, ConfigWithArbitraryCollectionTypes, ConfigWithSQLiteInputType, ConfigWithSQLiteTypes, EnhancedPowerSyncCollectionConfig, InferPowerSyncOutputType, PowerSyncCollectionUtils } from './definitions.cjs';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { Table } from '@powersync/common';
+/**
+ * Creates PowerSync collection options for use with a standard Collection.
+ *
+ * @template TTable - The SQLite-based typing
+ * @template TSchema - The validation schema type (optionally supports a custom input type)
+ * @param config - Configuration options for the PowerSync collection
+ * @returns Collection options with utilities
+ */
+/**
+ * Creates a PowerSync collection configuration with basic default validation.
+ * Input and Output types are the SQLite column types.
+ *
+ * @example
+ * ```typescript
+ * const APP_SCHEMA = new Schema({
+ *   documents: new Table({
+ *     name: column.text,
+ *   }),
+ * })
+ *
+ * type Document = (typeof APP_SCHEMA)["types"]["documents"]
+ *
+ * const db = new PowerSyncDatabase({
+ *   database: {
+ *     dbFilename: "test.sqlite",
+ *   },
+ *   schema: APP_SCHEMA,
+ * })
+ *
+ * const collection = createCollection(
+ *   powerSyncCollectionOptions({
+ *     database: db,
+ *     table: APP_SCHEMA.props.documents
+ *   })
+ * )
+ * ```
+ */
+export declare function powerSyncCollectionOptions<TTable extends Table = Table>(config: BasePowerSyncCollectionConfig<TTable, never> & ConfigWithSQLiteTypes): EnhancedPowerSyncCollectionConfig<TTable, OptionalExtractedTable<TTable>, never>;
+/**
+ * Creates a PowerSync collection configuration with schema validation.
+ *
+ * The input types satisfy the SQLite column types.
+ *
+ * The output types are defined by the provided schema. This schema can enforce additional
+ * validation or type transforms.
+ * Arbitrary output typed mutations are encoded to SQLite for persistence. We provide a basic standard
+ * serialization implementation to serialize column values. Custom or advanced types require providing additional
+ * serializer specifications. Partial column overrides can be supplied to `serializer`.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod"
+ *
+ * // The PowerSync SQLite schema
+ * const APP_SCHEMA = new Schema({
+ *   documents: new Table({
+ *     name: column.text,
+ *     // Dates are stored as ISO date strings in SQLite
+ *     created_at: column.text
+ *   }),
+ * })
+ *
+ * // Advanced Zod validations. The output type of this schema
+ * // is constrained to the SQLite schema of APP_SCHEMA
+ * const schema = z.object({
+ *   id: z.string(),
+ *   // Notice that `name` is not nullable (is required) here and it has additional validation
+ *   name: z.string().min(3, { message: "Should be at least 3 characters" }).nullable(),
+ *   // The input type is still the SQLite string type. While collections will output smart Date instances.
+ *   created_at: z.string().transform(val => new Date(val))
+ * })
+ *
+ * const collection = createCollection(
+ *   powerSyncCollectionOptions({
+ *     database: db,
+ *     table: APP_SCHEMA.props.documents,
+ *     schema,
+ *     serializer: {
+ *        // The default is toISOString, this is just to demonstrate custom overrides
+ *        created_at: (outputValue) => outputValue.toISOString(),
+ *     },
+ *   })
+ * )
+ * ```
+ */
+export declare function powerSyncCollectionOptions<TTable extends Table, TSchema extends StandardSchemaV1<OptionalExtractedTable<TTable>, AnyTableColumnType<TTable>>>(config: BasePowerSyncCollectionConfig<TTable, TSchema> & ConfigWithSQLiteInputType<TTable, TSchema>): EnhancedPowerSyncCollectionConfig<TTable, InferPowerSyncOutputType<TTable, TSchema>, TSchema> & {
+    schema: TSchema;
+};
+/**
+ * Creates a PowerSync collection configuration with schema validation.
+ *
+ * The input types are not linked to the internal SQLite table types. This can
+ * give greater flexibility, e.g. by accepting rich types as input for `insert` or `update` operations.
+ * An additional `deserializationSchema` is required in order to process incoming SQLite updates to the output type.
+ *
+ * The output types are defined by the provided schema. This schema can enforce additional
+ * validation or type transforms.
+ * Arbitrary output typed mutations are encoded to SQLite for persistence. We provide a basic standard
+ * serialization implementation to serialize column values. Custom or advanced types require providing additional
+ * serializer specifications. Partial column overrides can be supplied to `serializer`.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod"
+ *
+ * // The PowerSync SQLite schema
+ * const APP_SCHEMA = new Schema({
+ *   documents: new Table({
+ *     name: column.text,
+ *     // Booleans are represented as integers in SQLite
+ *     is_active: column.integer
+ *   }),
+ * })
+ *
+ * // Advanced Zod validations.
+ * // We accept boolean values as input for operations and expose Booleans in query results
+ * const schema = z.object({
+ *   id: z.string(),
+ *   isActive: z.boolean(), // TInput and TOutput are boolean
+ * })
+ *
+ * // The deserializationSchema converts the SQLite synced INTEGER (0/1) values to booleans.
+ * const deserializationSchema = z.object({
+ *   id: z.string(),
+ *   isActive: z.number().nullable().transform((val) => val == null ? true : val > 0),
+ * })
+ *
+ * const collection = createCollection(
+ *   powerSyncCollectionOptions({
+ *     database: db,
+ *     table: APP_SCHEMA.props.documents,
+ *     schema,
+ *     deserializationSchema,
+ *   })
+ * )
+ * ```
+ */
+export declare function powerSyncCollectionOptions<TTable extends Table, TSchema extends StandardSchemaV1<AnyTableColumnType<TTable>, AnyTableColumnType<TTable>>>(config: BasePowerSyncCollectionConfig<TTable, TSchema> & ConfigWithArbitraryCollectionTypes<TTable, TSchema>): EnhancedPowerSyncCollectionConfig<TTable, InferPowerSyncOutputType<TTable, TSchema>, TSchema> & {
+    utils: PowerSyncCollectionUtils<TTable>;
+    schema: TSchema;
+};

package/dist/cjs/schema.cjs

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const common = require("@powersync/common");
+function convertTableToSchema(table) {
+  const validate = (value) => {
+    if (typeof value != `object` || value == null) {
+      return {
+        issues: [
+          {
+            message: `Value must be an object`
+          }
+        ]
+      };
+    }
+    const issues = [];
+    if (!(`id` in value) || typeof value.id != `string`) {
+      issues.push({
+        message: `id field must be a string`,
+        path: [`id`]
+      });
+    }
+    for (const column of table.columns) {
+      const val = value[column.name];
+      if (val == null) {
+        continue;
+      }
+      switch (column.type) {
+        case common.ColumnType.TEXT:
+          if (typeof val != `string`) {
+            issues.push({
+              message: `${column.name} must be a string or null`,
+              path: [column.name]
+            });
+          }
+          break;
+        case common.ColumnType.INTEGER:
+        case common.ColumnType.REAL:
+          if (typeof val != `number`) {
+            issues.push({
+              message: `${column.name} must be a number or null`,
+              path: [column.name]
+            });
+          }
+          break;
+      }
+    }
+    if (issues.length > 0) {
+      return { issues };
+    }
+    return { value: { ...value } };
+  };
+  return {
+    "~standard": {
+      version: 1,
+      vendor: `powersync`,
+      validate,
+      types: {
+        input: {},
+        output: {}
+      }
+    }
+  };
+}
+exports.convertTableToSchema = convertTableToSchema;
+//# sourceMappingURL=schema.cjs.map

package/dist/cjs/schema.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.cjs","sources":["../../src/schema.ts"],"sourcesContent":["import { ColumnType } from \"@powersync/common\"\nimport type { Table } from \"@powersync/common\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { ExtractedTable } from \"./helpers\"\n\n/**\n * Converts a PowerSync Table instance to a StandardSchemaV1 schema.\n * Creates a schema that validates the structure and types of table records\n * according to the PowerSync table definition.\n *\n * @template TTable - The PowerSync schema-typed Table definition\n * @param table - The PowerSync Table instance to convert\n * @returns A StandardSchemaV1-compatible schema with proper type validation\n *\n * @example\n * ```typescript\n * const usersTable = new Table({\n *   name: column.text,\n *   age: column.integer\n * })\n * ```\n */\nexport function convertTableToSchema<TTable extends Table>(\n  table: TTable\n): StandardSchemaV1<ExtractedTable<TTable>> {\n  type TExtracted = ExtractedTable<TTable>\n  // Create validate function that checks types according to column definitions\n  const validate = (\n    value: unknown\n  ):\n    | StandardSchemaV1.SuccessResult<TExtracted>\n    | StandardSchemaV1.FailureResult => {\n    if (typeof value != `object` || value == null) {\n      return {\n        issues: [\n          {\n            message: `Value must be an object`,\n          },\n        ],\n      }\n    }\n\n    const issues: Array<StandardSchemaV1.Issue> = []\n\n    // Check id field\n    if (!(`id` in value) || typeof (value as any).id != `string`) {\n      issues.push({\n        message: `id field must be a string`,\n        path: [`id`],\n      })\n    }\n\n    // Check each column\n    for (const column of table.columns) {\n      const val = (value as TExtracted)[column.name as keyof TExtracted]\n\n      if (val == null) {\n        continue\n      }\n\n      switch (column.type) {\n        case ColumnType.TEXT:\n          if (typeof val != `string`) {\n            issues.push({\n              message: `${column.name} must be a string or null`,\n              path: [column.name],\n            })\n          }\n          break\n        case ColumnType.INTEGER:\n        case ColumnType.REAL:\n          if (typeof val != `number`) {\n            issues.push({\n              message: `${column.name} must be a number or null`,\n              path: [column.name],\n            })\n          }\n          break\n      }\n    }\n\n    if (issues.length > 0) {\n      return { issues }\n    }\n\n    return { value: { ...value } as TExtracted }\n  }\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: `powersync`,\n      validate,\n      types: {\n        input: {} as TExtracted,\n        output: {} as TExtracted,\n      },\n    },\n  }\n}\n"],"names":["ColumnType"],"mappings":";;;AAsBO,SAAS,qBACd,OAC0C;AAG1C,QAAM,WAAW,CACf,UAGoC;AACpC,QAAI,OAAO,SAAS,YAAY,SAAS,MAAM;AAC7C,aAAO;AAAA,QACL,QAAQ;AAAA,UACN;AAAA,YACE,SAAS;AAAA,UAAA;AAAA,QACX;AAAA,MACF;AAAA,IAEJ;AAEA,UAAM,SAAwC,CAAA;AAG9C,QAAI,EAAE,QAAQ,UAAU,OAAQ,MAAc,MAAM,UAAU;AAC5D,aAAO,KAAK;AAAA,QACV,SAAS;AAAA,QACT,MAAM,CAAC,IAAI;AAAA,MAAA,CACZ;AAAA,IACH;AAGA,eAAW,UAAU,MAAM,SAAS;AAClC,YAAM,MAAO,MAAqB,OAAO,IAAwB;AAEjE,UAAI,OAAO,MAAM;AACf;AAAA,MACF;AAEA,cAAQ,OAAO,MAAA;AAAA,QACb,KAAKA,OAAAA,WAAW;AACd,cAAI,OAAO,OAAO,UAAU;AAC1B,mBAAO,KAAK;AAAA,cACV,SAAS,GAAG,OAAO,IAAI;AAAA,cACvB,MAAM,CAAC,OAAO,IAAI;AAAA,YAAA,CACnB;AAAA,UACH;AACA;AAAA,QACF,KAAKA,OAAAA,WAAW;AAAA,QAChB,KAAKA,OAAAA,WAAW;AACd,cAAI,OAAO,OAAO,UAAU;AAC1B,mBAAO,KAAK;AAAA,cACV,SAAS,GAAG,OAAO,IAAI;AAAA,cACvB,MAAM,CAAC,OAAO,IAAI;AAAA,YAAA,CACnB;AAAA,UACH;AACA;AAAA,MAAA;AAAA,IAEN;AAEA,QAAI,OAAO,SAAS,GAAG;AACrB,aAAO,EAAE,OAAA;AAAA,IACX;AAEA,WAAO,EAAE,OAAO,EAAE,GAAG,QAAM;AAAA,EAC7B;AAEA,SAAO;AAAA,IACL,aAAa;AAAA,MACX,SAAS;AAAA,MACT,QAAQ;AAAA,MACR;AAAA,MACA,OAAO;AAAA,QACL,OAAO,CAAA;AAAA,QACP,QAAQ,CAAA;AAAA,MAAC;AAAA,IACX;AAAA,EACF;AAEJ;;"}

package/dist/cjs/schema.d.cts

@@ -0,0 +1,21 @@
+import { Table } from '@powersync/common';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { ExtractedTable } from './helpers.cjs';
+/**
+ * Converts a PowerSync Table instance to a StandardSchemaV1 schema.
+ * Creates a schema that validates the structure and types of table records
+ * according to the PowerSync table definition.
+ *
+ * @template TTable - The PowerSync schema-typed Table definition
+ * @param table - The PowerSync Table instance to convert
+ * @returns A StandardSchemaV1-compatible schema with proper type validation
+ *
+ * @example
+ * ```typescript
+ * const usersTable = new Table({
+ *   name: column.text,
+ *   age: column.integer
+ * })
+ * ```
+ */
+export declare function convertTableToSchema<TTable extends Table>(table: TTable): StandardSchemaV1<ExtractedTable<TTable>>;

package/dist/cjs/serialization.cjs

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const common = require("@powersync/common");
+function serializeForSQLite(value, tableSchema, customSerializer = {}) {
+  return Object.fromEntries(
+    Object.entries(value).map(([key, value2]) => {
+      const outputType = key == `id` ? common.ColumnType.TEXT : tableSchema.columns.find((column) => column.name == key)?.type;
+      if (!outputType) {
+        throw new Error(`Could not find schema for ${key} column.`);
+      }
+      if (value2 == null) {
+        return [key, value2];
+      }
+      const customTransform = customSerializer[key];
+      if (customTransform) {
+        return [key, customTransform(value2)];
+      }
+      switch (outputType) {
+        case common.ColumnType.TEXT:
+          if (typeof value2 == `string`) {
+            return [key, value2];
+          } else if (value2 instanceof Date) {
+            return [key, value2.toISOString()];
+          } else {
+            return [key, JSON.stringify(value2)];
+          }
+        case common.ColumnType.INTEGER:
+        case common.ColumnType.REAL:
+          if (typeof value2 == `number`) {
+            return [key, value2];
+          } else if (typeof value2 == `boolean`) {
+            return [key, value2 ? 1 : 0];
+          } else {
+            const numberValue = Number(value2);
+            if (isNaN(numberValue)) {
+              throw new Error(
+                `Could not convert ${key}=${value2} to a number for SQLite`
+              );
+            }
+            return [key, numberValue];
+          }
+      }
+    })
+  );
+}
+exports.serializeForSQLite = serializeForSQLite;
+//# sourceMappingURL=serialization.cjs.map

package/dist/cjs/serialization.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.cjs","sources":["../../src/serialization.ts"],"sourcesContent":["import { ColumnType } from \"@powersync/common\"\nimport type { Table } from \"@powersync/common\"\nimport type { CustomSQLiteSerializer } from \"./definitions\"\nimport type {\n  ExtractedTable,\n  ExtractedTableColumns,\n  MapBaseColumnType,\n} from \"./helpers\"\n\n/**\n * Serializes an object for persistence to a SQLite table, mapping its values to appropriate SQLite types.\n *\n * This function takes an object representing a row, a table schema, and an optional custom serializer map.\n * It returns a new object with values transformed to be compatible with SQLite column types.\n *\n * ## Generics\n * - `TOutput`: The shape of the input object, typically matching the row data.\n * - `TTable`: The table schema, which must match the keys of `TOutput`.\n *\n * ## Parameters\n * - `value`: The object to serialize (row data).\n * - `tableSchema`: The schema describing the SQLite table columns and types.\n * - `customSerializer`: An optional map of custom serialization functions for specific keys.\n *\n * ## Behavior\n * - For each key in `value`, finds the corresponding column in `tableSchema`.\n * - If a custom serializer is provided for a key, it is used to transform the value.\n * - Otherwise, values are mapped according to the column type:\n *   - `TEXT`: Strings are passed through; Dates are converted to ISO strings; other types are JSON-stringified.\n *   - `INTEGER`/`REAL`: Numbers are passed through; booleans are mapped to 1/0; other types are coerced to numbers.\n * - Throws if a column type is unknown or a value cannot be converted.\n *\n * ## Returns\n * - An object with the same keys as `value`, with values transformed for SQLite compatibility.\n *\n * ## Errors\n * - Throws if a key in `value` does not exist in the schema.\n * - Throws if a value cannot be converted to the required SQLite type.\n */\nexport function serializeForSQLite<\n  TOutput extends Record<string, unknown>,\n  // The keys should match\n  TTable extends Table<MapBaseColumnType<TOutput>> = Table<\n    MapBaseColumnType<TOutput>\n  >,\n>(\n  value: TOutput,\n  tableSchema: TTable,\n  customSerializer: Partial<\n    CustomSQLiteSerializer<TOutput, ExtractedTableColumns<TTable>>\n  > = {}\n): ExtractedTable<TTable> {\n  return Object.fromEntries(\n    Object.entries(value).map(([key, value]) => {\n      // First get the output schema type\n      const outputType =\n        key == `id`\n          ? ColumnType.TEXT\n          : tableSchema.columns.find((column) => column.name == key)?.type\n      if (!outputType) {\n        throw new Error(`Could not find schema for ${key} column.`)\n      }\n\n      if (value == null) {\n        return [key, value]\n      }\n\n      const customTransform = customSerializer[key]\n      if (customTransform) {\n        return [key, customTransform(value as TOutput[string])]\n      }\n\n      // Map to the output\n      switch (outputType) {\n        case ColumnType.TEXT:\n          if (typeof value == `string`) {\n            return [key, value]\n          } else if (value instanceof Date) {\n            return [key, value.toISOString()]\n          } else {\n            return [key, JSON.stringify(value)]\n          }\n        case ColumnType.INTEGER:\n        case ColumnType.REAL:\n          if (typeof value == `number`) {\n            return [key, value]\n          } else if (typeof value == `boolean`) {\n            return [key, value ? 1 : 0]\n          } else {\n            const numberValue = Number(value)\n            if (isNaN(numberValue)) {\n              throw new Error(\n                `Could not convert ${key}=${value} to a number for SQLite`\n              )\n            }\n            return [key, numberValue]\n          }\n      }\n    })\n  )\n}\n"],"names":["value","ColumnType"],"mappings":";;;AAuCO,SAAS,mBAOd,OACA,aACA,mBAEI,CAAA,GACoB;AACxB,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,KAAKA,MAAK,MAAM;AAE1C,YAAM,aACJ,OAAO,OACHC,OAAAA,WAAW,OACX,YAAY,QAAQ,KAAK,CAAC,WAAW,OAAO,QAAQ,GAAG,GAAG;AAChE,UAAI,CAAC,YAAY;AACf,cAAM,IAAI,MAAM,6BAA6B,GAAG,UAAU;AAAA,MAC5D;AAEA,UAAID,UAAS,MAAM;AACjB,eAAO,CAAC,KAAKA,MAAK;AAAA,MACpB;AAEA,YAAM,kBAAkB,iBAAiB,GAAG;AAC5C,UAAI,iBAAiB;AACnB,eAAO,CAAC,KAAK,gBAAgBA,MAAwB,CAAC;AAAA,MACxD;AAGA,cAAQ,YAAA;AAAA,QACN,KAAKC,OAAAA,WAAW;AACd,cAAI,OAAOD,UAAS,UAAU;AAC5B,mBAAO,CAAC,KAAKA,MAAK;AAAA,UACpB,WAAWA,kBAAiB,MAAM;AAChC,mBAAO,CAAC,KAAKA,OAAM,aAAa;AAAA,UAClC,OAAO;AACL,mBAAO,CAAC,KAAK,KAAK,UAAUA,MAAK,CAAC;AAAA,UACpC;AAAA,QACF,KAAKC,OAAAA,WAAW;AAAA,QAChB,KAAKA,OAAAA,WAAW;AACd,cAAI,OAAOD,UAAS,UAAU;AAC5B,mBAAO,CAAC,KAAKA,MAAK;AAAA,UACpB,WAAW,OAAOA,UAAS,WAAW;AACpC,mBAAO,CAAC,KAAKA,SAAQ,IAAI,CAAC;AAAA,UAC5B,OAAO;AACL,kBAAM,cAAc,OAAOA,MAAK;AAChC,gBAAI,MAAM,WAAW,GAAG;AACtB,oBAAM,IAAI;AAAA,gBACR,qBAAqB,GAAG,IAAIA,MAAK;AAAA,cAAA;AAAA,YAErC;AACA,mBAAO,CAAC,KAAK,WAAW;AAAA,UAC1B;AAAA,MAAA;AAAA,IAEN,CAAC;AAAA,EAAA;AAEL;;"}