📄 tanstack/db/latest/docs/reference/classes/CollectionImpl

File: CollectionImpl.md | Updated: 11/15/2025

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl



TanStack

DB v0v0

Search...

+ K

Auto

Log In

TanStack StartRC

Docs Examples GitHub Contributors

TanStack Router

Docs Examples GitHub Contributors

TanStack Query

Docs Examples GitHub Contributors

TanStack Table

Docs Examples Github Contributors

TanStack Formnew

Docs Examples Github Contributors

TanStack DBbeta

Docs Github Contributors

TanStack Virtual

Docs Examples Github Contributors

TanStack Paceralpha

Docs Examples Github Contributors

TanStack Storealpha

Docs Examples Github Contributors

TanStack Devtoolsalpha

Docs Github Contributors

More Libraries

Maintainers Partners Support Learn StatsBETA Discord Merch Blog GitHub Ethos Brand Guide

Documentation

Framework

React logo

React

Version

Latest

Search...

+ K

Menu

Getting Started

Guides

Collections

Frameworks

Community

API Reference

Framework

React logo

React

Version

Latest

Menu

Getting Started

Guides

Collections

Frameworks

Community

API Reference

On this page

CollectionImpl

Copy Markdown

Class: CollectionImpl<TOutput, TKey, TUtils, TSchema, TInput>
=============================================================

Defined in: packages/db/src/collection/index.ts:203

Extended by
-----------

Type Parameters
--------------- ### TOutput

TOutput extends object = Record<string, unknown>

### TKey

TKey extends string | number = string | number

### TUtils

TUtils extends UtilsRecord = { }

### TSchema

TSchema extends StandardSchemaV1 = StandardSchemaV1

### TInput

TInput extends object = TOutput

Constructors
------------ ### Constructor

ts

new CollectionImpl<TOutput, TKey, TUtils, TSchema, TInput>(config): CollectionImpl<TOutput, TKey, TUtils, TSchema, TInput>;


new CollectionImpl<TOutput, TKey, TUtils, TSchema, TInput>(config): CollectionImpl<TOutput, TKey, TUtils, TSchema, TInput>;

Defined in: packages/db/src/collection/index.ts:242

Creates a new Collection instance

#### Parameters ##### config

CollectionConfig <TOutput, TKey, TSchema>

Configuration object for the collection

#### Returns

CollectionImpl<TOutput, TKey, TUtils, TSchema, TInput>

#### Throws

Error if sync config is missing

Properties
---------- ### _lifecycle

ts

_lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>;


_lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>;

Defined in: packages/db/src/collection/index.ts:220

### _state

ts

_state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;


_state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;

Defined in: packages/db/src/collection/index.ts:232

### _sync

ts

_sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>;


_sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>;

Defined in: packages/db/src/collection/index.ts:221

### config

ts

config: CollectionConfig<TOutput, TKey, TSchema>;


config: CollectionConfig<TOutput, TKey, TSchema>;

Defined in: packages/db/src/collection/index.ts:211

### id

ts

id: string;


id: string;

Defined in: packages/db/src/collection/index.ts:210

### utils

ts

utils: Record<string, Fn> = {};


utils: Record<string, Fn> = {};

Defined in: packages/db/src/collection/index.ts:215

Accessors
--------- ### compareOptions #### Get Signature

ts

get compareOptions(): StringCollationConfig;


get compareOptions(): StringCollationConfig;

Defined in: packages/db/src/collection/index.ts:516

##### Returns

StringCollationConfig

### indexes #### Get Signature

ts

get indexes(): Map<number, BaseIndex<TKey>>;


get indexes(): Map<number, BaseIndex<TKey>>;

Defined in: packages/db/src/collection/index.ts:501

Get resolved indexes for query optimization

##### Returns

Map<number, BaseIndex <TKey>>

### isLoadingSubset #### Get Signature

ts

get isLoadingSubset(): boolean;


get isLoadingSubset(): boolean;

Defined in: packages/db/src/collection/index.ts:367

Check if the collection is currently loading more data

##### Returns

boolean

true if the collection has pending load more operations, false otherwise

### size #### Get Signature

ts

get size(): number;


get size(): number;

Defined in: packages/db/src/collection/index.ts:404

Get the current size of the collection (cached)

##### Returns

number

### state #### Get Signature

ts

