Schemas Step 1: Infer types from PowerSync schema table.

stevensJourney · stevensJourney · commit 8d489e955618 · 2025-10-21T13:59:39.000+02:00
diff --git a/docs/collections/powersync-collection.md b/docs/collections/powersync-collection.md
@@ -85,22 +85,26 @@ db.connect(new Connector())
 
 There are two ways to create a collection: using type inference or using schema validation.
 
-#### Option 1: Using Type Inference
+#### Option 1: Using Table Type Inference
+
+The collection types are automatically inferred from the PowerSync Schema Table definition. The table is used to construct a default StandardSchema validator which is used internally to validate collection data and operations.
 
 ```ts
 import { createCollection } from "@tanstack/react-db"
 import { powerSyncCollectionOptions } from "@tanstack/powersync-db-collection"
 
 const documentsCollection = createCollection(
-  powerSyncCollectionOptions<Document>({
+  powerSyncCollectionOptions({
     database: db,
-    tableName: "documents",
+    table: APP_SCHEMA.props.documents,
   })
 )
 ```
 
 #### Option 2: Using Schema Validation
 
+TODO
+
 ```ts
 import { createCollection } from "@tanstack/react-db"
 import {
diff --git a/packages/powersync-db-collection/package.json b/packages/powersync-db-collection/package.json
@@ -10,11 +10,11 @@
     "p-defer": "^4.0.1"
   },
   "peerDependencies": {
-    "@powersync/common": "^1.39.0"
+    "@powersync/common": "0.0.0-dev-20251021113138"
   },
   "devDependencies": {
-    "@powersync/common": "0.0.0-dev-20251003085035",
-    "@powersync/node": "0.0.0-dev-20251003085035",
+    "@powersync/common": "0.0.0-dev-20251021113138",
+    "@powersync/node": "0.0.0-dev-20251021113138",
     "@types/debug": "^4.1.12",
     "@vitest/coverage-istanbul": "^3.2.4"
   },
diff --git a/packages/powersync-db-collection/src/definitions.ts b/packages/powersync-db-collection/src/definitions.ts
@@ -1,4 +1,9 @@
-import type { AbstractPowerSyncDatabase } from "@powersync/common"
+import type { ExtractedTable } from "./helpers"
+import type {
+  AbstractPowerSyncDatabase,
+  ColumnsType,
+  Table,
+} from "@powersync/common"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { BaseCollectionConfig, CollectionConfig } from "@tanstack/db"
 
@@ -36,14 +41,14 @@ import type { BaseCollectionConfig, CollectionConfig } from "@tanstack/db"
  * ```
  */
 export type PowerSyncCollectionConfig<
-  T extends object = Record<string, unknown>,
+  TableType extends Table<ColumnsType> = Table<ColumnsType>,
   TSchema extends StandardSchemaV1 = never,
 > = Omit<
