@estiva-app/platform 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @estiva-app/platform
 
+## 0.5.0
+
+A copy on the device a reload draws from (PEE-2, Peek opens instantly). Additive.
+
+`createEventSnapshot` keeps one person's signed events from one relay —
+never a folded view — and answers the same filters from them on the next
+load, before the relay has. Every relay answer it takes in is also a
+correction, since the relay has no sequence number to replay: what matches a
+filter the relay just answered and is not in that answer is dropped (a
+deletion, a lost Folder); a cut answer judges only the window it covers; a
+`kind:5` drops what its own author signed; a replaceable event keeps its
+newest. A filter it never saw answered is not answered (`null`), and `since`
+and `until` are not part of a filter's key. It keeps the plaintext of a
+person's own blob beside its event, so the same ciphertext is never
+decrypted twice.
+
+- `createEventSnapshot({ storage, scope, version, maxEvents?, saveAfterMs?, now?, timers? })`
+  → `{ ready, answer(filters), absorb(filters, events), plaintextOf, keepPlaintext, size, flush, close, discard }`.
+  An answer absorbed before `ready` is applied over the stored copy; a failed
+  save is asked again; `close` writes what changed, `discard` (sign-out) does not.
+  A `kind:5` drops `e` targets and `a` coordinates its own author signed.
+  A plaintext is kept only beside the person's own replaceable event.
+- `SnapshotStorage` — `load(scope)` → `{ epoch, record }`, `save(scope, change)`
+  with `change.epoch`, `clear()`. `clear` counts a sign-out, and a save naming
+  an older count writes nothing: a copy opened before a sign-out, in any tab,
+  cannot write the person's data back after it.
+  A copy written under another `version` is dropped unread; past `maxEvents`
+  (10,000) the least recently seen go.
+- `indexedDbSnapshotStorage(indexedDB, name?)` — the browser's storage, the
+  factory passed in (the package compiles without `lib: dom`);
+  `memorySnapshotStorage()` for tests and browsers without it; `clear()` is
+  sign-out.
+- `snapshotScope(relayUrl, pubkey)`, `snapshotFilterKey(filter)`,
+  `matchesSnapshotFilter(filter, event)`.
+
 ## 0.4.0
 
 One read a tab holds on to, and reads again when it fails (FOL-5). Additive.

package/README.md

@@ -140,9 +140,46 @@ await relayBudget.whenClear()
 Nothing here gates a read. A read somebody asked for by clicking still goes out
 at once; only the cadence backs off.
 
+### A copy on the device, so a reload draws at once
+
+`createEventSnapshot` keeps what the relay told one person — signed events,
+never a folded view — and answers the same filters from it on the next load.
+Fold its answer as you fold the relay's, then send the relay the read as
+before and fold again: the relay's answer replaces the copy's.
+
+```ts
+import { createEventSnapshot, indexedDbSnapshotStorage, snapshotScope } from '@estiva-app/platform'
+
+const storage = indexedDbSnapshotStorage(indexedDB, 'my-app-copy')
+const copy = createEventSnapshot({
+  storage,
+  scope: snapshotScope(relayUrl, pubkey),
+  version: 1, // bump when what you fold from it changes meaning
+})
+
+// In the transport, on every answer the relay gives:
+copy.absorb(filters, events)
+
+// Before the relay answers: null means the copy never saw this read answered.
+await copy.ready
+const drawnFirst = copy.answer(filters)
+
+// Signing out: every copy goes, and one still open — in this tab or another —
+// can never write the person's data back (the storage counts sign-outs).
+copy.discard()
+await storage.clear()
+```
+
+Every answer is also a correction: an event the copy holds that matches a
+filter the relay just answered, and is not in that answer, is dropped — a
+deletion, or a Folder the person lost. A `kind:5` drops what its author
+signed. `keepPlaintext` keeps the plaintext of the person's own blob beside
+the event, so an unchanged blob needs no decrypt on the next load. Never
+publish over something drawn from the copy: it may be older than the relay.
+
 ## What this deliberately does not know
 
-Where anything is stored. Peek's version took a `LiveProjectionApi`, and
+Where anything is stored, beyond the copy's storage you hand it. Peek's version took a `LiveProjectionApi`, and
 extracting that as-is would have baked a Convex assumption into a package two
 apps depend on. This delivers frames and connection state and nothing else, so
 it bets on neither outcome of "do we need Convex": if Convex stays nothing here

