@tanstack/db 0.0.11 → 0.0.12

package/src/types.ts

@@ -3,6 +3,39 @@ import type { Collection } from "./collection"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { Transaction } from "./transactions"
 
+/**
+ * Helper type to extract the output type from a standard schema
+ *
+ * @internal This is used by the type resolution system
+ */
+export type InferSchemaOutput<T> = T extends StandardSchemaV1
+  ? StandardSchemaV1.InferOutput<T> extends object
+    ? StandardSchemaV1.InferOutput<T>
+    : Record<string, unknown>
+  : Record<string, unknown>
+
+/**
+ * Helper type to determine the final type based on priority:
+ * 1. Explicit generic TExplicit (if not 'unknown')
+ * 2. Schema output type (if schema provided)
+ * 3. Fallback type TFallback
+ *
+ * @remarks
+ * This type is used internally to resolve the collection item type based on the provided generics and schema.
+ * Users should not need to use this type directly, but understanding the priority order helps when defining collections.
+ */
+export type ResolveType<
+  TExplicit,
+  TSchema extends StandardSchemaV1 = never,
+  TFallback extends object = Record<string, unknown>,
+> = unknown extends TExplicit
+  ? [TSchema] extends [never]
+    ? TFallback
+    : InferSchemaOutput<TSchema>
+  : TExplicit extends object
+    ? TExplicit
+    : Record<string, unknown>
+
 export type TransactionState = `pending` | `persisting` | `completed` | `failed`
 
 /**
@@ -19,11 +52,18 @@ export type UtilsRecord = Record<string, Fn>
  * Represents a pending mutation within a transaction
  * Contains information about the original and modified data, as well as metadata
  */
-export interface PendingMutation<T extends object = Record<string, unknown>> {
+export interface PendingMutation<
+  T extends object = Record<string, unknown>,
+  TOperation extends OperationType = OperationType,
+> {
   mutationId: string
-  original: Partial<T>
+  original: TOperation extends `insert` ? {} : T
   modified: T
-  changes: Partial<T>
+  changes: TOperation extends `insert`
+    ? T
+    : TOperation extends `delete`
+      ? T
+      : Partial<T>
   globalKey: string
   key: any
   type: OperationType
@@ -56,8 +96,9 @@ export type NonEmptyArray<T> = [T, ...Array<T>]
  */
 export type TransactionWithMutations<
   T extends object = Record<string, unknown>,
+  TOperation extends OperationType = OperationType,
 > = Transaction<T> & {
-  mutations: NonEmptyArray<PendingMutation<T>>
+  mutations: NonEmptyArray<PendingMutation<T, TOperation>>
 }
 
 export interface TransactionConfig<T extends object = Record<string, unknown>> {
@@ -148,15 +189,43 @@ export interface InsertConfig {
   metadata?: Record<string, unknown>
 }
 
+export type UpdateMutationFnParams<T extends object = Record<string, unknown>> =
+  {
+    transaction: TransactionWithMutations<T, `update`>
+  }
+
+export type InsertMutationFnParams<T extends object = Record<string, unknown>> =
+  {
+    transaction: TransactionWithMutations<T, `insert`>
+  }
+
+export type DeleteMutationFnParams<T extends object = Record<string, unknown>> =
+  {
+    transaction: TransactionWithMutations<T, `delete`>
+  }
+
+export type InsertMutationFn<T extends object = Record<string, unknown>> = (
+  params: InsertMutationFnParams<T>
+) => Promise<any>
+
+export type UpdateMutationFn<T extends object = Record<string, unknown>> = (
+  params: UpdateMutationFnParams<T>
+) => Promise<any>
+
+export type DeleteMutationFn<T extends object = Record<string, unknown>> = (
+  params: DeleteMutationFnParams<T>
+) => Promise<any>
+
 export interface CollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
 > {
   // If an id isn't passed in, a UUID will be
   // generated for it.
   id?: string
   sync: SyncConfig<T, TKey>
-  schema?: StandardSchema<T>
+  schema?: TSchema
   /**
    * Function to extract the ID from an object
    * This is required for update/delete operations which now only accept IDs
@@ -172,19 +241,19 @@ export interface CollectionConfig<
    * @param params Object containing transaction and mutation information
    * @returns Promise resolving to any value
    */
-  onInsert?: MutationFn<T>
+  onInsert?: InsertMutationFn<T>
   /**
    * Optional asynchronous handler function called before an update operation
    * @param params Object containing transaction and mutation information
    * @returns Promise resolving to any value
    */
-  onUpdate?: MutationFn<T>
+  onUpdate?: UpdateMutationFn<T>
   /**
    * Optional asynchronous handler function called before a delete operation
    * @param params Object containing transaction and mutation information
    * @returns Promise resolving to any value
    */
-  onDelete?: MutationFn<T>
+  onDelete?: DeleteMutationFn<T>
 }
 
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<