@dabble/patches 0.7.24 → 0.8.1

package/dist/micro/client.d.ts

@@ -0,0 +1,44 @@
+import { Signal } from 'easy-signal';
+import { MicroDoc } from './doc.js';
+import '@dabble/delta';
+import './types.js';
+
+interface ClientOptions {
+    /** Base URL for REST API, e.g. "https://api.example.com" */
+    url: string;
+    /** If provided, persists state to IndexedDB with this database name. */
+    dbName?: string;
+    /** Debounce delay in ms before flushing pending ops. Default: 300 */
+    debounce?: number;
+}
+declare class MicroClient {
+    private _url;
+    private _dbName?;
+    private _debounce;
+    private _docs;
+    private _ws;
+    private _wsBackoff;
+    private _wsTimer;
+    private _db;
+    readonly onConnection: Signal<(connected: boolean) => void>;
+    constructor(opts: ClientOptions);
+    /** Open a document. Fetches from server (or IDB cache), subscribes via WS. */
+    open<T = Record<string, any>>(docId: string): Promise<MicroDoc<T>>;
+    /** Close a document subscription. */
+    close(docId: string): void;
+    /** Force flush pending ops for a document immediately. */
+    flush(docId: string): Promise<void>;
+    /** Disconnect WebSocket and clean up. */
+    destroy(): void;
+    private _scheduleFlush;
+    private _doFlush;
+    private _ensureWS;
+    private _reconnectWS;
+    private _wsSend;
+    private _fetch;
+    private _idbOpen;
+    private _idbLoad;
+    private _idbSave;
+}
+
+export { type ClientOptions, MicroClient };

package/dist/micro/client.js

