Feat: Add support for custom parsers/serializers in LocalStorage collections (#730)

* feat(local-storage): add support for custom parsers/serializers

* added changeset

* feat(local-storage): using parser instead of JSON in loadFromStorage

* feat(local-storage): changed argument order in loadFromStorage to respect previous one

* feat(local-storage): exporting parser type

Author: sadkebab

.changeset/cruel-signs-work.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Added support for custom parsers/serializers like superjson in LocalStorage collections

packages/db/package.json

@@ -9,6 +9,7 @@
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.2.4",
     "arktype": "^2.1.23",
+    "superjson": "^2.2.5",
     "temporal-polyfill": "^0.3.0"
   },
   "exports": {

packages/db/src/local-storage.ts

@@ -44,6 +44,11 @@ interface StoredItem<T> {
   data: T
 }
 
+export interface Parser {
+  parse: (data: string) => unknown
+  stringify: (data: unknown) => string
+}
+
 /**
  * Configuration interface for localStorage collection options
  * @template T - The type of items in the collection
@@ -71,6 +76,12 @@ export interface LocalStorageCollectionConfig<
    * Can be any object that implements addEventListener/removeEventListener for storage events
    */
   storageEventApi?: StorageEventApi
+
+  /**
+   * Parser to use for serializing and deserializing data to and from storage
+   * Defaults to JSON
+   */
+  parser?: Parser
 }
 
 /**
@@ -113,13 +124,18 @@ export interface LocalStorageCollectionUtils extends UtilsRecord {
 
 /**
  * Validates that a value can be JSON serialized
+ * @param parser - The parser to use for serialization
  * @param value - The value to validate for JSON serialization
  * @param operation - The operation type being performed (for error messages)
  * @throws Error if the value cannot be JSON serialized
  */
