Class Table<Document, PrimaryIndex, Indices>

A signal which updates whenever the table has been modified.

A promise which resolves when this table is ready to use.

If the table isn't connected to a StorageBackend, this is a promise which resolves immediately, and you don't really need to await it. The table will be ready for use immediately.

With an attached StorageBackend, this promise will resolve when the table has finished restoring its contents from the storage. You should not under any circumstances use the table before this is complete.

Iterate over the documents in the table, ordered by primary key.

Add documents to the table, overwriting any previous values under their primary keys.

Add documents to the table, overwriting any previous values under their primary keys.

Delete all documents from the table.

Given a primary key, apply an update function to the value stored under that key. If there's no value, call the create function to create the value before passing it to the update function.

Create or update a document.

Given a primary key, apply the update function to the document stored under that key.

If there's no such document, call the create function to create a new document and insert that under the given primary key. In this case, the update function is not called.

The update function is passed to Immer.produce to perform the update. It should modify the provided document in place, and it's not necessary to return it.

Delete documents from the table by their primary keys.

Delete documents from the table by their primary keys.

Perform an IndexQuery using the specified index.

This is an alias for Table.where.

Get the number of documents currently stored in the table.

Update a document.

Apply the update function to the document stored under the given primary key.

If no such document exists, the update function is not called and undefined is returned. Otherwise, the updated document is returned.

The update function is passed to Immer.produce to perform the update. It should modify the provided document in place, and it's not necessary to return it.

Perform an IndexQuery using the specified index.

Add an index to a table.

Attach a table to a StorageBackend.

See IndexedDBBackend.open for an example of how to use this.

Create a database Table.

Table.create is a function which takes one type argument, the type of the object (which we'll call a document) you want the table to store, and no value arguments.

This returns an object with one method: withPrimaryIndex. This method is what actually creates the table. So, the full incantation is, for instance:

type Document = { id: string; value: number };
const table = Table.create<Document>()
    .withPrimaryIndex(index<Document>().key("id"));
Copy

In order to look up something in a database table, you need an index. You can create an index using the index function, which, like Table.create, takes the document you're creating an index for as its type argument, and returns a selection of index constructors, of which the most straightforward one is IndexConstructor.key. This creates an index for a single named property of the document containing a primitive comparable value (a string, a number, or a bigint), and allows you to search for documents where the given property matches any given value. You can also create an index over multiple keys using IndexConstructor.keys or over a key containing an array using IndexConstructor.array. You can even create a completely customised index using IndexConstructor.custom.

The primary index, unlike a regular index, is a unique identifier, and only one document can exist at any given time under the key or keys represented by the primary index. A table is required to have a primary index, which is why Table.create doesn't actually create the table until you call withPrimaryIndex on it. You can then add as many extra indices as you like using withIndex. To extend our example above with an additional index over the value property:

type Document = { id: string; value: number };
const table = Table.create<Document>()
    .withPrimaryIndex(index<Document>().key("id"))
    .withIndex(index<Document>().key("value"));
Copy