Kebechet.Blazor.IndexedDB 1.0.0

Blazor.IndexedDB

Key/value and collection storage over IndexedDB for Blazor WebAssembly, Blazor Server and .NET MAUI Blazor Hybrid. One database, any number of named stores, values moved as UTF-8 JSON bytes, an atomic collection replace, and an in-memory fallback so a WebView without a working IndexedDB never breaks the app.

Live storybook - interactive stories for every feature.

Why

WebView storage is not a given. WKWebView can leave window.indexedDB undefined for a whole session after a background launch, and both iOS and Android may evict web storage under pressure. Most IndexedDB wrappers assume the API is there and throw when it is not - which, at startup, means a broken app. This package treats "no storage" as a normal state:

• Nothing throws. A failed read is a miss, a failed write is dropped and logged, and GetDriver() tells you which mode the session runs in.
• Bytes, not strings. Values cross the interop as byte[] produced by your JsonSerializerOptions, so a source-generated context keeps trimming and AOT safe under MAUI on iOS, and a 5k-record cache does not marshal a multi-megabyte string.
• Atomic collection replace. ReplaceCollection swaps a store's whole collection in one transaction; a reader never sees half old, half new.
• One database, many stores. Stores are namespaces inside one IndexedDB database, so listing, replacing or clearing a store is a single key range, not a schema migration.

Installation

dotnet add package Kebechet.Blazor.IndexedDB

Register the service. Pass your own JsonSerializerOptions when you use a source-generated context:

using Kebechet.Blazor.IndexedDB;

builder.Services.AddIndexedDbStorage(options =>
{
    options.DatabaseName = "my-app";
    options.JsonSerializerOptions = new JsonSerializerOptions
    {
        TypeInfoResolver = MyJsonContext.Default,
    };
});

No script tag: the JS module is imported on demand from the package's static web assets.

Usage

@inject IIndexedDbStorage _storage

@code {
    private const string SettingsStore = "settings";
    private const string ExercisesStore = "exercises";

    private async Task Example()
    {
        // key/value
        await _storage.Write(SettingsStore, "theme", new ThemeSettings { IsDark = true });
        var theme = await _storage.Read<ThemeSettings>(SettingsStore, "theme");   // null when missing
        var hasTheme = await _storage.Exists(SettingsStore, "theme");
        var keys = await _storage.GetKeys(SettingsStore);
        await _storage.Remove(SettingsStore, "theme");

        // a store's collection - replaced atomically, read back as a whole
        await _storage.ReplaceCollection(ExercisesStore, exercises);
        var cached = await _storage.ReadCollection<Exercise>(ExercisesStore);    // empty when missing

        // values that must survive a crash right after the write
        await _storage.Write("auth", "refreshToken", token, StorageDurability.Strict);

        // know what this session runs on
        var driver = await _storage.GetDriver();   // IndexedDb, Memory or Unavailable
        await _storage.Clear(ExercisesStore);
    }
}

API

StorageDurability maps to the IndexedDB transaction durability hint: Relaxed (default, faster) or Strict (flushed before the transaction completes).

Semantics worth knowing

• A store holds key/value entries and, independently, one collection. Clear wipes both; ReplaceCollection touches only the collection.
• The driver is decided once per session, on the first operation. A database that stops opening mid-session also switches the session to memory - the same rule, applied late.
• An existing database with the configured name is reused as it is; the package's own object store is added to it with a one-version bump, so it can share a database with other code.
• Every failure is logged through ILogger<IndexedDbStorage>: errors per failed operation, one warning when a session falls back to memory. Route those to your error reporting to learn how often real users run degraded.

Testing

dotnet test src/Blazor.IndexedDB.slnx                       # the .NET service: serialization, degradation, lifecycle
cd tests/Blazor.IndexedDB.JsTests && npm ci && npm test     # the JS module: IndexedDB path over fake-indexeddb, and the memory fallback

License

MIT