get state(): Map<TKey, TOutput>;


get state(): Map<TKey, TOutput>;

Defined in: packages/db/src/collection/index.ts:693

Gets the current state of the collection as a Map

##### Example

ts

const itemsMap = collection.state
console.log(`Collection has ${itemsMap.size} items`)

for (const [key, item] of itemsMap) {
  console.log(`${key}: ${item.title}`)
}

// Check if specific item exists
if (itemsMap.has("todo-1")) {
  console.log("Todo 1 exists:", itemsMap.get("todo-1"))
}


const itemsMap = collection.state
console.log(`Collection has ${itemsMap.size} items`)

for (const [key, item] of itemsMap) {
  console.log(`${key}: ${item.title}`)
}

// Check if specific item exists
if (itemsMap.has("todo-1")) {
  console.log("Todo 1 exists:", itemsMap.get("todo-1"))
}

##### Returns

Map<TKey, TOutput>

Map containing all items in the collection, with keys as identifiers

### status #### Get Signature

ts

get status(): CollectionStatus;


get status(): CollectionStatus;

Defined in: packages/db/src/collection/index.ts:322

Gets the current status of the collection

##### Returns

CollectionStatus

### subscriberCount #### Get Signature

ts

get subscriberCount(): number;


get subscriberCount(): number;

Defined in: packages/db/src/collection/index.ts:329

Get the number of subscribers to the collection

##### Returns

number

### toArray #### Get Signature

ts

get toArray(): TOutput[];


get toArray(): TOutput[];

Defined in: packages/db/src/collection/index.ts:722

Gets the current state of the collection as an Array

##### Returns

TOutput[]

An Array containing all items in the collection

Methods
------- ### [iterator]()

ts

iterator: IterableIterator<[TKey, TOutput]>;


iterator: IterableIterator<[TKey, TOutput]>;

Defined in: packages/db/src/collection/index.ts:432

Get all entries (virtual derived state)

#### Returns

IterableIterator<[TKey, TOutput]>

### cleanup()

ts

cleanup(): Promise<void>;


cleanup(): Promise<void>;

Defined in: packages/db/src/collection/index.ts:856

Clean up the collection by stopping sync and clearing data This can be called manually or automatically by garbage collection

#### Returns

Promise<void>

### createIndex()

ts

createIndex<TResolver>(indexCallback, config): IndexProxy<TKey>;


createIndex<TResolver>(indexCallback, config): IndexProxy<TKey>;

Defined in: packages/db/src/collection/index.ts:491

Creates an index on a collection for faster queries. Indexes significantly improve query performance by allowing constant time lookups and logarithmic time range queries instead of full scans.

#### Type Parameters ##### TResolver

TResolver extends IndexResolver <TKey> = typeof BTreeIndex

The type of the index resolver (constructor or async loader)

#### Parameters ##### indexCallback

(row) => any

Function that extracts the indexed value from each item

##### config

IndexOptions <TResolver> = {}

Configuration including index type and type-specific options

#### Returns

IndexProxy <TKey>

An index proxy that provides access to the index when ready

#### Example

ts

// Create a default B+ tree index
const ageIndex = collection.createIndex((row) => row.age)

// Create a ordered index with custom options
const ageIndex = collection.createIndex((row) => row.age, {
  indexType: BTreeIndex,
  options: {
    compareFn: customComparator,
    compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' }
  },
  name: 'age_btree'
})

// Create an async-loaded index
const textIndex = collection.createIndex((row) => row.content, {
  indexType: async () => {
    const { FullTextIndex } = await import('./indexes/fulltext.js')
    return FullTextIndex
  },
  options: { language: 'en' }
})


// Create a default B+ tree index
const ageIndex = collection.createIndex((row) => row.age)

// Create a ordered index with custom options
const ageIndex = collection.createIndex((row) => row.age, {
  indexType: BTreeIndex,
  options: {
    compareFn: customComparator,
    compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' }
  },
  name: 'age_btree'
})

// Create an async-loaded index
const textIndex = collection.createIndex((row) => row.content, {
  indexType: async () => {
    const { FullTextIndex } = await import('./indexes/fulltext.js')
    return FullTextIndex
  },
  options: { language: 'en' }
})

### currentStateAsChanges()

ts

currentStateAsChanges(options): 
  | void
  | ChangeMessage<TOutput, string | number>[];