@@ -0,0 +1,206 @@
+import "../chunk-IZ2YBCUP.js";
+import { signal } from "easy-signal";
+import { MicroDoc } from "./doc.js";
+class MicroClient {
+  _url;
+  _dbName;
+  _debounce;
+  _docs = /* @__PURE__ */ new Map();
+  _ws = null;
+  _wsBackoff = 0;
+  _wsTimer = null;
+  _db = null;
+  onConnection = signal();
+  constructor(opts) {
+    this._url = opts.url.replace(/\/$/, "");
+    this._dbName = opts.dbName;
+    this._debounce = opts.debounce ?? 300;
+  }
+  /** Open a document. Fetches from server (or IDB cache), subscribes via WS. */
+  async open(docId) {
+    if (this._docs.has(docId)) return this._docs.get(docId).doc;
+    let state = { rev: 0, fields: {} };
+    let pending = {};
+    if (this._dbName) {
+      const cached = await this._idbLoad(docId);
+      if (cached) {
+        state = { rev: cached.rev, fields: cached.fields };
+        pending = cached.pending;
+      }
+    }
+    try {
+      const remote = await this._fetch(`/docs/${docId}`);
+      if (remote.rev > state.rev) {
+        state = remote;
+        pending = {};
+      }
+    } catch {
+    }
+    const doc = new MicroDoc(state.fields, pending, state.rev);
+    const entry = { doc, timer: null };
+    this._docs.set(docId, entry);
+    doc._onUpdate = () => this._scheduleFlush(docId);
+    this._ensureWS();
+    this._wsSend({ type: "sub", docId });
+    return doc;
+  }
+  /** Close a document subscription. */
+  close(docId) {
+    const entry = this._docs.get(docId);
+    if (!entry) return;
+    if (entry.timer) clearTimeout(entry.timer);
+    this._docs.delete(docId);
+    this._wsSend({ type: "unsub", docId });
+  }
+  /** Force flush pending ops for a document immediately. */
+  async flush(docId) {
+    const entry = this._docs.get(docId);
+    if (!entry) return;
+    if (entry.timer) {
+      clearTimeout(entry.timer);
+      entry.timer = null;
+    }
+    await this._doFlush(docId, entry);
+  }
+  /** Disconnect WebSocket and clean up. */
+  destroy() {
+    for (const [id, entry] of this._docs) {
+      if (entry.timer) clearTimeout(entry.timer);
+      this._docs.delete(id);
+    }
+    if (this._wsTimer) clearTimeout(this._wsTimer);
+    this._ws?.close();
+    this._ws = null;
+    this._db?.close();
+    this._db = null;
+  }
+  // --- Sync ---
+  _scheduleFlush(docId) {
+    const entry = this._docs.get(docId);
+    if (!entry || entry.timer) return;
+    entry.timer = setTimeout(() => {
+      entry.timer = null;
+      this._doFlush(docId, entry);
+    }, this._debounce);
+  }
+  async _doFlush(docId, entry) {
+    const change = entry.doc._flush();
+    if (!change) return;
+    if (this._dbName) this._idbSave(docId, entry.doc);
+    try {
+      const result = await this._fetch(`/docs/${docId}/changes`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(change)
+      });
+      entry.doc._confirmSend(result.rev);
+      if (this._dbName) this._idbSave(docId, entry.doc);
+      if (Object.keys(entry.doc.pending).length) this._scheduleFlush(docId);
+    } catch {
+      entry.doc._failSend();
+      entry.timer = setTimeout(() => {
+        entry.timer = null;
+        this._doFlush(docId, entry);
+      }, 2e3);
+    }
+  }
+  // --- WebSocket ---
+  _ensureWS() {
+    if (this._ws && this._ws.readyState <= WebSocket.OPEN) return;
+    const wsUrl = this._url.replace(/^http/, "ws") + "/ws";
+    const ws = new WebSocket(wsUrl);
+    this._ws = ws;
+    ws.onopen = () => {
+      this._wsBackoff = 0;
+      this.onConnection.emit(true);
+      for (const docId of this._docs.keys()) {
+        this._wsSend({ type: "sub", docId });
+      }
+    };
+    ws.onmessage = (e) => {
+      try {
+        const msg = JSON.parse(e.data);
+        if (msg.type === "change" && msg.docId) {
+          const entry = this._docs.get(msg.docId);
+          if (entry) entry.doc.applyRemote(msg.fields, msg.rev);
+        }
+      } catch {
+      }
+    };
+    ws.onclose = () => {
+      this.onConnection.emit(false);
+      this._reconnectWS();
+    };
+    ws.onerror = () => ws.close();
+  }
+  _reconnectWS() {
+    if (this._wsTimer) return;
+    const delay = Math.min(1e3 * 2 ** this._wsBackoff, 3e4);
+    this._wsBackoff++;
+    this._wsTimer = setTimeout(() => {
+      this._wsTimer = null;
+      if (this._docs.size > 0) this._ensureWS();
+    }, delay);
+  }
+  _wsSend(msg) {
+    if (this._ws?.readyState === WebSocket.OPEN) {
+      this._ws.send(JSON.stringify(msg));
+    }
+  }
+  // --- REST ---
+  async _fetch(path, init) {
+    const res = await fetch(this._url + path, init);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return res.json();
+  }
+  // --- IndexedDB ---
+  async _idbOpen() {
+    if (this._db) return this._db;
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open(this._dbName, 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains("docs")) db.createObjectStore("docs");
+        if (!db.objectStoreNames.contains("pending")) db.createObjectStore("pending");
+      };
+      req.onsuccess = () => {
+        this._db = req.result;
+        resolve(req.result);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+  async _idbLoad(docId) {
+    try {
+      const db = await this._idbOpen();
+      const tx = db.transaction(["docs", "pending"], "readonly");
+      const [docData, pendingData] = await Promise.all([
+        idbGet(tx.objectStore("docs"), docId),
+        idbGet(tx.objectStore("pending"), docId)
+      ]);
+      if (!docData) return null;
+      return { fields: docData.fields, rev: docData.rev, pending: pendingData?.ops ?? {} };
+    } catch {
+      return null;
+    }
+  }
+  async _idbSave(docId, doc) {
+    try {
+      const db = await this._idbOpen();
+      const tx = db.transaction(["docs", "pending"], "readwrite");
+      tx.objectStore("docs").put({ fields: doc.confirmed, rev: doc.rev }, docId);
+      tx.objectStore("pending").put({ ops: doc.pending }, docId);
+    } catch {
+    }
+  }
+}
+function idbGet(store, key) {
+  return new Promise((resolve, reject) => {
+    const req = store.get(key);
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+export {
+  MicroClient
+};

package/dist/micro/doc.d.ts

@@ -0,0 +1,51 @@
+import { Delta } from '@dabble/delta';
+import { Subscriber, Unsubscriber } from 'easy-signal';
+import { FieldMap, Change } from './types.js';
+
+interface BaseUpdates<T> {
+    set(val: T): void;
+    del(): void;
+}
+interface NumberUpdates extends BaseUpdates<number> {
+    inc(val?: number): void;
+    bit(val: number): void;
+    max(val: number): void;
+}
+interface StringUpdates extends BaseUpdates<string> {
+    max(val: string): void;
+}
+interface DeltaUpdates extends BaseUpdates<Delta> {
+    txt(delta: Delta): void;
+}
+type Updatable<T> = T extends Delta ? DeltaUpdates : T extends number ? NumberUpdates : T extends string ? StringUpdates : T extends object ? {
+    [K in keyof T]-?: Updatable<NonNullable<T[K]>>;
+} & BaseUpdates<T> : BaseUpdates<T>;
+declare class MicroDoc<T = Record<string, any>> {
+    rev: number;
+    private _store;
+    private _confirmed;
+    private _sending;
+    private _sendingId;
+    private _pending;
+    /** Called by client when ops are queued. */
+    _onUpdate?: () => void;
+    constructor(confirmed?: FieldMap, pending?: FieldMap, rev?: number);
+    get state(): T;
+    get pending(): FieldMap;
+    get confirmed(): FieldMap;
+    get isSending(): boolean;
+    subscribe(cb: Subscriber<T>, noInit?: false): Unsubscriber;
+    /** Apply changes via proxy-based updater. */
+    update(fn: (doc: Updatable<T>) => void): void;
+    /** Move pending to sending, return the Change to POST. Returns null if nothing to send. */
+    _flush(): Change | null;
+    /** Confirm a successful send. Merge sending into confirmed. */
+    _confirmSend(rev: number): void;
+    /** Roll sending back into pending on failure. */
+    _failSend(): void;
+    /** Apply remote fields from another client (via WS push). */
+    applyRemote(fields: FieldMap, rev: number): void;
+    private _rebuild;
+}
+
+export { MicroDoc, type Updatable };

package/dist/micro/doc.js

@@ -0,0 +1,138 @@
+import "../chunk-IZ2YBCUP.js";
+import { Delta } from "@dabble/delta";
+import { batch, store } from "easy-signal";
+import { buildState, consolidateOps, effectiveFields, generateId, mergeField } from "./ops.js";
+import { TXT, parseSuffix } from "./types.js";
+function createUpdater(emit, path = "") {
+  return new Proxy({}, {
+    get(_, prop) {
+      const p = path ? `${path}.${prop}` : prop;
+      switch (prop) {
+        case "set":
+          return (val) => emit(path, "", val);
+        case "del":
+          return () => emit(path, "", null);
+        case "inc":
+          return (val = 1) => emit(path, "+", val);
+        case "bit":
+          return (val) => emit(path, "~", val);
+        case "max":
+          return (val) => emit(path, "^", val);
+        case "txt":
+          return (delta) => emit(path, "#", delta.ops);
+        default:
+          return createUpdater(emit, p);
+      }
+    }
+  });
+}
+class MicroDoc {
+  constructor(confirmed = {}, pending = {}, rev = 0) {
+    this.rev = rev;
+    this._confirmed = { ...confirmed };
+    this._pending = { ...pending };
+    this._store = store(this._rebuild());
+  }
+  _store;
+  _confirmed;
+  _sending = null;
+  _sendingId = null;
+  _pending = {};
+  /** Called by client when ops are queued. */
+  _onUpdate;
+  get state() {
+    return this._store.state;
+  }
+  get pending() {
+    return this._pending;
+  }
+  get confirmed() {
+    return this._confirmed;
+  }
+  get isSending() {
+    return this._sending !== null;
+  }
+  subscribe(cb, noInit) {
+    return this._store.subscribe(cb, noInit);
+  }
+  /** Apply changes via proxy-based updater. */
+  update(fn) {
+    const ops = {};
+    const ts = Date.now();
+    const emit = (path, suffix, val) => {
+      ops[suffix ? path + suffix : path] = { val, ts };
+    };
+    fn(createUpdater(emit));
+    if (!Object.keys(ops).length) return;
+    this._pending = consolidateOps(this._pending, ops);
+    this._store.state = this._rebuild();
+    this._onUpdate?.();
+  }
+  /** Move pending to sending, return the Change to POST. Returns null if nothing to send. */
+  _flush() {
+    if (this._sending || !Object.keys(this._pending).length) return null;
+    this._sending = this._pending;
+    this._sendingId = generateId();
+    this._pending = {};
+    return { id: this._sendingId, rev: this.rev, fields: this._sending };
+  }
+  /** Confirm a successful send. Merge sending into confirmed. */
+  _confirmSend(rev) {
+    if (!this._sending) return;
+    for (const [key, field] of Object.entries(this._sending)) {
+      const { suffix } = parseSuffix(key);
+      if (suffix === TXT) {
+        const base = this._confirmed[key]?.val ? new Delta(this._confirmed[key].val) : new Delta();
+        this._confirmed[key] = { val: base.compose(new Delta(field.val)).ops, ts: field.ts };
+      } else {
+        this._confirmed[key] = mergeField(this._confirmed[key], field, suffix);
+      }
+    }
+    this._sending = null;
+    this._sendingId = null;
+    this.rev = rev;
+    this._store.state = this._rebuild();
+  }
+  /** Roll sending back into pending on failure. */
+  _failSend() {
+    if (!this._sending) return;
+    this._pending = consolidateOps(this._sending, this._pending);
+    this._sending = null;
+    this._sendingId = null;
+  }
+  /** Apply remote fields from another client (via WS push). */
+  applyRemote(fields, rev) {
+    batch(() => {
+      for (const [key, field] of Object.entries(fields)) {
+        const { suffix } = parseSuffix(key);
+        if (suffix === TXT) {
+          const remote = new Delta(field.val);
+          if (this._sending?.[key]) {
+            const s = new Delta(this._sending[key].val);
+            this._sending[key] = { val: s.transform(remote, false).ops, ts: this._sending[key].ts };
+            const rPrime = remote.transform(s, true);
+            if (this._pending[key]) {
+              const p = new Delta(this._pending[key].val);
+              this._pending[key] = { val: p.transform(rPrime, false).ops, ts: this._pending[key].ts };
+            }
+          } else if (this._pending[key]) {
+            const p = new Delta(this._pending[key].val);
+            this._pending[key] = { val: p.transform(remote, false).ops, ts: this._pending[key].ts };
+          }
+          const base = this._confirmed[key]?.val ? new Delta(this._confirmed[key].val) : new Delta();
+          this._confirmed[key] = { val: base.compose(remote).ops, ts: field.ts };
+        } else {
+          this._confirmed[key] = field;
+        }
+      }
+      this.rev = rev;
+      this._store.state = this._rebuild();
+    });
+  }
+  _rebuild() {
+    return buildState(effectiveFields(this._confirmed, this._sending, this._pending));
+  }
+}
+export {
+  MicroDoc
+};

package/dist/micro/index.d.ts

@@ -0,0 +1,7 @@
+export { ClientOptions, MicroClient } from './client.js';
+export { MicroDoc, Updatable } from './doc.js';
+export { applyBitmask, bitmask, buildState, combineBitmasks, consolidateOps, effectiveFields, generateId, mergeField } from './ops.js';
+export { MemoryDbBackend, MicroServer } from './server.js';
+export { BIT, Change, ChangeLogEntry, CommitResult, DbBackend, DocState, Field, FieldMap, INC, MAX, ObjectStore, REF_THRESHOLD, TXT, TextLogEntry, parseSuffix } from './types.js';
+import 'easy-signal';
+import '@dabble/delta';

package/dist/micro/index.js

@@ -0,0 +1,26 @@
+import "../chunk-IZ2YBCUP.js";
+import { MicroClient } from "./client.js";
+import { MicroDoc } from "./doc.js";
+import { applyBitmask, bitmask, buildState, combineBitmasks, consolidateOps, effectiveFields, generateId, mergeField } from "./ops.js";
+import { MemoryDbBackend, MicroServer } from "./server.js";
+import { BIT, INC, MAX, parseSuffix, REF_THRESHOLD, TXT } from "./types.js";
+export {
+  BIT,
+  INC,
+  MAX,
+  MemoryDbBackend,
+  MicroClient,
+  MicroDoc,
+  MicroServer,
+  REF_THRESHOLD,
+  TXT,
+  applyBitmask,
+  bitmask,
+  buildState,
+  combineBitmasks,
+  consolidateOps,
+  effectiveFields,
+  generateId,
+  mergeField,
+  parseSuffix
+};

package/dist/micro/ops.d.ts

@@ -0,0 +1,20 @@
+import { FieldMap, Field } from './types.js';
+
+/** Create a bitmask value. Bottom 15 bits = on, top 15 bits = off. */
+declare function bitmask(index: number, value: boolean): number;
+/** Apply a bitmask to a number. */
+declare function applyBitmask(num: number, mask: number): number;
+/** Combine two bitmasks into one. */
+declare function combineBitmasks(a: number, b: number): number;
+/** Generate a random ID. */
+declare function generateId(): string;
+/** Merge a single incoming field with an existing value, based on suffix type. */
+declare function mergeField(existing: Field | undefined, incoming: Field, suffix: string): Field;
+/** Consolidate new ops into existing pending ops (client-side batching). */
+declare function consolidateOps(pending: FieldMap, newOps: FieldMap): FieldMap;
+/** Convert flat dot-notation FieldMap to a nested object. Strips suffixes from keys. */
+declare function buildState<T = Record<string, any>>(fields: FieldMap): T;
+/** Compute effective fields by layering confirmed + sending + pending. */
+declare function effectiveFields(confirmed: FieldMap, sending: FieldMap | null, pending: FieldMap): FieldMap;
+
+export { applyBitmask, bitmask, buildState, combineBitmasks, consolidateOps, effectiveFields, generateId, mergeField };

package/dist/micro/ops.js

@@ -0,0 +1,100 @@
+import "../chunk-IZ2YBCUP.js";
+import { Delta } from "@dabble/delta";
+import { BIT, INC, MAX, parseSuffix, TXT } from "./types.js";
+function bitmask(index, value) {
+  if (index < 0 || index > 14) throw new Error("Index must be between 0 and 14");
+  return value ? 1 << index : 1 << index + 15;
+}
+function applyBitmask(num, mask) {
+  return num & ~(mask >> 15 & 32767) | mask & 32767;
+}
+function combineBitmasks(a, b) {
+  const aOff = a >> 15 & 32767, aOn = a & 32767;
+  const bOff = b >> 15 & 32767, bOn = b & 32767;
+  return (aOff & ~bOn | bOff) << 15 | (aOn & ~bOff | bOn);
+}
+function generateId() {
+  return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+}
+function mergeField(existing, incoming, suffix) {
+  const ev = existing?.val ?? 0;
+  switch (suffix) {
+    case INC:
+      return { val: ev + incoming.val, ts: incoming.ts };
+    case BIT:
+      return { val: applyBitmask(ev, incoming.val), ts: incoming.ts };
+    case MAX:
+      return incoming.val >= ev ? incoming : existing;
+    case TXT:
+      return incoming;
+    // text composed separately
+    default:
+      return incoming.ts >= (existing?.ts ?? 0) ? incoming : existing;
+  }
+}
+function consolidateOps(pending, newOps) {
+  const result = { ...pending };
+  for (const [key, field] of Object.entries(newOps)) {
+    const ex = result[key];
+    if (!ex) {
+      result[key] = field;
+      continue;
+    }
+    const { suffix } = parseSuffix(key);
+    switch (suffix) {
+      case INC:
+        result[key] = { val: ex.val + field.val, ts: field.ts };
+        break;
+      case BIT:
+        result[key] = { val: combineBitmasks(ex.val, field.val), ts: field.ts };
+        break;
+      case MAX:
+        result[key] = field.val >= ex.val ? field : ex;
+        break;
+      case TXT:
+        result[key] = { val: new Delta(ex.val).compose(new Delta(field.val)).ops, ts: field.ts };
+        break;
+      default:
+        result[key] = field;
+    }
+  }
+  return result;
+}
+function buildState(fields) {
+  const obj = {};
+  for (const [key, field] of Object.entries(fields)) {
+    if (field.val == null) continue;
+    const { path } = parseSuffix(key);
+    const parts = path.split(".");
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) cur = cur[parts[i]] ??= {};
+    cur[parts[parts.length - 1]] = field.val;
+  }
+  return obj;
+}
+function effectiveFields(confirmed, sending, pending) {
+  const result = { ...confirmed };
+  const layers = sending ? [sending, pending] : [pending];
+  for (const layer of layers) {
+    for (const [key, field] of Object.entries(layer)) {
+      const { suffix } = parseSuffix(key);
+      if (suffix === TXT) {
+        const base = result[key]?.val ? new Delta(result[key].val) : new Delta();
+        result[key] = { val: base.compose(new Delta(field.val)).ops, ts: field.ts };
+      } else {
+        result[key] = mergeField(result[key], field, suffix);
+      }
+    }
+  }
+  return result;
+}
+export {
+  applyBitmask,
+  bitmask,
+  buildState,
+  combineBitmasks,
+  consolidateOps,
+  effectiveFields,
+  generateId,
+  mergeField
+};

package/dist/micro/server.d.ts

@@ -0,0 +1,44 @@
+import { DbBackend, FieldMap, Field, TextLogEntry, ChangeLogEntry, ObjectStore, DocState, CommitResult, Change } from './types.js';
+
+type Subscriber = (fields: FieldMap, rev: number) => void;
+declare class MicroServer {
+    private _db;
+    private _objects?;
+    private _subs;
+    constructor(_db: DbBackend, _objects?: ObjectStore | undefined);
+    /** Get full document state. */
+    getDoc(docId: string): Promise<DocState>;
+    /** Get fields changed since a given revision (for reconnection). */
+    getChangesSince(docId: string, sinceRev: number): Promise<CommitResult>;
+    /** Process an incoming change from a client. */
+    commitChanges(docId: string, change: Change): Promise<CommitResult>;
+    /** Compact text log entries up to a revision. */
+    compactTextLog(docId: string, key: string, throughRev: number): Promise<void>;
+    /** Prune old change log entries. */
+    pruneChanges(docId: string, beforeTs: number): Promise<void>;
+    /** Subscribe to changes for a document. */
+    subscribe(docId: string, cb: Subscriber): () => void;
+    /** Get subscriber count for a document. */
+    subscriberCount(docId: string): number;
+    private _broadcast;
+    private _handleLargeValue;
+}
+declare class MemoryDbBackend implements DbBackend {
+    private _fields;
+    private _textLog;
+    private _changeLog;
+    private _revs;
+    getFields(docId: string): Promise<FieldMap>;
+    getField(docId: string, key: string): Promise<Field | null>;
+    setFields(docId: string, fields: FieldMap): Promise<void>;
+    getTextLog(docId: string, key: string, sinceRev?: number): Promise<TextLogEntry[]>;
+    appendTextLog(docId: string, entry: TextLogEntry): Promise<void>;
+    compactTextLog(docId: string, key: string, throughRev: number, composedDelta: any): Promise<void>;
+    hasChange(docId: string, changeId: string): Promise<boolean>;
+    addChange(docId: string, entry: ChangeLogEntry): Promise<void>;
+    pruneChanges(docId: string, beforeTs: number): Promise<void>;
+    getRev(docId: string): Promise<number>;
+    setRev(docId: string, rev: number): Promise<void>;
+}
+
+export { MemoryDbBackend, MicroServer };