Store • tldraw Docs

Table of contents

history
id
props
query
schema
scopedTypes
sideEffects
Properties
Methods

A store of records.

class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {}

Constructor

Constructs a new instance of the Store class

Parameters

Name	Description
`config`	`{ schema: StoreSchema<R, Props> initialData?: SerializedStore<R> id?: string props: Props }`

Properties

history

readonly

An atom containing the store's history.

readonly history: Atom<number, RecordsDiff<R>>

id

readonly

The random id of the store.

readonly id: string

props

readonly

readonly props: Props

query

readonly

A StoreQueries instance for this store.

readonly query: StoreQueries<R>

schema

readonly

readonly schema: StoreSchema<R, Props>

scopedTypes

readonly

readonly scopedTypes: {
  readonly [K in RecordScope]: ReadonlySet<R['typeName']>
}

sideEffects

readonly

readonly sideEffects: StoreSideEffects<R>

Methods

allRecords()

Get an array of all values in the store.

allRecords(): R[]

applyDiff()

applyDiff(
  diff: RecordsDiff<R>,
  {
    runCallbacks,
    ignoreEphemeralKeys,
  }?: {
    ignoreEphemeralKeys?: boolean
    runCallbacks?: boolean
  }
): void

Parameters

Name	Description
`diff`	`RecordsDiff<R>`
`{ runCallbacks, ignoreEphemeralKeys, }`	`{ ignoreEphemeralKeys?: boolean runCallbacks?: boolean }`

Returns

void

clear()

Removes all records from the store.

clear(): void

createCache()

Create a cache based on values in the store. Pass in a function that takes and ID and a signal for the underlying record. Return a signal (usually a computed) for the cached value. For simple derivations, use Store.createComputedCache. This function is useful if you need more precise control over intermediate values.

createCache<Result, Record extends R = R>(
  create: (id: IdOf<Record>, recordSignal: Signal<R>) => Signal<Result>
): {
  get: (id: IdOf<Record>) => Result | undefined
}

Parameters

Name	Description
`create`	`( id: IdOf<Record>, recordSignal: Signal<R> ) => Signal<Result>`

Returns

{
  get: (id: IdOf<Record>) => Result | undefined
}

createComputedCache()

Create a computed cache.

createComputedCache<Result, Record extends R = R>(
  name: string,
  derive: (record: Record) => Result | undefined,
  opts?: CreateComputedCacheOpts<Result, Record>
): ComputedCache<Result, Record>

Parameters

Name	Description
`name`	`string` The name of the derivation cache.
`derive`	`(record: Record) => Result \| undefined` A function used to derive the value of the cache.
`opts`	`CreateComputedCacheOpts<Result, Record>` Options for the computed cache.

Returns

ComputedCache<Result, Record>

dispose()

dispose(): void

extractingChanges()

Run fn and return a RecordsDiff of the changes that occurred as a result.

extractingChanges(fn: () => void): RecordsDiff<R>

Parameters

Name	Description
`fn`	`() => void`

Returns

RecordsDiff<R>

filterChangesByScope()

Filters out non-document changes from a diff. Returns null if there are no changes left.

filterChangesByScope(
  change: RecordsDiff<R>,
  scope: RecordScope
): {
  added: { [K in IdOf<R>]: R }
  removed: { [K in IdOf<R>]: R }
  updated: { [K_1 in IdOf<R>]: [from: R, to: R] }
} | null

Parameters

Name	Description
`change`	`RecordsDiff<R>` the records diff
`scope`	`RecordScope` the records scope

Returns

{
  added: { [K in IdOf<R>]: R }
  removed: { [K in IdOf<R>]: R }
  updated: { [K_1 in IdOf<R>]: [from: R, to: R] }
} | null

get()

Get the value of a store record by its id.

get<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined

Parameters

Name	Description
`id`	`K` The id of the record to get.

Returns

RecordFromId<K> | undefined

getSnapshot()

Deprecated: use getSnapshot from the 'tldraw' package instead.

getSnapshot(scope?: 'all' | RecordScope): StoreSnapshot<R>