currentStateAsChanges(options): 
  | void
  | ChangeMessage<TOutput, string | number>[];

Defined in: packages/db/src/collection/index.ts:760

Returns the current state of the collection as an array of changes

#### Parameters ##### options

CurrentStateAsChangesOptions = {}

Options including optional where filter

#### Returns

| void | ChangeMessage <TOutput, string | number>[]

An array of changes

#### Example

ts

// Get all items as changes
const allChanges = collection.currentStateAsChanges()

// Get only items matching a condition
const activeChanges = collection.currentStateAsChanges({
  where: (row) => row.status === 'active'
})

// Get only items using a pre-compiled expression
const activeChanges = collection.currentStateAsChanges({
  whereExpression: eq(row.status, 'active')
})


// Get all items as changes
const allChanges = collection.currentStateAsChanges()

// Get only items matching a condition
const activeChanges = collection.currentStateAsChanges({
  where: (row) => row.status === 'active'
})

// Get only items using a pre-compiled expression
const activeChanges = collection.currentStateAsChanges({
  whereExpression: eq(row.status, 'active')
})

### delete()

ts

delete(keys, config?): Transaction<any>;


delete(keys, config?): Transaction<any>;

Defined in: packages/db/src/collection/index.ts:670

Deletes one or more items from the collection

#### Parameters ##### keys

Single key or array of keys to delete

TKey | TKey[]

##### config?

OperationConfig

Optional configuration including metadata

#### Returns

Transaction <any>

A Transaction object representing the delete operation(s)

#### Examples

ts

// Delete a single item
const tx = collection.delete("todo-1")
await tx.isPersisted.promise


// Delete a single item
const tx = collection.delete("todo-1")
await tx.isPersisted.promise

ts

// Delete multiple items
const tx = collection.delete(["todo-1", "todo-2"])
await tx.isPersisted.promise


// Delete multiple items
const tx = collection.delete(["todo-1", "todo-2"])
await tx.isPersisted.promise

ts

// Delete with metadata
const tx = collection.delete("todo-1", { metadata: { reason: "completed" } })
await tx.isPersisted.promise


// Delete with metadata
const tx = collection.delete("todo-1", { metadata: { reason: "completed" } })
await tx.isPersisted.promise

ts

// Handle errors
try {
  const tx = collection.delete("item-1")
  await tx.isPersisted.promise
  console.log('Delete successful')
} catch (error) {
  console.log('Delete failed:', error)
}


// Handle errors
try {
  const tx = collection.delete("item-1")
  await tx.isPersisted.promise
  console.log('Delete successful')
} catch (error) {
  console.log('Delete failed:', error)
}

### entries()

ts

entries(): IterableIterator<[TKey, TOutput]>;


entries(): IterableIterator<[TKey, TOutput]>;

Defined in: packages/db/src/collection/index.ts:425

Get all entries (virtual derived state)

#### Returns

IterableIterator<[TKey, TOutput]>

### forEach()

ts

forEach(callbackfn): void;


forEach(callbackfn): void;

Defined in: packages/db/src/collection/index.ts:439

Execute a callback for each entry in the collection

#### Parameters ##### callbackfn

(value, key, index) => void

#### Returns

void

### get()

ts

get(key): TOutput | undefined;


get(key): TOutput | undefined;

Defined in: packages/db/src/collection/index.ts:390

Get the current value for a key (virtual derived state)

#### Parameters ##### key

TKey

#### Returns

TOutput | undefined

### getKeyFromItem()

ts

getKeyFromItem(item): TKey;


getKeyFromItem(item): TKey;

Defined in: packages/db/src/collection/index.ts:454

#### Parameters ##### item

TOutput

#### Returns

TKey

### has()

ts

has(key): boolean;


has(key): boolean;

Defined in: packages/db/src/collection/index.ts:397

Check if a key exists in the collection (virtual derived state)

#### Parameters ##### key

TKey

#### Returns

boolean

### insert()

ts

insert(data, config?): 
  | Transaction<Record<string, unknown>>
| Transaction<TOutput>;


insert(data, config?): 
  | Transaction<Record<string, unknown>>
| Transaction<TOutput>;

Defined in: packages/db/src/collection/index.ts:557

Inserts one or more items into the collection

#### Parameters ##### data

TInput | TInput[]

