@ebbjs/storage 0.0.0-stage → 0.1.1

package/dist/memory/index.js

@@ -0,0 +1,296 @@
+import { m as b, a as E, i as M, c as m } from "../cursor-record-D39emd6R.js";
+import { l as D, c as _, a as A, f as T, b as h, h as w, k as j, j as v, n as R, M as f, m as k, p as I, r as F, i as q } from "../replica-record-D3lkFACh.js";
+import { compare as C } from "@ebbjs/core";
+const O = (t, n) => {
+  const e = /* @__PURE__ */ new Map();
+  for (const [s, a] of t)
+    e.set(s, new Set(a));
+  for (const s of n.updates) {
+    const a = e.get(s.subject_type);
+    a ? a.add(s.subject_id) : e.set(s.subject_type, /* @__PURE__ */ new Set([s.subject_id]));
+  }
+  return Array.from(e.entries()).map(([s, a]) => [s, Array.from(a)]);
+}, P = () => {
+  let t = {
+    actions: [],
+    typeIndex: []
+  };
+  const n = async (e) => {
+    const s = t.actions.findIndex((d) => d.id === e.id), a = s === -1 ? void 0 : t.actions[s], o = a === void 0 ? e : { ...a, updates: b(a.updates, e.updates) }, c = a === void 0, r = c ? t.actions.length + 1 : s + 1, i = E(a?.updates ?? [], e.updates);
+    return t = {
+      actions: c ? [...t.actions, o] : t.actions.map((d) => d.id === e.id ? o : d),
+      typeIndex: O(t.typeIndex, o)
+    }, { action: o, position: r, added: i };
+  };
+  return {
+    append: n,
+    async appendMany(e) {
+      const s = [];
+      for (const a of e) s.push(await n(a));
+      return s;
+    },
+    async readTail(e) {
+      return t.actions.slice(e).map((s, a) => ({
+        action: s,
+        position: e + a + 1,
+        added: s.updates
+      }));
+    },
+    async lastPosition() {
+      return t.actions.length;
+    },
+    async getAll() {
+      return t.actions;
+    },
+    async getForEntity(e) {
+      return t.actions.filter(
+        (a) => a.updates.some((o) => o.subject_id === e)
+      ).sort((a, o) => a.gsn - o.gsn);
+    },
+    async clear() {
+      t = { actions: [], typeIndex: [] };
+    }
+  };
+}, B = () => {
+  let t = {
+    entities: {},
+    typeIndex: {}
+  };
+  return {
+    async mark(n, e) {
+      n in t.entities || (t = {
+        entities: { ...t.entities, [n]: e },
+        typeIndex: {
+          ...t.typeIndex,
+          [e]: new Set(t.typeIndex[e] ?? []).add(n)
+        }
+      });
+    },
+    async isDirty(n) {
+      return n in t.entities;
+    },
+    async getDirtyForType(n) {
+      const e = t.typeIndex[n];
+      return e ? [...e] : [];
+    },
+    async clear(n) {
+      const e = t.entities[n];
+      if (!e) return;
+      const { [n]: s, ...a } = t.entities, o = t.typeIndex[e], c = new Set(o);
+      c.delete(n), t = {
+        entities: a,
+        typeIndex: {
+          ...t.typeIndex,
+          [e]: c
+        }
+      };
+    },
+    async clearAll() {
+      t = { entities: {}, typeIndex: {} };
+    }
+  };
+}, u = (t) => JSON.parse(JSON.stringify(t)), g = (t, n, e) => {
+  const s = { ...t };
+  if (e && e !== n.type) {
+    const a = new Set(s[e] ?? []);
+    a.delete(n.id), s[e] = a;
+  }
+  return s[n.type] || (s[n.type] = /* @__PURE__ */ new Set()), s[n.type] = new Set(s[n.type]).add(n.id), s;
+}, S = (t, n, e) => w(
+  w(t, v(n, e)),
+  j(n, e)
+), L = (t, n) => {
+  let e = { entities: {}, typeIndex: {}, index: {} };
+  const s = async (r) => {
+    if (!await n.isDirty(r)) return;
+    const d = await t.getForEntity(r);
+    if (d.length === 0) return;
+    let y = null;
+    for (const p of d)
+      for (const x of p.updates)
+        x.subject_id === r && (y = R(y, x, p.gsn, p.hlc));
+    if (y === null) return;
+    const l = e.entities[r];
+    e = {
+      entities: { ...e.entities, [r]: u(y) },
+      typeIndex: g(e.typeIndex, y, l?.type),
+      index: S(e.index, l, y)
+    }, await n.clear(r);
+  }, a = async (r) => {
+    for (const i of await n.getDirtyForType(r))
+      await s(i);
+  }, o = (r) => h(e.index[r]);
+  return {
+    async get(r) {
+      await s(r);
+      const i = e.entities[r];
+      return i ? u(i) : null;
+    },
+    async set(r) {
+      const i = e.entities[r.id];
+      e = {
+        entities: { ...e.entities, [r.id]: u(r) },
+        typeIndex: g(e.typeIndex, r, i?.type),
+        index: S(e.index, i, r)
+      };
+    },
+    async query(r) {
+      return await a(r), [...e.typeIndex[r] ?? /* @__PURE__ */ new Set()].map((d) => u(e.entities[d]));
+    },
+    async queryByRelationship({
+      as: r,
+      type: i,
+      targetId: d
+    }) {
+      return await a(I), o(F(r, i, d));
+    },
+    async queryByRelationshipSource({
+      as: r,
+      type: i,
+      sourceId: d
+    }) {
+      return await a(I), A(e.index[T(r, i, d)]);
+    },
+    async queryByMembership(r) {
+      return await a(f), o(k(r));
+    },
+    async queryByMembershipEntity(r) {
+      return await a(f), D(e.index[_(r)]);
+    },
+    async reset() {
+      e = { entities: {}, typeIndex: {}, index: {} };
+    }
+  };
+}, N = () => {
+  let t = { records: {} };
+  const n = (e) => t.records[e] ?? null;
+  return {
+    async get(e) {
+      return n(e)?.cursor ?? null;
+    },
+    async set(e, s) {
+      t = {
+        records: { ...t.records, [e]: m({ ...n(e), cursor: s }) }
+      };
+    },
+    async getRecord(e) {
+      return n(e);
+    },
+    async setRecord(e, s) {
+      if (M(s)) {
+        const { [e]: a, ...o } = t.records;
+        t = { records: o };
+        return;
+      }
+      t = { records: { ...t.records, [e]: m(s) } };
+    },
+    async records() {
+      return new Map(Object.entries(t.records));
+    },
+    async clear() {
+      t = { records: {} };
+    }
+  };
+}, H = () => {
+  let t = {};
+  return {
+    async put(n) {
+      t = { ...t, [n.action.id]: structuredClone(n) };
+    },
+    async putAndDelete(n, e) {
+      const { [e]: s, ...a } = t;
+      t = { ...a, [n.action.id]: structuredClone(n) };
+    },
+    async list() {
+      return Object.values(t).map((n) => structuredClone(n)).sort((n, e) => C(n.enqueuedAtHlc, e.enqueuedAtHlc));
+    },
+    async get(n) {
+      const e = t[n];
+      return e === void 0 ? null : structuredClone(e);
+    },
+    async delete(n) {
+      const { [n]: e, ...s } = t;
+      t = s;
+    },
+    async clear() {
+      t = {};
+    }
+  };
+}, K = () => {
+  let t = null;
+  return {
+    async load() {
+      return q(t) ? t : null;
+    },
+    async save(n) {
+      t = n;
+    },
+    async clear() {
+      t = null;
+    }
+  };
+}, z = () => {
+  const t = P(), n = B(), e = L(t, n), s = N(), a = H(), o = K();
+  return {
+    actions: {
+      async append(c) {
+        const r = await t.append(c);
+        for (const i of c.updates)
+          await n.mark(i.subject_id, i.subject_type);
+        return r;
+      },
+      async appendMany(c) {
+        const r = await t.appendMany(c);
+        for (const i of c)
+          for (const d of i.updates)
+            await n.mark(d.subject_id, d.subject_type);
+        return r;
+      },
+      async readTail(c) {
+        return t.readTail(c);
+      },
+      async lastPosition() {
+        return t.lastPosition();
+      },
+      async getAll() {
+        return t.getAll();
+      },
+      async getForEntity(c) {
+        return t.getForEntity(c);
+      },
+      async clear() {
+        await t.clear(), await n.clearAll(), await e.reset(), await o.clear();
+      }
+    },
+    entities: e,
+    dirtyTracker: {
+      async mark(c, r) {
+        await n.mark(c, r);
+      },
+      async isDirty(c) {
+        return n.isDirty(c);
+      },
+      async getDirtyForType(c) {
+        return n.getDirtyForType(c);
+      },
+      async clear(c) {
+        await n.clear(c);
+      },
+      async clearAll() {
+        await n.clearAll();
+      }
+    },
+    cursors: s,
+    outbox: a,
+    replica: o,
+    async isDirty(c) {
+      return n.isDirty(c);
+    },
+    async reset() {
+      await t.clear(), await n.clearAll(), await e.reset(), await o.clear(), await s.clear();
+    }
+  };
+};
+export {
+  z as createMemoryAdapter
+};

