Update doc comments. Code cleanup.

Author: stevensJourney

docs/collections/powersync-collection.md

@@ -44,8 +44,6 @@ const APP_SCHEMA = new Schema({
   }),
 })
 
-type Document = (typeof APP_SCHEMA)["types"]["documents"]
-
 // Initialize PowerSync database
 const db = new PowerSyncDatabase({
   database: {
@@ -87,7 +85,7 @@ There are two ways to create a collection: using type inference or using schema
 
 #### 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.
+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 operations.
 
 ```ts
 import { createCollection } from "@tanstack/react-db"
@@ -103,7 +101,7 @@ const documentsCollection = createCollection(
 
 #### Option 2: Using Advanced Schema Validation
 
-Additional validations can be performed by supplying a Standard Schema.
+Additional validations can be performed by supplying a Standard Schema. The typing of the validator is constrained to match the typing of the SQLite table.
 
 ```ts
 import { createCollection } from "@tanstack/react-db"
@@ -128,8 +126,6 @@ const documentsCollection = createCollection(
 )
 ```
 
-With schema validation, the collection will validate all inputs at runtime to ensure they match the PowerSync schema types. This provides an extra layer of type safety beyond TypeScript's compile-time checks.
-
 ## Features
 
 ### Offline-First

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

@@ -2,10 +2,10 @@ import { sanitizeSQL } from "@powersync/common"
 import DebugModule from "debug"
 import { PendingOperationStore } from "./PendingOperationStore"
 import { asPowerSyncRecord, mapOperationToPowerSync } from "./helpers"
-import type { AbstractPowerSyncDatabase, LockContext } from "@powersync/common"
-import type { PendingMutation, Transaction } from "@tanstack/db"
-import type { PendingOperation } from "./PendingOperationStore"
 import type { EnhancedPowerSyncCollectionConfig } from "./definitions"
+import type { PendingOperation } from "./PendingOperationStore"
+import type { PendingMutation, Transaction } from "@tanstack/db"
+import type { AbstractPowerSyncDatabase, LockContext } from "@powersync/common"
 
 const debug = DebugModule.debug(`ts/db:powersync`)
 
@@ -24,7 +24,7 @@ export type TransactorOptions = {
  * const collection = createCollection(
  *   powerSyncCollectionOptions<Document>({
  *     database: db,
- *     tableName: "documents",
+ *     table: APP_SCHEMA.props.documents,
  *   })
  * )
  *
@@ -239,15 +239,17 @@ export class PowerSyncTransactor<T extends object = Record<string, unknown>> {
     waitForCompletion: boolean,
     handler: (tableName: string, mutation: PendingMutation<T>) => Promise<void>
   ): Promise<PendingOperation | null> {
-    const { tableName, trackedTableName } = (
-      mutation.collection.config as EnhancedPowerSyncCollectionConfig
-    ).utils.getMeta()
-
-    if (!tableName) {
+    if (
+      typeof (mutation.collection.config as any).utils?.getMeta != `function`
+    ) {
       throw new Error(`Could not get tableName from mutation's collection config.
         The provided mutation might not have originated from PowerSync.`)
     }
 
+    const { tableName, trackedTableName } = (
+      mutation.collection.config as unknown as EnhancedPowerSyncCollectionConfig
+    ).utils.getMeta()
+
     await handler(sanitizeSQL`${tableName}`, mutation)
 
     if (!waitForCompletion) {

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

@@ -5,7 +5,7 @@ import type { ExtractedTable } from "./helpers"
 
 /**
  * Configuration interface for PowerSync collection options
- * @template T - The type of items in the collection
+ * @template TTable - The PowerSync table schema definition
  * @template TSchema - The schema type for validation
  */
 /**
@@ -19,8 +19,6 @@ import type { ExtractedTable } from "./helpers"
  *   }),
  * })
  *
- * type Document = (typeof APP_SCHEMA)["types"]["documents"]
- *
  * const db = new PowerSyncDatabase({
  *   database: {
  *     dbFilename: "test.sqlite",
@@ -29,9 +27,9 @@ import type { ExtractedTable } from "./helpers"
  * })
  *
  * const collection = createCollection(
- *   powerSyncCollectionOptions<Document>({
+ *   powerSyncCollectionOptions({
  *     database: db,
- *     tableName: "documents",
+ *     table: APP_SCHEMA.props.documents
  *   })
  * )
  * ```
@@ -62,6 +60,9 @@ export type PowerSyncCollectionConfig<
   syncBatchSize?: number
 }
 
+/**
+ * Meta data for the PowerSync Collection
+ */
 export type PowerSyncCollectionMeta = {
   /**
    * The SQLite table representing the collection.
@@ -73,6 +74,9 @@ export type PowerSyncCollectionMeta = {
   trackedTableName: string
 }
 
+/**
+ * A CollectionConfig which includes utilities for PowerSync
+ */
 export type EnhancedPowerSyncCollectionConfig<
   TTable extends Table = Table,
   TSchema extends StandardSchemaV1 = never,
@@ -82,6 +86,9 @@ export type EnhancedPowerSyncCollectionConfig<
   schema?: TSchema
 }
 
+/**
+ * Collection level utilities for PowerSync
+ */
 export type PowerSyncCollectionUtils = {
   getMeta: () => PowerSyncCollectionMeta
 }

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

@@ -9,11 +9,23 @@ export type PowerSyncRecord = {
   [key: string]: unknown
 }
 
+/**
+ * Utility type: If T includes null, add undefined.
+ * PowerSync records typically are typed as `string | null`, where insert
+ * and update operations 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]
+}
+
 /**
  * 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
+ * @template TTable - The PowerSync table definition
  * @example
  * ```typescript
  * const table = new Table({
@@ -24,11 +36,11 @@ export type PowerSyncRecord = {
  * // Results in: { name: string | null, age: number | null }
  * ```
  */
-export type ExtractedTable<TTable extends Table> = {
-  [K in keyof TTable[`columnMap`]]: ExtractColumnValueType<
-    TTable[`columnMap`][K]
+export type ExtractedTable<TTable extends Table> = OptionalIfUndefined<{
+  [K in keyof TTable[`columnMap`]]: WithUndefinedIfNull<
+    ExtractColumnValueType<TTable[`columnMap`][K]>
   >
-} & {
+}> & {
   id: string
 }
 

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

@@ -1,4 +1,3 @@
 export * from "./definitions"
 export * from "./powersync"
 export * from "./PowerSyncTransactor"
-export * from "./schema"

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

@@ -1,5 +1,5 @@
 import { ColumnType } from "@powersync/common"
-import type { ColumnsType, Schema, Table } from "@powersync/common"
+import type { Table } from "@powersync/common"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { ExtractedTable } from "./helpers"
 
@@ -8,7 +8,7 @@ import type { ExtractedTable } from "./helpers"
  * Creates a schema that validates the structure and types of table records
  * according to the PowerSync table definition.
  *
- * @template Columns - The ColumnsType definition containing column configurations
+ * @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
  *
@@ -18,26 +18,17 @@ import type { ExtractedTable } from "./helpers"
  *   name: column.text,
  *   age: column.integer
  * })
- *
- * const schema = convertTableToSchema(usersTable)
- * // Now you can use this schema with powerSyncCollectionOptions
- * const collection = createCollection(
- *   powerSyncCollectionOptions({
- *     database: db,
- *     tableName: "users",
- *     schema: schema
- *   })
- * )
  * ```
  */
-export function convertTableToSchema<Columns extends ColumnsType>(
-  table: Table<Columns>
-): StandardSchemaV1<ExtractedTable<Columns>> {
+export function convertTableToSchema<TTable extends Table>(
+  table: TTable
+): StandardSchemaV1<ExtractedTable<TTable>> {
+  type TExtracted = ExtractedTable<TTable>
   // Create validate function that checks types according to column definitions
   const validate = (
     value: unknown
   ):
-    | StandardSchemaV1.SuccessResult<ExtractedTable<Columns>>
+    | StandardSchemaV1.SuccessResult<TExtracted>
     | StandardSchemaV1.FailureResult => {
     if (typeof value != `object` || value == null) {
       return {
@@ -61,7 +52,7 @@ export function convertTableToSchema<Columns extends ColumnsType>(
 
     // Check each column
     for (const column of table.columns) {
-      const val = (value as ExtractedTable<Columns>)[column.name]
+      const val = (value as TExtracted)[column.name as keyof TExtracted]
 
       if (val == null) {
         continue
@@ -92,7 +83,7 @@ export function convertTableToSchema<Columns extends ColumnsType>(
       return { issues }
     }
 
-    return { value: { ...value } as ExtractedTable<Columns> }
+    return { value: { ...value } as TExtracted }
   }
 
   return {
@@ -101,72 +92,9 @@ export function convertTableToSchema<Columns extends ColumnsType>(
       vendor: `powersync`,
       validate,
       types: {
-        input: {} as ExtractedTable<Columns>,
-        output: {} as ExtractedTable<Columns>,
+        input: {} as TExtracted,
+        output: {} as TExtracted,
       },
     },
   }
 }
-
-/**
- * Converts an entire PowerSync Schema (containing multiple tables) into a collection of StandardSchemaV1 schemas.
- * Each table in the schema is converted to its own StandardSchemaV1 schema while preserving all type information.
- *
- * @template Tables - A record type mapping table names to their Table definitions
- * @param schema - The PowerSync Schema containing multiple table definitions
- * @returns An object where each key is a table name and each value is that table's StandardSchemaV1 schema
- *
- * @example
- * ```typescript
- * const mySchema = new Schema({
- *   users: new Table({
- *     name: column.text,
- *     age: column.integer
- *   }),
- *   posts: new Table({
- *     title: column.text,
- *     views: column.integer
- *   })
- * })
- *
- * const standardizedSchemas = convertSchemaToSpecs(mySchema)
- * // Result has type:
- * // {
- * //   users: StandardSchemaV1<{ name: string | null, age: number | null }>,
- * //   posts: StandardSchemaV1<{ title: string | null, views: number | null }>
- * // }
- *
- * // Can be used with collections:
- * const usersCollection = createCollection(
- *   powerSyncCollectionOptions({
- *     database: db,
- *     tableName: "users",
- *     schema: standardizedSchemas.users
- *   })
- * )
- * ```
- */
-export function convertPowerSyncSchemaToSpecs<
-  Tables extends Record<string, Table<ColumnsType>>,
->(
-  schema: Schema<Tables>
-): {
-  [TableName in keyof Tables]: StandardSchemaV1<
-    ExtractedTable<Tables[TableName][`columnMap`]>
-  >
-} {
-  // Create a map to store the standardized schemas
-  const standardizedSchemas = {} as {
-    [TableName in keyof Tables]: StandardSchemaV1<
-      ExtractedTable<Tables[TableName][`columnMap`]>
-    >
-  }
-
-  // Iterate through each table in the schema
-  schema.tables.forEach((table) => {
-    // Convert each table to a StandardSchemaV1 and store it in the result map
-    ;(standardizedSchemas as any)[table.name] = convertTableToSchema(table)
-  })
-
-  return standardizedSchemas
-}

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

@@ -27,6 +27,7 @@ const APP_SCHEMA = new Schema({
   documents: new Table(
     {
       name: column.text,
+      author: column.text,
     },
     { viewName: `documents` }
   ),
@@ -110,7 +111,11 @@ describe(`PowerSync Integration`, () => {
       const errorMessage = `Name must be at least 3 characters`
       const schema = z.object({
         id: z.string(),
-        name: z.string().min(3, { message: errorMessage }).nullable(),
+        name: z
+          .string()
+          .min(3, { message: errorMessage })
+          .nullable()
+          .optional(),
       })
 
       const collection = createCollection(
@@ -258,12 +263,14 @@ describe(`PowerSync Integration`, () => {
       const tx = collection.insert({
         id,
         name: `new`,
+        author: `somebody`,
       })
 
       // The insert should optimistically update the collection
       const newDoc = collection.get(id)
       expect(newDoc).toBeDefined()
       expect(newDoc!.name).toBe(`new`)
+      expect(newDoc!.author).toBe(`somebody`)
 
       await tx.isPersisted.promise
       // The item should now be present in PowerSync
@@ -276,6 +283,8 @@ describe(`PowerSync Integration`, () => {
       const updatedDoc = collection.get(id)
       expect(updatedDoc).toBeDefined()
       expect(updatedDoc!.name).toBe(`updatedNew`)
+      // Only the updated field should be updated
+      expect(updatedDoc!.author).toBe(`somebody`)
 
       await collection.delete(id).isPersisted.promise
 
@@ -511,7 +520,7 @@ describe(`PowerSync Integration`, () => {
     })
   })
 
-  describe(`Multiple Clients`, async () => {
+  describe(`Multiple Clients`, () => {
     it(`should sync updates between multiple clients`, async () => {
       const db = await createDatabase()
 
@@ -535,7 +544,7 @@ describe(`PowerSync Integration`, () => {
     })
   })
 
-  describe(`Lifecycle`, async () => {
+  describe(`Lifecycle`, () => {
     it(`should cleanup resources`, async () => {
       const db = await createDatabase()
       const collectionOptions = powerSyncCollectionOptions({