tldraw/packages/store

@tldraw/tlstore

tlstore is a library for creating and managing data.

In this library, a "record" is an object that is stored under a typed id.

tlstore is used by tldraw to store its data.

It is designed to be used with tlstate (@tldraw/tlstate).

Usage

First create types for your records.

interface Book extends BaseRecord<'book'> {
	title: string
	author: ID<Author>
	numPages: number
}

interface Author extends BaseRecord<'author'> {
	name: string
	isPseudonym: boolean
}

Then create your RecordType instances.

const Book = createRecordType<Book>('book')

const Author = createRecordType<Author>('author').withDefaultProperties(() => ({
	isPseudonym: false,
}))

Then create your RecordStore instance.

const store = new RecordStore<Book | Author>()

Then you can create records, add them to the store, update, and remove them.

const tolkeinId = Author.createCustomId('tolkein')

store.put([
	Author.create({
		id: jrrTolkeinId,
		name: 'J.R.R Tolkein',
	}),
])

store.update(tolkeinId, (author) => ({
	...author,
	name: 'DJJ Tolkz',
	isPseudonym: true,
}))

store.remove(tolkeinId)

---

API

RecordStore

The RecordStore class is the main class of the library.

const store = new RecordStore()

put(records: R[]): void

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

const record = Author.create({
	name: 'J.R.R Tolkein',
	id: Author.createCustomId('tolkein'),
})

store.put([record])

update(id: ID<R>, updater: (record: R) => R): void

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

const id = Author.createCustomId('tolkein')

store.update(id, (r) => ({ ...r, name: 'Jimmy Tolks' }))

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

Remove some records from the store via their ids.

const id = Author.createCustomId('tolkein')

store.remove([id])

get(id: ID<R>): R

Get the value of a store record by its id.

const id = Author.createCustomId('tolkein')

const result = store.get(id)

allRecords(): R[]

Get an array of all values in the store.

const results = store.allRecords()

clear(): void

Remove all records from the store.

store.clear()

has(id: ID<R>): boolean

Get whether the record store has an record stored under the given id.

const id = Author.createCustomId('tolkein')

const result = store.has(id)

serialize(filter?: (record: R) => boolean): RecordStoreSnapshot<R>

Opposite of deserialize. Creates a JSON payload from the record store.

const serialized = store.serialize()

const serialized = store.serialize((record) => record.name === 'J.R.R Tolkein')

deserialize(snapshot: RecordStoreSnapshot<R>): void

Opposite of serialize. Replace the store's current records with records as defined by a simple JSON structure into the stores.

const serialized = { ... }

store.deserialize(serialized)

listen(listener: ((entry: HistoryEntry) => void): () => void

Add a new listener to the store The store will call the function each time the history changes. Returns a function to remove the listener.

store.listen((entry) => doSomethingWith(entry))

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

Merge changes from a remote source without triggering listeners.

store.mergeRemoteChanges(() => {
	store.put(recordsFromRemoteSource)
})

createDerivationCache(name: string, derive: ((record: R) => R | undefined)): DerivationCache<R>

Create a new derivation cache.

const derivationCache = createDerivationCache('popular_authors', (record) => {
	return record.popularity > 62 ? record : undefined
})

---

RecordType

The RecordType class is used to define the structure of a record.

const recordType = new RecordType('author', () => ({ living: true }))

RecordType instances are most often created with createRecordType.

create(properties: Pick<R, RequiredProperties> & Omit<Partial<R>, RequiredProperties>): R

Create a new record of this type.

const record = recordType.create({ name: 'J.R.R Tolkein' })

clone(record: R): R

Clone a record of this type.

const record = recordType.create({ name: 'J.R.R Tolkein' })

const clone = recordType.clone(record)

createId(): ID<R>

Create an Id for a record of this type.

const id = recordType.createId()

createCustomId(id: string): ID<R>

Create a custom Id for a record of this type.

const id = recordType.createCustomId('tolkein')

isInstance

Check if a value is an instance of this record type.

const record = recordType.create({ name: 'J.R.R Tolkein' })

const result1 = recordType.isInstance(record) // true
const result2 = recordType.isInstance(someOtherRecord) // false

isId

Check if a value is an id for a record of this type.

const id = recordType.createCustomId('tolkein')

const result1 = recordType.isId(id) // true
const result2 = recordType.isId(someOtherId) // false

withDefaultProperties

Create a new record type with default properties.

const youngLivingAuthor = new RecordType('author', () => ({ age: 28, living: true }))

const oldDeadAuthor = recordType.withDefaultProperties({ age: 93, living: false })

RecordStoreQueries

TODO

Helpers

executeQuery

TODO

DerivationCache

The DerivationCache class is used to create a cache of derived records.

const derivationCache = new DerivationCache('popular_authors', (record) => {
	return record.popularity > 62 ? record : undefined
})

createRecordType

A helper used to create a new RecordType instance with no default properties.

const recordType = createRecordType('author'))

assertIdType

A helper used to assert that a value is an id for a record of a given type.

const id = recordType.createCustomId('tolkein')

assertIdType(id, recordType)

---

Types

ID

A type used to represent a record's id.

const id: ID<Author> = Author.createCustomId('tolkein')

BaseRecord

A BaseRecord is a record that has an id and a type. It is the base type for all records.

type AuthorRecord extends BaseRecord<"author"> {
  name: string
  age: number
  living: boolean
}

RecordsDiff

A diff describing the changes to a record.

CollectionDiff

A diff describing the changes to a collection.

License

The tldraw source code and its distributions are provided under the tldraw license. This license does not permit commercial use.

If you wish to use this project in commercial product, you need to purchase a commercial license. To obtain a commercial license or learn more, please fill out this form.