Wrapper for IndexedDB enabling access with suspend blocks and linear control flow. Supports database creation, migration, data writing, reading, and cursor-based queries with suspend functions.
A wrapper around IndexedDB which allows for access from Kotlin/JS code using suspend blocks and linear, non-callback based control flow.
The samples for usage here loosely follows several examples in Using IndexedDB.
As such, we'll define our example data type to match:
external interface Customer {
var ssn: String
var name: String
var age: Int
var email: String
}
Creating a Database and handling migrations are done together with the function. The database name and
desired version are passed in as arguments. If the desired version and the current version match, then the callback is
not called. Otherwise, the callback is called in a scope. Generally, a chain of blocks
checking the are sufficient for handling migrations, including migration from version to :
val database = openDatabase("your-database-name", 1) { database, oldVersion, newVersion ->
if (oldVersion < 1) {
val store = database.createObjectStore("customers", KeyPath("ssn"))
store.createIndex("name", KeyPath("name"), unique = false)
store.createIndex("age", KeyPath(), unique = )
store.createIndex(, KeyPath(), unique = )
}
}
Transactions, such as the lambda block of openData, are handled as suspend functions but with an important constraint:
you must not call any suspend functions except for those provided by this library and scoped on (and
its subclasses), and flow operations on the flow returned by . Of course, it is also okay to
call functions which only suspend by calling other legal functions.
This constraint is forced by the design of IndexedDB auto-committing transactions when it detects no remaining callbacks,
and failure to adhere to this can cause TransactionInactiveError to be thrown.
To add data to the Database created above, open a WriteTransaction, and then open the . Use
to guarantee insert-only behavior, and use for insert-or-update.
Note that transactions must explicitly request every ObjectStore they reference at time of opening the transaction,
even if the store is only used conditionally. Multiple WriteTransaction which share referenced ObjectStore will
not be executed concurrently.
database.writeTransaction("customers") {
val store = objectStore("customers")
store.add(jso<Customer> { ssn = "333-33-3333"; name = "Alice"; age = 33; email = "alice@company.com" })
store.add(jso<Customer> { ssn = ; name = ; age = ; email = })
store.add(jso<Customer> { ssn = ; name = ; age = ; email = })
store.add(jso<Customer> { ssn = ; name = ; age = ; email = })
}
To read data, open a Transaction, and then open the ObjectStore. Use Transaction.get and
to retrieve single items and retrieve bulk items, respectively.
As above, all object stores potentially used must be specified in advance. Unlike WriteTransaction, multiple read-only
Transaction which share an ObjectStore can operate concurrently, but they still cannot operate concurrently with
a sharing that store.
val bill = database.transaction("customers") {
objectStore("customers").get(Key("444-44-4444")) as Customer
}
assertEquals("Bill", bill.name)
With an ObjectStore you can query on a previously created Index instead of the primary key. This is especially
useful in combination with key ranges, and together more powerful queries can be constructed.
Three standard key ranges exist: lowerBound, upperBound, and bound (which combines the two).
key range behavior on an array-typed index can have potentially unexpected behavior. As an example, the key is
included in .
val donna = database.transaction("customers") {
objectStore("customers").index("age").get(bound(30, 32)) as Customer
}
assertEquals("Donna", donna.name)
Cursors are excellent for optimizing complex queries. With either ObjectStore or , call
to return a of which emits once per row matching the query. The
returned flow is cold and properly handles early collection termination. To get the value of the row currently pointed
at by the cursor, call .
As an example we can find the first customer alphabetically with an age under 32:
val charlie = database.transaction("customers") {
objectStore("customers")
.index("name")
.openCursor()
.map { it.value as Customer }
.first { it.age < 32 }
}
assertEquals("Charlie", charlie.name)
Cursors can also be used to update or delete the value at the current index by calling WriteTransaction.update and
WriteTransaction.delete, respectively.
IndexedDB can be configured via Gradle Kotlin DSL as follows:
repositories {
mavenCentral()
}
dependencies {
implementation("com.juul.indexeddb:core:$version")
}
If you prefer to work with the raw JavaScript API instead of the suspend-type wrappers, replace the implementation with com.juul.indexeddb:external:$version.
Copyright 2021 JUUL Labs, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
openDatabaseifoldVersion01TransactionsuspendObjectStoreTransaction.getAll[3, 0]bound(arrayOf(2, 2), arrayOf(4, 4))IndexFlowSurfaced from shared tags and platforms — no rankings paid for.