package/dist/event-snapshot.d.ts

@@ -0,0 +1,179 @@
+/**
+ * A copy of what the relay told one person, kept on the device (PEE-2).
+ *
+ * The copy holds **signed events**, the stores' raw input, never a folded view:
+ * a fold can change shape in any release, an event cannot. So an app draws
+ * from the copy by running the reads it would have sent, against the copy, and
+ * folding the answer exactly as it folds the relay's — and then sends the same
+ * reads to the relay and folds again. Nothing here knows which app or store it
+ * feeds.
+ *
+ * ## What the copy may answer
+ *
+ * A read whose every filter has been answered by the relay before, on this
+ * device, for this person. Its key leaves out `since` and `until`, which are
+ * usually a clock: "the last 30 days" asked yesterday is the same question.
+ * A filter never asked, or a `search`, is not answered — an empty answer from
+ * a copy that simply never saw the question would draw "nothing here", which
+ * is a claim, where no answer draws today's placeholder.
+ *
+ * ## Keeping it honest without a sequence number
+ *
+ * The relay has no change feed to replay, so every answer it gives is also a
+ * correction: an event the copy holds that matches a filter the relay just
+ * answered, and is not in that answer, is gone (deleted, or in a Folder this
+ * person has lost — Buzz answers lost access with an empty list). When the
+ * answer was cut by its `limit`, only the window it covers is judged: below
+ * its oldest event the relay said nothing. A `kind:5` drops the events it
+ * names that its own author signed. A replaceable event keeps only its newest.
+ *
+ * ## Plaintexts
+ *
+ * An app's own blob is ciphertext on the wire; decrypting it is a round trip
+ * the relay's signer meters. The plaintext is the person's own data, so it is
+ * kept beside the event that carried it and handed back for the same
+ * ciphertext — which always decrypts to the same text, so it is never stale.
+ */
+import type { SignedEvent } from '@estiva-app/protocol';
+/** A Nostr filter as an app sends it: `ids`, `kinds`, `authors`, `#x`, `since`, `until`, `limit`. */
+export type SnapshotFilter = Record<string, unknown>;
+/** One event in storage, with the plaintext of its content when the app kept one. */
+export interface StoredSnapshotEvent {
+    event: SignedEvent;
+    plaintext?: string;
+    /** Epoch ms of the last answer that carried it: the oldest go first past the cap. */
+    seenAt: number;
+}
+/** What a scope holds in storage. */
+export interface SnapshotRecord {
+    version: number;
+    events: StoredSnapshotEvent[];
+    /** The keys of every filter the relay has answered (see {@link snapshotFilterKey}). */
+    filters: string[];
+}
+/** What changed since the last save. */
+export interface SnapshotChange {
+    version: number;
+    /** The storage's sign-out count when the copy was read: a save from before a sign-out is refused. */
+    epoch: number;
+    put: StoredSnapshotEvent[];
+    remove: string[];
+    filters: string[];
+}
+/** Where a copy lives between page loads. {@link indexedDbSnapshotStorage} is the browser's. */
+export interface SnapshotStorage {
+    /** A scope's record, or null; and the storage's sign-out count, which every save names. */
+    load(scope: string): Promise<{
+        epoch: number;
+        record: SnapshotRecord | null;
+    }>;
+    /** Writes nothing when `change.epoch` is not the current count: somebody signed out since. */
+    save(scope: string, change: SnapshotChange): Promise<void>;
+    /**
+     * Remove every scope and count a sign-out, so a copy still open — in this
+     * tab or another — can never write the person's data back afterwards.
+     */
+    clear(): Promise<void>;
+}
+export interface SnapshotTimers {
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface EventSnapshotOptions {
+    storage: SnapshotStorage;
+    /** Whose blobs' plaintexts are kept; defaults to the pubkey in `scope`. */
+    owner?: string;
+    /** One person on one relay: {@link snapshotScope}. */
+    scope: string;
+    /** The app's schema version. A copy written under another one is dropped unread. */
+    version: number;
+    /** Past this many events the least recently seen are dropped. */
+    maxEvents?: number;
+    /** How long after a change the copy is written. */
+    saveAfterMs?: number;
+    now?: () => number;
+    timers?: SnapshotTimers;
+}
+export interface EventSnapshot {
+    /** Settles once the stored copy has been read, or found unusable. Never rejects. */
+    ready: Promise<void>;
+    /** The events the copy holds for these filters, as the relay would order them; `null` when it cannot answer. */
+    answer(filters: SnapshotFilter[]): SignedEvent[] | null;
+    /** Take in the relay's answer to these filters: add what it sent, drop what it no longer has. */
+    absorb(filters: SnapshotFilter[], events: SignedEvent[]): void;
+    /** The kept plaintext of a ciphertext this copy holds, if any. */
+    plaintextOf(content: string): string | undefined;
+    keepPlaintext(content: string, plaintext: string): void;
+    size(): number;
+    /** Write what changed now, rather than after `saveAfterMs`. */
+    flush(): Promise<void>;
+    /** Stop, writing what changed first; nothing more is written after. */
+    close(): void;
+    /** Stop and write nothing: the copy is about to be cleared (sign-out). */
+    discard(): void;
+}
+export declare const SNAPSHOT_MAX_EVENTS = 10000;
+export declare const SNAPSHOT_SAVE_AFTER_MS = 1000;
+/** The scope of one person's copy on one relay. */
+export declare function snapshotScope(relayUrl: string, pubkey: string): string;
+/** A filter's identity as a question, without its clock (`since`, `until`). */
+export declare function snapshotFilterKey(filter: SnapshotFilter): string;
+/** Whether an event matches a filter, `limit` aside — NIP-01's rule. */
+export declare function matchesSnapshotFilter(filter: SnapshotFilter, event: SignedEvent): boolean;
+export declare function createEventSnapshot(options: EventSnapshotOptions): EventSnapshot;
+/**
+ * Keeps nothing between page loads: for a test, and for a browser without
+ * IndexedDB, where the copy still answers within one load.
+ */
+export declare function memorySnapshotStorage(): SnapshotStorage & {
+    records: Map<string, SnapshotRecord>;
+};
+interface IdbRequest<T = unknown> {
+    result: T;
+    error: unknown;
+    onsuccess: ((this: unknown, ev: unknown) => unknown) | null;
+    onerror: ((this: unknown, ev: unknown) => unknown) | null;
+}
+interface IdbOpenRequest extends IdbRequest<IdbDatabase> {
+    onupgradeneeded: ((this: unknown, ev: unknown) => unknown) | null;
+}
+interface IdbIndex {
+    getAll(query: unknown): IdbRequest<unknown[]>;
+    getAllKeys(query: unknown): IdbRequest<unknown[]>;
+}
+interface IdbObjectStore {
+    put(value: unknown): IdbRequest;
+    get(key: unknown): IdbRequest<unknown>;
+    delete(key: unknown): IdbRequest;
+    clear(): IdbRequest;
+    index(name: string): IdbIndex;
+    createIndex(name: string, keyPath: string): unknown;
+}
+interface IdbTransaction {
+    objectStore(name: string): IdbObjectStore;
+    oncomplete: ((this: unknown, ev: unknown) => unknown) | null;
+    onerror: ((this: unknown, ev: unknown) => unknown) | null;
+    onabort: ((this: unknown, ev: unknown) => unknown) | null;
+    error: unknown;
+}
+interface IdbDatabase {
+    objectStoreNames: {
+        contains(name: string): boolean;
+    };
+    createObjectStore(name: string, options: {
+        keyPath: string | string[];
+    }): IdbObjectStore;
+    transaction(stores: string[], mode: 'readonly' | 'readwrite'): IdbTransaction;
+    close(): void;
+}
+/** The part of `window.indexedDB` a snapshot uses. */
+export interface IdbFactoryLike {
+    open(name: string, version: number): IdbOpenRequest;
+}
+/**
+ * The browser's storage for a copy: one database, `events` keyed by scope and
+ * id, and a `meta` row per scope with its version and answered filters.
+ */
+export declare function indexedDbSnapshotStorage(indexedDB: IdbFactoryLike, name?: string): SnapshotStorage;
+export {};
+//# sourceMappingURL=event-snapshot.d.ts.map

package/dist/event-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-snapshot.d.ts","sourceRoot":"","sources":["../src/event-snapshot.ts"],"names":[],"mappings":"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"}