Support input schema validations with Zod

Author: stevensJourney

docs/collections/powersync-collection.md

@@ -101,25 +101,29 @@ const documentsCollection = createCollection(
 )
 ```
 
-#### Option 2: Using Schema Validation
+#### Option 2: Using Advanced Schema Validation
 
-TODO
+Additional validations can be performed by supplying a Standard Schema.
 
 ```ts
 import { createCollection } from "@tanstack/react-db"
 import {
   powerSyncCollectionOptions,
   convertPowerSyncSchemaToSpecs,
 } from "@tanstack/powersync-db-collection"
+import { z } from "zod"
 
-// Convert PowerSync schema to TanStack DB schema
-const schemas = convertPowerSyncSchemaToSpecs(APP_SCHEMA)
+// The output of this schema must correspond to the SQLite schema
+const schema = z.object({
+  id: z.string(),
+  name: z.string().min(3, { message: errorMessage }).nullable(),
+})
 
 const documentsCollection = createCollection(
   powerSyncCollectionOptions({
     database: db,
-    tableName: "documents",
-    schema: schemas.documents, // Use schema for runtime type validation
+    table: APP_SCHEMA.props.documents,
+    schema,
   })
 )
 ```

packages/powersync-db-collection/src/definitions.ts

@@ -1,11 +1,7 @@
-import type { ExtractedTable } from "./helpers"
-import type {
-  AbstractPowerSyncDatabase,
-  ColumnsType,
-  Table,
-} from "@powersync/common"
+import type { AbstractPowerSyncDatabase, Table } from "@powersync/common"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { BaseCollectionConfig, CollectionConfig } from "@tanstack/db"
+import type { ExtractedTable } from "./helpers"
 
 /**
  * Configuration interface for PowerSync collection options
@@ -41,14 +37,14 @@ import type { BaseCollectionConfig, CollectionConfig } from "@tanstack/db"
  * ```
  */
 export type PowerSyncCollectionConfig<
-  TableType extends Table<ColumnsType> = Table<ColumnsType>,
+  TTable extends Table = Table,
   TSchema extends StandardSchemaV1 = never,
 > = Omit<