-  BaseCollectionConfig<T, string, TSchema>,
+  BaseCollectionConfig<ExtractedTable<TableType[`columnMap`]>, string, TSchema>,
   `onInsert` | `onUpdate` | `onDelete` | `getKey`
 > & {
-  /** The name of the table in PowerSync database */
-  tableName: string
+  /** The PowerSync Schema Table definition */
+  table: TableType
   /** The PowerSync database instance */
   database: AbstractPowerSyncDatabase
   /**
@@ -73,9 +78,13 @@ export type PowerSyncCollectionMeta = {
 }
 
 export type EnhancedPowerSyncCollectionConfig<
-  T extends object = Record<string, unknown>,
+  TableType extends Table<any> = Table<any>,
   TSchema extends StandardSchemaV1 = never,
-> = CollectionConfig<T, string, TSchema> & {
+> = CollectionConfig<
+  ExtractedTable<TableType[`columnMap`]>,
+  string,
+  TSchema
+> & {
   id?: string
   utils: PowerSyncCollectionUtils
   schema?: TSchema
diff --git a/packages/powersync-db-collection/src/helpers.ts b/packages/powersync-db-collection/src/helpers.ts
@@ -1,4 +1,5 @@
 import { DiffTriggerOperation } from "@powersync/common"
+import type { ColumnsType, ExtractColumnValueType } from "@powersync/common"
 
 /**
  * All PowerSync table records have a uuid `id` column.
@@ -8,6 +9,27 @@ export type PowerSyncRecord = {
   [key: string]: unknown
 }
 
+/**
+ * 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 Columns - The ColumnsType definition containing column configurations
+ * @example
+ * ```typescript
+ * const table = new Table({
+ *   name: column.text,
+ *   age: column.integer
+ * })
+ * type TableType = ExtractedTable<typeof table.columnMap>
+ * // Results in: { name: string | null, age: number | null }
+ * ```
+ */
+export type ExtractedTable<Columns extends ColumnsType> = {
+  [K in keyof Columns]: ExtractColumnValueType<Columns[K]>
+} & {
+  id: string
+}
+
 export function asPowerSyncRecord(record: any): PowerSyncRecord {
   if (typeof record.id !== `string`) {
     throw new Error(`Record must have a string id field`)
diff --git a/packages/powersync-db-collection/src/powersync.ts b/packages/powersync-db-collection/src/powersync.ts
@@ -3,19 +3,17 @@ import { DEFAULT_BATCH_SIZE } from "./definitions"
 import { asPowerSyncRecord, mapOperation } from "./helpers"
 import { PendingOperationStore } from "./PendingOperationStore"
 import { PowerSyncTransactor } from "./PowerSyncTransactor"
-import type { TriggerDiffRecord } from "@powersync/common"
-import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type {
-  CollectionConfig,
-  InferSchemaOutput,
-  SyncConfig,
-} from "@tanstack/db"
+import { convertTableToSchema } from "./schema"
+import type { ExtractedTable } from "./helpers"
+import type { PendingOperation } from "./PendingOperationStore"
 import type {
   EnhancedPowerSyncCollectionConfig,
   PowerSyncCollectionConfig,
   PowerSyncCollectionUtils,
 } from "./definitions"
-import type { PendingOperation } from "./PendingOperationStore"
+import type { CollectionConfig, SyncConfig } from "@tanstack/db"
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { ColumnsType, Table, TriggerDiffRecord } from "@powersync/common"
 
 /**
  * Creates PowerSync collection options for use with a standard Collection
@@ -42,18 +40,19 @@ import type { PendingOperation } from "./PendingOperationStore"
  * const collection = createCollection(
  *   powerSyncCollectionOptions({
  *     database: db,
- *     tableName: "documents",
- *     schema: APP_SCHEMA,
+ *     table: APP_SCHEMA.props.documents,
+ *     schema: TODO
  *   })
  * )
  * ```
  */
-export function powerSyncCollectionOptions<T extends StandardSchemaV1>(
-  config: PowerSyncCollectionConfig<InferSchemaOutput<T>, T>
-): CollectionConfig<InferSchemaOutput<T>, string, T> & {
-  schema: T
-  utils: PowerSyncCollectionUtils
-}
+// TODO!!!
+// export function powerSyncCollectionOptions<T extends StandardSchemaV1>(
+//   config: PowerSyncCollectionConfig<InferSchemaOutput<T>, T>
+// ): CollectionConfig<InferSchemaOutput<T>, string, T> & {
+//   schema: T
+//   utils: PowerSyncCollectionUtils
+// }
 
 /**
  * Creates a PowerSync collection configuration without schema validation.
@@ -76,18 +75,20 @@ export function powerSyncCollectionOptions<T extends StandardSchemaV1>(
  * })
  *
  * const collection = createCollection(
- *   powerSyncCollectionOptions<Document>({
+ *   powerSyncCollectionOptions({
  *     database: db,
- *     tableName: "documents",
+ *     table: APP_SCHEMA.props.documents
  *   })
  * )
  * ```
  */
-export function powerSyncCollectionOptions<T extends object>(
-  config: PowerSyncCollectionConfig<T> & {
+export function powerSyncCollectionOptions<
+  TableType extends Table<ColumnsType> = Table<ColumnsType>,
+>(
+  config: PowerSyncCollectionConfig<TableType> & {
     schema?: never
   }
-): CollectionConfig<T, string> & {
+): CollectionConfig<ExtractedTable<TableType[`columnMap`]>, string> & {
   schema?: never
   utils: PowerSyncCollectionUtils
 }
@@ -96,18 +97,24 @@ export function powerSyncCollectionOptions<T extends object>(
  * Implementation of powerSyncCollectionOptions that handles both schema and non-schema configurations.
  */
 export function powerSyncCollectionOptions<
-  T extends object = Record<string, unknown>,
+  TableType extends Table<ColumnsType> = Table<ColumnsType>,
   TSchema extends StandardSchemaV1 = never,
 >(
-  config: PowerSyncCollectionConfig<T, TSchema>
-): EnhancedPowerSyncCollectionConfig<T, TSchema> {
+  config: PowerSyncCollectionConfig<TableType, TSchema>
+): EnhancedPowerSyncCollectionConfig<TableType, TSchema> {
   const {
     database,
-    tableName,
+    table,
+    schema: inputSchema,
     syncBatchSize = DEFAULT_BATCH_SIZE,
     ...restConfig
   } = config
 
+  type RecordType = ExtractedTable<TableType[`columnMap`]>
+  const { viewName } = table
+
+  // We can do basic runtime validations for columns if not explicit schema has been provided
+  const schema = inputSchema ?? (convertTableToSchema(table) as TSchema)
   /**
    * The onInsert, onUpdate, onDelete handlers should only return
    * after we have written the changes to Tanstack DB.
@@ -120,13 +127,13 @@ export function powerSyncCollectionOptions<
    */
   const pendingOperationStore = PendingOperationStore.GLOBAL
   // Keep the tracked table unique in case of multiple tabs.
-  const trackedTableName = `__${tableName}_tracking_${Math.floor(
+  const trackedTableName = `__${viewName}_tracking_${Math.floor(
     Math.random() * 0xffffffff
   )
     .toString(16)
     .padStart(8, `0`)}`
 
-  const transactor = new PowerSyncTransactor<T>({
+  const transactor = new PowerSyncTransactor<RecordType>({
     database,
   })
 
@@ -135,15 +142,15 @@ export function powerSyncCollectionOptions<
    * Notice that this describes the Sync between the local SQLite table
    * and the in-memory tanstack-db collection.
    */
-  const sync: SyncConfig<T, string> = {
+  const sync: SyncConfig<RecordType, string> = {
     sync: (params) => {
       const { begin, write, commit, markReady } = params
       const abortController = new AbortController()
 
       // The sync function needs to be synchronous
       async function start() {
         database.logger.info(
-          `Sync is starting for ${tableName} into ${trackedTableName}`
+          `Sync is starting for ${viewName} into ${trackedTableName}`
         )
         database.onChangeWithCallback(
           {
@@ -175,7 +182,7 @@ export function powerSyncCollectionOptions<
                       id,
                       operation,
                       timestamp,
-                      tableName,
+                      tableName: viewName,
                     })
                   }
 
@@ -201,7 +208,7 @@ export function powerSyncCollectionOptions<
         )
 
         const disposeTracking = await database.triggers.createDiffTrigger({
-          source: tableName,
+          source: viewName,
           destination: trackedTableName,
           when: {
             [DiffTriggerOperation.INSERT]: `TRUE`,
@@ -214,8 +221,8 @@ export function powerSyncCollectionOptions<
               let cursor = 0
               while (currentBatchCount == syncBatchSize) {
                 begin()
-                const batchItems = await context.getAll<T>(
-                  sanitizeSQL`SELECT * FROM ${tableName} LIMIT ? OFFSET ?`,
+                const batchItems = await context.getAll<RecordType>(
+                  sanitizeSQL`SELECT * FROM ${viewName} LIMIT ? OFFSET ?`,
                   [syncBatchSize, cursor]
                 )
                 currentBatchCount = batchItems.length
@@ -230,7 +237,7 @@ export function powerSyncCollectionOptions<
               }
               markReady()
               database.logger.info(
-                `Sync is ready for ${tableName} into ${trackedTableName}`
+                `Sync is ready for ${viewName} into ${trackedTableName}`
               )
             },
           },
@@ -252,14 +259,14 @@ export function powerSyncCollectionOptions<
 
       start().catch((error) =>
         database.logger.error(
-          `Could not start syncing process for ${tableName} into ${trackedTableName}`,
+          `Could not start syncing process for ${viewName} into ${trackedTableName}`,
           error
         )
       )
 
       return () => {
         database.logger.info(
-          `Sync has been stopped for ${tableName} into ${trackedTableName}`
+          `Sync has been stopped for ${viewName} into ${trackedTableName}`
         )
         abortController.abort()
       }
@@ -268,16 +275,18 @@ export function powerSyncCollectionOptions<
     getSyncMetadata: undefined,
   }
 
-  const getKey = (record: T) => asPowerSyncRecord(record).id
+  const getKey = (record: RecordType) => asPowerSyncRecord(record).id
 
-  const outputConfig: EnhancedPowerSyncCollectionConfig<T, TSchema> = {
+  const outputConfig: EnhancedPowerSyncCollectionConfig<TableType, TSchema> = {
     ...restConfig,
+    schema,
     getKey,
     // Syncing should start immediately since we need to monitor the changes for mutations
     startSync: true,
     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) => {
@@ -290,7 +299,7 @@ export function powerSyncCollectionOptions<
     },
     utils: {
       getMeta: () => ({
-        tableName,
+        tableName: viewName,
         trackedTableName,
       }),
     },
diff --git a/packages/powersync-db-collection/src/schema.ts b/packages/powersync-db-collection/src/schema.ts
@@ -1,32 +1,7 @@
 import { ColumnType } from "@powersync/common"
-import type {
-  ColumnsType,
-  ExtractColumnValueType,
-  Schema,
-  Table,
-} from "@powersync/common"
+import type { ColumnsType, Schema, Table } from "@powersync/common"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
-
-/**
- * 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 Columns - The ColumnsType definition containing column configurations
- * @example
- * ```typescript
- * const table = new Table({
- *   name: column.text,
- *   age: column.integer
- * })
- * type TableType = ExtractedTable<typeof table.columnMap>
- * // Results in: { name: string | null, age: number | null }
- * ```
- */
-type ExtractedTable<Columns extends ColumnsType> = {
-  [K in keyof Columns]: ExtractColumnValueType<Columns[K]>
-} & {
-  id: string
-}
+import type { ExtractedTable } from "./helpers"
 
 /**
  * Converts a PowerSync Table instance to a StandardSchemaV1 schema.
diff --git a/packages/powersync-db-collection/tests/powersync.test.ts b/packages/powersync-db-collection/tests/powersync.test.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