##### config?

InsertConfig

Optional configuration including metadata

#### Returns

| Transaction <Record<string, unknown>> | Transaction <TOutput>

A Transaction object representing the insert operation(s)

#### Throws

If the data fails schema validation

#### Examples

ts

// Insert a single todo (requires onInsert handler)
const tx = collection.insert({ id: "1", text: "Buy milk", completed: false })
await tx.isPersisted.promise


// Insert a single todo (requires onInsert handler)
const tx = collection.insert({ id: "1", text: "Buy milk", completed: false })
await tx.isPersisted.promise

ts

// Insert multiple todos at once
const tx = collection.insert([\
  { id: "1", text: "Buy milk", completed: false },\
  { id: "2", text: "Walk dog", completed: true }\
])
await tx.isPersisted.promise


// Insert multiple todos at once
const tx = collection.insert([\
  { id: "1", text: "Buy milk", completed: false },\
  { id: "2", text: "Walk dog", completed: true }\
])
await tx.isPersisted.promise

ts

// Insert with metadata
const tx = collection.insert({ id: "1", text: "Buy groceries" },
  { metadata: { source: "mobile-app" } }
)
await tx.isPersisted.promise


// Insert with metadata
const tx = collection.insert({ id: "1", text: "Buy groceries" },
  { metadata: { source: "mobile-app" } }
)
await tx.isPersisted.promise

ts

// Handle errors
try {
  const tx = collection.insert({ id: "1", text: "New item" })
  await tx.isPersisted.promise
  console.log('Insert successful')
} catch (error) {
  console.log('Insert failed:', error)
}


// Handle errors
try {
  const tx = collection.insert({ id: "1", text: "New item" })
  await tx.isPersisted.promise
  console.log('Insert successful')
} catch (error) {
  console.log('Insert failed:', error)
}

### isReady()

ts

isReady(): boolean;


isReady(): boolean;

Defined in: packages/db/src/collection/index.ts:359

Check if the collection is ready for use Returns true if the collection has been marked as ready by its sync implementation

#### Returns

boolean

true if the collection is ready, false otherwise

#### Example

ts

if (collection.isReady()) {
  console.log('Collection is ready, data is available')
  // Safe to access collection.state
} else {
  console.log('Collection is still loading')
}


if (collection.isReady()) {
  console.log('Collection is ready, data is available')
  // Safe to access collection.state
} else {
  console.log('Collection is still loading')
}

### keys()

ts

keys(): IterableIterator<TKey>;


keys(): IterableIterator<TKey>;

Defined in: packages/db/src/collection/index.ts:411

Get all keys (virtual derived state)

#### Returns

IterableIterator<TKey>

### map()

ts

map<U>(callbackfn): U[];


map<U>(callbackfn): U[];

Defined in: packages/db/src/collection/index.ts:448

Create a new array with the results of calling a function for each entry in the collection

#### Type Parameters ##### U

U

#### Parameters ##### callbackfn

(value, key, index) => U

#### Returns

U[]

### off()

ts

off<T>(event, callback): void;


off<T>(event, callback): void;

Defined in: packages/db/src/collection/index.ts:835

Unsubscribe from a collection event

#### Type Parameters ##### T

T extends | "status:idle" | "status:loading" | "status:ready" | "status:error" | "status:cleaned-up" | "status:change" | "subscribers:change" | "loadingSubset:change"

#### Parameters ##### event

T

##### callback

CollectionEventHandler<T>

#### Returns

void

### on()

ts

on<T>(event, callback): () => void;


on<T>(event, callback): () => void;

Defined in: packages/db/src/collection/index.ts:815

Subscribe to a collection event

#### Type Parameters ##### T

T extends | "status:idle" | "status:loading" | "status:ready" | "status:error" | "status:cleaned-up" | "status:change" | "subscribers:change" | "loadingSubset:change"

#### Parameters ##### event

T

##### callback

CollectionEventHandler<T>

#### Returns

ts

(): void;


(): void;

##### Returns

void

### once()

ts

once<T>(event, callback): () => void;


once<T>(event, callback): () => void;

Defined in: packages/db/src/collection/index.ts:825

Subscribe to a collection event once

#### Type Parameters ##### T

T extends | "status:idle" | "status:loading" | "status:ready" | "status:error" | "status:cleaned-up" | "status:change" | "subscribers:change" | "loadingSubset:change"

