@foir/sdk 0.9.0 → 0.11.0

package/dist/live-react.js

@@ -0,0 +1,395 @@
+"use client";
+"use client";
+
+// src/live/react/index.tsx
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore
+} from "react";
+
+// src/live/resync.ts
+var FOIR_RESYNC_ERROR_CODES = ["cursor_expired", "backlog_too_large"];
+function foirRequiresResync(error) {
+  const code = error.code;
+  return typeof code === "string" && FOIR_RESYNC_ERROR_CODES.includes(code);
+}
+
+// src/live/manager.ts
+function createFoirLiveManager(options) {
+  const watches = /* @__PURE__ */ new Map();
+  function open(modelKey, watch) {
+    const after = watch.cursor ?? void 0;
+    watch.subscription = options.subscribe(
+      modelKey,
+      after === void 0 ? {} : { after },
+      {
+        onData: (event) => {
+          if (typeof event.seq === "number" && (watch.cursor === null || event.seq > watch.cursor)) {
+            watch.cursor = event.seq;
+          }
+          options.onChange(event);
+        },
+        onError: (error) => {
+          if (foirRequiresResync(error)) {
+            watch.cursor = null;
+            options.onResync?.(error, modelKey);
+            return;
+          }
+          options.onError?.(error, modelKey);
+        },
+        onReconnect: () => {
+          resume(modelKey);
+        }
+      }
+    );
+  }
+  function resume(modelKey) {
+    const watch = watches.get(modelKey);
+    if (!watch || watch.count === 0 || watch.resuming) return;
+    watch.resuming = true;
+    try {
+      watch.subscription?.unsubscribe();
+      watch.subscription = null;
+      open(modelKey, watch);
+    } finally {
+      watch.resuming = false;
+    }
+    options.reconcile?.(modelKey);
+  }
+  return {
+    retain(modelKey) {
+      let watch = watches.get(modelKey);
+      if (!watch) {
+        watch = { count: 0, subscription: null, cursor: null, resuming: false };
+        watches.set(modelKey, watch);
+      }
+      watch.count += 1;
+      if (watch.count === 1) open(modelKey, watch);
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        const current = watches.get(modelKey);
+        if (!current) return;
+        current.count -= 1;
+        if (current.count > 0) return;
+        current.subscription?.unsubscribe();
+        current.subscription = null;
+      };
+    },
+    cursorFor(modelKey) {
+      return watches.get(modelKey)?.cursor ?? null;
+    },
+    watchers(modelKey) {
+      return watches.get(modelKey)?.count ?? 0;
+    },
+    get watching() {
+      return [...watches.entries()].filter(([, w]) => w.subscription !== null).map(([k]) => k);
+    },
+    dispose() {
+      for (const watch of watches.values()) {
+        watch.subscription?.unsubscribe();
+        watch.subscription = null;
+        watch.count = 0;
+      }
+      watches.clear();
+    }
+  };
+}
+
+// src/live/coalesce.ts
+var DEFAULT_WINDOW_MS = 25;
+var DEFAULT_MAX_CONCURRENT = 4;
+function createFoirCoalescer(options) {
+  const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  const maxConcurrent = Math.max(1, options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT);
+  const timers = options.timers ?? {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle)
+  };
+  const waiting = /* @__PURE__ */ new Set();
+  const running = /* @__PURE__ */ new Set();
+  const superseded = /* @__PURE__ */ new Set();
+  let timer = null;
+  let idle = [];
+  let disposed = false;
+  function settleIdle() {
+    if (waiting.size > 0 || running.size > 0 || timer !== null) return;
+    const waiters = idle;
+    idle = [];
+    for (const resolve of waiters) resolve();
+  }
+  function pump() {
+    while (running.size < maxConcurrent && waiting.size > 0) {
+      const key = waiting.values().next().value;
+      waiting.delete(key);
+      running.add(key);
+      void start(key);
+    }
+    settleIdle();
+  }
+  async function start(key) {
+    try {
+      await options.run(key);
+    } catch (error) {
+      options.onError?.(error, key);
+    } finally {
+      running.delete(key);
+      if (superseded.delete(key) && !disposed) {
+        waiting.add(key);
+      }
+      pump();
+    }
+  }
+  function arm() {
+    if (timer !== null || disposed) return;
+    timer = timers.setTimeout(() => {
+      timer = null;
+      pump();
+    }, windowMs);
+  }
+  return {
+    invalidate(key) {
+      if (disposed) return;
+      if (running.has(key)) {
+        superseded.add(key);
+        return;
+      }
+      waiting.add(key);
+      arm();
+    },
+    async flush() {
+      if (timer !== null) {
+        timers.clearTimeout(timer);
+        timer = null;
+      }
+      pump();
+      if (waiting.size === 0 && running.size === 0) return;
+      await new Promise((resolve) => idle.push(resolve));
+    },
+    get pending() {
+      return waiting.size;
+    },
+    get inFlight() {
+      return running.size;
+    },
+    dispose() {
+      disposed = true;
+      if (timer !== null) {
+        timers.clearTimeout(timer);
+        timer = null;
+      }
+      waiting.clear();
+      superseded.clear();
+      settleIdle();
+    }
+  };
+}
+
+// src/live/tanstack.ts
+var FOIR_QUERY_KEY_ROOT = "foir";
+function foirModelQueryKey(modelKey) {
+  return [FOIR_QUERY_KEY_ROOT, modelKey];
+}
+function applyFoirRecordChange(queryClient, event, options = {}) {
+  const mode = options.mode ?? "auto";
+  const idField = options.idField ?? "_id";
+  const effect = {
+    invalidated: [],
+    removed: [],
+    created: event.action === "created",
+    totalCountStale: event.action === "created" || event.action === "deleted"
+  };
+  if (mode === "off" || mode === "notify") return effect;
+  const modelKey = foirModelQueryKey(event.modelKey);
+  if (event.action === "deleted") {
+    const removed = [];
+    queryClient.setQueriesData({ queryKey: modelKey }, (previous) => {
+      const next = withoutRecord(previous, event.recordId, idField);
+      return next.changed ? next.value : previous;
+    });
+    for (const [key, value] of queryClient.getQueriesData({ queryKey: modelKey })) {
+      if (!containsRecord(value, event.recordId, idField)) removed.push(key);
+    }
+    return { ...effect, removed };
+  }
+  if (event.action === "updated") {
+    const invalidated = [];
+    const invalidate = options.invalidate ?? ((key) => {
+      queryClient.invalidateQueries({ queryKey: key, exact: true });
+    });
+    for (const [key, value] of queryClient.getQueriesData({ queryKey: modelKey })) {
+      if (!containsRecord(value, event.recordId, idField)) continue;
+      invalidate(key);
+      invalidated.push(key);
+    }
+    return { ...effect, invalidated };
+  }
+  return effect;
+}
+function ids(value, idField) {
+  const page = value;
+  if (!page || typeof page !== "object") return [];
+  const out = [];
+  for (const edge of page.edges ?? []) {
+    const id = edge?.node?.[idField];
+    if (typeof id === "string") out.push(id);
+  }
+  for (const node of page.nodes ?? []) {
+    const id = node?.[idField];
+    if (typeof id === "string") out.push(id);
+  }
+  const own = page[idField];
+  if (typeof own === "string") out.push(own);
+  return out;
+}
+function containsRecord(value, recordId, idField) {
+  return ids(value, idField).includes(recordId);
+}
+function withoutRecord(value, recordId, idField) {
+  const page = value;
+  if (!page || typeof page !== "object") return { value, changed: false };
+  let changed = false;
+  const next = { ...page };
+  if (Array.isArray(page.edges)) {
+    const edges = page.edges.filter(
+      (edge) => edge?.node?.[idField] !== recordId
+    );
+    if (edges.length !== page.edges.length) {
+      next.edges = edges;
+      changed = true;
+    }
+  }
+  if (Array.isArray(page.nodes)) {
+    const nodes = page.nodes.filter(
+      (node) => node?.[idField] !== recordId
+    );
+    if (nodes.length !== page.nodes.length) {
+      next.nodes = nodes;
+      changed = true;
+    }
+  }
+  return changed ? { value: next, changed: true } : { value, changed: false };
+}
+
+// src/live/react/index.tsx
+var EMPTY_SNAPSHOT = {
+  newCounts: {},
+  totalCountStale: [],
+  lastEvent: {}
+};
+var FoirLiveContext = createContext(null);
+function FoirLive(props) {
+  const {
+    subscribe,
+    queryClient,
+    mode = "auto",
+    idField,
+    onResync,
+    onError,
+    onEffect,
+    reconcile,
+    coalesceWindowMs,
+    maxConcurrentRefetches,
+    children
+  } = props;
+  const latest = useRef({ queryClient, mode, idField, onResync, onError, onEffect, reconcile });
+  latest.current = { queryClient, mode, idField, onResync, onError, onEffect, reconcile };
+  const snapshotRef = useRef(EMPTY_SNAPSHOT);
+  const listeners = useRef(/* @__PURE__ */ new Set()).current;
+  const emit = useCallback(
+    (next) => {
+      snapshotRef.current = next;
+      for (const listener of listeners) listener();
+    },
+    [listeners]
+  );
+  const subscribeRef = useRef(subscribe);
+  subscribeRef.current = subscribe;
+  const coalescerRef = useRef(null);
+  if (coalescerRef.current === null) {
+    coalescerRef.current = createFoirCoalescer({
+      run: (key) => latest.current.queryClient.invalidateQueries({
+        queryKey: JSON.parse(key),
+        exact: true
+      }),
+      windowMs: coalesceWindowMs,
+      maxConcurrent: maxConcurrentRefetches,
+      onError: (error) => latest.current.onError?.(error, "")
+    });
+  }
+  const manager = useMemo(
+    () => createFoirLiveManager({
+      subscribe: (modelKey, options, handlers) => subscribeRef.current(modelKey, options, handlers),
+      onChange: (event) => {
+        const current = latest.current;
+        const effect = applyFoirRecordChange(current.queryClient, event, {
+          mode: current.mode,
+          idField: current.idField,
+          // The key is carried as JSON because a coalescer keys on a string —
+          // two structurally identical query keys are different objects, and
+          // a burst on one query would otherwise coalesce nothing at all.
+          invalidate: (key) => coalescerRef.current?.invalidate(JSON.stringify(key))
+        });
+        const previous = snapshotRef.current;
+        emit({
+          newCounts: effect.created ? { ...previous.newCounts, [event.modelKey]: (previous.newCounts[event.modelKey] ?? 0) + 1 } : previous.newCounts,
+          totalCountStale: effect.totalCountStale ? [.../* @__PURE__ */ new Set([...previous.totalCountStale, event.modelKey])] : previous.totalCountStale,
+          lastEvent: { ...previous.lastEvent, [event.modelKey]: event }
+        });
+        current.onEffect?.(effect, event);
+      },
+      onResync: (error, modelKey) => latest.current.onResync?.(error, modelKey),
+      onError: (error, modelKey) => latest.current.onError?.(error, modelKey),
+      reconcile: (modelKey) => latest.current.reconcile?.(modelKey)
+    }),
+    [emit]
+  );
+  useEffect(
+    () => () => {
+      manager.dispose();
+      coalescerRef.current?.dispose();
+    },
+    [manager]
+  );
+  const value = useMemo(
+    () => ({
+      manager,
+      retain: (modelKey) => manager.retain(modelKey),
+      subscribeEffects: (listener) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      snapshot: () => snapshotRef.current
+    }),
+    [manager, listeners]
+  );
+  return createElement(FoirLiveContext.Provider, { value }, children);
+}
+function useFoirLiveContext(hook) {
+  const value = useContext(FoirLiveContext);
+  if (!value) {
+    throw new Error(`[foir] ${hook} must be used inside <FoirLive>`);
+  }
+  return value;
+}
+function useFoirLive(modelKey) {
+  const { retain } = useFoirLiveContext("useFoirLive");
+  useEffect(() => retain(modelKey), [retain, modelKey]);
+}
+function useFoirLiveStatus() {
+  const { subscribeEffects, snapshot } = useFoirLiveContext("useFoirLiveStatus");
+  return useSyncExternalStore(subscribeEffects, snapshot, () => EMPTY_SNAPSHOT);
+}
+export {
+  FoirLive,
+  foirModelQueryKey,
+  useFoirLive,
+  useFoirLiveStatus
+};