#indexed-db #future

idb

A futures based crate for interacting with IndexedDB on browsers using webassembly

11 unstable releases (5 breaking)

0.6.4 Oct 9, 2024
0.6.2 Jul 4, 2024
0.6.1 Jan 25, 2024
0.4.1 Mar 11, 2023
0.1.0 Jul 7, 2022

#54 in WebAssembly

Download history 456/week @ 2024-07-12 336/week @ 2024-07-19 760/week @ 2024-07-26 608/week @ 2024-08-02 1145/week @ 2024-08-09 713/week @ 2024-08-16 725/week @ 2024-08-23 1996/week @ 2024-08-30 1653/week @ 2024-09-06 1354/week @ 2024-09-13 2661/week @ 2024-09-20 2613/week @ 2024-09-27 2733/week @ 2024-10-04 1390/week @ 2024-10-11 2197/week @ 2024-10-18 2635/week @ 2024-10-25

9,348 downloads per month
Used in 11 crates (5 directly)

MIT/Apache

150KB
3.5K SLoC

idb

A futures based crate for interacting with IndexedDB on browsers using webassembly.

Usage

To use idb, you need to run following command from your project root:

cargo add idb

If you don't want to use async/await syntax, you can disable the futures feature using:

cargo add idb --no-default-features

After disabling the futures feature, you can use on_success and on_error methods on requests to attach callbacks.

Example

To create a new database, you can use Factory::open:

use idb::{Database, DatabaseEvent, Error, Factory, IndexParams, KeyPath, ObjectStoreParams};

async fn create_database() -> Result<Database, Error> {
    // Get a factory instance from global scope
    let factory = Factory::new()?;

    // Create an open request for the database
    let mut open_request = factory.open("test", Some(1)).unwrap();

    // Add an upgrade handler for database
    open_request.on_upgrade_needed(|event| {
        // Get database instance from event
        let database = event.database().unwrap();

        // Prepare object store params
        let mut store_params = ObjectStoreParams::new();
        store_params.auto_increment(true);
        store_params.key_path(Some(KeyPath::new_single("id")));

        // Create object store
        let store = database
            .create_object_store("employees", store_params)
            .unwrap();

        // Prepare index params
        let mut index_params = IndexParams::new();
        index_params.unique(true);

        // Create index on object store
        store
            .create_index("email", KeyPath::new_single("email"), Some(index_params))
            .unwrap();
    });

    // `await` open request
    open_request.await
}

To add data to an object store, you can use ObjectStore::add:

use idb::{Database, Error, TransactionMode};
use serde::Serialize;
use serde_wasm_bindgen::Serializer;
use wasm_bindgen::JsValue;

async fn add_data(database: &Database) -> Result<JsValue, Error> {
    // Create a read-write transaction
    let transaction = database.transaction(&["employees"], TransactionMode::ReadWrite)?;

    // Get the object store
    let store = transaction.object_store("employees").unwrap();

    // Prepare data to add
    let employee = serde_json::json!({
        "name": "John Doe",
        "email": "john@example.com",
    });

    // Add data to object store
    let id = store
        .add(
            &employee.serialize(&Serializer::json_compatible()).unwrap(),
            None,
        )
        .unwrap()
        .await?;

    // Commit the transaction
    transaction.commit()?.await?;

    Ok(id)
}

To get data from an object store, you can use ObjectStore::get:

use idb::{Database, Error, TransactionMode};
use serde_json::Value;
use wasm_bindgen::JsValue;

async fn get_data(database: &Database, id: JsValue) -> Result<Option<Value>, Error> {
    // Create a read-only transaction
    let transaction = database
        .transaction(&["employees"], TransactionMode::ReadOnly)
        .unwrap();

    // Get the object store
    let store = transaction.object_store("employees").unwrap();

    // Get the stored data
    let stored_employee: Option<JsValue> = store.get(id)?.await?;

    // Deserialize the stored data
    let stored_employee: Option<Value> = stored_employee
        .map(|stored_employee| serde_wasm_bindgen::from_value(stored_employee).unwrap());

    // Wait for the transaction to complete (alternatively, you can also commit the transaction)
    transaction.await?;

    Ok(stored_employee)
}

For more examples on using other functionality, see the tests directory.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~7–16MB
~203K SLoC