@ebbjs/storage 0.0.0-stage → 0.1.0

package/dist/indexeddb/index.d.ts

@@ -0,0 +1,465 @@
+import { Action, Update, Entity } from '@ebbjs/core';
+
+/**
+ * One entry in the append-ordered action log.
+ *
+ * `position` is the log's own monotonic append cursor. It exists because
+ * the server `gsn` is not a total log cursor: an Action can arrive once
+ * per group (#473), `gsn: 0` is legal (#475 backfill), and a `gsn` cannot
+ * distinguish "already folded into the persisted replica" from
+ * "appended after it". The replica loads a persisted base at `position`
+ * and replays `readTail(position)`.
+ */
+interface LoggedAction {
+    /**
+     * The merged Action. A repeated id (#473) reports the union of every
+     * Update delivered for that id, not just this delivery's slice.
+     */
+    readonly action: Action;
+    /** The log-local append cursor for this Action. Stable across re-delivery. */
+    readonly position: number;
+    /**
+     * The Updates to fold. For `append`, only those not already logged for
+     * this id — a repeated Action id (`#473`) can carry disjoint per-group
+     * copies, and folding a whole re-delivered copy would re-apply an older
+     * `put` and revert a newer `patch`. For `readTail`, every Update of the
+     * merged Action.
+     */
+    readonly added: readonly Update[];
+}
+/**
+ * ActionLog — the append-ordered, id-keyed source of truth.
+ *
+ * The replica's durable log. `append` returns the newly-added Updates and
+ * the log-local position; `readTail` replays the entries after a
+ * watermark. `getAll` / `getForEntity` remain for the entity store that
+ * still backs the pre-replica read path.
+ *
+ * ## Methods
+ * - `append(action)` — stores or merges an Action, returns the delta + position
+ * - `appendMany(actions)` — `append` for a batch, in one durable write
+ * - `readTail(afterPosition)` — every entry with `position > afterPosition`, in order
+ * - `lastPosition()` — the log's current append cursor
+ * - `getAll()` — returns all merged Actions
+ * - `getForEntity(entityId)` — returns all Actions affecting an entity, sorted by gsn
+ * - `clear()` — removes all actions (used for reset)
+ */
+interface ActionLog {
+    append(action: Action): Promise<LoggedAction>;
+    /**
+     * Append every Action in one durable write (one IndexedDB transaction), in
+     * order, returning the same entries `append` would. A listing seed writes a
+     * page this way: the page is the unit that must land whole or not at all
+     * (#476).
+     */
+    appendMany(actions: readonly Action[]): Promise<readonly LoggedAction[]>;
+    readTail(afterPosition: number): Promise<readonly LoggedAction[]>;
+    lastPosition(): Promise<number>;
+    getAll(): Promise<readonly Action[]>;
+    getForEntity(entityId: string): Promise<readonly Action[]>;
+    clear(): Promise<void>;
+}
+
+/**
+ * DirtyTracker — tracks which entities need rematerialization.
+ *
+ * An entity is "dirty" when it has pending actions that haven't been
+ * applied to the materialized entity cache. Callers should invoke
+ * `mark(entityId, entityType)` when an action affects an entity, then
+ * materialize via `EntityStore.get()` or `EntityStore.query()`.
+ *
+ * ## Methods
+ * - `mark(entityId, entityType)` — marks an entity dirty (idempotent)
+ * - `isDirty(entityId)` — checks if an entity needs materialization
+ * - `getDirtyForType(entityType)` — returns all dirty entity IDs of a type
+ * - `clear(entityId)` — clears dirty flag after materialization
+ * - `clearAll()` — clears all dirty flags (used for reset)
+ */
+interface DirtyTracker {
+    mark(entityId: string, entityType: string): Promise<void>;
+    isDirty(entityId: string): Promise<boolean>;
+    getDirtyForType(entityType: string): Promise<readonly string[]>;
+    clear(entityId: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
+
+/**
+ * Lookup key for the relationship index: the accessor name (`as`),
+ * the relationship type string, and the target entity id.
+ */
+interface RelationshipIndexQuery {
+    readonly as: string;
+    readonly type: string;
+    readonly targetId: string;
+}
+/**
+ * Lookup key for the source-keyed forward relationship index: the
+ * accessor name (`as`), the relationship type string, and the source
+ * entity id.
+ */
+interface RelationshipSourceQuery {
+    readonly as: string;
+    readonly type: string;
+    readonly sourceId: string;
+}
+/** One live relationship edge read from the source side. */
+interface RelationshipLink {
+    /** The `relationship` row id — the `subject_id` an unlink names. */
+    readonly relationshipId: string;
+    readonly targetId: string;
+}
+/** One live membership row read from the member entity side. */
+interface MembershipLink {
+    /** The `entityGroup` row id — the `subject_id` a delete names. */
+    readonly membershipId: string;
+    readonly groupId: string;
+}
+/**
+ * EntityStore — materialized entity cache supporting get-by-ID and query-by-type.
+ *
+ * Entities are materialized on-demand from the action log when they are dirty.
+ * The entity store is not responsible for marking entities dirty — that is
+ * handled by the DirtyTracker.
+ *
+ * ## Merge Semantics
+ * - **put** — full entity replacement
+ * - **patch** — field-level Last-Writer-Wins (LWW): higher HLC wins; tiebreak by lexicographic `update_id`
+ * - **delete** — soft delete (sets `deleted_hlc`); patch-on-deleted is ignored
+ *
+ * A field value is either a leaf merged by the LWW rule above, or a
+ * `{ map }` of nested field values merged key by key under the same
+ * rule. Map key sets are unioned, so a write to one key leaves its
+ * siblings untouched; a leaf `value: null` is a tombstone retained for
+ * late-apply and hidden by projection.
+ *
+ * ## Methods
+ * - `get(id)` — returns entity by ID, materializes if dirty
+ * - `set(entity)` — directly sets an entity (bypasses materialization)
+ * - `query(type)` — returns all materialized entities of a type
+ * - `queryByRelationship({ as, type, targetId })` — returns the distinct
+ *   source ids indexed under that triple in ascending order,
+ *   materializing dirty relationship rows first
+ * - `queryByRelationshipSource({ as, type, sourceId })` — returns the
+ *   live edges out of that source, ascending by target id,
+ *   materializing dirty relationship rows first
+ * - `queryByMembership(groupId)` — returns the distinct live member
+ *   entity ids whose `entityGroup` row points at the group, ascending,
+ *   materializing dirty `entityGroup` rows first
+ * - `queryByMembershipEntity(entityId)` — returns the live membership
+ *   rows of that member entity, ascending by group id, materializing
+ *   dirty `entityGroup` rows first
+ * - `reset()` — clears all cached entities
+ */
+interface EntityStore {
+    get(id: string): Promise<Entity | null>;
+    set(entity: Entity): Promise<void>;
+    query(type: string): Promise<readonly Entity[]>;
+    queryByRelationship(query: RelationshipIndexQuery): Promise<readonly string[]>;
+    queryByRelationshipSource(query: RelationshipSourceQuery): Promise<readonly RelationshipLink[]>;
+    queryByMembership(groupId: string): Promise<readonly string[]>;
+    queryByMembershipEntity(entityId: string): Promise<readonly MembershipLink[]>;
+    reset(): Promise<void>;
+}
+
+/**
+ * CursorStore — per-group sync resume state for the client.
+ *
+ * One record per group holds the cursor its view is complete as of, and,
+ * while a group listing seed is in flight, the marker that pins the seed's
+ * watermark so a crash redoes the same listing instead of a newer one
+ * (#476). Cursor and marker live in one record because they are one resume
+ * concept: the bootstrap trigger is a single read.
+ *
+ * ## Methods
+ * - `get(groupId)` — the group's cursor (GSN), or null if none
+ * - `set(groupId, cursor)` — writes the cursor, keeping any seed marker
+ * - `getRecord(groupId)` — the whole resume record (`{cursor?, seed?}`)
+ * - `setRecord(groupId, record)` — replaces the record; omitting `seed`
+ *   clears the marker, which is how the final seed page commits, and
+ *   `through` records how far the seed's base folded
+ * - `records()` — every group's record, for the handshake's cursor map
+ * - `clear()` — drops every group's resume state (a full local sync reset)
+ */
+/**
+ * A listing seed in flight: the watermark the redo must reuse and the
+ * server page token to resume from.
+ *
+ * `w` is absent while page 1's seed has not committed — the attempt then
+ * holds no rows that a newer watermark could skip past, so the redo lists
+ * from page 1 afresh (see `bootstrapGroupListing`). `token` is absent when
+ * `w` is, and otherwise names the page after the last one already seeded.
+ */
+interface SeedMarker {
+    /** The group being seeded. Guards a record against reuse across groups. */
+    readonly group_id: string;
+    /** Pinned listing watermark; absent while page 1's seed is uncommitted. */
+    readonly w?: number;
+    /** Opaque server page token for the next page to list. */
+    readonly token?: string;
+}
+/** One group's durable resume state. */
+interface CursorRecord {
+    /** Highest GSN the group's view is complete as of. Absent before any seed or catch-up. */
+    readonly cursor?: number;
+    /** Present while a listing seed is in flight. */
+    readonly seed?: SeedMarker;
+    /**
+     * Highest entity log position the group's seeded base folded. A row's
+     * `last_gsn` at or below it is the server's own state, so a re-delivered
+     * `put` / `delete` inside that window is already reflected and must not be
+     * folded again (#476). Absent until a listing seed completes; it outlives
+     * the marker because the tail re-delivers after the seed finishes.
+     */
+    readonly through?: number;
+}
+interface CursorStore {
+    get(groupId: string): Promise<number | null>;
+    set(groupId: string, cursor: number): Promise<void>;
+    getRecord(groupId: string): Promise<CursorRecord | null>;
+    setRecord(groupId: string, record: CursorRecord): Promise<void>;
+    records(): Promise<ReadonlyMap<string, CursorRecord>>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Lifecycle status of a buffered local Action. The store persists
+ * whatever status the writer assigns; which transitions are legal, and
+ * when they happen, is the client outbox's concern, not storage's.
+ *
+ * `conflicted` is a terminal-until-resolved hold: a catch-up pass
+ * classified the Action as a loser, so it is structurally excluded from
+ * `pending()` and never submitted. The application resolves it by
+ * retrying (back to `pending`) or discarding (removed).
+ */
+type OutboxStatus = "pending" | "acknowledged" | "error" | "conflicted";
+/**
+ * One side of a contested slot: the buffered local write, or the value
+ * the server holds once the catch-up window is applied. A leaf carries
+ * its LWW triple; a whole-field map replacement has no single leaf, so
+ * `update_id` / `hlc` are absent and `value` is the projected map. A
+ * field an inbound `put` or `delete` reverted also has no triple, and
+ * `value` is `undefined` because the server holds no value.
+ */
+interface ConflictSide {
+    /** Projected leaf or map value. `undefined` when the server holds nothing. */
+    readonly value: unknown;
+    /** `update_id` of the FieldValue; absent for a map side or a reverted field. */
+    readonly update_id?: string;
+    /** HLC carried by the FieldValue; absent for a map side or a reverted field. */
+    readonly hlc?: string;
+}
+/**
+ * One contested position on a losing Action: a field plus the map-key
+ * path from the field root to the position. `path` is empty for a plain
+ * leaf field, an entity-level touch that overlaps no position, or a
+ * field an inbound `put` / `delete` reverted. Concurrent writes to
+ * different keys are different slots and so are not conflicts.
+ */
+interface ConflictSlot {
+    /** The `subject_id` of the Update that carried the write. */
+    readonly subjectId: string;
+    /** The field name on that subject. */
+    readonly field: string;
+    /** Ordered map keys from the field root to the position; empty at the root. */
+    readonly path: readonly string[];
+    /** The buffered local value at the position. */
+    readonly local: ConflictSide;
+    /** The value the server holds at the position after the missed window. */
+    readonly remote: ConflictSide;
+}
+/**
+ * The before/after entity rows for one losing subject. `before` is the
+ * row as the client had it immediately before the catch-up window was
+ * applied: last-synced server state with its own unflushed writes
+ * optimistically applied. `after` is the materialized row at detection,
+ * once the inbound window has replaced the optimistic row with the
+ * server's view. Both are structured-clone copies, not references into
+ * the action log, so the comparison survives a reload and compaction.
+ */
+interface ConflictSubjectState {
+    readonly subjectId: string;
+    readonly subjectType: string;
+    readonly before: Entity | null;
+    readonly after: Entity | null;
+}
+/**
+ * The conflict payload detection stamps onto a losing Action's outbox
+ * row. It travels with the row rather than in a second store, so the
+ * hold and the record are the same durable write and cannot disagree.
+ */
+interface OutboxConflict {
+    /**
+     * Subjects that actually lost. A create-plus-update write names only
+     * the entity that lost, so a freshly created entity is not dragged in.
+     */
+    readonly subjects: readonly string[];
+    /**
+     * Full entity rows for each losing subject, in the same order as
+     * `subjects`. `after` is read as the materialized row at detection and
+     * is `null` only when replay yields no row.
+     */
+    readonly subjectStates: readonly ConflictSubjectState[];
+    /**
+     * Overlapping contested positions, in detection order. Empty when the
+     * entity-level scope surfaced a subject with no position overlap; an
+     * application reads that as "nothing of mine would be lost".
+     */
+    readonly slots: readonly ConflictSlot[];
+    /** The catch-up pass that produced this entry. */
+    readonly catchUpId: string;
+    /**
+     * Stamped at detection and persisted, so it survives a reload and
+     * partial resolution. Grouping is the connected set of losing
+     * subjects within one `catchUpId`.
+     */
+    readonly conflictId: string;
+    /** Client HLC stamped at detection. The conflict view's ordering key. */
+    readonly detectedAtHlc: string;
+}
+/**
+ * One locally-authored Action awaiting acknowledgement, plus the HLC at
+ * which it entered the outbox. A `conflicted` entry carries its
+ * {@link OutboxConflict} payload; the field is absent for every other
+ * status.
+ */
+interface OutboxEntry {
+    readonly action: Action;
+    readonly status: OutboxStatus;
+    /**
+     * Client HLC stamped when the Action was buffered. The ordering key
+     * for `list()` — Actions must flush in the order they were authored,
+     * independent of object-store iteration order.
+     */
+    readonly enqueuedAtHlc: string;
+    /**
+     * Highest server GSN the client had applied when the Action was
+     * authored. Catch-up detection treats an inbound Action as concurrent
+     * when its GSN is greater; `0` means "always concurrent", so a legacy
+     * or base-less entry is never silently dropped.
+     */
+    readonly basedOnGsn: number;
+    /** Present iff `status === "conflicted"`. */
+    readonly conflict?: OutboxConflict;
+}
+/**
+ * OutboxStore — durable buffer of pending local Actions.
+ *
+ * Entries are keyed by `action.id`. Re-`put`ting an id replaces the
+ * whole row, which is how a status transition — including a detection
+ * that stamps a conflict payload — is persisted; `list()` returns
+ * entries in ascending `enqueuedAtHlc` order so a rehydrating client
+ * replays them in authoring order.
+ */
+interface OutboxStore {
+    put(entry: OutboxEntry): Promise<void>;
+    /**
+     * Persist `entry` and delete `deleteId` in one durable operation. Used
+     * to resolve a conflict by retrying: the fresh re-assert must never
+     * exist without the conflicted row being gone, nor the row be gone
+     * without the re-assert persisted.
+     */
+    putAndDelete(entry: OutboxEntry, deleteId: string): Promise<void>;
+    list(): Promise<readonly OutboxEntry[]>;
+    get(actionId: string): Promise<OutboxEntry | null>;
+    delete(actionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * The persisted form of the materialized replica — the replica at rest.
+ *
+ * `position` is the `ActionLog` append cursor the record was taken at:
+ * load is `record ⊕ readTail(record.position)`. `revision` is the
+ * replica's observable-content version at that point. `entities` is the
+ * row-shaped entity set; derived indices are rebuilt on load, never
+ * persisted, because IndexedDB cannot index nested `FieldValue` paths,
+ * express live-row filtering, or query a stored map.
+ */
+interface ReplicaRecord {
+    /** Shape version of this record. A record of an unknown format reads as absent. */
+    readonly format: number;
+    /** The log position the record was taken at. */
+    readonly position: number;
+    /** The replica's revision when the record was taken. */
+    readonly revision: number;
+    readonly entities: readonly Entity[];
+}
+/**
+ * ReplicaStore — single-slot persistence for the materialized replica.
+ *
+ * Only ever a fast path. Correctness never depends on the record
+ * existing: an absent or corrupt record reads as `null` so the caller
+ * falls back to full log replay rather than hydrating a partial base.
+ */
+interface ReplicaStore {
+    load(): Promise<ReplicaRecord | null>;
+    save(record: ReplicaRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * StorageAdapter — unified interface composing all storage components.
+ *
+ * Use `createMemoryAdapter()` from `@ebbjs/storage` to get a full
+ * in-memory implementation.
+ *
+ * ## Composition
+ * - `actions` — ActionLog for storing and querying actions
+ * - `entities` — EntityStore for materialized entity cache
+ * - `dirtyTracker` — DirtyTracker for tracking entities needing materialization
+ * - `cursors` — CursorStore for per-group GSN tracking
+ * - `outbox` — OutboxStore for durable pending local Actions; a detected
+ *   conflict is a status + payload on its outbox row, not a sibling store
+ * - `replica` — ReplicaStore for the persisted materialized replica; single-slot
+ *   and a fast path only
+ *
+ * ## Cross-cutting Methods
+ * - `isDirty(entityId)` — delegates to dirtyTracker
+ * - `reset()` — clears the action log, dirty flags, entity cache, the
+ *   persisted replica, and every group cursor; outbox entries are durable
+ *   user data and survive a reset
+ */
+interface StorageAdapter {
+    readonly actions: ActionLog;
+    readonly entities: EntityStore;
+    readonly dirtyTracker: DirtyTracker;
+    readonly cursors: CursorStore;
+    readonly outbox: OutboxStore;
+    /**
+     * Single-slot persistence for the replica. An absent or corrupt record
+     * reads as `null`, so correctness never depends on it existing.
+     */
+    readonly replica: ReplicaStore;
+    isDirty(entityId: string): Promise<boolean>;
+    reset(): Promise<void>;
+}
+
+interface IndexedDBAdapterOptions {
+    dbName?: string;
+}
+/**
+ * Creates a `StorageAdapter` backed by IndexedDB.
+ *
+ * ## Usage
+ * ```ts
+ * const adapter = await createIndexedDBAdapter({ dbName: "my-app" });
+ * await adapter.actions.append(action);
+ * ```
+ *
+ * ## Browser-only
+ * This adapter requires `indexedDB` in the global scope. In Node /
+ * test environments it must be run inside a DOM environment that
+ * provides the API (e.g. `happy-dom`).
+ *
+ * ## Concurrency
+ * Single-tab ownership is assumed for v1. Multi-tab coordination is
+ * out of scope per issue #145.
+ *
+ * ## Schema version
+ * Opens at `EBB_SCHEMA_VERSION`; `openTestDb` opens the test schema at
+ * the same version so the two cannot drift.
+ */
+declare const createIndexedDBAdapter: (options?: IndexedDBAdapterOptions) => Promise<StorageAdapter>;
+
+export { createIndexedDBAdapter };
+export type { IndexedDBAdapterOptions };