Crate idb

Expand description

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.

Re-exports§

pub use self::event::DatabaseEvent;
pub use self::event::Event;
pub use self::event::StoreEvent;
pub use self::request::Request;

Modules§

builderbuilder: Contains the builder for the database.
event: This module contains the definition of the Event trait and its implementations.
request: This module contains all the types for handling database requests.

Structs§

Cursor: Represents a cursor for traversing or iterating over multiple records in a database.
Database: Database provides a connection to a database; you can use an Database object to open a transaction on your database then create, manipulate, and delete objects (data) in that database. The object provides the only way to get and manage versions of the database.
Factory: Lets applications asynchronously access the indexed databases.
Index: Provides asynchronous access to an index in a database.
IndexParams: Options when creating Index.
KeyCursor: Represents a key cursor for traversing or iterating over multiple records (only keys) in a database.
KeyRange: Represents a continuous interval over some data type that is used for keys.
ManagedCursorfutures: A cursor that is managed by the library (for ease of use).
ManagedKeyCursorfutures: A key cursor that is managed by the library (for ease of use).
ObjectStore: Represents an object store in a database.
ObjectStoreParams: Options when creating an ObjectStore.
Transaction: Provides a static, asynchronous transaction on a database. All reading and writing of data is done within transactions.
TransactionFuturefutures: Future that resolved when transaction is completed. Either successfully or with an error.

Enums§

CursorDirection: Specifies the cursor direction.
Error: Error type for idb-sys crate.
KeyPath: Represents key path of an object store
Query: Specifies a query when fetching data from object store
TransactionMode: Specifies the transaction mode.
TransactionResultfutures: An enum that represents the result state of a transaction.