@korajs/store 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -943,6 +943,8 @@ __export(index_exports, {
   PersistenceError: () => PersistenceError,
   QueryBuilder: () => QueryBuilder,
   QueryError: () => QueryError,
+  QueryStore: () => QueryStore,
+  QueryStoreCache: () => QueryStoreCache,
   RecordNotFoundError: () => RecordNotFoundError,
   SequenceManager: () => SequenceManager,
   Store: () => Store,
@@ -952,14 +954,18 @@ __export(index_exports, {
   TransactionContext: () => TransactionContext,
   WorkerInitError: () => WorkerInitError,
   WorkerTimeoutError: () => WorkerTimeoutError,
+  asRichTextSyncEngine: () => asRichTextSyncEngine,
+  assertQueryReady: () => assertQueryReady,
   collectOperationsAheadOfServer: () => collectOperationsAheadOfServer,
   compactOperationLog: () => compactOperationLog,
   computeAckCompactionWatermark: () => computeAckCompactionWatermark,
+  createRichTextController: () => createRichTextController,
   decodeAuditExport: () => decodeAuditExport,
   decodeRichtext: () => decodeRichtext,
   deserializeVersionVectorFromMeta: () => deserializeVersionVectorFromMeta,
   encodeRichtext: () => encodeRichtext,
   exportBackup: () => exportBackup,
+  getSharedQueryStoreCache: () => getSharedQueryStoreCache,
   mergeVersionVectors: () => mergeVersionVectors,
   persistedAuditTraceFromEvent: () => persistedAuditTraceFromEvent,
   pluralize: () => pluralize,
@@ -4074,6 +4080,483 @@ var Store = class {
   }
 };
 
+// src/reactivity/query-store.ts
+var EMPTY_ARRAY = Object.freeze([]);
+var QueryStore = class {
+  snapshot = EMPTY_ARRAY;
+  listeners = /* @__PURE__ */ new Set();
+  unsubscribeQuery = null;
+  active = false;
+  queryBuilder;
+  constructor(queryBuilder) {
+    this.queryBuilder = queryBuilder;
+  }
+  /**
+   * Subscribe to snapshot changes.
+   *
+   * @returns Unsubscribe function
+   */
+  subscribe = (onStoreChange) => {
+    this.listeners.add(onStoreChange);
+    if (!this.active) {
+      this.startSubscription();
+    }
+    return () => {
+      this.listeners.delete(onStoreChange);
+      if (this.listeners.size === 0) {
+        this.stopSubscription();
+      }
+    };
+  };
+  /** Synchronous read of the latest query results. */
+  getSnapshot = () => {
+    return this.snapshot;
+  };
+  /** Tear down listeners and the underlying query subscription. */
+  destroy() {
+    this.stopSubscription();
+    this.listeners.clear();
+    this.snapshot = EMPTY_ARRAY;
+  }
+  startSubscription() {
+    this.active = true;
+    this.unsubscribeQuery = this.queryBuilder.subscribe((results) => {
+      if (!this.active) return;
+      this.snapshot = Object.freeze([...results]);
+      this.notifyListeners();
+    });
+  }
+  stopSubscription() {
+    this.active = false;
+    if (this.unsubscribeQuery) {
+      this.unsubscribeQuery();
+      this.unsubscribeQuery = null;
+    }
+  }
+  notifyListeners() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+};
+
+// src/reactivity/assert-query-ready.ts
+var import_core18 = require("@korajs/core");
+var LEGACY_PENDING_COLLECTION = "__pending__";
+function assertQueryReady(query) {
+  const descriptor = query.getDescriptor();
+  if (descriptor.collection === LEGACY_PENDING_COLLECTION) {
+    throw new import_core18.AppNotReadyError(
+      "Cannot use useQuery() before app.ready. Await app.ready or wrap your UI in <KoraProvider app={app}>."
+    );
+  }
+}
+
+// src/reactivity/query-store-cache.ts
+var QueryStoreCache = class {
+  constructor(scopeKey = "default") {
+    this.scopeKey = scopeKey;
+  }
+  scopeKey;
+  entries = /* @__PURE__ */ new Map();
+  getOrCreate(queryBuilder) {
+    const key = this.getKey(queryBuilder);
+    const existing = this.entries.get(key);
+    if (existing) {
+      existing.refCount++;
+      return existing.queryStore;
+    }
+    const queryStore = new QueryStore(queryBuilder);
+    this.entries.set(key, {
+      queryStore,
+      refCount: 1
+    });
+    return queryStore;
+  }
+  release(queryBuilder) {
+    const key = this.getKey(queryBuilder);
+    const entry = this.entries.get(key);
+    if (!entry) {
+      return;
+    }
+    entry.refCount--;
+    if (entry.refCount <= 0) {
+      entry.queryStore.destroy();
+      this.entries.delete(key);
+    }
+  }
+  clear() {
+    for (const entry of this.entries.values()) {
+      entry.queryStore.destroy();
+    }
+    this.entries.clear();
+  }
+  get size() {
+    return this.entries.size;
+  }
+  getKey(queryBuilder) {
+    return `${this.scopeKey}:${JSON.stringify(queryBuilder.getDescriptor())}`;
+  }
+};
+var sharedCache = null;
+function getSharedQueryStoreCache() {
+  if (!sharedCache) {
+    sharedCache = new QueryStoreCache();
+  }
+  return sharedCache;
+}
+
+// src/richtext/create-richtext-controller.ts
+var Y2 = __toESM(require("yjs"), 1);
+init_richtext_serializer();
+var LOAD_ORIGIN = "kora-load";
+var REMOTE_ORIGIN = "kora-remote";
+var DOC_CHANNEL_ORIGIN = "kora-doc-channel";
+var TEXT_KEY2 = "content";
+var COMPACT_AFTER_DELTAS = 20;
+var PERSIST_DEBOUNCE_MS = 400;
+function createRichTextController(options) {
+  const {
+    collection,
+    collectionName,
+    recordId,
+    fieldName,
+    store,
+    syncEngine = null,
+    useDocChannel
+  } = options;
+  const doc = new Y2.Doc();
+  const text = doc.getText(TEXT_KEY2);
+  const undoManager = new Y2.UndoManager(text);
+  let user = options.user;
+  let disposed = false;
+  let ready = false;
+  let error = null;
+  let canUndo = false;
+  let canRedo = false;
+  let cursors = [];
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = {
+    ready: false,
+    error: null,
+    canUndo: false,
+    canRedo: false,
+    cursors: []
+  };
+  const baseUpdateRef = { current: null };
+  const pendingDeltasRef = { current: [] };
+  const docChannelActiveRef = { current: false };
+  let persistTimer = null;
+  let recordUnsubscribe = null;
+  let docChannelUnsubscribe = null;
+  let awarenessUnsubscribe = null;
+  const refreshSnapshot = () => {
+    snapshot = {
+      ready,
+      error,
+      canUndo,
+      canRedo,
+      cursors: [...cursors]
+    };
+  };
+  const notify = () => {
+    refreshSnapshot();
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  const syncHistoryState = () => {
+    canUndo = undoManager.undoStack.length > 0;
+    canRedo = undoManager.redoStack.length > 0;
+    notify();
+  };
+  const getSnapshot = () => snapshot;
+  const resolveAwarenessUser = () => {
+    if (user) {
+      return user;
+    }
+    if (syncEngine) {
+      const existing = syncEngine.getAwarenessManager().getLocalState()?.user;
+      if (existing) {
+        return existing;
+      }
+    }
+    return {
+      name: "Anonymous",
+      color: "#6366f1"
+    };
+  };
+  const setCursor = (anchor, head) => {
+    if (!syncEngine) {
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    const state = {
+      user: resolveAwarenessUser(),
+      cursor: {
+        collection: collectionName,
+        recordId,
+        field: fieldName,
+        anchor,
+        head
+      }
+    };
+    awareness.setLocalState(state);
+  };
+  const clearCursor = () => {
+    if (!syncEngine) {
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    const current = awareness.getLocalState();
+    if (!current?.cursor) {
+      return;
+    }
+    if (current.cursor.collection !== collectionName || current.cursor.recordId !== recordId || current.cursor.field !== fieldName) {
+      return;
+    }
+    awareness.setLocalState({ user: current.user });
+  };
+  const applyRemoteSnapshot = (value) => {
+    const encoded = encodeRichtextInput(value);
+    if (!encoded) {
+      return;
+    }
+    const currentSnapshot = Y2.encodeStateAsUpdate(doc);
+    if (updatesEqual(currentSnapshot, encoded)) {
+      return;
+    }
+    Y2.applyUpdate(doc, encoded, REMOTE_ORIGIN);
+    baseUpdateRef.current = encoded;
+    pendingDeltasRef.current = [];
+    syncHistoryState();
+  };
+  const flushPersist = async () => {
+    const snapshot2 = composeRichtextSnapshot(baseUpdateRef.current, pendingDeltasRef.current);
+    if (pendingDeltasRef.current.length >= COMPACT_AFTER_DELTAS) {
+      baseUpdateRef.current = snapshot2;
+      pendingDeltasRef.current = [];
+    }
+    try {
+      await collection.update(recordId, {
+        [fieldName]: snapshot2
+      });
+    } catch (cause) {
+      if (!disposed) {
+        error = cause instanceof Error ? cause : new Error(String(cause));
+        notify();
+      }
+    }
+  };
+  const schedulePersist = () => {
+    if (persistTimer) {
+      clearTimeout(persistTimer);
+    }
+    persistTimer = setTimeout(() => {
+      persistTimer = null;
+      void flushPersist();
+    }, PERSIST_DEBOUNCE_MS);
+  };
+  const onDocUpdate = (update, origin) => {
+    syncHistoryState();
+    if (origin === LOAD_ORIGIN || origin === REMOTE_ORIGIN || origin === DOC_CHANNEL_ORIGIN) {
+      return;
+    }
+    pendingDeltasRef.current.push(update);
+    if (docChannelActiveRef.current && syncEngine) {
+      syncEngine.getRichtextDocChannel?.().send(collectionName, recordId, fieldName, update);
+      schedulePersist();
+      return;
+    }
+    void flushPersist();
+  };
+  const subscribeRecordChanges = () => {
+    recordUnsubscribe?.();
+    recordUnsubscribe = store.collection(collectionName).where({ id: recordId }).subscribe((results) => {
+      const record = results[0];
+      if (!record) {
+        return;
+      }
+      applyRemoteSnapshot(record[fieldName]);
+    });
+  };
+  const subscribeDocChannel = () => {
+    docChannelUnsubscribe?.();
+    if (!ready || !syncEngine || !docChannelActiveRef.current) {
+      return;
+    }
+    const channel = syncEngine.getRichtextDocChannel?.();
+    if (!channel) {
+      return;
+    }
+    docChannelUnsubscribe = channel.subscribe(collectionName, recordId, fieldName, (update) => {
+      Y2.applyUpdate(doc, update, DOC_CHANNEL_ORIGIN);
+      syncHistoryState();
+    });
+  };
+  const updateCursors = () => {
+    if (!syncEngine) {
+      cursors = [];
+      notify();
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    const localClientId = awareness.clientId;
+    const states = awareness.getStates();
+    const fieldCursors = [];
+    for (const [clientId, state] of states) {
+      if (clientId === localClientId) continue;
+      if (!state.cursor) continue;
+      if (state.cursor.collection !== collectionName || state.cursor.recordId !== recordId || state.cursor.field !== fieldName) {
+        continue;
+      }
+      fieldCursors.push({
+        clientId,
+        userName: state.user.name,
+        color: state.user.color,
+        anchor: state.cursor.anchor,
+        head: state.cursor.head
+      });
+    }
+    cursors = fieldCursors;
+    notify();
+  };
+  const subscribeAwareness = () => {
+    awarenessUnsubscribe?.();
+    if (!syncEngine) {
+      cursors = [];
+      notify();
+      return;
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    awarenessUnsubscribe = awareness.on("change", () => {
+      updateCursors();
+    });
+    updateCursors();
+  };
+  const initialize = async () => {
+    ready = false;
+    error = null;
+    notify();
+    try {
+      const record = await collection.findById(recordId);
+      if (disposed) return;
+      doc.transact(() => {
+        const target = doc.getText(TEXT_KEY2);
+        target.delete(0, target.length);
+      }, LOAD_ORIGIN);
+      const encoded = encodeRichtextInput(record?.[fieldName]);
+      baseUpdateRef.current = encoded;
+      pendingDeltasRef.current = [];
+      if (encoded) {
+        Y2.applyUpdate(doc, encoded, LOAD_ORIGIN);
+      }
+      const channel = syncEngine?.getRichtextDocChannel?.();
+      docChannelActiveRef.current = channel?.shouldUseChannel(encoded?.length ?? 0, useDocChannel) ?? false;
+      ready = true;
+      syncHistoryState();
+      subscribeRecordChanges();
+      subscribeDocChannel();
+      subscribeAwareness();
+      notify();
+    } catch (cause) {
+      if (disposed) return;
+      error = cause instanceof Error ? cause : new Error(String(cause));
+      notify();
+    }
+  };
+  doc.on("update", onDocUpdate);
+  void initialize();
+  return {
+    doc,
+    text,
+    getSnapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    undo() {
+      undoManager.undo();
+      syncHistoryState();
+    },
+    redo() {
+      undoManager.redo();
+      syncHistoryState();
+    },
+    setCursor,
+    clearCursor,
+    setUser(nextUser) {
+      user = nextUser;
+    },
+    destroy() {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      if (persistTimer) {
+        clearTimeout(persistTimer);
+        persistTimer = null;
+      }
+      doc.off("update", onDocUpdate);
+      recordUnsubscribe?.();
+      docChannelUnsubscribe?.();
+      awarenessUnsubscribe?.();
+      clearCursor();
+      undoManager.destroy();
+      baseUpdateRef.current = null;
+      pendingDeltasRef.current = [];
+      docChannelActiveRef.current = false;
+      listeners.clear();
+    }
+  };
+}
+function encodeRichtextInput(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  try {
+    return encodeRichtext(value);
+  } catch {
+    if (typeof value === "string") {
+      const fallbackDoc = new Y2.Doc();
+      fallbackDoc.getText(TEXT_KEY2).insert(0, value);
+      return Y2.encodeStateAsUpdate(fallbackDoc);
+    }
+    throw new Error("Richtext record value must be a string, Uint8Array, ArrayBuffer, or null.");
+  }
+}
+function composeRichtextSnapshot(base, deltas) {
+  const mergedDoc = new Y2.Doc();
+  if (base) {
+    Y2.applyUpdate(mergedDoc, base);
+  }
+  for (const delta of deltas) {
+    Y2.applyUpdate(mergedDoc, delta);
+  }
+  return Y2.encodeStateAsUpdate(mergedDoc);
+}
+function updatesEqual(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index++) {
+    if (left[index] !== right[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/richtext/as-rich-text-sync-engine.ts
+function asRichTextSyncEngine(engine) {
+  if (engine == null) {
+    return null;
+  }
+  return engine;
+}
+
 // src/index.ts
 init_richtext_serializer();
 
@@ -4094,6 +4577,8 @@ init_export_audit();
   PersistenceError,
   QueryBuilder,
   QueryError,
+  QueryStore,
+  QueryStoreCache,
   RecordNotFoundError,
   SequenceManager,
   Store,
@@ -4103,14 +4588,18 @@ init_export_audit();
   TransactionContext,
   WorkerInitError,
   WorkerTimeoutError,
+  asRichTextSyncEngine,
+  assertQueryReady,
   collectOperationsAheadOfServer,
   compactOperationLog,
   computeAckCompactionWatermark,
+  createRichTextController,
   decodeAuditExport,
   decodeRichtext,
   deserializeVersionVectorFromMeta,
   encodeRichtext,
   exportBackup,
+  getSharedQueryStoreCache,
   mergeVersionVectors,
   persistedAuditTraceFromEvent,
   pluralize,