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(jsObject<Customer> { ssn = "333-33-3333"; name = "Alice"; age = 33; email = "[email protected]" })
store.add(jsObject<Customer> { ssn = "444-44-4444"; name = "Bill"; age = 35; email = "[email protected]" })
store.add(jsObject<Customer> { ssn = "555-55-5555"; name = "Charlie"; age = 29; email = "[email protected]" })
store.add(jsObject<Customer> { ssn = "666-66-6666"; name = "Donna"; age = 31; email = "[email protected]" })
}
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.
![[CRITICAL] Public Repositories are Disabled for this Org](https://avatars.githubusercontent.com/in/6895?v=4)
517 Nov 19, 2022
326 Dec 23, 2022
15 Oct 3, 2022
26 Oct 3, 2022
5 Feb 15, 2022
61 Nov 13, 2022
6 Jun 27, 2022
13 Jul 30, 2022
13 Aug 4, 2022
11 Nov 17, 2020
57 Dec 29, 2022
7 Dec 27, 2022
66 Aug 15, 2022
3 Aug 31, 2022
3 Aug 31, 2022
28 Dec 10, 2022
77 Dec 8, 2022
27 Nov 14, 2022