TanStack
DB v0v0
Documentation
Framework
Version
Menu
Getting Started
Guides
Collections
Community
API Reference

LocalStorageCollectionConfig

Interface: LocalStorageCollectionConfig<T, TSchema, TKey>

Defined in: packages/db/src/local-storage.ts:58

Configuration interface for localStorage collection options

Extends

Type Parameters

T

T extends object = object

The type of items in the collection

TSchema

TSchema extends StandardSchemaV1 = never

The schema type for validation

TKey

TKey extends string | number = string | number

The type of the key returned by getKey

Properties

autoIndex?
ts
optional autoIndex: "eager" | "off";

optional autoIndex: "eager" | "off";

Defined in: packages/db/src/types.ts:434

Auto-indexing mode for the collection. When enabled, indexes will be automatically created for simple where expressions.

Default
ts
"eager"

"eager"

Description
  • "off": No automatic indexing
  • "eager": Automatically create indexes for simple where expressions in subscribeChanges (default)

Inherited from

BaseCollectionConfig.autoIndex

compare()?
ts
optional compare: (x, y) => number;

optional compare: (x, y) => number;

Defined in: packages/db/src/types.ts:445

Optional function to compare two items. This is used to order the items in the collection.

Parameters
x

T

The first item to compare

y

T

The second item to compare

Returns

number

A number indicating the order of the items

Example
ts
// For a collection with a 'createdAt' field
compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()

// For a collection with a 'createdAt' field
compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()

Inherited from

BaseCollectionConfig.compare

gcTime?
ts
optional gcTime: number;

optional gcTime: number;

Defined in: packages/db/src/types.ts:414

Time in milliseconds after which the collection will be garbage collected when it has no active subscribers. Defaults to 5 minutes (300000ms).

Inherited from

BaseCollectionConfig.gcTime

getKey()
ts
getKey: (item) => TKey;

getKey: (item) => TKey;

Defined in: packages/db/src/types.ts:409

Function to extract the ID from an object This is required for update/delete operations which now only accept IDs

Parameters
item

T

The item to extract the ID from

Returns

TKey

The ID string for the item

Example
ts
// For a collection with a 'uuid' field as the primary key
getKey: (item) => item.uuid

// For a collection with a 'uuid' field as the primary key
getKey: (item) => item.uuid

Inherited from

BaseCollectionConfig.getKey

id?
ts
optional id: string;

optional id: string;

Defined in: packages/db/src/types.ts:398

Inherited from

BaseCollectionConfig.id

onDelete?
ts
optional onDelete: DeleteMutationFn<T, TKey, UtilsRecord, any>;

optional onDelete: DeleteMutationFn<T, TKey, UtilsRecord, any>;

Defined in: packages/db/src/types.ts:583

Optional asynchronous handler function called before a delete operation

Param

Object containing transaction and collection information

Returns

Promise resolving to any value

Examples
ts
// Basic delete handler
onDelete: async ({ transaction, collection }) => {
  const deletedKey = transaction.mutations[0].key
  await api.deleteTodo(deletedKey)
}

// Basic delete handler
onDelete: async ({ transaction, collection }) => {
  const deletedKey = transaction.mutations[0].key
  await api.deleteTodo(deletedKey)
}
ts
// Delete handler with multiple items
onDelete: async ({ transaction, collection }) => {
  const keysToDelete = transaction.mutations.map(m => m.key)
  await api.deleteTodos(keysToDelete)
}

// Delete handler with multiple items
onDelete: async ({ transaction, collection }) => {
  const keysToDelete = transaction.mutations.map(m => m.key)
  await api.deleteTodos(keysToDelete)
}
ts
// Delete handler with confirmation
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  const shouldDelete = await confirmDeletion(mutation.original)
  if (!shouldDelete) {
    throw new Error('Delete cancelled by user')
  }
  await api.deleteTodo(mutation.original.id)
}

// Delete handler with confirmation
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  const shouldDelete = await confirmDeletion(mutation.original)
  if (!shouldDelete) {
    throw new Error('Delete cancelled by user')
  }
  await api.deleteTodo(mutation.original.id)
}
ts
// Delete handler with optimistic rollback
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  try {
    await api.deleteTodo(mutation.original.id)
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Delete failed, rolling back:', error)
    throw error
  }
}

// Delete handler with optimistic rollback
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  try {
    await api.deleteTodo(mutation.original.id)
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Delete failed, rolling back:', error)
    throw error
  }
}

Inherited from

BaseCollectionConfig.onDelete

onInsert?
ts
optional onInsert: InsertMutationFn<T, TKey, UtilsRecord, any>;

optional onInsert: InsertMutationFn<T, TKey, UtilsRecord, any>;

Defined in: packages/db/src/types.ts:496

Optional asynchronous handler function called before an insert operation

Param

Object containing transaction and collection information

Returns

Promise resolving to any value

Examples
ts
// Basic insert handler
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
}

// Basic insert handler
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
}
ts
// Insert handler with multiple items
onInsert: async ({ transaction, collection }) => {
  const items = transaction.mutations.map(m => m.modified)
  await api.createTodos(items)
}

