@tanstack/db 0.4.6 → 0.4.8

package/src/local-only.ts

@@ -1,14 +1,19 @@
 import type {
   BaseCollectionConfig,
   CollectionConfig,
+  DeleteMutationFn,
   DeleteMutationFnParams,
   InferSchemaOutput,
+  InsertMutationFn,
   InsertMutationFnParams,
   OperationType,
+  PendingMutation,
   SyncConfig,
+  UpdateMutationFn,
   UpdateMutationFnParams,
   UtilsRecord,
 } from "./types"
+import type { Collection } from "./collection/index"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 
 /**
@@ -33,9 +38,44 @@ export interface LocalOnlyCollectionConfig<
 }
 
 /**
- * Local-only collection utilities type (currently empty but matches the pattern)
+ * Local-only collection utilities type
  */
-export interface LocalOnlyCollectionUtils extends UtilsRecord {}
+export interface LocalOnlyCollectionUtils extends UtilsRecord {
+  /**
+   * Accepts mutations from a transaction that belong to this collection and persists them.
+   * This should be called in your transaction's mutationFn to persist local-only data.
+   *
+   * @param transaction - The transaction containing mutations to accept
+   * @example
+   * const localData = createCollection(localOnlyCollectionOptions({...}))
+   *
+   * const tx = createTransaction({
+   *   mutationFn: async ({ transaction }) => {
+   *     // Make API call first
+   *     await api.save(...)
+   *     // Then persist local-only mutations after success
+   *     localData.utils.acceptMutations(transaction)
+   *   }
+   * })
+   */
+  acceptMutations: (transaction: {
+    mutations: Array<PendingMutation<Record<string, unknown>>>
+  }) => void
+}
+
+type LocalOnlyCollectionOptionsResult<
+  T extends object,
+  TKey extends string | number,
+  TSchema extends StandardSchemaV1 | never = never,
+> = Omit<
+  CollectionConfig<T, TKey, TSchema>,
+  `onInsert` | `onUpdate` | `onDelete`
+> & {
+  onInsert?: InsertMutationFn<T, TKey, LocalOnlyCollectionUtils>
+  onUpdate?: UpdateMutationFn<T, TKey, LocalOnlyCollectionUtils>
+  onDelete?: DeleteMutationFn<T, TKey, LocalOnlyCollectionUtils>
+  utils: LocalOnlyCollectionUtils
+}
 
 /**
  * Creates Local-only collection options for use with a standard Collection
@@ -44,10 +84,16 @@ export interface LocalOnlyCollectionUtils extends UtilsRecord {}
  * that immediately "syncs" all optimistic changes to the collection, making them permanent.
  * Perfect for local-only data that doesn't need persistence or external synchronization.
  *
+ * **Using with Manual Transactions:**
+ *
+ * For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
+ * to persist changes made during `tx.mutate()`. This is necessary because local-only collections
+ * don't participate in the standard mutation handler flow for manual transactions.
+ *
  * @template T - The schema type if a schema is provided, otherwise the type of items in the collection
  * @template TKey - The type of the key returned by getKey
  * @param config - Configuration options for the Local-only collection
- * @returns Collection options with utilities (currently empty but follows the pattern)
+ * @returns Collection options with utilities including acceptMutations
  *
  * @example
  * // Basic local-only collection
@@ -80,6 +126,32 @@ export interface LocalOnlyCollectionUtils extends UtilsRecord {}
  *     },
  *   })
  * )
+ *
+ * @example
+ * // Using with manual transactions
+ * const localData = createCollection(
+ *   localOnlyCollectionOptions({
+ *     getKey: (item) => item.id,
+ *   })
+ * )
+ *
+ * const tx = createTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     // Use local data in API call
+ *     const localMutations = transaction.mutations.filter(m => m.collection === localData)
+ *     await api.save({ metadata: localMutations[0]?.modified })
+ *
+ *     // Persist local-only mutations after API success
+ *     localData.utils.acceptMutations(transaction)
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   localData.insert({ id: 1, data: 'metadata' })
+ *   apiCollection.insert({ id: 2, data: 'main data' })
+ * })
+ *
+ * await tx.commit()
  */
 
 // Overload for when schema is provided
@@ -90,8 +162,7 @@ export function localOnlyCollectionOptions<
   config: LocalOnlyCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
     schema: T
   }
-): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
-  utils: LocalOnlyCollectionUtils
+): LocalOnlyCollectionOptionsResult<InferSchemaOutput<T>, TKey, T> & {
   schema: T
 }
 
@@ -104,15 +175,17 @@ export function localOnlyCollectionOptions<
   config: LocalOnlyCollectionConfig<T, never, TKey> & {
     schema?: never // prohibit schema
   }
-): CollectionConfig<T, TKey> & {
-  utils: LocalOnlyCollectionUtils
+): LocalOnlyCollectionOptionsResult<T, TKey> & {
   schema?: never // no schema in the result
 }
 
-export function localOnlyCollectionOptions(
-  config: LocalOnlyCollectionConfig<any, any, string | number>
-): CollectionConfig<any, string | number, any> & {
-  utils: LocalOnlyCollectionUtils
+export function localOnlyCollectionOptions<
+  T extends object = object,
+  TSchema extends StandardSchemaV1 = never,
+  TKey extends string | number = string | number,
+>(
+  config: LocalOnlyCollectionConfig<T, TSchema, TKey>
+): LocalOnlyCollectionOptionsResult<T, TKey, TSchema> & {
   schema?: StandardSchemaV1
 } {
   const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config
@@ -125,11 +198,7 @@ export function localOnlyCollectionOptions(
    * Wraps the user's onInsert handler to also confirm the transaction immediately
    */
   const wrappedOnInsert = async (
-    params: InsertMutationFnParams<
-      any,
-      string | number,
-      LocalOnlyCollectionUtils
-    >
+    params: InsertMutationFnParams<T, TKey, LocalOnlyCollectionUtils>
   ) => {
     // Call user handler first if provided
     let handlerResult
@@ -147,11 +216,7 @@ export function localOnlyCollectionOptions(
    * Wrapper for onUpdate handler that also confirms the transaction immediately
    */
   const wrappedOnUpdate = async (
-    params: UpdateMutationFnParams<
-      any,
-      string | number,
-      LocalOnlyCollectionUtils
-    >
+    params: UpdateMutationFnParams<T, TKey, LocalOnlyCollectionUtils>
   ) => {
     // Call user handler first if provided
     let handlerResult
@@ -169,11 +234,7 @@ export function localOnlyCollectionOptions(
    * Wrapper for onDelete handler that also confirms the transaction immediately
    */
   const wrappedOnDelete = async (
-    params: DeleteMutationFnParams<
-      any,
-      string | number,
-      LocalOnlyCollectionUtils
-    >
+    params: DeleteMutationFnParams<T, TKey, LocalOnlyCollectionUtils>
   ) => {
     // Call user handler first if provided
     let handlerResult
@@ -187,13 +248,38 @@ export function localOnlyCollectionOptions(
     return handlerResult
   }
 
+  /**
+   * Accepts mutations from a transaction that belong to this collection and persists them
+   */
+  const acceptMutations = (transaction: {
+    mutations: Array<PendingMutation<Record<string, unknown>>>
+  }) => {
+    // Filter mutations that belong to this collection
+    const collectionMutations = transaction.mutations.filter(
+      (m) =>
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        m.collection === syncResult.collection
+    )
+
+    if (collectionMutations.length === 0) {
+      return
+    }
+
+    // Persist the mutations through sync
+    syncResult.confirmOperationsSync(
+      collectionMutations as Array<PendingMutation<T>>
+    )
+  }
+
   return {
     ...restConfig,
     sync: syncResult.sync,
     onInsert: wrappedOnInsert,
     onUpdate: wrappedOnUpdate,
     onDelete: wrappedOnDelete,
-    utils: {} as LocalOnlyCollectionUtils,
+    utils: {
+      acceptMutations,
+    } as LocalOnlyCollectionUtils,
     startSync: true,
     gcTime: 0,
   }
@@ -212,11 +298,12 @@ export function localOnlyCollectionOptions(
 function createLocalOnlySync<T extends object, TKey extends string | number>(
   initialData?: Array<T>
 ) {
-  // Capture sync functions for transaction confirmation
+  // Capture sync functions and collection for transaction confirmation
   let syncBegin: (() => void) | null = null
   let syncWrite: ((message: { type: OperationType; value: T }) => void) | null =
     null
   let syncCommit: (() => void) | null = null
+  let collection: Collection<T, TKey, LocalOnlyCollectionUtils> | null = null
 
   const sync: SyncConfig<T, TKey> = {
     /**
@@ -227,10 +314,11 @@ function createLocalOnlySync<T extends object, TKey extends string | number>(
     sync: (params) => {
       const { begin, write, commit, markReady } = params
 
-      // Capture sync functions for later use by confirmOperationsSync
+      // Capture sync functions and collection for later use
       syncBegin = begin
       syncWrite = write
       syncCommit = commit
+      collection = params.collection
 
       // Apply initial data if provided
       if (initialData && initialData.length > 0) {
@@ -265,7 +353,7 @@ function createLocalOnlySync<T extends object, TKey extends string | number>(
    *
    * @param mutations - Array of mutation objects from the transaction
    */
-  const confirmOperationsSync = (mutations: Array<any>) => {
+  const confirmOperationsSync = (mutations: Array<PendingMutation<T>>) => {
     if (!syncBegin || !syncWrite || !syncCommit) {
       return // Sync not initialized yet, which is fine
     }
@@ -286,5 +374,6 @@ function createLocalOnlySync<T extends object, TKey extends string | number>(
   return {
     sync,
     confirmOperationsSync,
+    collection,
   }
 }

package/src/local-storage.ts

@@ -12,6 +12,7 @@ import type {
   DeleteMutationFnParams,
   InferSchemaOutput,
   InsertMutationFnParams,
+  PendingMutation,
   SyncConfig,
   UpdateMutationFnParams,
   UtilsRecord,
@@ -90,6 +91,26 @@ export type GetStorageSizeFn = () => number
 export interface LocalStorageCollectionUtils extends UtilsRecord {
   clearStorage: ClearStorageFn
   getStorageSize: GetStorageSizeFn
+  /**
+   * Accepts mutations from a transaction that belong to this collection and persists them to localStorage.
+   * This should be called in your transaction's mutationFn to persist local-storage data.
+   *
+   * @param transaction - The transaction containing mutations to accept
+   * @example
+   * const localSettings = createCollection(localStorageCollectionOptions({...}))
+   *
+   * const tx = createTransaction({
+   *   mutationFn: async ({ transaction }) => {
+   *     // Make API call first
+   *     await api.save(...)
+   *     // Then persist local-storage mutations after success
+   *     localSettings.utils.acceptMutations(transaction)
+   *   }
+   * })
+   */
+  acceptMutations: (transaction: {
+    mutations: Array<PendingMutation<Record<string, unknown>>>
+  }) => void
 }
 
 /**
@@ -123,11 +144,17 @@ function generateUuid(): string {
  * This function creates a collection that persists data to localStorage/sessionStorage
  * and synchronizes changes across browser tabs using storage events.
  *
+ * **Using with Manual Transactions:**
+ *
+ * For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
+ * to persist changes made during `tx.mutate()`. This is necessary because local-storage collections
+ * don't participate in the standard mutation handler flow for manual transactions.
+ *
  * @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 TFallback - The fallback type if no explicit or schema type is provided
  * @param config - Configuration options for the localStorage collection
- * @returns Collection options with utilities including clearStorage and getStorageSize
+ * @returns Collection options with utilities including clearStorage, getStorageSize, and acceptMutations
  *
  * @example
  * // Basic localStorage collection
@@ -159,6 +186,33 @@ function generateUuid(): string {
  *     },
  *   })
  * )
+ *
+ * @example
+ * // Using with manual transactions
+ * const localSettings = createCollection(
+ *   localStorageCollectionOptions({
+ *     storageKey: 'user-settings',
+ *     getKey: (item) => item.id,
+ *   })
+ * )
+ *
+ * const tx = createTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     // Use settings data in API call
+ *     const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)
+ *     await api.updateUserProfile({ settings: settingsMutations[0]?.modified })
+ *
+ *     // Persist local-storage mutations after API success
+ *     localSettings.utils.acceptMutations(transaction)
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   localSettings.insert({ id: 'theme', value: 'dark' })
+ *   apiCollection.insert({ id: 2, data: 'profile data' })
+ * })
+ *
+ * await tx.commit()
  */
 
 // Overload for when schema is provided
@@ -397,6 +451,76 @@ export function localStorageCollectionOptions(
   // Default id to a pattern based on storage key if not provided
   const collectionId = id ?? `local-collection:${config.storageKey}`
 
+  /**
+   * Accepts mutations from a transaction that belong to this collection and persists them to storage
+   */
+  const acceptMutations = (transaction: {
+    mutations: Array<PendingMutation<Record<string, unknown>>>
+  }) => {
+    // Filter mutations that belong to this collection
+    // Use collection ID for filtering if collection reference isn't available yet
+    const collectionMutations = transaction.mutations.filter((m) => {
+      // Try to match by collection reference first
+      if (sync.collection && m.collection === sync.collection) {
+        return true
+      }
+      // Fall back to matching by collection ID
+      return m.collection.id === collectionId
+    })
+
+    if (collectionMutations.length === 0) {
+      return
+    }
+
+    // Validate all mutations can be serialized before modifying storage
+    for (const mutation of collectionMutations) {
+      switch (mutation.type) {
+        case `insert`:
+        case `update`:
+          validateJsonSerializable(mutation.modified, mutation.type)
+          break
+        case `delete`:
+          validateJsonSerializable(mutation.original, mutation.type)
+          break
+      }
+    }
+
+    // Load current data from storage
+    const currentData = loadFromStorage<Record<string, unknown>>(
+      config.storageKey,
+      storage
+    )
+
+    // Apply each mutation
+    for (const mutation of collectionMutations) {
+      // Use the engine's pre-computed key to avoid key derivation issues
+      const key = mutation.key
+
+      switch (mutation.type) {
+        case `insert`:
+        case `update`: {
+          const storedItem: StoredItem<Record<string, unknown>> = {
+            versionKey: generateUuid(),
+            data: mutation.modified,
+          }
+          currentData.set(key, storedItem)
+          break
+        }
+        case `delete`: {
+          currentData.delete(key)
+          break
+        }
+      }
+    }
+
+    // Save to storage
+    saveToStorage(currentData)
+
+    // Confirm the mutations in the collection to move them from optimistic to synced state
+    // This writes them through the sync interface to make them "synced" instead of "optimistic"
+    sync.confirmOperationsSync(collectionMutations)
+  }
+
   return {
     ...restConfig,
     id: collectionId,
@@ -407,6 +531,7 @@ export function localStorageCollectionOptions(
     utils: {
       clearStorage,
       getStorageSize,
+      acceptMutations,
     },
   }
 }
@@ -480,8 +605,13 @@ function createLocalStorageSync<T extends object>(
   storageEventApi: StorageEventApi,
   _getKey: (item: T) => string | number,
   lastKnownData: Map<string | number, StoredItem<T>>
-): SyncConfig<T> & { manualTrigger?: () => void } {
+): SyncConfig<T> & {
+  manualTrigger?: () => void
+  collection: any
+  confirmOperationsSync: (mutations: Array<any>) => void
+} {
   let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null
+  let collection: any = null
 
   /**
    * Compare two Maps to find differences using version keys
@@ -556,12 +686,16 @@ function createLocalStorageSync<T extends object>(
     }
   }
 
-  const syncConfig: SyncConfig<T> & { manualTrigger?: () => void } = {
+  const syncConfig: SyncConfig<T> & {
+    manualTrigger?: () => void
+    collection: any
+  } = {
     sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {
       const { begin, write, commit, markReady } = params
 
-      // Store sync params for later use
+      // Store sync params and collection for later use
       syncParams = params
+      collection = params.collection
 
       // Initial load
       const initialData = loadFromStorage<T>(storageKey, storage)
@@ -613,7 +747,38 @@ function createLocalStorageSync<T extends object>(
 
     // Manual trigger function for local updates
     manualTrigger: processStorageChanges,
+
+    // Collection instance reference
+    collection,
   }
 
-  return syncConfig
+  /**
+   * Confirms mutations by writing them through the sync interface
+   * This moves mutations from optimistic to synced state
+   * @param mutations - Array of mutation objects to confirm
+   */
+  const confirmOperationsSync = (mutations: Array<any>) => {
+    if (!syncParams) {
+      // Sync not initialized yet, mutations will be handled on next sync
+      return
+    }
+
+    const { begin, write, commit } = syncParams
+
+    // Write the mutations through sync to confirm them
+    begin()
+    mutations.forEach((mutation: any) => {
+      write({
+        type: mutation.type,
+        value:
+          mutation.type === `delete` ? mutation.original : mutation.modified,
+      })
+    })
+    commit()
+  }
+
+  return {
+    ...syncConfig,
+    confirmOperationsSync,
+  }
 }