rastack 0.0.16

package/sync/provider.tsx

@@ -0,0 +1,91 @@
+import React, {
+  createContext,
+  ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+} from "react";
+import { AxiosInstance } from "axios";
+import { API } from "../hooks/query/api";
+import { SyncEngine } from "./engine";
+import { SyncEngineConfig } from "./types";
+
+interface RadSyncContextValue {
+  engine: SyncEngine;
+}
+
+const RadSyncContext = createContext<RadSyncContextValue | null>(null);
+
+export interface RadSyncProviderProps extends SyncEngineConfig {
+  children: ReactNode;
+  /** Axios instance to sync through. Defaults to the shared rastack API client. */
+  api?: AxiosInstance;
+  /** When provided, a Bearer token is attached to every request on the instance. */
+  getToken?: () => string | Promise<string>;
+  /** Start the engine on mount (default true). */
+  autoStart?: boolean;
+}
+
+/**
+ * Mounts the sync engine for the app. This is the only client-side
+ * configuration a consumer does — every generated hook finds the engine
+ * through this context.
+ */
+export function RadSyncProvider({
+  children,
+  api,
+  getToken,
+  autoStart = true,
+  ...config
+}: RadSyncProviderProps) {
+  const instance = api || API;
+  const engine = useMemo(
+    () => new SyncEngine(instance, config),
+    // The engine is created once for the provider's lifetime.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [instance],
+  );
+
+  useEffect(() => {
+    let interceptor: number | undefined;
+    if (getToken) {
+      interceptor = instance.interceptors.request.use(async (request) => {
+        const token = await getToken();
+        request.headers = request.headers || ({} as any);
+        (request.headers as any).Authorization = `Bearer ${token}`;
+        return request;
+      });
+    }
+    if (autoStart) {
+      void engine.start().catch(() => {
+        // Reported through config.onError and engine status.
+      });
+    }
+    return () => {
+      engine.stop();
+      if (interceptor !== undefined) {
+        instance.interceptors.request.eject(interceptor);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [engine]);
+
+  const value = useMemo(() => ({ engine }), [engine]);
+  return (
+    <RadSyncContext.Provider value={value}>{children}</RadSyncContext.Provider>
+  );
+}
+
+export function useSyncEngine(): SyncEngine {
+  const context = useContext(RadSyncContext);
+  if (!context) {
+    throw new Error(
+      "No RadSyncProvider found. Wrap your app in <RadSyncProvider> to use sync-mode entity hooks.",
+    );
+  }
+  return context.engine;
+}
+
+export function useSyncEngineOptional(): SyncEngine | null {
+  return useContext(RadSyncContext)?.engine ?? null;
+}

package/sync/registry.ts

@@ -0,0 +1,36 @@
+import { EntityDescriptor, EntityKey, entityKey } from "./types";
+
+const entities = new Map<EntityKey, EntityDescriptor>();
+
+/**
+ * Registers a sync-mode entity. Called from generated entity modules at
+ * import time, so every entity a bundle uses is known before the engine
+ * starts. Idempotent per (app, model).
+ */
+export function defineEntity<TRow = any>(
+  descriptor: Omit<EntityDescriptor<TRow>, "__row">,
+): EntityDescriptor<TRow> {
+  const key = entityKey(descriptor as EntityDescriptor);
+  const existing = entities.get(key);
+  if (existing) {
+    return existing as EntityDescriptor<TRow>;
+  }
+  const entity: EntityDescriptor<TRow> = {
+    idField: "id",
+    ...descriptor,
+  };
+  entities.set(key, entity as EntityDescriptor);
+  return entity;
+}
+
+export function getRegisteredEntities(): EntityDescriptor[] {
+  return Array.from(entities.values());
+}
+
+export function getEntity(key: EntityKey): EntityDescriptor | undefined {
+  return entities.get(key);
+}
+
+export function clearEntityRegistry(): void {
+  entities.clear();
+}

package/sync/store.ts

@@ -0,0 +1,126 @@
+import { EntityKey } from "./types";
+
+type Listener = () => void;
+
+interface EntityCache {
+  rows: Map<string, Record<string, any>>;
+  /** Stable array reference for useSyncExternalStore; rebuilt on change. */
+  listSnapshot: Record<string, any>[] | null;
+  ready: boolean;
+  listeners: Set<Listener>;
+}
+
+/**
+ * The in-memory object pool. One cache per entity, keyed `${app}.${model}`.
+ * The store is only the live working set: durable state lives in the
+ * persistence layer and is only written from server deltas, so local disk
+ * always remains a subset of server state (Linear's invariant).
+ */
+export class SyncStore {
+  private caches = new Map<EntityKey, EntityCache>();
+
+  private cache(entity: EntityKey): EntityCache {
+    let cache = this.caches.get(entity);
+    if (!cache) {
+      cache = {
+        rows: new Map(),
+        listSnapshot: null,
+        ready: false,
+        listeners: new Set(),
+      };
+      this.caches.set(entity, cache);
+    }
+    return cache;
+  }
+
+  get(entity: EntityKey, id: string): Record<string, any> | undefined {
+    return this.cache(entity).rows.get(id);
+  }
+
+  getList(entity: EntityKey): Record<string, any>[] {
+    const cache = this.cache(entity);
+    if (!cache.listSnapshot) {
+      cache.listSnapshot = Array.from(cache.rows.values());
+    }
+    return cache.listSnapshot;
+  }
+
+  isReady(entity: EntityKey): boolean {
+    return this.cache(entity).ready;
+  }
+
+  markReady(entity: EntityKey): void {
+    const cache = this.cache(entity);
+    if (!cache.ready) {
+      cache.ready = true;
+      this.emit(cache);
+    }
+  }
+
+  upsert(entity: EntityKey, id: string, row: Record<string, any>): void {
+    const cache = this.cache(entity);
+    cache.rows.set(id, row);
+    this.emit(cache);
+  }
+
+  merge(
+    entity: EntityKey,
+    id: string,
+    changes: Record<string, any>,
+  ): Record<string, any> {
+    const cache = this.cache(entity);
+    const next = { ...(cache.rows.get(id) || {}), ...changes };
+    cache.rows.set(id, next);
+    this.emit(cache);
+    return next;
+  }
+
+  remove(entity: EntityKey, id: string): void {
+    const cache = this.cache(entity);
+    if (cache.rows.delete(id)) {
+      this.emit(cache);
+    }
+  }
+
+  replaceId(entity: EntityKey, fromId: string, toId: string): void {
+    const cache = this.cache(entity);
+    const row = cache.rows.get(fromId);
+    if (row !== undefined) {
+      cache.rows.delete(fromId);
+      cache.rows.set(toId, row);
+      this.emit(cache);
+    }
+  }
+
+  hydrate(entity: EntityKey, rows: Record<string, any>[], idField: string): void {
+    const cache = this.cache(entity);
+    rows.forEach((row) => {
+      const id = String(row[idField]);
+      cache.rows.set(id, row);
+    });
+    cache.ready = true;
+    this.emit(cache);
+  }
+
+  subscribe(entity: EntityKey, listener: Listener): () => void {
+    const cache = this.cache(entity);
+    cache.listeners.add(listener);
+    return () => {
+      cache.listeners.delete(listener);
+    };
+  }
+
+  clear(): void {
+    this.caches.forEach((cache) => {
+      cache.rows.clear();
+      cache.listSnapshot = null;
+      cache.ready = false;
+      cache.listeners.forEach((listener) => listener());
+    });
+  }
+
+  private emit(cache: EntityCache): void {
+    cache.listSnapshot = null;
+    cache.listeners.forEach((listener) => listener());
+  }
+}

package/sync/transactions.ts

@@ -0,0 +1,300 @@
+import { AxiosInstance } from "axios";
+import { SyncPersistence } from "./persistence";
+import { SyncStore } from "./store";
+import {
+  EntityDescriptor,
+  EntityKey,
+  SyncTransaction,
+  TransactionOp,
+} from "./types";
+
+export function randomId(): string {
+  const cryptoObject =
+    typeof crypto !== "undefined" ? (crypto as Crypto) : undefined;
+  if (cryptoObject && typeof cryptoObject.randomUUID === "function") {
+    return cryptoObject.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** RFC 4122 v4 UUID — always a server-acceptable UUID (unlike randomId's fallback). */
+export function uuid4(): string {
+  const cryptoObject =
+    typeof crypto !== "undefined" ? (crypto as Crypto) : undefined;
+  if (cryptoObject && typeof cryptoObject.randomUUID === "function") {
+    return cryptoObject.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (cryptoObject && typeof cryptoObject.getRandomValues === "function") {
+    cryptoObject.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < 16; i += 1) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0"));
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex
+    .slice(6, 8)
+    .join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
+
+export function tempId(): string {
+  return `tmp_${randomId()}`;
+}
+
+export function isTempId(id: string): boolean {
+  return id.startsWith("tmp_");
+}
+
+interface TransactionQueueDeps {
+  api: AxiosInstance;
+  persistence: SyncPersistence;
+  store: SyncStore;
+  getEntity: (key: EntityKey) => EntityDescriptor | undefined;
+  onError?: (error: unknown, txn: SyncTransaction) => void;
+}
+
+interface EnqueueInput {
+  entity: EntityKey;
+  op: TransactionOp;
+  id: string;
+  method: SyncTransaction["method"];
+  url: string;
+  payload: Record<string, any> | null;
+  original: Record<string, any> | null;
+}
+
+/**
+ * The optimistic write path. Changes apply to the in-memory store
+ * immediately, persist to the local transaction log (so offline writes
+ * survive reload), then replay through the normal generated REST endpoints
+ * in order. Server rejection (4xx) rolls the optimistic change back;
+ * network failure retries with backoff and resumes on reconnect.
+ */
+export class TransactionQueue {
+  private pending: SyncTransaction[] = [];
+  private idAliases = new Map<string, string>();
+  private settlers = new Map<
+    string,
+    { resolve: (data: any) => void; reject: (error: unknown) => void }
+  >();
+  private flushing = false;
+  private retryTimer: ReturnType<typeof setTimeout> | null = null;
+  private retryDelay = 1000;
+
+  constructor(private deps: TransactionQueueDeps) {}
+
+  /** Load persisted transactions after a reload and re-apply their optimistic effect. */
+  async resume(): Promise<void> {
+    const persisted = await this.deps.persistence.getTransactions();
+    for (const txn of persisted) {
+      if (txn.status === "completed") {
+        // Server already confirmed it before the reload; catch-up sync will
+        // deliver the authoritative row, so the log entry is done.
+        await this.deps.persistence.deleteTransaction(txn.txnId);
+        continue;
+      }
+      txn.status = "queued";
+      this.pending.push(txn);
+      this.applyOptimistic(txn);
+    }
+    void this.flush();
+  }
+
+  async enqueue(input: EnqueueInput): Promise<any> {
+    const txn: SyncTransaction = {
+      txnId: randomId(),
+      status: "queued",
+      createdAt: Date.now(),
+      ...input,
+    };
+    this.applyOptimistic(txn);
+    this.pending.push(txn);
+    await this.deps.persistence.putTransaction(txn);
+    const settled = new Promise<any>((resolve, reject) => {
+      this.settlers.set(txn.txnId, { resolve, reject });
+    });
+    void this.flush();
+    return settled;
+  }
+
+  /** Pending (not yet server-confirmed) transactions touching a row — used for rebase. */
+  pendingFor(entity: EntityKey, id: string): SyncTransaction[] {
+    return this.pending.filter(
+      (txn) =>
+        txn.entity === entity &&
+        (txn.id === id || this.idAliases.get(txn.id) === id) &&
+        txn.status !== "completed",
+    );
+  }
+
+  /** A server delta touched this row: confirmed transactions for it are fully synced. */
+  async resolveForRow(entity: EntityKey, id: string): Promise<void> {
+    const done = this.pending.filter(
+      (txn) =>
+        txn.entity === entity &&
+        (txn.id === id || this.idAliases.get(txn.id) === id) &&
+        txn.status === "completed",
+    );
+    for (const txn of done) {
+      this.pending = this.pending.filter((item) => item !== txn);
+      await this.deps.persistence.deleteTransaction(txn.txnId);
+    }
+  }
+
+  hasPending(): boolean {
+    return this.pending.some((txn) => txn.status !== "completed");
+  }
+
+  resolveAlias(id: string): string {
+    return this.idAliases.get(id) || id;
+  }
+
+  wake(): void {
+    this.retryDelay = 1000;
+    void this.flush();
+  }
+
+  private applyOptimistic(txn: SyncTransaction): void {
+    const { store, getEntity } = this.deps;
+    const entity = getEntity(txn.entity);
+    const idField = entity?.idField || "id";
+    if (txn.op === "create") {
+      store.upsert(txn.entity, txn.id, {
+        [idField]: txn.id,
+        ...(txn.payload || {}),
+      });
+    } else if (txn.op === "update") {
+      store.merge(txn.entity, txn.id, txn.payload || {});
+    } else if (txn.op === "delete") {
+      store.remove(txn.entity, txn.id);
+    }
+  }
+
+  private rollback(txn: SyncTransaction): void {
+    const { store } = this.deps;
+    if (txn.op === "create") {
+      store.remove(txn.entity, txn.id);
+    } else if (txn.op === "update" && txn.original) {
+      store.merge(txn.entity, txn.id, txn.original);
+    } else if (txn.op === "delete" && txn.original) {
+      store.upsert(txn.entity, txn.id, txn.original);
+    }
+  }
+
+  private rewriteTempIds(txn: SyncTransaction): void {
+    const realId = this.idAliases.get(txn.id);
+    if (!realId) {
+      return;
+    }
+    txn.url = txn.url.split(txn.id).join(realId);
+    if (txn.payload) {
+      Object.keys(txn.payload).forEach((key) => {
+        if (txn.payload![key] === txn.id) {
+          txn.payload![key] = realId;
+        }
+      });
+    }
+    txn.id = realId;
+  }
+
+  private async flush(): Promise<void> {
+    if (this.flushing) {
+      return;
+    }
+    this.flushing = true;
+    try {
+      for (;;) {
+        const txn = this.pending.find((item) => item.status === "queued");
+        if (!txn) {
+          break;
+        }
+        if (typeof navigator !== "undefined" && navigator.onLine === false) {
+          break;
+        }
+        this.rewriteTempIds(txn);
+        txn.status = "inflight";
+        await this.deps.persistence.putTransaction(txn);
+        try {
+          const response = await this.send(txn);
+          await this.confirm(txn, response);
+          this.retryDelay = 1000;
+        } catch (error: any) {
+          const status = error?.response?.status;
+          const isRejection =
+            typeof status === "number" &&
+            status >= 400 &&
+            status < 500 &&
+            status !== 408 &&
+            status !== 429;
+          if (isRejection) {
+            // The server refused the write (validation, permissions):
+            // roll the optimistic change back and surface the error.
+            this.rollback(txn);
+            this.pending = this.pending.filter((item) => item !== txn);
+            await this.deps.persistence.deleteTransaction(txn.txnId);
+            this.settlers.get(txn.txnId)?.reject(error);
+            this.settlers.delete(txn.txnId);
+            this.deps.onError?.(error, txn);
+          } else {
+            // Network failure or server trouble: keep the optimistic state,
+            // stay queued, retry with backoff.
+            txn.status = "queued";
+            await this.deps.persistence.putTransaction(txn);
+            this.scheduleRetry();
+            break;
+          }
+        }
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  private async send(txn: SyncTransaction): Promise<any> {
+    const { api } = this.deps;
+    switch (txn.method) {
+      case "post":
+        return (await api.post(txn.url, txn.payload)).data;
+      case "put":
+        return (await api.put(txn.url, txn.payload)).data;
+      case "patch":
+        return (await api.patch(txn.url, txn.payload)).data;
+      case "delete":
+        return (await api.delete(txn.url)).data;
+      default:
+        throw new Error(`Unsupported method: ${txn.method}`);
+    }
+  }
+
+  private async confirm(txn: SyncTransaction, response: any): Promise<void> {
+    const entity = this.deps.getEntity(txn.entity);
+    const idField = entity?.idField || "id";
+    if (txn.op === "create" && response && response[idField] !== undefined) {
+      const realId = String(response[idField]);
+      if (isTempId(txn.id) && realId !== txn.id) {
+        this.idAliases.set(txn.id, realId);
+        this.deps.store.replaceId(txn.entity, txn.id, realId);
+        this.deps.store.merge(txn.entity, realId, response);
+        txn.id = realId;
+      }
+    }
+    txn.status = "completed";
+    await this.deps.persistence.putTransaction(txn);
+    this.settlers.get(txn.txnId)?.resolve(response);
+    this.settlers.delete(txn.txnId);
+  }
+
+  private scheduleRetry(): void {
+    if (this.retryTimer) {
+      return;
+    }
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      void this.flush();
+    }, this.retryDelay);
+    this.retryDelay = Math.min(this.retryDelay * 2, 30000);
+  }
+}

package/sync/types.ts

@@ -0,0 +1,94 @@
+export type EntityKey = string; // `${app}.${model}`
+
+export interface EntityDescriptor<TRow = any> {
+  app: string;
+  model: string;
+  /** Collection endpoint, e.g. /api/shop/v1/pets */
+  listUrl: string;
+  /** Detail endpoint builder, e.g. (id) => `/api/shop/v1/pets/${id}` */
+  detailUrl?: (id: string) => string;
+  /** Primary key field on the row. Defaults to "id". */
+  idField?: string;
+  /**
+   * Lazy entities (Sync.load = "lazy") are excluded from the initial
+   * bootstrap and partial-bootstrapped on first use instead.
+   */
+  lazy?: boolean;
+  /**
+   * Sync.client_ids = True: the row's primary key is a client-generated
+   * UUID, so creates carry their real id from the start (no temp-id
+   * reconciliation) and offline-created rows can be referenced immediately.
+   */
+  clientIds?: boolean;
+  /** Phantom field so TRow is used; never set at runtime. */
+  __row?: TRow;
+}
+
+export function entityKey(entity: EntityDescriptor): EntityKey {
+  return `${entity.app}.${entity.model}`;
+}
+
+export type SyncOp = "I" | "U" | "D";
+
+export interface SyncActionPacket {
+  op: SyncOp;
+  model: EntityKey;
+  id: string;
+  data: Record<string, any> | null;
+  sync_id: number;
+}
+
+export interface ChangesResponse {
+  actions: SyncActionPacket[];
+  last_sync_id: number;
+  /** Hash of the sync-relevant server schema; a change forces a re-bootstrap. */
+  schema_hash?: string;
+}
+
+export interface BootstrapResponse {
+  models: { [key: EntityKey]: Record<string, any>[] };
+  last_sync_id: number;
+  schema_hash?: string;
+}
+
+export type TransactionOp = "create" | "update" | "delete";
+
+export type TransactionStatus = "queued" | "inflight" | "completed";
+
+export interface SyncTransaction {
+  txnId: string;
+  entity: EntityKey;
+  op: TransactionOp;
+  /** Row id. Creates use a temporary `tmp_*` id until the server echoes the real one. */
+  id: string;
+  method: "post" | "put" | "patch" | "delete";
+  url: string;
+  payload: Record<string, any> | null;
+  /**
+   * Rollback snapshot: for updates, the previous values of the changed
+   * fields; for deletes, the full previous row; null for creates.
+   */
+  original: Record<string, any> | null;
+  status: TransactionStatus;
+  createdAt: number;
+}
+
+export type EngineStatus =
+  | "idle"
+  | "hydrating"
+  | "bootstrapping"
+  | "live"
+  | "offline"
+  | "error";
+
+export interface SyncEngineConfig {
+  /** Base path of the sync endpoints. */
+  syncBasePath?: string; // default /api/sync/v1
+  /** Long-poll hold time requested from /changes, seconds. */
+  wait?: number; // default 25
+  /** Persist to IndexedDB (default true; falls back to memory when unavailable). */
+  persist?: boolean;
+  /** Database name for IndexedDB. */
+  databaseName?: string; // default "rad-sync"
+  onError?: (error: unknown) => void;
+}