Kotlin IndexedDB

A wrapper around IndexedDB which allows for access from Kotlin/JS code using suspend blocks and linear, non-callback based control flow.

Usage

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
}

Creation & Migration

Creating a Database and handling migrations are done together with the openDatabase 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 VersionChangeTransaction scope. Generally, a chain of if blocks checking the oldVersion are sufficient for handling migrations, including migration from version 0 to 1:

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("age"), unique = false)
        store.createIndex("email", KeyPath("email"), unique = true)
    }
}

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 Transaction (and its subclasses), and flow operations on the flow returned by Transaction.openCursor. Of course, it is also okay to call suspend 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.

Writing Data

To add data to the Database created above, open a WriteTransaction, and then open the ObjectStore. Use WriteTransaction.add to guarantee insert-only behavior, and use WriteTransaction.put 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 = "444-44-4444"; name = "Bill"; age = 35; email = "bill@company.com" })
    store.add(jso<Customer> { ssn = "555-55-5555"; name = "Charlie"; age = 29; email = "charlie@home.org" })
    store.add(jso<Customer> { ssn = "666-66-6666"; name = "Donna"; age = 31; email = "donna@home.org" })
}

Reading Data

To read data, open a Transaction, and then open the ObjectStore. Use Transaction.get and Transaction.getAll 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 WriteTransaction sharing that store.

val bill = database.transaction("customers") {
    objectStore("customers").get(Key("444-44-4444")) as Customer
}
assertEquals("Bill", bill.name)

Key Ranges and Indices

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). Warning: key range behavior on an array-typed index can have potentially unexpected behavior. As an example, the key [3, 0] is included in bound(arrayOf(2, 2), arrayOf(4, 4)).

val donna = database.transaction("customers") {
    objectStore("customers").index("age").get(bound(30, 32)) as Customer
}
assertEquals("Donna", donna.name)

Cursors

Cursors are excellent for optimizing complex queries. With either ObjectStore or Index, call Transaction.openCursor to return a Flow of CursorWithValue 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 CursorWithValue.value.

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.

Setup

Gradle

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.

License

Copyright 2021 JUUL Labs, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.