applesauce-indexeddb

Framework-independent IAsyncEventDatabase for browsers and workers with IndexedDB. Uses nostr-idb 5.1's schema, tag encoding and low-level author/kind/tag query helpers, plus idb for typed transactions. It has no dependency on browserdb or Qwik.

import { openIndexedDBEventDatabase } from "applesauce-indexeddb";
const database = await openIndexedDBEventDatabase({ name: "my-events-v1" });
// await database.add(aVerifiedNostrEvent);
const timeline = await database.getTimeline({ kinds: [1], limit: 50 });
await database.close();

The adapter always requires IndexedDB. Denied/absent storage rejects; it never creates a memory cache. Fallback belongs in an application selector such as mostard-qwik-browserdb. persistence, if supplied, must be "required". Options include injected factory, signal, timeoutMs and an advisory probe. Applications close the returned database. Abort, timeout and blocked upgrades reject and release late connections. Version changes close the connection; subsequent operations fail until the application explicitly initializes a new lifetime.

The high-level nostr-idb class is deliberately not instantiated: its cached map, queued writes, pruning and address-key replacement would change Applesauce's database contract. This adapter stores plain signed fields under event-id primary keys so replaceable history remains queryable. No runtime symbols are persisted. It awaits transaction completion (tx.done), not merely a request or commit() call. There is no automatic pruning.

Schema version 3 contains nostr-idb events and used stores and its standard indexes. used is reserved for compatibility and is not used for a RAM/pruning layer. Upgrading an earlier applesauce generic records cache copies its plain events into the new store in the upgrade transaction; old records remain untouched. Existing nostr-idb databases with address-keyed replaceables are not interchangeable: use a distinct application database name.

Queries narrow with one index and then apply Applesauce's complete Nostr matcher. Filter branches union after each branch's limit, sort newest first with ascending id ties, preserve NIP-91 tag semantics, and match empty ids/authors/kinds/OR-tag groups to no events. Full-text search and invalid limits reject with Validation. Replaceable history remains available until explicit removal.

This is a cache adapter, not an event verifier. Verify network events through Applesauce's EventStore before inserting. removeByFilters() selects matching ids, then deletes those ids in one write transaction; concurrent new arrivals after selection are not included.

Run package tests with pnpm exec vitest run --project applesauce-indexeddb from the Applesauce workspace, and build with pnpm --filter applesauce-indexeddb build.