-function validateJsonSerializable(value: any, operation: string): void {
+function validateJsonSerializable(
+  parser: Parser,
+  value: any,
+  operation: string
+): void {
   try {
-    JSON.stringify(value)
+    parser.stringify(value)
   } catch (error) {
     throw new SerializationError(
       operation,
@@ -314,6 +330,9 @@ export function localStorageCollectionOptions(
     (typeof window !== `undefined` ? window : null) ||
     createNoOpStorageEventApi()
 
+  // Default to JSON parser if no parser is provided
+  const parser = config.parser || JSON
+
   // Track the last known state to detect changes
   const lastKnownData = new Map<string | number, StoredItem<any>>()
 
@@ -322,6 +341,7 @@ export function localStorageCollectionOptions(
     config.storageKey,
     storage,
     storageEventApi,
+    parser,
     config.getKey,
     lastKnownData
   )
@@ -349,7 +369,7 @@ export function localStorageCollectionOptions(
       dataMap.forEach((storedItem, key) => {
         objectData[String(key)] = storedItem
       })
-      const serialized = JSON.stringify(objectData)
+      const serialized = parser.stringify(objectData)
       storage.setItem(config.storageKey, serialized)
     } catch (error) {
       console.error(
@@ -383,7 +403,7 @@ export function localStorageCollectionOptions(
   const wrappedOnInsert = async (params: InsertMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
-      validateJsonSerializable(mutation.modified, `insert`)
+      validateJsonSerializable(parser, mutation.modified, `insert`)
     })
 
     // Call the user handler BEFORE persisting changes (if provided)
@@ -394,7 +414,7 @@ export function localStorageCollectionOptions(
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage)
+    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
 
     // Add new items with version keys
     params.transaction.mutations.forEach((mutation) => {
@@ -418,7 +438,7 @@ export function localStorageCollectionOptions(
   const wrappedOnUpdate = async (params: UpdateMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
-      validateJsonSerializable(mutation.modified, `update`)
+      validateJsonSerializable(parser, mutation.modified, `update`)
     })
 
     // Call the user handler BEFORE persisting changes (if provided)
@@ -429,7 +449,7 @@ export function localStorageCollectionOptions(
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage)
+    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
 
     // Update items with new version keys
     params.transaction.mutations.forEach((mutation) => {
@@ -459,7 +479,7 @@ export function localStorageCollectionOptions(
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage)
+    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
 
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
@@ -518,18 +538,19 @@ export function localStorageCollectionOptions(
       switch (mutation.type) {
         case `insert`:
         case `update`:
-          validateJsonSerializable(mutation.modified, mutation.type)
+          validateJsonSerializable(parser, mutation.modified, mutation.type)
           break
         case `delete`:
-          validateJsonSerializable(mutation.original, mutation.type)
+          validateJsonSerializable(parser, mutation.original, mutation.type)
           break
       }
     }
 
     // Load current data from storage
     const currentData = loadFromStorage<Record<string, unknown>>(
       config.storageKey,
-      storage
+      storage,
+      parser
     )
 
     // Apply each mutation
@@ -579,21 +600,23 @@ export function localStorageCollectionOptions(
 
 /**
  * Load data from storage and return as a Map
+ * @param parser - The parser to use for deserializing the data
  * @param storageKey - The key used to store data in the storage API
  * @param storage - The storage API to load from (localStorage, sessionStorage, etc.)
  * @returns Map of stored items with version tracking, or empty Map if loading fails
  */
 function loadFromStorage<T extends object>(
   storageKey: string,
-  storage: StorageApi
+  storage: StorageApi,
+  parser: Parser
 ): Map<string | number, StoredItem<T>> {
   try {
     const rawData = storage.getItem(storageKey)
     if (!rawData) {
       return new Map()
     }
 
-    const parsed = JSON.parse(rawData)
+    const parsed = parser.parse(rawData)
     const dataMap = new Map<string | number, StoredItem<T>>()
 
     // Handle object format where keys map to StoredItem values
@@ -644,6 +667,7 @@ function createLocalStorageSync<T extends object>(
   storageKey: string,
   storage: StorageApi,
   storageEventApi: StorageEventApi,
+  parser: Parser,
   _getKey: (item: T) => string | number,
   lastKnownData: Map<string | number, StoredItem<T>>
 ): SyncConfig<T> & {
@@ -704,7 +728,7 @@ function createLocalStorageSync<T extends object>(
     const { begin, write, commit } = syncParams
 
     // Load the new data
-    const newData = loadFromStorage<T>(storageKey, storage)
+    const newData = loadFromStorage<T>(storageKey, storage, parser)
 
     // Find the specific changes
     const changes = findChanges(lastKnownData, newData)
@@ -713,7 +737,7 @@ function createLocalStorageSync<T extends object>(
       begin()
       changes.forEach(({ type, value }) => {
         if (value) {
-          validateJsonSerializable(value, type)
+          validateJsonSerializable(parser, value, type)
           write({ type, value })
         }
       })
@@ -739,11 +763,11 @@ function createLocalStorageSync<T extends object>(
       collection = params.collection
 
       // Initial load
-      const initialData = loadFromStorage<T>(storageKey, storage)
+      const initialData = loadFromStorage<T>(storageKey, storage, parser)
       if (initialData.size > 0) {
         begin()
         initialData.forEach((storedItem) => {
-          validateJsonSerializable(storedItem.data, `load`)
+          validateJsonSerializable(parser, storedItem.data, `load`)
           write({ type: `insert`, value: storedItem.data })
         })
         commit()

packages/db/tests/local-storage.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import superjson from "superjson"
 import { createCollection } from "../src/index"
 import { localStorageCollectionOptions } from "../src/local-storage"
 import { createTransaction } from "../src/transactions"
@@ -175,6 +176,40 @@ describe(`localStorage collection`, () => {
       // Restore window
       globalThis.window = originalWindow
     })
+
+    it(`should support custom parsers like superjson`, async () => {
+      const collection = createCollection(
+        localStorageCollectionOptions<Todo>({
+          storageKey: `todos`,
+          storage: mockStorage,
+          storageEventApi: mockStorageEventApi,
+          getKey: (item) => item.id,
+          parser: superjson,
+        })
+      )
+
+      const todo: Todo = {
+        id: `1`,
+        title: `superjson`,
+        completed: false,
+        createdAt: new Date(),
+      }
+
+      const insertTx = collection.insert(todo)
+
+      await insertTx.isPersisted.promise
+
+      const storedData = mockStorage.getItem(`todos`)
+      expect(storedData).toBeDefined()
+
+      const parsed = superjson.parse<Record<string, { data: Todo }>>(
+        storedData!
+      )
+
+      expect(parsed[`1`]?.data.title).toBe(`superjson`)
+      expect(parsed[`1`]?.data.completed).toBe(false)
+      expect(parsed[`1`]?.data.createdAt).toBeInstanceOf(Date)
+    })
   })
 
   describe(`data persistence`, () => {