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
Functions
Section titled “Functions”openSimpleIdb()
Section titled “openSimpleIdb()”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.
| Parameter | Type | Description |
|---|---|---|
storeName | string | Optional. Name of the object store. Default: 'default'. |
dbName | string | Optional. 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()
Section titled “openIdbDatabase()”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.
| Parameter | Type | Description |
|---|---|---|
name | string | Name of the database. |
version | number | Optional. 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. |
callbacks | OpenDBCallbacks<T> | Optional. Callbacks for version changes. |
OpenDBCallbacks<T> fields
| Field | Type | Required | Description |
|---|---|---|---|
upgrade | (database, oldVersion, newVersion, transaction, event) => void | Optional | Called when the database is created or opened with a higher version. Create object stores and indexes here. |
blocked | (currentVersion, blockedVersion, event) => void | Optional | Called 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) => void | Optional | Called when this connection prevents a newer version of the database from opening. |
terminated | () => void | Optional | Called 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
Properties
Section titled “Properties”localStorage
Section titled “localStorage”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
indexedDB
Section titled “indexedDB”get indexedDB(): IDBFactory;The browser’s IndexedDB factory, for using the IndexedDB API directly.
Type: IDBFactory · Availability: Client
Classes
Section titled “Classes”SimpleIdbConnection
Section titled “SimpleIdbConnection”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.
| Parameter | Type | Description |
|---|---|---|
key | StoreKey<T, Name> | IDBKeyRange | The key, for example a string or number. |
value | any | The value to store. |
Returns: Promise<void> · Availability: Client
getFirst()
Section titled “getFirst()”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.
| Parameter | Type | Description |
|---|---|---|
key | StoreKey<T, Name> | IDBKeyRange | The key, or an IDBKeyRange. |
Returns: Promise<StoreValue<T, StoreNames<T>>> · Availability: Client
getAll()
Section titled “getAll()”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.
| Parameter | Type | Description |
|---|---|---|
key | StoreKey<T, Name> | IDBKeyRange | The 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()
Section titled “delete()”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.
| Parameter | Type | Description |
|---|---|---|
key | StoreKey<T, Name> | IDBKeyRange | The key, or an IDBKeyRange. |
Returns: Promise<void> · Availability: Client
clearStore()
Section titled “clearStore()”clearStore(storeName: string, dbName: string): Promise<void>;Deletes all values in the store.
| Parameter | Type | Description |
|---|---|---|
storeName | string | Name of the object store. |
dbName | string | Name of the database. |
Note
Both parameters are ignored: clearStore() always clears the store of this connection.
Returns: Promise<void> · Availability: Client
transaction()
Section titled “transaction()”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.
| Parameter | Type | Description |
|---|---|---|
fn | (tx: IDBPObjectStore<T, [StoreNames<T>], StoreNames<T>, 'readwrite'>) => R | Function 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