@tanstack/powersync-db-collection 0.1.30 → 0.1.32

package/dist/cjs/definitions.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.cjs","sources":["../../src/definitions.ts"],"sourcesContent":["import type { AbstractPowerSyncDatabase, Table } from '@powersync/common'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  InferSchemaOutput,\n} from '@tanstack/db'\nimport type {\n  AnyTableColumnType,\n  ExtractedTable,\n  OptionalExtractedTable,\n  PowerSyncRecord,\n} from './helpers'\n\n/**\n * Small helper which determines the output type if:\n * - Standard SQLite types are to be used OR\n * - If the provided schema should be used.\n */\nexport type InferPowerSyncOutputType<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<PowerSyncRecord> = never,\n> = TSchema extends never ? ExtractedTable<TTable> : InferSchemaOutput<TSchema>\n\n/**\n * A mapping type for custom serialization of object properties to SQLite-compatible values.\n *\n * This type allows you to override, for keys in the input object (`TOutput`), a function that transforms\n * the value to the corresponding SQLite type (`TSQLite`). Keys not specified will use the default SQLite serialization.\n *\n * ## Generics\n * - `TOutput`: The input object type, representing the row data to be serialized.\n * - `TSQLite`: The target SQLite-compatible type for each property, typically inferred from the table schema.\n *\n * ## Usage\n * Use this type to define a map of serialization functions for specific keys when you need custom handling\n * (e.g., converting complex objects, formatting dates, or handling enums).\n *\n * Example:\n * ```ts\n * const serializer: CustomSQLiteSerializer<MyRowType, MySQLiteType> = {\n *   createdAt: (date) => date.toISOString(),\n *   status: (status) => status ? 1 : 0,\n *   meta: (meta) => JSON.stringify(meta),\n * };\n * ```\n *\n * ## Behavior\n * - Each key maps to a function that receives the value and returns the SQLite-compatible value.\n * - Used by `serializeForSQLite` to override default serialization for specific columns.\n */\nexport type CustomSQLiteSerializer<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = Partial<{\n  [Key in keyof TOutput]: (\n    value: TOutput[Key],\n  ) => Key extends keyof TSQLite ? TSQLite[Key] : never\n}>\n\nexport type SerializerConfig<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = {\n  /**\n   * Optional partial serializer object for customizing how individual columns are serialized for SQLite.\n   *\n   * This should be a partial map of column keys to serialization functions, following the\n   * {@link CustomSQLiteSerializer} type. Each function receives the column value and returns a value\n   * compatible with SQLite storage.\n   *\n   * If not provided for a column, the default behavior is used:\n   *   - `TEXT`: Strings are stored as-is; Dates are converted to ISO strings; other types are JSON-stringified.\n   *   - `INTEGER`/`REAL`: Numbers are stored as-is; booleans are mapped to 1/0.\n   *\n   * Use this option to override serialization for specific columns, such as formatting dates, handling enums,\n   * or serializing complex objects.\n   *\n   * Example:\n   * ```typescript\n   * serializer: {\n   *   createdAt: (date) => date.getTime(), // Store as timestamp\n   *   meta: (meta) => JSON.stringify(meta), // Custom object serialization\n   * }\n   * ```\n   */\n  serializer?: CustomSQLiteSerializer<TOutput, TSQLite>\n\n  /**\n   * Application logic should ensure that incoming synced data is always valid.\n   * Failing to deserialize and apply incoming changes results in data inconsistency - which is a fatal error.\n   * Use this callback to react to deserialization errors.\n   */\n  onDeserializationError: (error: StandardSchemaV1.FailureResult) => void\n}\n\n/**\n * Config for when TInput and TOutput are both the SQLite types.\n */\nexport type ConfigWithSQLiteTypes = {}\n\n/**\n * Config where TInput is the SQLite types while TOutput can be defined by TSchema.\n * We can use the same schema to validate TInput and incoming SQLite changes.\n */\nexport type ConfigWithSQLiteInputType<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // TInput is the SQLite types.\n    OptionalExtractedTable<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n}\n\n/**\n * Config where TInput and TOutput have arbitrarily typed values.\n * The keys of the types need to equal the SQLite types.\n * Since TInput is not the SQLite types, we require a schema in order to deserialize incoming SQLite updates. The schema should validate from SQLite to TOutput.\n */\nexport type ConfigWithArbitraryCollectionTypes<\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> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n  /**\n   * Schema for deserializing and validating input data from the sync stream.\n   *\n   * This schema defines how to transform and validate data coming from SQLite types (as stored in the database)\n   * into the desired output types (`TOutput`) expected by your application or validation logic.\n   *\n   * The generic parameters allow for arbitrary input and output types, so you can specify custom conversion rules\n   * for each column. This is especially useful when your application expects richer types (e.g., Date, enums, objects)\n   * than what SQLite natively supports.\n   *\n   * Use this to ensure that incoming data from the sync stream is properly converted and validated before use.\n   *\n   * Example:\n   * ```typescript\n   * deserializationSchema: z.object({\n   *   createdAt: z.preprocess((val) => new Date(val as string), z.date()),\n   *   meta: z.preprocess((val) => JSON.parse(val as string), z.object({ ... })),\n   * })\n   * ```\n   *\n   * This enables robust type safety and validation for incoming data, bridging the gap between SQLite storage\n   * and your application's expected types.\n   */\n  deserializationSchema: StandardSchemaV1<\n    ExtractedTable<TTable>,\n    StandardSchemaV1.InferOutput<TSchema>\n  >\n}\nexport type BasePowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1 = never,\n> = Omit<\n  BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>,\n  `onInsert` | `onUpdate` | `onDelete` | `getKey`\n> & {\n  /** The PowerSync schema Table definition */\n  table: TTable\n  /** The PowerSync database instance */\n  database: AbstractPowerSyncDatabase\n  /**\n   * The maximum number of documents to read from the SQLite table\n   * in a single batch during the initial sync between PowerSync and the\n   * in-memory TanStack DB collection.\n   *\n   * @remarks\n   * - Defaults to {@link DEFAULT_BATCH_SIZE} if not specified.\n   * - Larger values reduce the number of round trips to the storage\n   *   engine but increase memory usage per batch.\n   * - Smaller values may lower memory usage and allow earlier\n   *   streaming of initial results, at the cost of more query calls.\n   */\n  syncBatchSize?: number\n}\n\n/**\n * Configuration interface for PowerSync collection options.\n * @template TTable - The PowerSync table schema definition\n * @template TSchema - The validation schema type\n */\n/**\n * Configuration options for creating a PowerSync collection.\n *\n * @example\n * ```typescript\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *   }),\n * })\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 type PowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<any> = never,\n> = BasePowerSyncCollectionConfig<TTable, TSchema> &\n  (\n    | ConfigWithSQLiteTypes\n    | ConfigWithSQLiteInputType<TTable, TSchema>\n    | ConfigWithArbitraryCollectionTypes<TTable, TSchema>\n  )\n\n/**\n * Metadata for the PowerSync Collection.\n */\nexport type PowerSyncCollectionMeta<TTable extends Table = Table> = {\n  /**\n   * The SQLite table representing the collection.\n   */\n  tableName: string\n  /**\n   * The internal table used to track diffs for the collection.\n   */\n  trackedTableName: string\n\n  /**\n   * Serializes a collection value to the SQLite type\n   */\n  serializeValue: (value: any) => ExtractedTable<TTable>\n\n  /**\n   * Whether the PowerSync table tracks metadata.\n   */\n  metadataIsTracked: boolean\n}\n\n/**\n * A CollectionConfig which includes utilities for PowerSync.\n */\nexport type EnhancedPowerSyncCollectionConfig<\n  TTable extends Table,\n  OutputType extends Record<string, unknown> = Record<string, unknown>,\n  TSchema extends StandardSchemaV1 = never,\n> = CollectionConfig<OutputType, string, TSchema> & {\n  id?: string\n  utils: PowerSyncCollectionUtils<TTable>\n  schema?: TSchema\n}\n\n/**\n * Collection-level utilities for PowerSync.\n */\nexport type PowerSyncCollectionUtils<TTable extends Table = Table> = {\n  getMeta: () => PowerSyncCollectionMeta<TTable>\n}\n\n/**\n * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}.\n */\nexport const DEFAULT_BATCH_SIZE = 1000\n"],"names":[],"mappings":";;AAsRO,MAAM,qBAAqB;;"}
+{"version":3,"file":"definitions.cjs","sources":["../../src/definitions.ts"],"sourcesContent":["import type { AbstractPowerSyncDatabase, Table } from '@powersync/common'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  InferSchemaOutput,\n} from '@tanstack/db'\nimport type {\n  AnyTableColumnType,\n  ExtractedTable,\n  OptionalExtractedTable,\n  PowerSyncRecord,\n} from './helpers'\n\n/**\n * Small helper which determines the output type if:\n * - Standard SQLite types are to be used OR\n * - If the provided schema should be used.\n */\nexport type InferPowerSyncOutputType<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<PowerSyncRecord> = never,\n> = TSchema extends never ? ExtractedTable<TTable> : InferSchemaOutput<TSchema>\n\n/**\n * A mapping type for custom serialization of object properties to SQLite-compatible values.\n *\n * This type allows you to override, for keys in the input object (`TOutput`), a function that transforms\n * the value to the corresponding SQLite type (`TSQLite`). Keys not specified will use the default SQLite serialization.\n *\n * ## Generics\n * - `TOutput`: The input object type, representing the row data to be serialized.\n * - `TSQLite`: The target SQLite-compatible type for each property, typically inferred from the table schema.\n *\n * ## Usage\n * Use this type to define a map of serialization functions for specific keys when you need custom handling\n * (e.g., converting complex objects, formatting dates, or handling enums).\n *\n * Example:\n * ```ts\n * const serializer: CustomSQLiteSerializer<MyRowType, MySQLiteType> = {\n *   createdAt: (date) => date.toISOString(),\n *   status: (status) => status ? 1 : 0,\n *   meta: (meta) => JSON.stringify(meta),\n * };\n * ```\n *\n * ## Behavior\n * - Each key maps to a function that receives the value and returns the SQLite-compatible value.\n * - Used by `serializeForSQLite` to override default serialization for specific columns.\n */\nexport type CustomSQLiteSerializer<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = Partial<{\n  [Key in keyof TOutput]: (\n    value: TOutput[Key],\n  ) => Key extends keyof TSQLite ? TSQLite[Key] : never\n}>\n\nexport type SerializerConfig<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = {\n  /**\n   * Optional partial serializer object for customizing how individual columns are serialized for SQLite.\n   *\n   * This should be a partial map of column keys to serialization functions, following the\n   * {@link CustomSQLiteSerializer} type. Each function receives the column value and returns a value\n   * compatible with SQLite storage.\n   *\n   * If not provided for a column, the default behavior is used:\n   *   - `TEXT`: Strings are stored as-is; Dates are converted to ISO strings; other types are JSON-stringified.\n   *   - `INTEGER`/`REAL`: Numbers are stored as-is; booleans are mapped to 1/0.\n   *\n   * Use this option to override serialization for specific columns, such as formatting dates, handling enums,\n   * or serializing complex objects.\n   *\n   * Example:\n   * ```typescript\n   * serializer: {\n   *   createdAt: (date) => date.getTime(), // Store as timestamp\n   *   meta: (meta) => JSON.stringify(meta), // Custom object serialization\n   * }\n   * ```\n   */\n  serializer?: CustomSQLiteSerializer<TOutput, TSQLite>\n\n  /**\n   * Application logic should ensure that incoming synced data is always valid.\n   * Failing to deserialize and apply incoming changes results in data inconsistency - which is a fatal error.\n   * Use this callback to react to deserialization errors.\n   */\n  onDeserializationError: (error: StandardSchemaV1.FailureResult) => void\n}\n\n/**\n * Config for when TInput and TOutput are both the SQLite types.\n */\nexport type ConfigWithSQLiteTypes = {}\n\n/**\n * Config where TInput is the SQLite types while TOutput can be defined by TSchema.\n * We can use the same schema to validate TInput and incoming SQLite changes.\n */\nexport type ConfigWithSQLiteInputType<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // TInput is the SQLite types.\n    OptionalExtractedTable<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n}\n\n/**\n * Config where TInput and TOutput have arbitrarily typed values.\n * The keys of the types need to equal the SQLite types.\n * Since TInput is not the SQLite types, we require a schema in order to deserialize incoming SQLite updates. The schema should validate from SQLite to TOutput.\n */\nexport type ConfigWithArbitraryCollectionTypes<\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> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n  /**\n   * Schema for deserializing and validating input data from the sync stream.\n   *\n   * This schema defines how to transform and validate data coming from SQLite types (as stored in the database)\n   * into the desired output types (`TOutput`) expected by your application or validation logic.\n   *\n   * The generic parameters allow for arbitrary input and output types, so you can specify custom conversion rules\n   * for each column. This is especially useful when your application expects richer types (e.g., Date, enums, objects)\n   * than what SQLite natively supports.\n   *\n   * Use this to ensure that incoming data from the sync stream is properly converted and validated before use.\n   *\n   * Example:\n   * ```typescript\n   * deserializationSchema: z.object({\n   *   createdAt: z.preprocess((val) => new Date(val as string), z.date()),\n   *   meta: z.preprocess((val) => JSON.parse(val as string), z.object({ ... })),\n   * })\n   * ```\n   *\n   * This enables robust type safety and validation for incoming data, bridging the gap between SQLite storage\n   * and your application's expected types.\n   */\n  deserializationSchema: StandardSchemaV1<\n    ExtractedTable<TTable>,\n    StandardSchemaV1.InferOutput<TSchema>\n  >\n}\nexport type BasePowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1 = never,\n> = Omit<\n  BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>,\n  `onInsert` | `onUpdate` | `onDelete` | `getKey`\n> & {\n  /** The PowerSync schema Table definition */\n  table: TTable\n  /** The PowerSync database instance */\n  database: AbstractPowerSyncDatabase\n  /**\n   * The maximum number of documents to read from the SQLite table\n   * in a single batch during the initial sync between PowerSync and the\n   * in-memory TanStack DB collection.\n   *\n   * @remarks\n   * - Defaults to {@link DEFAULT_BATCH_SIZE} if not specified.\n   * - Larger values reduce the number of round trips to the storage\n   *   engine but increase memory usage per batch.\n   * - Smaller values may lower memory usage and allow earlier\n   *   streaming of initial results, at the cost of more query calls.\n   */\n  syncBatchSize?: number\n}\n\n/**\n * Configuration interface for PowerSync collection options.\n * @template TTable - The PowerSync table schema definition\n * @template TSchema - The validation schema type\n */\n/**\n * Configuration options for creating a PowerSync collection.\n *\n * @example\n * ```typescript\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *   }),\n * })\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 type PowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<any> = never,\n> = BasePowerSyncCollectionConfig<TTable, TSchema> &\n  (\n    | ConfigWithSQLiteTypes\n    | ConfigWithSQLiteInputType<TTable, TSchema>\n    | ConfigWithArbitraryCollectionTypes<TTable, TSchema>\n  )\n\n/**\n * Metadata for the PowerSync Collection.\n */\nexport type PowerSyncCollectionMeta<TTable extends Table = Table> = {\n  /**\n   * The SQLite table representing the collection.\n   */\n  tableName: string\n  /**\n   * The internal table used to track diffs for the collection.\n   */\n  trackedTableName: string\n\n  /**\n   * Serializes a collection value to the SQLite type\n   */\n  serializeValue: (value: any) => ExtractedTable<TTable>\n\n  /**\n   * Whether the PowerSync table tracks metadata.\n   */\n  metadataIsTracked: boolean\n}\n\n/**\n * A CollectionConfig which includes utilities for PowerSync.\n */\nexport type EnhancedPowerSyncCollectionConfig<\n  TTable extends Table,\n  OutputType extends Record<string, unknown> = Record<string, unknown>,\n  TSchema extends StandardSchemaV1 = never,\n> = CollectionConfig<\n  OutputType,\n  string,\n  TSchema,\n  PowerSyncCollectionUtils<TTable>\n> & {\n  id?: string\n  utils: PowerSyncCollectionUtils<TTable>\n  schema?: TSchema\n}\n\n/**\n * Collection-level utilities for PowerSync.\n */\nexport type PowerSyncCollectionUtils<TTable extends Table = Table> = {\n  getMeta: () => PowerSyncCollectionMeta<TTable>\n}\n\n/**\n * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}.\n */\nexport const DEFAULT_BATCH_SIZE = 1000\n"],"names":[],"mappings":";;AA2RO,MAAM,qBAAqB;;"}

