rastack 0.0.16

package/sync/hooks.ts

@@ -0,0 +1,450 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import { API } from "../hooks/query/api";
+import { useSyncEngine, useSyncEngineOptional } from "./provider";
+import { tempId, uuid4 } from "./transactions";
+import {
+  EngineStatus,
+  EntityDescriptor,
+  entityKey,
+  TransactionOp,
+} from "./types";
+
+export function useEngineStatus(): EngineStatus {
+  const engine = useSyncEngine();
+  return useSyncExternalStore(
+    (listener) => engine.subscribeStatus(listener),
+    () => engine.getStatus(),
+    () => engine.getStatus(),
+  );
+}
+
+export interface EntityListOptions<TRow> {
+  /** Local predicate applied to every row. */
+  filter?: (row: TRow) => boolean;
+  /** Local comparator. */
+  sort?: (a: TRow, b: TRow) => number;
+  /** Local search text, matched with searchFunction (or against searchFields). */
+  search?: string;
+  searchFields?: (keyof TRow)[];
+  searchFunction?: (search: string, row: TRow) => boolean;
+}
+
+export interface EntityListResult<TRow> {
+  data: TRow[] | undefined;
+  isLoading: boolean;
+  isReady: boolean;
+}
+
+/**
+ * List read for a sync-mode entity — served from the local store: instant
+ * after bootstrap, reactive to every delta and optimistic write thereafter.
+ * Filtering, sorting and search all run locally.
+ */
+export function useEntityList<TRow = any>(
+  entity: EntityDescriptor<TRow>,
+  options?: EntityListOptions<TRow>,
+): EntityListResult<TRow> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+
+  // Lazy entities partial-bootstrap the first time a component asks.
+  useEffect(() => {
+    void engine.ensureEntity(key).catch(() => {});
+  }, [engine, key]);
+
+  const rows = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () => engine.store.getList(key),
+    () => engine.store.getList(key),
+  ) as TRow[];
+  const isReady = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () => engine.store.isReady(key),
+    () => engine.store.isReady(key),
+  );
+
+  const { filter, sort, search, searchFields, searchFunction } = options || {};
+  const data = useMemo(() => {
+    let result = rows;
+    if (filter) {
+      result = result.filter(filter);
+    }
+    if (search) {
+      const lowered = search.toLowerCase();
+      const matches =
+        searchFunction ||
+        ((text: string, row: TRow) => {
+          const fields = searchFields || (Object.keys(row as any) as any[]);
+          return fields.some((field: any) =>
+            String((row as any)[field] ?? "")
+              .toLowerCase()
+              .includes(text.toLowerCase()),
+          );
+        });
+      result = result.filter((row) => matches(lowered, row));
+    }
+    if (sort) {
+      result = [...result].sort(sort);
+    }
+    return result;
+  }, [rows, filter, sort, search, searchFields, searchFunction]);
+
+  return {
+    data: isReady ? data : undefined,
+    isLoading: !isReady,
+    isReady,
+  };
+}
+
+export interface EntityRecordResult<TRow> {
+  data: TRow | undefined;
+  isLoading: boolean;
+  isReady: boolean;
+}
+
+/** Single-record read for a sync-mode entity, served from the local store. */
+export function useEntityRecord<TRow = any>(
+  entity: EntityDescriptor<TRow>,
+  id: string | number | undefined,
+): EntityRecordResult<TRow> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+
+  useEffect(() => {
+    void engine.ensureEntity(key).catch(() => {});
+  }, [engine, key]);
+
+  const resolvedId =
+    id === undefined ? undefined : engine.queue.resolveAlias(String(id));
+
+  const data = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () =>
+      resolvedId === undefined
+        ? undefined
+        : (engine.store.get(key, resolvedId) as TRow | undefined),
+    () =>
+      resolvedId === undefined
+        ? undefined
+        : (engine.store.get(key, resolvedId) as TRow | undefined),
+  );
+  const isReady = useSyncExternalStore(
+    (listener) => engine.store.subscribe(key, listener),
+    () => engine.store.isReady(key),
+    () => engine.store.isReady(key),
+  );
+
+  return { data, isLoading: !isReady && data === undefined, isReady };
+}
+
+export interface MutationState<TResult> {
+  status: "idle" | "loading" | "success" | "error";
+  data: TResult | undefined;
+  error: unknown;
+}
+
+export interface EntityMutationResult<TVariables, TResult> {
+  /**
+   * Fire-and-forget: applies locally at once and syncs in the background.
+   * This is the default write mode.
+   */
+  mutate: (
+    variables: TVariables,
+    callbacks?: {
+      onSuccess?: (data: TResult) => void;
+      onError?: (error: unknown) => void;
+    },
+  ) => void;
+  /** Awaits the server acknowledgement (the local apply already happened). */
+  mutateAsync: (variables: TVariables) => Promise<TResult>;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+  data: TResult | undefined;
+  error: unknown;
+  status: MutationState<TResult>["status"];
+  reset: () => void;
+}
+
+function useMutationState<TResult>() {
+  const [state, setState] = useState<MutationState<TResult>>({
+    status: "idle",
+    data: undefined,
+    error: undefined,
+  });
+  const reset = useCallback(
+    () => setState({ status: "idle", data: undefined, error: undefined }),
+    [],
+  );
+  return { state, setState, reset };
+}
+
+export interface WriteVariables<TParams, TPayload> {
+  params: TParams;
+  payload: TPayload;
+}
+
+export interface EntityMutationConfig<TParams> {
+  op: Exclude<TransactionOp, "delete">;
+  method: "post" | "put" | "patch";
+  url: (params: TParams) => string;
+  /** For updates: extract the row id from the call params. */
+  id?: (params: TParams) => string | number | undefined;
+}
+
+/**
+ * Optimistic write for a sync-mode entity. The store updates immediately,
+ * the transaction persists locally (offline writes replay on reconnect),
+ * and the change is sent through the entity's normal REST endpoint.
+ * Server rejection rolls back and reports through the error state.
+ */
+export function useEntityMutation<TParams, TPayload, TResult = any>(
+  entity: EntityDescriptor,
+  config: EntityMutationConfig<TParams>,
+): EntityMutationResult<WriteVariables<TParams, TPayload>, TResult> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+  const { state, setState, reset } = useMutationState<TResult>();
+
+  const mutateAsync = useCallback(
+    async (variables: WriteVariables<TParams, TPayload>): Promise<TResult> => {
+      const idField = entity.idField || "id";
+      const payload = (variables.payload || {}) as Record<string, any>;
+      let id: string;
+      let original: Record<string, any> | null = null;
+
+      if (config.op === "create") {
+        if (entity.clientIds) {
+          // Client-generated UUID pk: the id is real from the start and is
+          // sent to the server with the payload.
+          id = (payload[idField] as string) || uuid4();
+          payload[idField] = id;
+        } else {
+          id = tempId();
+        }
+      } else {
+        const rawId =
+          config.id?.(variables.params) ??
+          (payload as any)[idField] ??
+          (variables.params as any)?.[idField];
+        if (rawId === undefined || rawId === null) {
+          throw new Error(
+            `Cannot resolve the ${idField} of the ${key} row being updated`,
+          );
+        }
+        id = engine.queue.resolveAlias(String(rawId));
+        const current = engine.store.get(key, id);
+        if (current) {
+          original = {};
+          Object.keys(payload).forEach((field) => {
+            original![field] = current[field];
+          });
+        }
+      }
+
+      setState({ status: "loading", data: undefined, error: undefined });
+      try {
+        const data = (await engine.queue.enqueue({
+          entity: key,
+          op: config.op,
+          id,
+          method: config.method,
+          url: config.url(variables.params),
+          payload,
+          original,
+        })) as TResult;
+        setState({ status: "success", data, error: undefined });
+        return data;
+      } catch (error) {
+        setState({ status: "error", data: undefined, error });
+        throw error;
+      }
+    },
+    [engine, key, config.op, config.method], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const mutate = useCallback(
+    (
+      variables: WriteVariables<TParams, TPayload>,
+      callbacks?: {
+        onSuccess?: (data: TResult) => void;
+        onError?: (error: unknown) => void;
+      },
+    ) => {
+      mutateAsync(variables)
+        .then((data) => callbacks?.onSuccess?.(data))
+        .catch((error) => {
+          if (callbacks?.onError) {
+            callbacks.onError(error);
+          }
+        });
+    },
+    [mutateAsync],
+  );
+
+  return {
+    mutate,
+    mutateAsync,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    data: state.data,
+    error: state.error,
+    status: state.status,
+    reset,
+  };
+}
+
+export interface EntityDeleteConfig {
+  url: (id: string) => string;
+}
+
+/** Optimistic delete for a sync-mode entity (server-side it's a soft delete). */
+export function useEntityDelete<TResult = any>(
+  entity: EntityDescriptor,
+  config: EntityDeleteConfig,
+): EntityMutationResult<{ id?: string }, TResult> {
+  const engine = useSyncEngine();
+  const key = entityKey(entity);
+  const { state, setState, reset } = useMutationState<TResult>();
+
+  const mutateAsync = useCallback(
+    async (variables: { id?: string }): Promise<TResult> => {
+      if (variables.id === undefined) {
+        throw new Error("ID is required for delete operation");
+      }
+      const id = engine.queue.resolveAlias(String(variables.id));
+      const original = engine.store.get(key, id) || null;
+      setState({ status: "loading", data: undefined, error: undefined });
+      try {
+        const data = (await engine.queue.enqueue({
+          entity: key,
+          op: "delete",
+          id,
+          method: "delete",
+          url: config.url(id),
+          payload: null,
+          original,
+        })) as TResult;
+        setState({ status: "success", data, error: undefined });
+        return data;
+      } catch (error) {
+        setState({ status: "error", data: undefined, error });
+        throw error;
+      }
+    },
+    [engine, key], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const mutate = useCallback(
+    (
+      variables: { id?: string },
+      callbacks?: {
+        onSuccess?: (data: TResult) => void;
+        onError?: (error: unknown) => void;
+      },
+    ) => {
+      mutateAsync(variables)
+        .then((data) => callbacks?.onSuccess?.(data))
+        .catch((error) => {
+          if (callbacks?.onError) {
+            callbacks.onError(error);
+          }
+        });
+    },
+    [mutateAsync],
+  );
+
+  return {
+    mutate,
+    mutateAsync,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    data: state.data,
+    error: state.error,
+    status: state.status,
+    reset,
+  };
+}
+
+export interface ConfirmedMutationConfig<TParams> {
+  method: "post" | "put" | "patch" | "delete";
+  url: (params: TParams) => string;
+}
+
+/**
+ * A confirmed ("sync") operation — e.g. a password change. No optimistic
+ * apply, no queue, online-only: resolves only when the server has accepted
+ * the write. Anything it changed flows back through the changefeed like any
+ * other write.
+ */
+export function useConfirmedMutation<TParams, TPayload, TResult = any>(
+  config: ConfirmedMutationConfig<TParams>,
+): EntityMutationResult<WriteVariables<TParams, TPayload>, TResult> {
+  const engine = useSyncEngineOptional();
+  const { state, setState, reset } = useMutationState<TResult>();
+
+  const mutateAsync = useCallback(
+    async (variables: WriteVariables<TParams, TPayload>): Promise<TResult> => {
+      if (typeof navigator !== "undefined" && navigator.onLine === false) {
+        throw new Error("This operation requires a network connection");
+      }
+      const api = engine?.api || API;
+      const url = config.url(variables.params);
+      setState({ status: "loading", data: undefined, error: undefined });
+      try {
+        const response =
+          config.method === "delete"
+            ? await api.delete<TResult>(url)
+            : await api[config.method]<TResult>(url, variables.payload);
+        setState({ status: "success", data: response.data, error: undefined });
+        // Whatever the operation changed will arrive via the changefeed;
+        // kick the engine so it lands promptly.
+        engine?.wake();
+        return response.data;
+      } catch (error) {
+        setState({ status: "error", data: undefined, error });
+        throw error;
+      }
+    },
+    [engine, config.method], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const mutate = useCallback(
+    (
+      variables: WriteVariables<TParams, TPayload>,
+      callbacks?: {
+        onSuccess?: (data: TResult) => void;
+        onError?: (error: unknown) => void;
+      },
+    ) => {
+      mutateAsync(variables)
+        .then((data) => callbacks?.onSuccess?.(data))
+        .catch((error) => {
+          if (callbacks?.onError) {
+            callbacks.onError(error);
+          }
+        });
+    },
+    [mutateAsync],
+  );
+
+  return {
+    mutate,
+    mutateAsync,
+    isLoading: state.status === "loading",
+    isError: state.status === "error",
+    isSuccess: state.status === "success",
+    data: state.data,
+    error: state.error,
+    status: state.status,
+    reset,
+  };
+}

package/sync/index.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./registry";
+export * from "./store";
+export * from "./persistence";
+export * from "./transactions";
+export * from "./engine";
+export * from "./provider";
+export * from "./hooks";

package/sync/persistence.ts

@@ -0,0 +1,237 @@
+import { EntityKey, SyncTransaction } from "./types";
+
+/**
+ * Durable storage behind the sync engine: entity rows, the transaction
+ * queue, and cursor metadata. IndexedDB in the browser; an in-memory
+ * fallback everywhere else (SSR, tests, unsupported browsers) so the
+ * engine still runs — it just re-bootstraps on reload.
+ */
+export interface SyncPersistence {
+  getMeta(key: string): Promise<any | undefined>;
+  setMeta(key: string, value: any): Promise<void>;
+  getRecords(entity: EntityKey): Promise<Record<string, any>[]>;
+  putRecords(
+    entity: EntityKey,
+    rows: { id: string; data: Record<string, any> }[],
+  ): Promise<void>;
+  deleteRecord(entity: EntityKey, id: string): Promise<void>;
+  replaceRecords(
+    entity: EntityKey,
+    rows: { id: string; data: Record<string, any> }[],
+  ): Promise<void>;
+  getTransactions(): Promise<SyncTransaction[]>;
+  putTransaction(txn: SyncTransaction): Promise<void>;
+  deleteTransaction(txnId: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+const RECORDS = "records";
+const TRANSACTIONS = "transactions";
+const META = "meta";
+
+class IndexedDbPersistence implements SyncPersistence {
+  private db: Promise<IDBDatabase>;
+
+  constructor(databaseName: string) {
+    this.db = new Promise((resolve, reject) => {
+      const request = indexedDB.open(databaseName, 1);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(RECORDS)) {
+          const records = db.createObjectStore(RECORDS, {
+            keyPath: ["entity", "id"],
+          });
+          records.createIndex("entity", "entity", { unique: false });
+        }
+        if (!db.objectStoreNames.contains(TRANSACTIONS)) {
+          db.createObjectStore(TRANSACTIONS, { keyPath: "txnId" });
+        }
+        if (!db.objectStoreNames.contains(META)) {
+          db.createObjectStore(META, { keyPath: "key" });
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  private async transaction(
+    stores: string[],
+    mode: IDBTransactionMode,
+  ): Promise<IDBTransaction> {
+    const db = await this.db;
+    return db.transaction(stores, mode);
+  }
+
+  private request<T>(request: IDBRequest<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  private done(txn: IDBTransaction): Promise<void> {
+    return new Promise((resolve, reject) => {
+      txn.oncomplete = () => resolve();
+      txn.onerror = () => reject(txn.error);
+      txn.onabort = () => reject(txn.error);
+    });
+  }
+
+  async getMeta(key: string): Promise<any | undefined> {
+    const txn = await this.transaction([META], "readonly");
+    const row = await this.request(txn.objectStore(META).get(key));
+    return row ? (row as any).value : undefined;
+  }
+
+  async setMeta(key: string, value: any): Promise<void> {
+    const txn = await this.transaction([META], "readwrite");
+    txn.objectStore(META).put({ key, value });
+    await this.done(txn);
+  }
+
+  async getRecords(entity: EntityKey): Promise<Record<string, any>[]> {
+    const txn = await this.transaction([RECORDS], "readonly");
+    const index = txn.objectStore(RECORDS).index("entity");
+    const rows = await this.request(index.getAll(entity));
+    return (rows as any[]).map((row) => row.data);
+  }
+
+  async putRecords(
+    entity: EntityKey,
+    rows: { id: string; data: Record<string, any> }[],
+  ): Promise<void> {
+    const txn = await this.transaction([RECORDS], "readwrite");
+    const store = txn.objectStore(RECORDS);
+    rows.forEach(({ id, data }) => store.put({ entity, id, data }));
+    await this.done(txn);
+  }
+
+  async deleteRecord(entity: EntityKey, id: string): Promise<void> {
+    const txn = await this.transaction([RECORDS], "readwrite");
+    txn.objectStore(RECORDS).delete([entity, id]);
+    await this.done(txn);
+  }
+
+  async replaceRecords(
+    entity: EntityKey,
+    rows: { id: string; data: Record<string, any> }[],
+  ): Promise<void> {
+    const txn = await this.transaction([RECORDS], "readwrite");
+    const store = txn.objectStore(RECORDS);
+    const index = store.index("entity");
+    const keys = await this.request(index.getAllKeys(entity));
+    (keys as IDBValidKey[]).forEach((key) => store.delete(key));
+    rows.forEach(({ id, data }) => store.put({ entity, id, data }));
+    await this.done(txn);
+  }
+
+  async getTransactions(): Promise<SyncTransaction[]> {
+    const txn = await this.transaction([TRANSACTIONS], "readonly");
+    const rows = await this.request(txn.objectStore(TRANSACTIONS).getAll());
+    return (rows as SyncTransaction[]).sort(
+      (a, b) => a.createdAt - b.createdAt,
+    );
+  }
+
+  async putTransaction(transaction: SyncTransaction): Promise<void> {
+    const txn = await this.transaction([TRANSACTIONS], "readwrite");
+    txn.objectStore(TRANSACTIONS).put(transaction);
+    await this.done(txn);
+  }
+
+  async deleteTransaction(txnId: string): Promise<void> {
+    const txn = await this.transaction([TRANSACTIONS], "readwrite");
+    txn.objectStore(TRANSACTIONS).delete(txnId);
+    await this.done(txn);
+  }
+
+  async clear(): Promise<void> {
+    const txn = await this.transaction(
+      [RECORDS, TRANSACTIONS, META],
+      "readwrite",
+    );
+    txn.objectStore(RECORDS).clear();
+    txn.objectStore(TRANSACTIONS).clear();
+    txn.objectStore(META).clear();
+    await this.done(txn);
+  }
+}
+
+export class MemoryPersistence implements SyncPersistence {
+  private meta = new Map<string, any>();
+  private records = new Map<EntityKey, Map<string, Record<string, any>>>();
+  private transactions = new Map<string, SyncTransaction>();
+
+  private entityRecords(entity: EntityKey): Map<string, Record<string, any>> {
+    let rows = this.records.get(entity);
+    if (!rows) {
+      rows = new Map();
+      this.records.set(entity, rows);
+    }
+    return rows;
+  }
+
+  async getMeta(key: string): Promise<any | undefined> {
+    return this.meta.get(key);
+  }
+
+  async setMeta(key: string, value: any): Promise<void> {
+    this.meta.set(key, value);
+  }
+
+  async getRecords(entity: EntityKey): Promise<Record<string, any>[]> {
+    return Array.from(this.entityRecords(entity).values());
+  }
+
+  async putRecords(
+    entity: EntityKey,
+    rows: { id: string; data: Record<string, any> }[],
+  ): Promise<void> {
+    const store = this.entityRecords(entity);
+    rows.forEach(({ id, data }) => store.set(id, data));
+  }
+
+  async deleteRecord(entity: EntityKey, id: string): Promise<void> {
+    this.entityRecords(entity).delete(id);
+  }
+
+  async replaceRecords(
+    entity: EntityKey,
+    rows: { id: string; data: Record<string, any> }[],
+  ): Promise<void> {
+    const store = this.entityRecords(entity);
+    store.clear();
+    rows.forEach(({ id, data }) => store.set(id, data));
+  }
+
+  async getTransactions(): Promise<SyncTransaction[]> {
+    return Array.from(this.transactions.values()).sort(
+      (a, b) => a.createdAt - b.createdAt,
+    );
+  }
+
+  async putTransaction(txn: SyncTransaction): Promise<void> {
+    this.transactions.set(txn.txnId, txn);
+  }
+
+  async deleteTransaction(txnId: string): Promise<void> {
+    this.transactions.delete(txnId);
+  }
+
+  async clear(): Promise<void> {
+    this.meta.clear();
+    this.records.clear();
+    this.transactions.clear();
+  }
+}
+
+export function createPersistence(
+  persist: boolean,
+  databaseName: string,
+): SyncPersistence {
+  if (persist && typeof indexedDB !== "undefined") {
+    return new IndexedDbPersistence(databaseName);
+  }
+  return new MemoryPersistence();
+}