Parameters

Name	Description
`scope`	`'all' \| RecordScope`

Returns

StoreSnapshot<R>

getStoreSnapshot()

Get a serialized snapshot of the store and its schema.

const snapshot = store.getStoreSnapshot()
store.loadStoreSnapshot(snapshot)

getStoreSnapshot(scope?: 'all' | RecordScope): StoreSnapshot<R>

Parameters

Name	Description
`scope`	`'all' \| RecordScope` The scope of records to serialize. Defaults to 'document'.

Returns

StoreSnapshot<R>

has()

Get whether the record store has a id.

has<K extends IdOf<R>>(id: K): boolean

Parameters

Name	Description
`id`	`K` The id of the record to check.

Returns

boolean

listen()

Add a new listener to the store.

listen(
  onHistory: StoreListener<R>,
  filters?: Partial<StoreListenerFilters>
): () => void

Parameters

Name	Description
`onHistory`	`StoreListener<R>` The listener to call when the store updates.
`filters`	`Partial<StoreListenerFilters>` Filters to apply to the listener.

Returns

() => void

A function to remove the listener.

loadSnapshot()

Deprecated: use loadSnapshot from the 'tldraw' package instead.

loadSnapshot(snapshot: StoreSnapshot<R>): void

Parameters

Name	Description
`snapshot`	`StoreSnapshot<R>`

Returns

void

loadStoreSnapshot()

Load a serialized snapshot.

const snapshot = store.getStoreSnapshot()
store.loadStoreSnapshot(snapshot)

loadStoreSnapshot(snapshot: StoreSnapshot<R>): void

Parameters

Name	Description
`snapshot`	`StoreSnapshot<R>` The snapshot to load.

Returns

void

mergeRemoteChanges()

Merge changes from a remote source without triggering listeners.

mergeRemoteChanges(fn: () => void): void

Parameters

Name	Description
`fn`	`() => void` A function that merges the external changes.

Returns

void

migrateSnapshot()

Migrate a serialized snapshot of the store and its schema.

const snapshot = store.getSnapshot()
store.migrateSnapshot(snapshot)

migrateSnapshot(snapshot: StoreSnapshot<R>): StoreSnapshot<R>

Parameters

Name	Description
`snapshot`	`StoreSnapshot<R>` The snapshot to load.

Returns

StoreSnapshot<R>

put()

Add some records to the store. It's an error if they already exist.

put(records: R[], phaseOverride?: 'initialize'): void

Parameters

Name	Description
`records`	`R[]` The records to add.
`phaseOverride`	`'initialize'` The phase override.

Returns

void

remove()

Remove some records from the store via their ids.

remove(ids: IdOf<R>[]): void

Parameters

Name	Description
`ids`	`IdOf<R>[]` The ids of the records to remove.

Returns

void

serialize()

Creates a JSON payload from the record store.

serialize(scope?: 'all' | RecordScope): SerializedStore<R>

Parameters

Name	Description
`scope`	`'all' \| RecordScope` The scope of records to serialize. Defaults to 'document'.

Returns

SerializedStore<R>

The record store snapshot as a JSON payload.

unsafeGetWithoutCapture()

Get the value of a store record by its id without updating its epoch.

unsafeGetWithoutCapture<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined

Parameters

Name	Description
`id`	`K` The id of the record to get.

Returns

RecordFromId<K> | undefined

update()

Update a record. To update multiple records at once, use the update method of the TypedStore class.

update<K extends IdOf<R>>(
  id: K,
  updater: (record: RecordFromId<K>) => RecordFromId<K>
): void

Parameters

Name	Description
`id`	`K` The id of the record to update.
`updater`	`(record: RecordFromId<K>) => RecordFromId<K>` A function that updates the record.

Returns

void

validate()

validate(
  phase: 'createRecord' | 'initialize' | 'tests' | 'updateRecord'
): void

Parameters

Name	Description
`phase`	`\| 'createRecord' \| 'initialize' \| 'tests' \| 'updateRecord'`

Returns

void