package/dist/cjs/definitions.d.cts

@@ -187,7 +187,7 @@ export type PowerSyncCollectionMeta<TTable extends Table = Table> = {
 /**
  * A CollectionConfig which includes utilities for PowerSync.
  */
-export type EnhancedPowerSyncCollectionConfig<TTable extends Table, OutputType extends Record<string, unknown> = Record<string, unknown>, TSchema extends StandardSchemaV1 = never> = CollectionConfig<OutputType, string, TSchema> & {
+export type EnhancedPowerSyncCollectionConfig<TTable extends Table, OutputType extends Record<string, unknown> = Record<string, unknown>, TSchema extends StandardSchemaV1 = never> = CollectionConfig<OutputType, string, TSchema, PowerSyncCollectionUtils<TTable>> & {
     id?: string;
     utils: PowerSyncCollectionUtils<TTable>;
     schema?: TSchema;

package/dist/esm/definitions.d.ts

@@ -187,7 +187,7 @@ export type PowerSyncCollectionMeta<TTable extends Table = Table> = {
 /**
  * A CollectionConfig which includes utilities for PowerSync.
  */
-export type EnhancedPowerSyncCollectionConfig<TTable extends Table, OutputType extends Record<string, unknown> = Record<string, unknown>, TSchema extends StandardSchemaV1 = never> = CollectionConfig<OutputType, string, TSchema> & {
+export type EnhancedPowerSyncCollectionConfig<TTable extends Table, OutputType extends Record<string, unknown> = Record<string, unknown>, TSchema extends StandardSchemaV1 = never> = CollectionConfig<OutputType, string, TSchema, PowerSyncCollectionUtils<TTable>> & {
     id?: string;
     utils: PowerSyncCollectionUtils<TTable>;
     schema?: TSchema;

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sources":["../../src/definitions.ts"],"sourcesContent":["import type { AbstractPowerSyncDatabase, Table } from '@powersync/common'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  InferSchemaOutput,\n} from '@tanstack/db'\nimport type {\n  AnyTableColumnType,\n  ExtractedTable,\n  OptionalExtractedTable,\n  PowerSyncRecord,\n} from './helpers'\n\n/**\n * Small helper which determines the output type if:\n * - Standard SQLite types are to be used OR\n * - If the provided schema should be used.\n */\nexport type InferPowerSyncOutputType<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<PowerSyncRecord> = never,\n> = TSchema extends never ? ExtractedTable<TTable> : InferSchemaOutput<TSchema>\n\n/**\n * A mapping type for custom serialization of object properties to SQLite-compatible values.\n *\n * This type allows you to override, for keys in the input object (`TOutput`), a function that transforms\n * the value to the corresponding SQLite type (`TSQLite`). Keys not specified will use the default SQLite serialization.\n *\n * ## Generics\n * - `TOutput`: The input object type, representing the row data to be serialized.\n * - `TSQLite`: The target SQLite-compatible type for each property, typically inferred from the table schema.\n *\n * ## Usage\n * Use this type to define a map of serialization functions for specific keys when you need custom handling\n * (e.g., converting complex objects, formatting dates, or handling enums).\n *\n * Example:\n * ```ts\n * const serializer: CustomSQLiteSerializer<MyRowType, MySQLiteType> = {\n *   createdAt: (date) => date.toISOString(),\n *   status: (status) => status ? 1 : 0,\n *   meta: (meta) => JSON.stringify(meta),\n * };\n * ```\n *\n * ## Behavior\n * - Each key maps to a function that receives the value and returns the SQLite-compatible value.\n * - Used by `serializeForSQLite` to override default serialization for specific columns.\n */\nexport type CustomSQLiteSerializer<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = Partial<{\n  [Key in keyof TOutput]: (\n    value: TOutput[Key],\n  ) => Key extends keyof TSQLite ? TSQLite[Key] : never\n}>\n\nexport type SerializerConfig<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = {\n  /**\n   * Optional partial serializer object for customizing how individual columns are serialized for SQLite.\n   *\n   * This should be a partial map of column keys to serialization functions, following the\n   * {@link CustomSQLiteSerializer} type. Each function receives the column value and returns a value\n   * compatible with SQLite storage.\n   *\n   * If not provided for a column, the default behavior is used:\n   *   - `TEXT`: Strings are stored as-is; Dates are converted to ISO strings; other types are JSON-stringified.\n   *   - `INTEGER`/`REAL`: Numbers are stored as-is; booleans are mapped to 1/0.\n   *\n   * Use this option to override serialization for specific columns, such as formatting dates, handling enums,\n   * or serializing complex objects.\n   *\n   * Example:\n   * ```typescript\n   * serializer: {\n   *   createdAt: (date) => date.getTime(), // Store as timestamp\n   *   meta: (meta) => JSON.stringify(meta), // Custom object serialization\n   * }\n   * ```\n   */\n  serializer?: CustomSQLiteSerializer<TOutput, TSQLite>\n\n  /**\n   * Application logic should ensure that incoming synced data is always valid.\n   * Failing to deserialize and apply incoming changes results in data inconsistency - which is a fatal error.\n   * Use this callback to react to deserialization errors.\n   */\n  onDeserializationError: (error: StandardSchemaV1.FailureResult) => void\n}\n\n/**\n * Config for when TInput and TOutput are both the SQLite types.\n */\nexport type ConfigWithSQLiteTypes = {}\n\n/**\n * Config where TInput is the SQLite types while TOutput can be defined by TSchema.\n * We can use the same schema to validate TInput and incoming SQLite changes.\n */\nexport type ConfigWithSQLiteInputType<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // TInput is the SQLite types.\n    OptionalExtractedTable<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n}\n\n/**\n * Config where TInput and TOutput have arbitrarily typed values.\n * The keys of the types need to equal the SQLite types.\n * Since TInput is not the SQLite types, we require a schema in order to deserialize incoming SQLite updates. The schema should validate from SQLite to TOutput.\n */\nexport type ConfigWithArbitraryCollectionTypes<\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> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n  /**\n   * Schema for deserializing and validating input data from the sync stream.\n   *\n   * This schema defines how to transform and validate data coming from SQLite types (as stored in the database)\n   * into the desired output types (`TOutput`) expected by your application or validation logic.\n   *\n   * The generic parameters allow for arbitrary input and output types, so you can specify custom conversion rules\n   * for each column. This is especially useful when your application expects richer types (e.g., Date, enums, objects)\n   * than what SQLite natively supports.\n   *\n   * Use this to ensure that incoming data from the sync stream is properly converted and validated before use.\n   *\n   * Example:\n   * ```typescript\n   * deserializationSchema: z.object({\n   *   createdAt: z.preprocess((val) => new Date(val as string), z.date()),\n   *   meta: z.preprocess((val) => JSON.parse(val as string), z.object({ ... })),\n   * })\n   * ```\n   *\n   * This enables robust type safety and validation for incoming data, bridging the gap between SQLite storage\n   * and your application's expected types.\n   */\n  deserializationSchema: StandardSchemaV1<\n    ExtractedTable<TTable>,\n    StandardSchemaV1.InferOutput<TSchema>\n  >\n}\nexport type BasePowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1 = never,\n> = Omit<\n  BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>,\n  `onInsert` | `onUpdate` | `onDelete` | `getKey`\n> & {\n  /** The PowerSync schema Table definition */\n  table: TTable\n  /** The PowerSync database instance */\n  database: AbstractPowerSyncDatabase\n  /**\n   * The maximum number of documents to read from the SQLite table\n   * in a single batch during the initial sync between PowerSync and the\n   * in-memory TanStack DB collection.\n   *\n   * @remarks\n   * - Defaults to {@link DEFAULT_BATCH_SIZE} if not specified.\n   * - Larger values reduce the number of round trips to the storage\n   *   engine but increase memory usage per batch.\n   * - Smaller values may lower memory usage and allow earlier\n   *   streaming of initial results, at the cost of more query calls.\n   */\n  syncBatchSize?: number\n}\n\n/**\n * Configuration interface for PowerSync collection options.\n * @template TTable - The PowerSync table schema definition\n * @template TSchema - The validation schema type\n */\n/**\n * Configuration options for creating a PowerSync collection.\n *\n * @example\n * ```typescript\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *   }),\n * })\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 type PowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<any> = never,\n> = BasePowerSyncCollectionConfig<TTable, TSchema> &\n  (\n    | ConfigWithSQLiteTypes\n    | ConfigWithSQLiteInputType<TTable, TSchema>\n    | ConfigWithArbitraryCollectionTypes<TTable, TSchema>\n  )\n\n/**\n * Metadata for the PowerSync Collection.\n */\nexport type PowerSyncCollectionMeta<TTable extends Table = Table> = {\n  /**\n   * The SQLite table representing the collection.\n   */\n  tableName: string\n  /**\n   * The internal table used to track diffs for the collection.\n   */\n  trackedTableName: string\n\n  /**\n   * Serializes a collection value to the SQLite type\n   */\n  serializeValue: (value: any) => ExtractedTable<TTable>\n\n  /**\n   * Whether the PowerSync table tracks metadata.\n   */\n  metadataIsTracked: boolean\n}\n\n/**\n * A CollectionConfig which includes utilities for PowerSync.\n */\nexport type EnhancedPowerSyncCollectionConfig<\n  TTable extends Table,\n  OutputType extends Record<string, unknown> = Record<string, unknown>,\n  TSchema extends StandardSchemaV1 = never,\n> = CollectionConfig<OutputType, string, TSchema> & {\n  id?: string\n  utils: PowerSyncCollectionUtils<TTable>\n  schema?: TSchema\n}\n\n/**\n * Collection-level utilities for PowerSync.\n */\nexport type PowerSyncCollectionUtils<TTable extends Table = Table> = {\n  getMeta: () => PowerSyncCollectionMeta<TTable>\n}\n\n/**\n * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}.\n */\nexport const DEFAULT_BATCH_SIZE = 1000\n"],"names":[],"mappings":"AAsRO,MAAM,qBAAqB;"}
+{"version":3,"file":"definitions.js","sources":["../../src/definitions.ts"],"sourcesContent":["import type { AbstractPowerSyncDatabase, Table } from '@powersync/common'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  InferSchemaOutput,\n} from '@tanstack/db'\nimport type {\n  AnyTableColumnType,\n  ExtractedTable,\n  OptionalExtractedTable,\n  PowerSyncRecord,\n} from './helpers'\n\n/**\n * Small helper which determines the output type if:\n * - Standard SQLite types are to be used OR\n * - If the provided schema should be used.\n */\nexport type InferPowerSyncOutputType<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<PowerSyncRecord> = never,\n> = TSchema extends never ? ExtractedTable<TTable> : InferSchemaOutput<TSchema>\n\n/**\n * A mapping type for custom serialization of object properties to SQLite-compatible values.\n *\n * This type allows you to override, for keys in the input object (`TOutput`), a function that transforms\n * the value to the corresponding SQLite type (`TSQLite`). Keys not specified will use the default SQLite serialization.\n *\n * ## Generics\n * - `TOutput`: The input object type, representing the row data to be serialized.\n * - `TSQLite`: The target SQLite-compatible type for each property, typically inferred from the table schema.\n *\n * ## Usage\n * Use this type to define a map of serialization functions for specific keys when you need custom handling\n * (e.g., converting complex objects, formatting dates, or handling enums).\n *\n * Example:\n * ```ts\n * const serializer: CustomSQLiteSerializer<MyRowType, MySQLiteType> = {\n *   createdAt: (date) => date.toISOString(),\n *   status: (status) => status ? 1 : 0,\n *   meta: (meta) => JSON.stringify(meta),\n * };\n * ```\n *\n * ## Behavior\n * - Each key maps to a function that receives the value and returns the SQLite-compatible value.\n * - Used by `serializeForSQLite` to override default serialization for specific columns.\n */\nexport type CustomSQLiteSerializer<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = Partial<{\n  [Key in keyof TOutput]: (\n    value: TOutput[Key],\n  ) => Key extends keyof TSQLite ? TSQLite[Key] : never\n}>\n\nexport type SerializerConfig<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = {\n  /**\n   * Optional partial serializer object for customizing how individual columns are serialized for SQLite.\n   *\n   * This should be a partial map of column keys to serialization functions, following the\n   * {@link CustomSQLiteSerializer} type. Each function receives the column value and returns a value\n   * compatible with SQLite storage.\n   *\n   * If not provided for a column, the default behavior is used:\n   *   - `TEXT`: Strings are stored as-is; Dates are converted to ISO strings; other types are JSON-stringified.\n   *   - `INTEGER`/`REAL`: Numbers are stored as-is; booleans are mapped to 1/0.\n   *\n   * Use this option to override serialization for specific columns, such as formatting dates, handling enums,\n   * or serializing complex objects.\n   *\n   * Example:\n   * ```typescript\n   * serializer: {\n   *   createdAt: (date) => date.getTime(), // Store as timestamp\n   *   meta: (meta) => JSON.stringify(meta), // Custom object serialization\n   * }\n   * ```\n   */\n  serializer?: CustomSQLiteSerializer<TOutput, TSQLite>\n\n  /**\n   * Application logic should ensure that incoming synced data is always valid.\n   * Failing to deserialize and apply incoming changes results in data inconsistency - which is a fatal error.\n   * Use this callback to react to deserialization errors.\n   */\n  onDeserializationError: (error: StandardSchemaV1.FailureResult) => void\n}\n\n/**\n * Config for when TInput and TOutput are both the SQLite types.\n */\nexport type ConfigWithSQLiteTypes = {}\n\n/**\n * Config where TInput is the SQLite types while TOutput can be defined by TSchema.\n * We can use the same schema to validate TInput and incoming SQLite changes.\n */\nexport type ConfigWithSQLiteInputType<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // TInput is the SQLite types.\n    OptionalExtractedTable<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n}\n\n/**\n * Config where TInput and TOutput have arbitrarily typed values.\n * The keys of the types need to equal the SQLite types.\n * Since TInput is not the SQLite types, we require a schema in order to deserialize incoming SQLite updates. The schema should validate from SQLite to TOutput.\n */\nexport type ConfigWithArbitraryCollectionTypes<\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> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n  /**\n   * Schema for deserializing and validating input data from the sync stream.\n   *\n   * This schema defines how to transform and validate data coming from SQLite types (as stored in the database)\n   * into the desired output types (`TOutput`) expected by your application or validation logic.\n   *\n   * The generic parameters allow for arbitrary input and output types, so you can specify custom conversion rules\n   * for each column. This is especially useful when your application expects richer types (e.g., Date, enums, objects)\n   * than what SQLite natively supports.\n   *\n   * Use this to ensure that incoming data from the sync stream is properly converted and validated before use.\n   *\n   * Example:\n   * ```typescript\n   * deserializationSchema: z.object({\n   *   createdAt: z.preprocess((val) => new Date(val as string), z.date()),\n   *   meta: z.preprocess((val) => JSON.parse(val as string), z.object({ ... })),\n   * })\n   * ```\n   *\n   * This enables robust type safety and validation for incoming data, bridging the gap between SQLite storage\n   * and your application's expected types.\n   */\n  deserializationSchema: StandardSchemaV1<\n    ExtractedTable<TTable>,\n    StandardSchemaV1.InferOutput<TSchema>\n  >\n}\nexport type BasePowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1 = never,\n> = Omit<\n  BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>,\n  `onInsert` | `onUpdate` | `onDelete` | `getKey`\n> & {\n  /** The PowerSync schema Table definition */\n  table: TTable\n  /** The PowerSync database instance */\n  database: AbstractPowerSyncDatabase\n  /**\n   * The maximum number of documents to read from the SQLite table\n   * in a single batch during the initial sync between PowerSync and the\n   * in-memory TanStack DB collection.\n   *\n   * @remarks\n   * - Defaults to {@link DEFAULT_BATCH_SIZE} if not specified.\n   * - Larger values reduce the number of round trips to the storage\n   *   engine but increase memory usage per batch.\n   * - Smaller values may lower memory usage and allow earlier\n   *   streaming of initial results, at the cost of more query calls.\n   */\n  syncBatchSize?: number\n}\n\n/**\n * Configuration interface for PowerSync collection options.\n * @template TTable - The PowerSync table schema definition\n * @template TSchema - The validation schema type\n */\n/**\n * Configuration options for creating a PowerSync collection.\n *\n * @example\n * ```typescript\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *   }),\n * })\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 type PowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<any> = never,\n> = BasePowerSyncCollectionConfig<TTable, TSchema> &\n  (\n    | ConfigWithSQLiteTypes\n    | ConfigWithSQLiteInputType<TTable, TSchema>\n    | ConfigWithArbitraryCollectionTypes<TTable, TSchema>\n  )\n\n/**\n * Metadata for the PowerSync Collection.\n */\nexport type PowerSyncCollectionMeta<TTable extends Table = Table> = {\n  /**\n   * The SQLite table representing the collection.\n   */\n  tableName: string\n  /**\n   * The internal table used to track diffs for the collection.\n   */\n  trackedTableName: string\n\n  /**\n   * Serializes a collection value to the SQLite type\n   */\n  serializeValue: (value: any) => ExtractedTable<TTable>\n\n  /**\n   * Whether the PowerSync table tracks metadata.\n   */\n  metadataIsTracked: boolean\n}\n\n/**\n * A CollectionConfig which includes utilities for PowerSync.\n */\nexport type EnhancedPowerSyncCollectionConfig<\n  TTable extends Table,\n  OutputType extends Record<string, unknown> = Record<string, unknown>,\n  TSchema extends StandardSchemaV1 = never,\n> = CollectionConfig<\n  OutputType,\n  string,\n  TSchema,\n  PowerSyncCollectionUtils<TTable>\n> & {\n  id?: string\n  utils: PowerSyncCollectionUtils<TTable>\n  schema?: TSchema\n}\n\n/**\n * Collection-level utilities for PowerSync.\n */\nexport type PowerSyncCollectionUtils<TTable extends Table = Table> = {\n  getMeta: () => PowerSyncCollectionMeta<TTable>\n}\n\n/**\n * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}.\n */\nexport const DEFAULT_BATCH_SIZE = 1000\n"],"names":[],"mappings":"AA2RO,MAAM,qBAAqB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/powersync-db-collection",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "PowerSync collection for TanStack DB",
   "author": "POWERSYNC",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "@tanstack/store": "^0.8.0",
     "debug": "^4.4.3",
     "p-defer": "^4.0.1",
-    "@tanstack/db": "0.5.26"
+    "@tanstack/db": "0.5.28"
   },
   "peerDependencies": {
     "@powersync/common": "^1.41.0"

package/src/definitions.ts

@@ -260,7 +260,12 @@ export type EnhancedPowerSyncCollectionConfig<
   TTable extends Table,
   OutputType extends Record<string, unknown> = Record<string, unknown>,
   TSchema extends StandardSchemaV1 = never,
-> = CollectionConfig<OutputType, string, TSchema> & {
+> = CollectionConfig<
+  OutputType,
+  string,
+  TSchema,
+  PowerSyncCollectionUtils<TTable>
+> & {
   id?: string
   utils: PowerSyncCollectionUtils<TTable>
   schema?: TSchema