// Insert handler with multiple items
onInsert: async ({ transaction, collection }) => {
  const items = transaction.mutations.map(m => m.modified)
  await api.createTodos(items)
}
ts
// Insert handler with error handling
onInsert: async ({ transaction, collection }) => {
  try {
    const newItem = transaction.mutations[0].modified
    const result = await api.createTodo(newItem)
    return result
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // This will cause the transaction to fail
  }
}

// Insert handler with error handling
onInsert: async ({ transaction, collection }) => {
  try {
    const newItem = transaction.mutations[0].modified
    const result = await api.createTodo(newItem)
    return result
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // This will cause the transaction to fail
  }
}
ts
// Insert handler with metadata
onInsert: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.createTodo(mutation.modified, {
    source: mutation.metadata?.source,
    timestamp: mutation.createdAt
  })
}

// Insert handler with metadata
onInsert: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.createTodo(mutation.modified, {
    source: mutation.metadata?.source,
    timestamp: mutation.createdAt
  })
}

Inherited from

BaseCollectionConfig.onInsert

onUpdate?
ts
optional onUpdate: UpdateMutationFn<T, TKey, UtilsRecord, any>;

optional onUpdate: UpdateMutationFn<T, TKey, UtilsRecord, any>;

Defined in: packages/db/src/types.ts:540

Optional asynchronous handler function called before an update operation

Param

Object containing transaction and collection information

Returns

Promise resolving to any value

Examples
ts
// Basic update handler
onUpdate: async ({ transaction, collection }) => {
  const updatedItem = transaction.mutations[0].modified
  await api.updateTodo(updatedItem.id, updatedItem)
}

// Basic update handler
onUpdate: async ({ transaction, collection }) => {
  const updatedItem = transaction.mutations[0].modified
  await api.updateTodo(updatedItem.id, updatedItem)
}
ts
// Update handler with partial updates
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  const changes = mutation.changes // Only the changed fields
  await api.updateTodo(mutation.original.id, changes)
}

// Update handler with partial updates
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  const changes = mutation.changes // Only the changed fields
  await api.updateTodo(mutation.original.id, changes)
}
ts
// Update handler with multiple items
onUpdate: async ({ transaction, collection }) => {
  const updates = transaction.mutations.map(m => ({
    id: m.key,
    changes: m.changes
  }))
  await api.updateTodos(updates)
}

// Update handler with multiple items
onUpdate: async ({ transaction, collection }) => {
  const updates = transaction.mutations.map(m => ({
    id: m.key,
    changes: m.changes
  }))
  await api.updateTodos(updates)
}
ts
// Update handler with optimistic rollback
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  try {
    await api.updateTodo(mutation.original.id, mutation.changes)
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Update failed, rolling back:', error)
    throw error
  }
}

// Update handler with optimistic rollback
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  try {
    await api.updateTodo(mutation.original.id, mutation.changes)
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Update failed, rolling back:', error)
    throw error
  }
}

Inherited from

BaseCollectionConfig.onUpdate

parser?
ts
optional parser: Parser;

optional parser: Parser;

Defined in: packages/db/src/local-storage.ts:84

Parser to use for serializing and deserializing data to and from storage Defaults to JSON

schema?
ts
optional schema: TSchema;

optional schema: TSchema;

Defined in: packages/db/src/types.ts:399

Inherited from

BaseCollectionConfig.schema

startSync?
ts
optional startSync: boolean;

optional startSync: boolean;

Defined in: packages/db/src/types.ts:425

Whether to eagerly start syncing on collection creation. When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches.

Note: Even with startSync=true, collections will pause syncing when there are no active subscribers (typically when components querying the collection unmount), resuming when new subscribers attach. This preserves normal staleTime/gcTime behavior.

Default
ts
false

false

Inherited from

BaseCollectionConfig.startSync

storage?
ts
optional storage: StorageApi;

optional storage: StorageApi;

Defined in: packages/db/src/local-storage.ts:72

Storage API to use (defaults to window.localStorage) Can be any object that implements the Storage interface (e.g., sessionStorage)

storageEventApi?
ts
optional storageEventApi: StorageEventApi;

optional storageEventApi: StorageEventApi;

Defined in: packages/db/src/local-storage.ts:78

Storage event API to use for cross-tab synchronization (defaults to window) Can be any object that implements addEventListener/removeEventListener for storage events

storageKey
ts
storageKey: string;

storageKey: string;

Defined in: packages/db/src/local-storage.ts:66

The key to use for storing the collection data in localStorage/sessionStorage

syncMode?
ts
optional syncMode: SyncMode;

optional syncMode: SyncMode;

Defined in: packages/db/src/types.ts:454

The mode of sync to use for the collection.

Default

eager

Description
  • eager: syncs all data immediately on preload
  • on-demand: syncs data in incremental snapshots when the collection is queried The exact implementation of the sync mode is up to the sync implementation.

Inherited from

BaseCollectionConfig.syncMode

utils?
ts
optional utils: UtilsRecord;

optional utils: UtilsRecord;

Defined in: packages/db/src/types.ts:585

Inherited from

BaseCollectionConfig.utils

Edit on GitHub
Home
Partners
Code Rabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
Sentry
Prisma
Strapi
Unkey
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.