-  BaseCollectionConfig<ExtractedTable<TableType[`columnMap`]>, string, TSchema>,
+  BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>,
   `onInsert` | `onUpdate` | `onDelete` | `getKey`
 > & {
   /** The PowerSync Schema Table definition */
-  table: TableType
+  table: TTable
   /** The PowerSync database instance */
   database: AbstractPowerSyncDatabase
   /**
@@ -78,13 +74,9 @@ export type PowerSyncCollectionMeta = {
 }
 
 export type EnhancedPowerSyncCollectionConfig<
-  TableType extends Table<any> = Table<any>,
+  TTable extends Table = Table,
   TSchema extends StandardSchemaV1 = never,
-> = CollectionConfig<
-  ExtractedTable<TableType[`columnMap`]>,
-  string,
-  TSchema
-> & {
+> = CollectionConfig<ExtractedTable<TTable>, string, TSchema> & {
   id?: string
   utils: PowerSyncCollectionUtils
   schema?: TSchema

packages/powersync-db-collection/src/helpers.ts

@@ -1,5 +1,5 @@
 import { DiffTriggerOperation } from "@powersync/common"
-import type { ColumnsType, ExtractColumnValueType } from "@powersync/common"
+import type { ExtractColumnValueType, Table } from "@powersync/common"
 
 /**
  * All PowerSync table records have a uuid `id` column.
@@ -20,12 +20,14 @@ export type PowerSyncRecord = {
  *   name: column.text,
  *   age: column.integer
  * })
- * type TableType = ExtractedTable<typeof table.columnMap>
+ * type TableType = ExtractedTable<typeof table>
  * // Results in: { name: string | null, age: number | null }
  * ```
  */
-export type ExtractedTable<Columns extends ColumnsType> = {
-  [K in keyof Columns]: ExtractColumnValueType<Columns[K]>
+export type ExtractedTable<TTable extends Table> = {
+  [K in keyof TTable[`columnMap`]]: ExtractColumnValueType<
+    TTable[`columnMap`][K]
+  >
 } & {
   id: string
 }

packages/powersync-db-collection/src/powersync.ts

@@ -4,104 +4,110 @@ import { asPowerSyncRecord, mapOperation } from "./helpers"
 import { PendingOperationStore } from "./PendingOperationStore"
 import { PowerSyncTransactor } from "./PowerSyncTransactor"
 import { convertTableToSchema } from "./schema"
-import type { ExtractedTable } from "./helpers"
-import type { PendingOperation } from "./PendingOperationStore"
+import type { Table, TriggerDiffRecord } from "@powersync/common"
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { CollectionConfig, SyncConfig } from "@tanstack/db"
 import type {
   EnhancedPowerSyncCollectionConfig,
   PowerSyncCollectionConfig,
   PowerSyncCollectionUtils,
 } from "./definitions"
-import type { CollectionConfig, SyncConfig } from "@tanstack/db"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { ColumnsType, Table, TriggerDiffRecord } from "@powersync/common"
+import type { ExtractedTable } from "./helpers"
+import type { PendingOperation } from "./PendingOperationStore"
 
 /**
  * Creates PowerSync collection options for use with a standard Collection
  *
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @template TSchema - The schema type for validation and type inference (second priority)
+ * @template TTable - The SQLite based typing
+ * @template TSchema - The schema type for validation - optionally supports a custom input type
  * @param config - Configuration options for the PowerSync collection
  * @returns Collection options with utilities
  */
 
-// Overload for when schema is provided
 /**
- * Creates a PowerSync collection configuration with schema validation.
+ * Creates a PowerSync collection configuration with basic default validation.
  *
  * @example
  * ```typescript
- * // With schema validation
  * 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,
- *     schema: TODO
+ *     table: APP_SCHEMA.props.documents
  *   })
  * )
  * ```
  */
-// TODO!!!
-// export function powerSyncCollectionOptions<T extends StandardSchemaV1>(
-//   config: PowerSyncCollectionConfig<InferSchemaOutput<T>, T>
-// ): CollectionConfig<InferSchemaOutput<T>, string, T> & {
-//   schema: T
-//   utils: PowerSyncCollectionUtils
-// }
+export function powerSyncCollectionOptions<TTable extends Table = Table>(
+  config: PowerSyncCollectionConfig<TTable, never>
+): CollectionConfig<ExtractedTable<TTable>, string, never> & {
+  utils: PowerSyncCollectionUtils
+}
 
+// Overload for when schema is provided
 /**
- * Creates a PowerSync collection configuration without schema validation.
+ * Creates a PowerSync collection configuration with schema validation.
  *
  * @example
  * ```typescript
+ * import { z } from "zod"
+ *
+ * // The PowerSync SQLite Schema
  * 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,
+ * // 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(),
+ *    name: z.string().min(3, { message: "Should be at least 3 characters" }).nullable(),
  * })
  *
  * const collection = createCollection(
  *   powerSyncCollectionOptions({
  *     database: db,
- *     table: APP_SCHEMA.props.documents
+ *     table: APP_SCHEMA.props.documents,
+ *     schema
  *   })
  * )
  * ```
  */
 export function powerSyncCollectionOptions<
-  TableType extends Table<ColumnsType> = Table<ColumnsType>,
+  TTable extends Table,
+  TSchema extends StandardSchemaV1<ExtractedTable<TTable>, any>,
 >(
-  config: PowerSyncCollectionConfig<TableType> & {
-    schema?: never
-  }
-): CollectionConfig<ExtractedTable<TableType[`columnMap`]>, string> & {
-  schema?: never
+  config: PowerSyncCollectionConfig<TTable, TSchema>
+): CollectionConfig<ExtractedTable<TTable>, string, TSchema> & {
   utils: PowerSyncCollectionUtils
+  schema: TSchema
 }
 
 /**
  * Implementation of powerSyncCollectionOptions that handles both schema and non-schema configurations.
  */
 export function powerSyncCollectionOptions<
-  TableType extends Table<ColumnsType> = Table<ColumnsType>,
+  TTable extends Table = Table,
   TSchema extends StandardSchemaV1 = never,
 >(
-  config: PowerSyncCollectionConfig<TableType, TSchema>
-): EnhancedPowerSyncCollectionConfig<TableType, TSchema> {
+  config: PowerSyncCollectionConfig<TTable, TSchema>
+): EnhancedPowerSyncCollectionConfig<TTable, TSchema> {
   const {
     database,
     table,
@@ -110,7 +116,7 @@ export function powerSyncCollectionOptions<
     ...restConfig
   } = config
 
-  type RecordType = ExtractedTable<TableType[`columnMap`]>
+  type RecordType = ExtractedTable<TTable>
   const { viewName } = table
 
   // We can do basic runtime validations for columns if not explicit schema has been provided
@@ -277,7 +283,7 @@ export function powerSyncCollectionOptions<
 
   const getKey = (record: RecordType) => asPowerSyncRecord(record).id
 
-  const outputConfig: EnhancedPowerSyncCollectionConfig<TableType, TSchema> = {
+  const outputConfig: EnhancedPowerSyncCollectionConfig<TTable, TSchema> = {
     ...restConfig,
     schema,
     getKey,
@@ -286,7 +292,6 @@ export function powerSyncCollectionOptions<
     sync,
     onInsert: async (params) => {
       // The transaction here should only ever contain a single insert mutation
-      params.transaction
       return await transactor.applyTransaction(params.transaction)
     },
     onUpdate: async (params) => {

packages/powersync-db-collection/tests/powersync.test.ts

@@ -15,6 +15,7 @@ import {
   liveQueryCollectionOptions,
 } from "@tanstack/db"
 import { describe, expect, it, onTestFinished, vi } from "vitest"
+import { z } from "zod"
 import { powerSyncCollectionOptions } from "../src"
 import { PowerSyncTransactor } from "../src/PowerSyncTransactor"
 import type { AbstractPowerSyncDatabase } from "@powersync/node"
@@ -102,6 +103,58 @@ describe(`PowerSync Integration`, () => {
         }
       }
     })
+
+    it(`should allow for advanced validations`, async () => {
+      const db = await createDatabase()
+
+      const errorMessage = `Name must be at least 3 characters`
+      const schema = z.object({
+        id: z.string(),
+        name: z.string().min(3, { message: errorMessage }).nullable(),
+      })
+
+      const collection = createCollection(
+        powerSyncCollectionOptions({
+          database: db,
+          table: APP_SCHEMA.props.documents,
+          schema,
+        })
+      )
+      onTestFinished(() => collection.cleanup())
+
+      try {
+        collection.insert({
+          id: randomUUID(),
+          name: `2`,
+        })
+        expect.fail(`Should throw a validation error`)
+      } catch (ex) {
+        expect(ex instanceof SchemaValidationError).true
+        if (ex instanceof SchemaValidationError) {
+          console.log(ex)
+          expect(ex.message).contains(errorMessage)
+        }
+      }
+
+      collection.insert({
+        id: randomUUID(),
+        name: null,
+      })
+
+      expect(collection.size).eq(1)
+
+      // should validate inputs
+      try {
+        collection.insert({} as any)
+        console.log(`failed`)
+      } catch (ex) {
+        expect(ex instanceof SchemaValidationError).true
+        if (ex instanceof SchemaValidationError) {
+          console.log(ex)
+          expect(ex.message).contains(`Required - path: id`)
+        }
+      }
+    })
   })
 
   describe(`sync`, () => {