#### Parameters ##### event

T

##### callback

CollectionEventHandler<T>

#### Returns

ts

(): void;


(): void;

##### Returns

void

### onFirstReady()

ts

onFirstReady(callback): void;


onFirstReady(callback): void;

Defined in: packages/db/src/collection/index.ts:343

Register a callback to be executed when the collection first becomes ready Useful for preloading collections

#### Parameters ##### callback

() => void

Function to call when the collection first becomes ready

#### Returns

void

#### Example

ts

collection.onFirstReady(() => {
  console.log('Collection is ready for the first time')
  // Safe to access collection.state now
})


collection.onFirstReady(() => {
  console.log('Collection is ready for the first time')
  // Safe to access collection.state now
})

### preload()

ts

preload(): Promise<void>;


preload(): Promise<void>;

Defined in: packages/db/src/collection/index.ts:383

Preload the collection data by starting sync if not already started Multiple concurrent calls will share the same promise

#### Returns

Promise<void>

### startSyncImmediate()

ts

startSyncImmediate(): void;


startSyncImmediate(): void;

Defined in: packages/db/src/collection/index.ts:375

Start sync immediately - internal method for compiled queries This bypasses lazy loading for special cases like live query results

#### Returns

void

### stateWhenReady()

ts

stateWhenReady(): Promise<Map<TKey, TOutput>>;


stateWhenReady(): Promise<Map<TKey, TOutput>>;

Defined in: packages/db/src/collection/index.ts:707

Gets the current state of the collection as a Map, but only resolves when data is available Waits for the first sync commit to complete before resolving

#### Returns

Promise<Map<TKey, TOutput>>

Promise that resolves to a Map containing all items in the collection

### subscribeChanges()

ts

subscribeChanges(callback, options): CollectionSubscription;


subscribeChanges(callback, options): CollectionSubscription;

Defined in: packages/db/src/collection/index.ts:805

Subscribe to changes in the collection

#### Parameters ##### callback

(changes) => void

Function called when items change

##### options

SubscribeChangesOptions = {}

Subscription options including includeInitialState and where filter

#### Returns

CollectionSubscription

Unsubscribe function - Call this to stop listening for changes

#### Examples

ts

// Basic subscription
const subscription = collection.subscribeChanges((changes) => {
  changes.forEach(change => {
    console.log(`${change.type}: ${change.key}`, change.value)
  })
})

// Later: subscription.unsubscribe()


// Basic subscription
const subscription = collection.subscribeChanges((changes) => {
  changes.forEach(change => {
    console.log(`${change.type}: ${change.key}`, change.value)
  })
})

// Later: subscription.unsubscribe()

ts

// Include current state immediately
const subscription = collection.subscribeChanges((changes) => {
  updateUI(changes)
}, { includeInitialState: true })


// Include current state immediately
const subscription = collection.subscribeChanges((changes) => {
  updateUI(changes)
}, { includeInitialState: true })

ts

// Subscribe only to changes matching a condition
const subscription = collection.subscribeChanges((changes) => {
  updateUI(changes)
}, {
  includeInitialState: true,
  where: (row) => row.status === 'active'
})


// Subscribe only to changes matching a condition
const subscription = collection.subscribeChanges((changes) => {
  updateUI(changes)
}, {
  includeInitialState: true,
  where: (row) => row.status === 'active'
})

ts

// Subscribe using a pre-compiled expression
const subscription = collection.subscribeChanges((changes) => {
  updateUI(changes)
}, {
  includeInitialState: true,
  whereExpression: eq(row.status, 'active')
})


// Subscribe using a pre-compiled expression
const subscription = collection.subscribeChanges((changes) => {
  updateUI(changes)
}, {
  includeInitialState: true,
  whereExpression: eq(row.status, 'active')
})

### toArrayWhenReady()

ts

toArrayWhenReady(): Promise<TOutput[]>;


toArrayWhenReady(): Promise<TOutput[]>;

Defined in: packages/db/src/collection/index.ts:732

Gets the current state of the collection as an Array, but only resolves when data is available Waits for the first sync commit to complete before resolving

#### Returns

Promise<TOutput[]>

Promise that resolves to an Array containing all items in the collection

### update() #### Call Signature

ts

update(key, callback): Transaction;


