Skip to content

Sys.Storage

Sys.Storage gives client-side code access to storage in the End user’s browser: the browser’s local storage, its IndexedDB databases, and SimpleIdbConnection, a small key-value store on top of IndexedDB. Data stored here stays in that browser only and is not sent to the server.

For a single ready-made key-value store, see also Sys.Idb.

Availability: Client

openSimpleIdb<T>(storeName?: string, dbName?: string): SimpleIdbConnection<T>;

Returns a SimpleIdbConnection for an IndexedDB object store. The database and the store are created the first time they are used.

ParameterTypeDescription
storeNamestringOptional. Name of the object store. Default: 'default'.
dbNamestringOptional. Name of the IndexedDB database. Default: 'default'.

Note

The object store is only created together with its database. If the database already exists without a store named storeName, every call on the connection fails. Use a separate dbName for each storeName.

Returns: SimpleIdbConnection<T> · Availability: Client

openIdbDatabase<T extends DBSchema | unknown = unknown>(name: string, version?: number, { blocked, upgrade, blocking, terminated }?: OpenDBCallbacks<T>): Promise<IDBPDatabase<T>>;

Opens an IndexedDB database with the idb library (version 8, see the idb documentation), which wraps the browser’s IndexedDB API in promises. Use it when you need your own object stores, indexes or schema versions.

ParameterTypeDescription
namestringName of the database.
versionnumberOptional. Schema version. If it is higher than the version stored in the browser, upgrade is called. Default: the stored version, or 1 for a new database.
callbacksOpenDBCallbacks<T>Optional. Callbacks for version changes.

OpenDBCallbacks<T> fields

FieldTypeRequiredDescription
upgrade(database, oldVersion, newVersion, transaction, event) => voidOptionalCalled when the database is created or opened with a higher version. Create object stores and indexes here.
blocked(currentVersion, blockedVersion, event) => voidOptionalCalled when an older version of the database is still open elsewhere (for example in another tab), so this version can’t open yet.
blocking(currentVersion, blockedVersion, event) => voidOptionalCalled when this connection prevents a newer version of the database from opening.
terminated() => voidOptionalCalled when the browser closes the connection abnormally.
const db = await Sys.Storage.openIdbDatabase('myDatabase', 1, {
upgrade(database) {
database.createObjectStore('notes')
},
})
await db.put('notes', 'Remember this', 'note1')
const note = await db.get('notes', 'note1')

Returns: Promise<IDBPDatabase<T>> · Availability: Client

get localStorage(): Storage;

The browser’s local storage for the app’s origin. It stores strings by key and keeps them when the browser is closed.

Type: Storage · Availability: Client

get indexedDB(): IDBFactory;

The browser’s IndexedDB factory, for using the IndexedDB API directly.

Type: IDBFactory · Availability: Client

A key-value store backed by one IndexedDB object store. You get an instance from openSimpleIdb(). The connection opens the database when needed and closes it again after 10 seconds without use.

set() converts values to plain objects in Lowgile’s JSON format before storing them, and getFirst() converts them back, so class instances such as Entities come back as instances of their class.

set<Name extends StoreNames<T>>(key: StoreKey<T, Name> | IDBKeyRange, value: any): Promise<void>;

Stores a value under a key, replacing any value already stored under it.

ParameterTypeDescription
keyStoreKey<T, Name> | IDBKeyRangeThe key, for example a string or number.
valueanyThe value to store.

Returns: Promise<void> · Availability: Client

getFirst<Name extends StoreNames<T>>(key: StoreKey<T, Name> | IDBKeyRange): Promise<import("idb").StoreValue<T, StoreNames<T>>>;

Returns the value stored under a key, or the first value in a key range. Resolves with undefined if there is none.

ParameterTypeDescription
keyStoreKey<T, Name> | IDBKeyRangeThe key, or an IDBKeyRange.

Returns: Promise<StoreValue<T, StoreNames<T>>> · Availability: Client

getAll<Name extends StoreNames<T>>(key: StoreKey<T, Name> | IDBKeyRange): Promise<import("idb").StoreValue<T, StoreNames<T>>[]>;

Returns all values whose key matches key or lies in the key range.

ParameterTypeDescription
keyStoreKey<T, Name> | IDBKeyRangeThe key, or an IDBKeyRange.

Note

Unlike getFirst(), getAll() returns the values as they are stored, as plain objects in Lowgile’s JSON format; class instances are not restored.

Returns: Promise<StoreValue<T, StoreNames<T>>[]> · Availability: Client

delete<Name extends StoreNames<T>>(key: StoreKey<T, Name> | IDBKeyRange): Promise<void>;

Deletes the value stored under a key, or all values in a key range.

ParameterTypeDescription
keyStoreKey<T, Name> | IDBKeyRangeThe key, or an IDBKeyRange.

Returns: Promise<void> · Availability: Client

clearStore(storeName: string, dbName: string): Promise<void>;

Deletes all values in the store.

ParameterTypeDescription
storeNamestringName of the object store.
dbNamestringName of the database.

Note

Both parameters are ignored: clearStore() always clears the store of this connection.

Returns: Promise<void> · Availability: Client

transaction<R>(fn: (tx: IDBPObjectStore<T, [StoreNames<T>], StoreNames<T>, 'readwrite'>) => R): Promise<R>;

Runs several operations on the store in one read-write transaction. If fn throws or its promise rejects, the transaction is aborted and none of its changes are kept.

ParameterTypeDescription
fn(tx: IDBPObjectStore<T, [StoreNames<T>], StoreNames<T>, 'readwrite'>) => RFunction that receives the object store (an idb object store) and performs the operations. Values written here are stored as they are, without Lowgile’s JSON conversion.
const store = Sys.Storage.openSimpleIdb('counters', 'myCounters')
await store.transaction(async (tx) => {
const count = (await tx.get('visits')) ?? 0
await tx.put(count + 1, 'visits')
})

Returns: Promise<R> · Availability: Client