Tavenem.Blazor.IndexedDB

Tavenem.Blazor.IndexedDB is a Razor class library (RCL) containing a Razor component. It grants managed access to the IndexedDB API.

It uses the idb javascript library by Jake Archibald, and implements the IDataStore interface from the Tavenem DataStore library.

Installation

Tavenem.Blazor.IndexedDB is available as a NuGet package.

Use

1. Construct an IndexedDb object to define the characteristics of your database.

   // simple
   var db = new IndexedDb("myDatabaseName", 1);
   
   // all options
   var db = new IndexedDb<int>(
       databaseName: "myDatabaseName",
       objectStores: ["valueStore"],
       version: 2);

   This object can be a static instance, or you can construct instances dynamically as needed.

2. Call AddIndexedDb(db) with an IndexedDb instance, or AddIndexedDb(provider => GetMyDatabase()) with a function that supplies one through dependency injection.

   Optional: you may also supply a customized instance of JsonSerializerOptions to control the serialization of your data items. If you do not choose to do so, the default Blazor options will be used, which are sufficient for most POCO objects, and optimizes the interop with the JavaScript layer.

3. Inject the IndexedDbService instance in a component.

4. Call the StoreItemAsync<T>, GetItemAsync<T>, and RemoveItemAsync<T> methods to work with strongly-typed data items.

   class Item : IIdItem
   {
       public string Id { get; set; }
       public string? Value { get; set; }
   }
   
   var item = new Item
   {
       Id = "1",
       Value = "Hello, World!",
   };
   
   var database = new IndexedDb<int>(
       databaseName: "myDatabaseName",
       objectStores: ["valueStore"],
       version: 2);
   
   var store = database["valueStore"];
   
   await store.StoreItemAsync(item);
   
   item.Value = "Goodbye!";
   await store.StoreItemAsync(item);
   
   var fetchedItem = await store.GetItemAsync<Item>(item.Id);
   // fetchedItem is an Item instance: item.Value = "Goodbye!"
   
   await store.RemoveItemAsync(item);
   
   fetchedItem = await store.GetItemAsync<Item>(item.Id);
   // fetchedItem is null

5. Call the Query<T> method to obtain an IDataStoreQueryable<T>. IDataStoreQueryable<T> is similar to IQueryable<T>, and can be used to make queries against the data source.

   await foreach (var item in store.Query().AsAsyncEnumerable())
   {
       Console.WriteLine(item.Value);
   }
   
   var helloCount = await store
       .Query()
       .Select(x => x.Value != null && x.Value.Contains("Hello"))
       .CountAsync();

6. Call the ClearAsync, CountAsync, and GetAllAsync<T> methods to work with the full object store.

   await store.StoreItemAsync(item);
   
   var count = await store.CountAsync();
   // count = 1
   
   var items = await store.GetAllAsync<Item>();
   // items is an array of Items with Length 1
   
   await store.ClearAsync();
   count = await store.CountAsync();
   // count = 0

7. Call the DeleteDatabaseAsync method to work with the full database.

   await database.DeleteDatabaseAsync();
   // the database has been removed (or will be, after all connections are closed)

Roadmap

New versions of Tavenem.IndexedDb should be expected whenever the API surface of the Tavenem DataStore library receives an update.

Other updates to resolve bugs or add new features may occur at any time.

Contributing

Contributions are always welcome. Please carefully read the contributing document to learn more before submitting issues or pull requests.

Code of conduct

Please read the code of conduct before engaging with our community, including but not limited to submitting or replying to an issue or pull request.