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. Register the IndexedDbService with dependency injection.

   builder.Services.AddIndexedDbService();

2. Register one or more IndexedDb instances with dependency injection.

   // simple
   builder.Services.AddIndexedDb("myDatabaseName");
   
   // all options
   builder.Services.AddIndexedDb(
       databaseName: "myDatabaseName", // the database name
       objectStores: ["valueStore"], // the names of value stores
       version: 2, // the version number of the current database schema
       jsonSerializerOptions: new(JsonSerializerDefaults.Web), // a JsonSerializerOptions instance
       key: "id"); // the name of the property to use as the primary key in stored objects

   Note that use of dependency injection for database instances is optional. They can also be initialized on demand with their public constructor, which requires an instance of IndexedDbService.

3. Inject an IndexedDb instance in a component.

   [Inject(Key = "myDatabaseName")] private IndexedDb MyDatabase { get; set; } = default!;

   Note that the @inject directive does not currently support keyed services.

4. Retrieve an IndexedDbStore instance by name.

   var store = MyDatabase["valueStore"];

5. Call the StoreItemAsync<T>, GetItemAsync<T>, and RemoveItemAsync<T> methods on an IndexedDbStore 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!",
   };
   
   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

6. 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<Item>().AsAsyncEnumerable())
   {
       Console.WriteLine(item.Value);
   }
   
   var helloCount = await store
       .Query<Item>()
       .Select(x => x.Value != null && x.Value.Contains("Hello"))
       .CountAsync();

7. 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

8. Call the DeleteDatabaseAsync method on the IndexedDb instance to remove the entire database.

   await MyDatabase.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.

There is a preview release available now. See README_preview.md for an updated example of how to use the new API.

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.