package/dist/replica/index.d.ts

@@ -0,0 +1,271 @@
+import { Entity, Update, HLCTimestamp, Action } from '@ebbjs/core';
+
+/**
+ * Whether a materialized row keeps large map fields in the replica's sharded
+ * container. The replica owns its rows and flattens them at the record
+ * boundary; the legacy adapters deep-clone every row, so they keep the plain
+ * wire shape.
+ */
+interface MaterializeOptions {
+    readonly residentMapFields?: boolean;
+}
+/**
+ * Applies a single update to an entity during materialization.
+ *
+ * - PUT: full replacement
+ * - PATCH: field-level LWW merge; ignored on a soft-deleted entity
+ * - DELETE: soft delete (sets `deleted_hlc`); bumps `last_gsn` and
+ *   `updated_hlc`. A delete for a row that was never materialized is a
+ *   no-op, so a per-Update delivery (#473) cannot break the drain.
+ */
+declare const applyUpdate: (entity: Entity | null, update: Update, gsn: number, hlc: HLCTimestamp, options?: MaterializeOptions) => Entity | null;
+
+/**
+ * True when `next` differs from `prev` in anything a reader can observe.
+ * `last_gsn` is delivery bookkeeping and is excluded, so a lower-HLC patch
+ * that only advances it leaves the revision untouched.
+ */
+declare const contentChanged: (prev: Entity | null | undefined, next: Entity | null | undefined) => boolean;
+
+/**
+ * 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;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * A monotonic counter over the replica's observable content. It bumps once
+ * per entity change a reader could see — never for delivery bookkeeping like
+ * `last_gsn` — so it doubles as the invalidation token for derived state.
+ */
+type Revision = number;
+/** One observable entity change, appended to the revision journal. */
+interface ReplicaChange {
+    readonly revision: Revision;
+    readonly id: string;
+    readonly type: string;
+    readonly deleted: boolean;
+}
+/**
+ * Whether the replica retains a type's rows. The seam #500 builds on-demand
+ * residency against: a policy that holds nothing lets the engine fetch a type
+ * on first read and react to the journal it still receives.
+ */
+interface MaterializationPolicy {
+    holds(type: string): boolean;
+}
+interface ReplicaOptions {
+    readonly materialization?: MaterializationPolicy;
+    /**
+     * Reads a row from the local stores when `open` misses. Without it an
+     * on-demand id that is not resident stays a miss.
+     */
+    readonly readEntity?: (id: string) => Promise<Entity | null>;
+    /**
+     * Maximum resident on-demand rows. Defaults to 16. A non-positive or
+     * non-finite value keeps every opened row resident; opening past the
+     * window releases the least recently opened one.
+     */
+    readonly pinnedCapacity?: number;
+    /**
+     * How long a closed on-demand row stays cached before release. Defaults to
+     * 30_000 ms. A non-positive or non-finite value releases it immediately on
+     * close. An open row is never released by the TTL.
+     */
+    readonly pinnedTtlMs?: number;
+    /**
+     * Maximum retained change-journal entries after trimming. Defaults to 1024.
+     * A non-positive or non-finite value keeps the journal unbounded; a
+     * positive fraction retains at least one entry.
+     */
+    readonly journalCapacity?: number;
+}
+/** A snapshot of what the replica currently materializes and retains. */
+interface ReplicaStats {
+    /** Number of row objects currently materialized (tombstones included). */
+    readonly entities: number;
+    /** Materialized row count per entity type. */
+    readonly byType: Readonly<Record<string, number>>;
+    /** Rows retained because their type is held: the metadata footprint. */
+    readonly held: number;
+    /** Held row count per type; excludes opened on-demand rows. */
+    readonly heldByType: Readonly<Record<string, number>>;
+    /** Resident on-demand rows (open or closed and waiting out their TTL). */
+    readonly pinned: number;
+    readonly revision: Revision;
+    /** Append cursor of the last durable position folded into the base. */
+    readonly position: number;
+    /** Retained journal entries. */
+    readonly changes: number;
+    /** Oldest revision after which `changesSince` is complete. */
+    readonly changeFloor: Revision;
+}
+/**
+ * Adjacency read key for the replica's relationship index. `sourceId`
+ * reads forward — the targets out of the source; `targetId` reads
+ * reverse — the sources pointing at the target. `sourceId` wins when
+ * both are set, and neither yields no ids.
+ */
+interface RelationshipQuery {
+    readonly as: string;
+    readonly type: string;
+    readonly sourceId?: string;
+    readonly targetId?: string;
+}
+/**
+ * Adjacency read key for the replica's membership index. `groupId`
+ * reads the group's members; `entityId` reads the entity's groups.
+ * `groupId` wins when both are set, and neither yields no ids.
+ */
+interface MembershipQuery {
+    readonly groupId?: string;
+    readonly entityId?: string;
+}
+/**
+ * The materialized read path. Writes are synchronous and single-writer: the
+ * caller serializes them and folds durable updates in ascending log position.
+ * Reads return the replica's own row objects (shared, not cloned), tombstones
+ * included; callers must treat them as immutable.
+ */
+interface Replica {
+    readonly revision: Revision;
+    /**
+     * Smallest revision for which the retained journal is complete: the
+     * revision of the newest trimmed change, or the loaded record's revision.
+     * A `changesSince` below this floor yields nothing because everything may
+     * have changed.
+     */
+    readonly changeFloor: Revision;
+    get(id: string): Entity | undefined;
+    /**
+     * The durable base row for `id`, without this client's optimistic overlay
+     * writes. A reader judging "has this row already folded a later Action than
+     * the one I am delivering" must read the base: an overlay `put` composes
+     * with gsn 0, which would hide the row's folded position.
+     */
+    base(id: string): Entity | undefined;
+    iterate(type: string): readonly Entity[];
+    /** Whether the materialization policy holds `type` in full. */
+    isHeld(type: string): boolean;
+    /**
+     * Load `id` through `readEntity` when absent, pinning it and journaling the
+     * install so a derived reader sees the row arrive. Idempotent: a resident row
+     * is marked open and touched (LRU order) without another read, a concurrent
+     * open shares the in-flight read, and a held row is returned without
+     * installing or pinning. Resolves to the composed row, or `null` when the
+     * read misses.
+     */
+    open(id: string): Promise<Entity | null>;
+    /**
+     * Close a pinned row. It stays cached until `pinnedTtlMs` so a remount reads
+     * it back, then leaves; with the TTL disabled it leaves immediately. A no-op
+     * for held rows.
+     */
+    close(id: string): void;
+    /** Whether `id` is currently open (closed rows waiting out their TTL are not). */
+    isOpen(id: string): boolean;
+    /**
+     * Changes newer than `revision`, ascending. Empty when the cursor predates
+     * `changeFloor`, where the trimmed journal can no longer answer it.
+     */
+    changesSince(revision: Revision): readonly ReplicaChange[];
+    stats(): ReplicaStats;
+    /**
+     * Distinct live targets out of `(as, type, sourceId)`, or distinct
+     * live sources pointing at `(as, type, targetId)`, ascending.
+     */
+    relationships(query: RelationshipQuery): readonly string[];
+    /**
+     * Distinct live member entity ids of a group, or distinct live group
+     * ids of an entity, ascending.
+     */
+    memberships(query: MembershipQuery): readonly string[];
+    /** Live forward relationship edges out of a source, ascending by target then row id. */
+    relationshipLinks(query: RelationshipSourceQuery): readonly RelationshipLink[];
+    /** Live member-keyed membership rows of an entity, ascending by group then row id. */
+    membershipLinks(entityId: string): readonly MembershipLink[];
+    /** Fold one durable Action's `delta` at its log position. */
+    ingest(action: Action, delta: readonly Update[], position: number): Revision;
+    /** Fold an unacknowledged local Action into the overlay only. */
+    optimistic(action: Action): Revision;
+    /** Drop an overlay Action's writes, reverting the composed view. */
+    discard(actionId: string): Revision;
+    /**
+     * Replace the materialized base with `record`. The journal resets to that
+     * baseline. The revision advances to the record's revision when that is
+     * newer, and by one otherwise, so a derived reader always observes the
+     * wholesale replacement even when the record is the same revision.
+     */
+    load(record: ReplicaRecord): Revision;
+    toRecord(): ReplicaRecord;
+    /**
+     * Drop rows from the in-memory base and indices without tombstoning them:
+     * afterwards `get(id)` is undefined and `iterate(type)` omits the row. Each
+     * removed row journals one change, so derived readers see it leave. Absent
+     * ids are ignored. Returns the resulting revision.
+     */
+    evict(ids: readonly string[]): Revision;
+    /**
+     * Subscribe to post-change notifications. Fires after every mutating call
+     * (`ingest` / `optimistic` / `discard` / `load` / `evict` / `open` /
+     * `close`) that settles the composed view, so a derived reader can
+     * resynchronise from `revision` and `changesSince`. A no-op write still
+     * fires; readers cheaply ignore an unchanged revision. Re-opening a resident
+     * row only touches the LRU window, so it fires nothing. Returns an
+     * unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+}
+
+declare const holdAll: MaterializationPolicy;
+declare const DEFAULT_PINNED_CAPACITY = 16;
+declare const DEFAULT_PINNED_TTL_MS = 30000;
+/**
+ * Mutable in-place core. `entities` is the durable base (what `toRecord`
+ * persists, once pinned on-demand rows are filtered out), `overlay` composes
+ * optimistic writes over it, and `effective` caches the composed view for
+ * overlaid ids so a read never recomposes.
+ * `typeIndex` indexes the base; `iterate` layers the overlay's type overrides
+ * on top of it.
+ */
+declare const createReplica: (options?: ReplicaOptions) => Replica;
+
+export { DEFAULT_PINNED_CAPACITY, DEFAULT_PINNED_TTL_MS, applyUpdate, contentChanged, createReplica, holdAll };
+export type { MaterializationPolicy, MembershipQuery, RelationshipQuery, Replica, ReplicaChange, ReplicaOptions, ReplicaStats, Revision };