update(key, callback): Transaction;

Defined in: packages/db/src/collection/index.ts:602

Updates one or more items in the collection using a callback function

##### Parameters ###### key

unknown[]

###### callback

(drafts) => void

##### Returns

Transaction

A Transaction object representing the update operation(s)

##### Throws

If the updated data fails schema validation

##### Examples

ts

// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise


// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise

ts

// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise


// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise

ts

// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise


// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise

ts

// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}


// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}

#### Call Signature

ts

update(
   keys, 
   config, 
   callback): Transaction;


update(
   keys, 
   config, 
   callback): Transaction;

Defined in: packages/db/src/collection/index.ts:608

Updates one or more items in the collection using a callback function

##### Parameters ###### keys

unknown[]

Single key or array of keys to update

###### config

OperationConfig

###### callback

(drafts) => void

##### Returns

Transaction

A Transaction object representing the update operation(s)

##### Throws

If the updated data fails schema validation

##### Examples

ts

// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise


// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise

ts

// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise


// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise

ts

// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise


// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise

ts

// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}


// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}

#### Call Signature

ts

update(id, callback): Transaction;


update(id, callback): Transaction;

Defined in: packages/db/src/collection/index.ts:615

Updates one or more items in the collection using a callback function

##### Parameters ###### id

unknown

###### callback

(draft) => void

##### Returns

Transaction

A Transaction object representing the update operation(s)

##### Throws

If the updated data fails schema validation

##### Examples

ts

// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise


// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise

ts

// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise


// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise

ts

// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise


// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise

ts

// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}


// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}

#### Call Signature

ts

update(
   id, 
   config, 
   callback): Transaction;


update(
   id, 
   config, 
   callback): Transaction;

Defined in: packages/db/src/collection/index.ts:621

Updates one or more items in the collection using a callback function

##### Parameters ###### id

unknown

###### config

OperationConfig

###### callback

(draft) => void

##### Returns

Transaction

A Transaction object representing the update operation(s)

##### Throws

If the updated data fails schema validation

##### Examples

ts

// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise


// Update single item by key
const tx = collection.update("todo-1", (draft) => {
  draft.completed = true
})
await tx.isPersisted.promise

ts

// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise


// Update multiple items
const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
  drafts.forEach(draft => { draft.completed = true })
})
await tx.isPersisted.promise

ts

// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise


// Update with metadata
const tx = collection.update("todo-1",
  { metadata: { reason: "user update" } },
  (draft) => { draft.text = "Updated text" }
)
await tx.isPersisted.promise

ts

// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}


// Handle errors
try {
  const tx = collection.update("item-1", draft => { draft.value = "new" })
  await tx.isPersisted.promise
  console.log('Update successful')
} catch (error) {
  console.log('Update failed:', error)
}

### validateData()

ts

validateData(
   data, 
   type, 
   key?): TOutput;


validateData(
   data, 
   type, 
   key?): TOutput;

Defined in: packages/db/src/collection/index.ts:508

Validates the data against the schema

#### Parameters ##### data

unknown

##### type

"insert" | "update"

##### key?

TKey

#### Returns

TOutput

### values()

ts

values(): IterableIterator<TOutput>;


values(): IterableIterator<TOutput>;

Defined in: packages/db/src/collection/index.ts:418

Get all values (virtual derived state)

#### Returns

IterableIterator<TOutput>

### waitFor()

ts

waitFor<T>(event, timeout?): Promise<AllCollectionEvents[T]>;


waitFor<T>(event, timeout?): Promise<AllCollectionEvents[T]>;

Defined in: packages/db/src/collection/index.ts:845

Wait for a collection event

#### Type Parameters ##### T

T extends | "status:idle" | "status:loading" | "status:ready" | "status:error" | "status:cleaned-up" | "status:change" | "subscribers:change" | "loadingSubset:change"

#### Parameters ##### event

T

##### timeout?

number

#### Returns

Promise<AllCollectionEvents[T]>

Edit on GitHub

Home

Partners Become a Partner

Code RabbitCode Rabbit CloudflareCloudflare AG GridAG Grid NetlifyNetlify NeonNeon WorkOSWorkOS ClerkClerk ConvexConvex ElectricElectric SentrySentry PrismaPrisma StrapiStrapi UnkeyUnkey