Persistence

Read the persistent cache guide. Signatures below come from the published SDK declarations. Access SDK services through db; use their constructors only when integrating at a lower level.

QueuedEvent

/** Only signed wire events are persisted. Decrypted records are never written here. */
interface QueuedEvent {
  event: NostrEvent;
  queuedAt: number;
  attempts: number;
  relays: RelayResult[];
}

PersistenceAdapter

interface PersistenceAdapter {
  loadEvents(namespace?: string): Promise<NostrEvent[]>;
  putEvents(events: readonly NostrEvent[], namespace?: string): Promise<void>;
  loadQueue(namespace?: string): Promise<QueuedEvent[]>;
  putQueue(entry: QueuedEvent, namespace?: string): Promise<void>;
  removeQueue(eventId: string, namespace?: string): Promise<void>;
  close(): void | Promise<void>;
}

PersistenceOptions

interface PersistenceOptions {
  adapter: PersistenceAdapter;
  flushInterval?: number;
  batchSize?: number;
  onError?: (error: NostrbaseError) => void;
}

MemoryPersistenceAdapter

/** Useful for tests, temporary caches, and explicit in-memory offline queues. */
declare class MemoryPersistenceAdapter implements PersistenceAdapter {}

loadEvents

loadEvents(namespace?: string): Promise<NostrEvent[]>;

putEvents

putEvents(events: readonly NostrEvent[], namespace?: string): Promise<void>;

loadQueue

loadQueue(namespace?: string): Promise<QueuedEvent[]>;

putQueue

putQueue(entry: QueuedEvent, namespace?: string): Promise<void>;

removeQueue

removeQueue(eventId: string, namespace?: string): Promise<void>;

close

close(): void;

IndexedDBPersistenceAdapter

/** Use a distinct name per namespace/profile. The supplied factory also permits worker/test use. */
declare class IndexedDBPersistenceAdapter implements PersistenceAdapter {}

constructor

constructor(name?: string, factory?: IDBFactory | undefined);

loadEvents

loadEvents(namespace?: string): Promise<NostrEvent[]>;

putEvents

putEvents(events: readonly NostrEvent[], namespace?: string): Promise<void>;

loadQueue

loadQueue(namespace?: string): Promise<QueuedEvent[]>;

putQueue

putQueue(entry: QueuedEvent, namespace?: string): Promise<void>;

removeQueue

removeQueue(eventId: string, namespace?: string): Promise<void>;

close

close(): Promise<void>;

NostrbasePersistence

/** Persist all verified ingested events, including deletion tombstones and ciphertext. */
declare class NostrbasePersistence {}

Properties

readonly adapter: PersistenceAdapter;

constructor

constructor(host: PersistenceHost, options: PersistenceOptions);

ready

ready(): Promise<void>;

record

record(event: NostrEvent): void;

flush

flush(): Promise<void>;

close

close(): Promise<void>;

Supporting declarations

These types appear in public signatures but are not package exports.

PersistenceHost

interface PersistenceHost {
  namespace: string;
  ingest(event: NostrEvent): boolean;
}