@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/offline/outbox.ts

@@ -1,348 +0,0 @@
-import { newId } from './id';
-import { OnlineController, isNetworkUnavailableError } from './online-controller';
-import { createDefaultOutboxStorage } from './storage';
-import {
-  OutboxEntryStatus,
-  type OutboxEntry,
-  type OutboxExecutor,
-  type OutboxSnapshot,
-  type OutboxStorage,
-} from './types';
-
-/** Read an HTTP status off an error (Orval/fetch shapes), or undefined. */
-function statusOf(err: unknown): number | undefined {
-  if (!err || typeof err !== 'object') {
-    return undefined;
-  }
-  const e = err as { status?: number; response?: { status?: number } };
-  if (typeof e.status === 'number') {
-    return e.status;
-  }
-  if (e.response && typeof e.response.status === 'number') {
-    return e.response.status;
-  }
-  return undefined;
-}
-
-/** Default retry policy: retry transport failures, timeouts, 429 and 5xx; a
- *  4xx client error is the caller's bug — dead-letter it, do not hammer. */
-function defaultIsRetriable(err: unknown): boolean {
-  if (isNetworkUnavailableError(err)) {
-    return true;
-  }
-  const status = statusOf(err);
-  if (status === undefined) {
-    return true; // unknown/opaque failure — give it a few tries
-  }
-  return status >= 500 || status === 429 || status === 408;
-}
-
-export interface OutboxOptions {
-  storage?: OutboxStorage;
-  online?: OnlineController;
-  /** Attempts before an entry is dead-lettered (Failed). Default 5. */
-  maxAttempts?: number;
-  /** Base backoff (ms) — doubled each attempt, capped at maxBackoffMs. */
-  baseBackoffMs?: number;
-  maxBackoffMs?: number;
-  isRetriable?: (err: unknown) => boolean;
-  /** Injectable clock (tests). Default Date.now. */
-  now?: () => number;
-  /** Injectable timer (tests). Default setTimeout. */
-  scheduler?: (fn: () => void, ms: number) => void;
-}
-
-export type OutboxListener = (snapshot: OutboxSnapshot) => void;
-
-export interface EnqueueOptions {
-  idempotencyKey?: string;
-  label?: string;
-}
-
-/**
- * A durable, provider-agnostic mutation outbox. Register an executor per `kind`
- * once; then `enqueue` mutations (they persist immediately). When online the
- * queue drains in FIFO order with retry/backoff and idempotency; when the send
- * fails as network-unavailable it stops and resumes on reconnect. A mutation
- * that exhausts retries is dead-lettered for manual retry/discard — never
- * silently dropped.
- */
-export class Outbox {
-  private readonly storage: OutboxStorage;
-  private readonly online: OnlineController;
-  private readonly maxAttempts: number;
-  private readonly baseBackoffMs: number;
-  private readonly maxBackoffMs: number;
-  private readonly isRetriable: (err: unknown) => boolean;
-  private readonly now: () => number;
-  private readonly scheduler: (fn: () => void, ms: number) => void;
-
-  private readonly executors = new Map<string, OutboxExecutor>();
-  private readonly listeners = new Set<OutboxListener>();
-  private cache: OutboxEntry[] = [];
-  private snapshot: OutboxSnapshot = {
-    entries: [],
-    pendingCount: 0,
-    failedCount: 0,
-    draining: false,
-    online: true,
-  };
-  private draining = false;
-  private drainRequested = false;
-  private retryScheduled = false;
-  private drainPromise: Promise<void> | null = null;
-  private unsubscribeOnline: (() => void) | null = null;
-
-  constructor(opts: OutboxOptions = {}) {
-    this.storage = opts.storage ?? createDefaultOutboxStorage();
-    this.online = opts.online ?? new OnlineController();
-    this.maxAttempts = opts.maxAttempts ?? 5;
-    this.baseBackoffMs = opts.baseBackoffMs ?? 1000;
-    this.maxBackoffMs = opts.maxBackoffMs ?? 60_000;
-    this.isRetriable = opts.isRetriable ?? defaultIsRetriable;
-    this.now = opts.now ?? (() => Date.now());
-    this.scheduler =
-      opts.scheduler ?? ((fn, ms) => void setTimeout(fn, ms));
-  }
-
-  /** Register the sender for a mutation `kind`. Registering re-triggers a drain
-   *  (entries that were parked waiting for their executor can now go). */
-  registerExecutor<TPayload>(kind: string, executor: OutboxExecutor<TPayload>): void {
-    this.executors.set(kind, executor as OutboxExecutor);
-    void this.drain();
-  }
-
-  hasExecutor(kind: string): boolean {
-    return this.executors.has(kind);
-  }
-
-  /** Begin: start connectivity listeners, hydrate from storage, drain. */
-  async start(): Promise<void> {
-    this.online.start();
-    this.unsubscribeOnline?.();
-    this.unsubscribeOnline = this.online.subscribe((online) => {
-      if (online) {
-        void this.drain();
-      } else {
-        this.notify();
-      }
-    });
-    await this.hydrate();
-    void this.drain();
-  }
-
-  stop(): void {
-    this.online.stop();
-    this.unsubscribeOnline?.();
-    this.unsubscribeOnline = null;
-  }
-
-  isOnline(): boolean {
-    return this.online.isOnline();
-  }
-
-  /** Persist a mutation for delivery. Resolves once it is durably queued. */
-  async enqueue<TPayload>(
-    kind: string,
-    payload: TPayload,
-    opts: EnqueueOptions = {},
-  ): Promise<OutboxEntry<TPayload>> {
-    const ts = this.now();
-    const entry: OutboxEntry<TPayload> = {
-      id: newId(),
-      kind,
-      payload,
-      idempotencyKey: opts.idempotencyKey ?? newId(),
-      status: OutboxEntryStatus.Pending,
-      attempts: 0,
-      createdAt: ts,
-      updatedAt: ts,
-      ...(opts.label !== undefined ? { label: opts.label } : {}),
-    };
-    await this.storage.put(entry);
-    await this.refresh();
-    void this.drain();
-    return entry;
-  }
-
-  /** Reset a dead-lettered entry to pending and drain. */
-  async retry(id: string): Promise<void> {
-    const entry = this.cache.find((e) => e.id === id);
-    if (!entry) {
-      return;
-    }
-    await this.storage.put({
-      ...entry,
-      status: OutboxEntryStatus.Pending,
-      attempts: 0,
-      updatedAt: this.now(),
-    });
-    await this.refresh();
-    void this.drain();
-  }
-
-  /** Permanently discard a queued/dead-lettered entry. */
-  async discard(id: string): Promise<void> {
-    await this.storage.delete(id);
-    await this.refresh();
-  }
-
-  async clear(): Promise<void> {
-    await this.storage.clear();
-    await this.refresh();
-  }
-
-  /** Returns a STABLE reference between changes (safe for useSyncExternalStore). */
-  getSnapshot(): OutboxSnapshot {
-    return this.snapshot;
-  }
-
-  subscribe(listener: OutboxListener): () => void {
-    this.listeners.add(listener);
-    listener(this.snapshot);
-    return () => this.listeners.delete(listener);
-  }
-
-  /** Attempt to deliver every deliverable entry once, in FIFO order. Safe to
-   *  call concurrently — a single flight runs and re-runs if requested. */
-  async drain(): Promise<void> {
-    if (!this.online.isOnline()) {
-      return;
-    }
-    // Single-flight: a concurrent drain() awaits the in-flight one (and requests
-    // an extra pass) rather than returning early — so `await drain()` always
-    // resolves after the queue is fully processed.
-    if (this.drainPromise) {
-      this.drainRequested = true;
-      return this.drainPromise;
-    }
-    this.drainPromise = this.runDrain();
-    try {
-      await this.drainPromise;
-    } finally {
-      this.drainPromise = null;
-    }
-  }
-
-  private async runDrain(): Promise<void> {
-    this.draining = true;
-    this.notify();
-    try {
-      do {
-        this.drainRequested = false;
-        await this.drainOnce();
-      } while (this.shouldContinueDrain());
-    } finally {
-      this.draining = false;
-      this.notify();
-    }
-  }
-
-  private shouldContinueDrain(): boolean {
-    return this.drainRequested && this.online.isOnline();
-  }
-
-  // ── internals ──────────────────────────────────────────────────────────────
-
-  private async hydrate(): Promise<void> {
-    const stored = await this.storage.getAll();
-    // Recover entries that were mid-flight when the tab/process died: they may
-    // or may not have applied server-side, but the idempotency key makes a
-    // redelivery safe, so re-queue them rather than drop them.
-    for (const entry of stored) {
-      if (entry.status === OutboxEntryStatus.Inflight) {
-        entry.status = OutboxEntryStatus.Pending;
-        await this.storage.put(entry);
-      }
-    }
-    await this.refresh();
-  }
-
-  private async drainOnce(): Promise<void> {
-    const entries = await this.storage.getAll();
-    for (const entry of entries) {
-      if (!this.online.isOnline()) {
-        break;
-      }
-      if (entry.status === OutboxEntryStatus.Failed) {
-        continue; // dead-letter — needs manual retry
-      }
-      const executor = this.executors.get(entry.kind);
-      if (!executor) {
-        continue; // no sender registered yet — leave pending
-      }
-
-      const attempt = entry.attempts + 1;
-      await this.write({ ...entry, status: OutboxEntryStatus.Inflight, attempts: attempt });
-
-      try {
-        await executor(entry.payload, {
-          idempotencyKey: entry.idempotencyKey,
-          attempt,
-          entryId: entry.id,
-        });
-        await this.storage.delete(entry.id);
-        await this.refresh();
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (isNetworkUnavailableError(err)) {
-          // Network is down. This is NOT the payload's fault, so do NOT advance
-          // the attempt counter (being offline for a long time must never
-          // dead-letter a capture). Park the entry, stop the burst, and resume
-          // on reconnect or after a backoff.
-          await this.write({ ...entry, status: OutboxEntryStatus.Pending, attempts: entry.attempts, lastError: message });
-          this.scheduleRetry(entry.attempts + 1);
-          break;
-        }
-        if (this.isRetriable(err) && attempt < this.maxAttempts) {
-          await this.write({ ...entry, status: OutboxEntryStatus.Retrying, attempts: attempt, lastError: message });
-          this.scheduleRetry(attempt);
-        } else {
-          // 4xx client error, or retries exhausted → dead-letter for manual
-          // retry/discard. Never silently dropped.
-          await this.write({ ...entry, status: OutboxEntryStatus.Failed, attempts: attempt, lastError: message });
-        }
-      }
-    }
-  }
-
-  private scheduleRetry(attempt: number): void {
-    if (this.retryScheduled) {
-      return;
-    }
-    this.retryScheduled = true;
-    const delay = Math.min(
-      this.maxBackoffMs,
-      this.baseBackoffMs * 2 ** Math.max(0, attempt - 1),
-    );
-    this.scheduler(() => {
-      this.retryScheduled = false;
-      void this.drain();
-    }, delay);
-  }
-
-  private async write(entry: OutboxEntry): Promise<void> {
-    await this.storage.put({ ...entry, updatedAt: this.now() });
-    await this.refresh();
-  }
-
-  private async refresh(): Promise<void> {
-    this.cache = await this.storage.getAll();
-    this.notify();
-  }
-
-  private notify(): void {
-    // Rebuild the cached snapshot ONCE per change so getSnapshot() returns a
-    // stable reference (required by React's useSyncExternalStore).
-    this.snapshot = {
-      entries: this.cache,
-      pendingCount: this.cache.filter((e) => e.status !== OutboxEntryStatus.Failed).length,
-      failedCount: this.cache.filter((e) => e.status === OutboxEntryStatus.Failed).length,
-      draining: this.draining,
-      online: this.online.isOnline(),
-    };
-    for (const l of this.listeners) {
-      l(this.snapshot);
-    }
-  }
-}

package/src/offline/react-hooks.ts

@@ -1,40 +0,0 @@
-import { createContext, useContext, useSyncExternalStore } from 'react';
-
-import { type Outbox } from './outbox';
-
-import type { OutboxSnapshot } from './types';
-
-export const OutboxContext = createContext<Outbox | null>(null);
-
-export function useOutbox(): Outbox {
-  const ctx = useContext(OutboxContext);
-  if (!ctx) {
-    throw new Error('useOutbox must be used within an <OutboxProvider>.');
-  }
-  return ctx;
-}
-
-function resolveOutbox(
-  explicit: Outbox | undefined,
-  ctx: Outbox | null,
-): Outbox {
-  const instance = explicit ?? ctx;
-  if (!instance) {
-    throw new Error('An <OutboxProvider> or an explicit outbox is required.');
-  }
-  return instance;
-}
-
-export function useOutboxSnapshot(outbox?: Outbox): OutboxSnapshot {
-  const ctx = useContext(OutboxContext);
-  const instance = resolveOutbox(outbox, ctx);
-  return useSyncExternalStore(
-    (cb) => instance.subscribe(cb),
-    () => instance.getSnapshot(),
-    () => instance.getSnapshot(),
-  );
-}
-
-export function useOnlineStatus(outbox?: Outbox): boolean {
-  return useOutboxSnapshot(outbox).online;
-}

package/src/offline/react.tsx

@@ -1,32 +0,0 @@
-import {
-  useEffect,
-  useMemo,
-  useRef,
-  type ReactNode,
-} from 'react';
-
-import { Outbox, type OutboxOptions } from './outbox';
-import { OutboxContext } from './react-hooks';
-
-export interface OutboxProviderProps {
-  /** Bring your own Outbox, or let the provider create one from `options`. */
-  outbox?: Outbox;
-  options?: OutboxOptions;
-  children: ReactNode;
-}
-
-/** Provides a shared {@link Outbox} and manages its lifecycle (starts
- *  connectivity listeners + hydrates on mount, stops on unmount). */
-export function OutboxProvider({ outbox, options, children }: OutboxProviderProps): JSX.Element {
-  // Options are captured once; changing them after mount does not recreate the
-  // outbox (a durable queue must not be swapped underneath in-flight work).
-  const optionsRef = useRef(options);
-  const instance = useMemo(() => outbox ?? new Outbox(optionsRef.current), [outbox]);
-
-  useEffect(() => {
-    void instance.start();
-    return () => instance.stop();
-  }, [instance]);
-
-  return <OutboxContext.Provider value={instance}>{children}</OutboxContext.Provider>;
-}

package/src/offline/storage.ts

@@ -1,112 +0,0 @@
-import type { OutboxEntry, OutboxStorage } from './types';
-
-/** In-memory outbox storage — the SSR / test fallback (no persistence). */
-export class InMemoryOutboxStorage implements OutboxStorage {
-  private readonly map = new Map<string, OutboxEntry>();
-
-  getAll(): Promise<OutboxEntry[]> {
-    return Promise.resolve(
-      [...this.map.values()].sort((a, b) => a.createdAt - b.createdAt),
-    );
-  }
-
-  put(entry: OutboxEntry): Promise<void> {
-    this.map.set(entry.id, { ...entry });
-    return Promise.resolve();
-  }
-
-  delete(id: string): Promise<void> {
-    this.map.delete(id);
-    return Promise.resolve();
-  }
-
-  clear(): Promise<void> {
-    this.map.clear();
-    return Promise.resolve();
-  }
-}
-
-const DB_VERSION = 1;
-
-/** IndexedDB-backed outbox storage — durable across reloads and app restarts,
- *  so a mutation captured offline survives the tab being closed. */
-export class IndexedDbOutboxStorage implements OutboxStorage {
-  private dbPromise: Promise<IDBDatabase> | null = null;
-
-  constructor(
-    private readonly dbName = 'xema-offline-outbox',
-    private readonly storeName = 'entries',
-  ) {}
-
-  private open(): Promise<IDBDatabase> {
-    if (this.dbPromise) {
-      return this.dbPromise;
-    }
-    this.dbPromise = new Promise<IDBDatabase>((resolve, reject) => {
-      const req = indexedDB.open(this.dbName, DB_VERSION);
-      req.onupgradeneeded = () => {
-        const db = req.result;
-        if (!db.objectStoreNames.contains(this.storeName)) {
-          db.createObjectStore(this.storeName, { keyPath: 'id' });
-        }
-      };
-      req.onsuccess = () => resolve(req.result);
-      req.onerror = () => reject(req.error ?? new Error('indexedDB open failed'));
-    });
-    return this.dbPromise;
-  }
-
-  private async tx<T>(
-    mode: IDBTransactionMode,
-    run: (store: IDBObjectStore) => IDBRequest<T> | void,
-  ): Promise<T | undefined> {
-    const db = await this.open();
-    return new Promise<T | undefined>((resolve, reject) => {
-      const transaction = db.transaction(this.storeName, mode);
-      const store = transaction.objectStore(this.storeName);
-      let request: IDBRequest<T> | void;
-      try {
-        request = run(store);
-      } catch (err) {
-        reject(err);
-        return;
-      }
-      transaction.onabort = () =>
-        reject(transaction.error ?? new Error('indexedDB tx aborted'));
-      transaction.oncomplete = () =>
-        resolve(request ? request.result : undefined);
-      transaction.onerror = () =>
-        reject(transaction.error ?? new Error('indexedDB tx error'));
-    });
-  }
-
-  async getAll(): Promise<OutboxEntry[]> {
-    const all = (await this.tx<OutboxEntry[]>('readonly', (s) => s.getAll())) ?? [];
-    return all.sort((a, b) => a.createdAt - b.createdAt);
-  }
-
-  async put(entry: OutboxEntry): Promise<void> {
-    await this.tx('readwrite', (s) => s.put(entry));
-  }
-
-  async delete(id: string): Promise<void> {
-    await this.tx('readwrite', (s) => s.delete(id));
-  }
-
-  async clear(): Promise<void> {
-    await this.tx('readwrite', (s) => s.clear());
-  }
-}
-
-/** Pick the best available storage: IndexedDB in a browser, else in-memory
- *  (SSR / tests / private-mode fallbacks). */
-export function createDefaultOutboxStorage(): OutboxStorage {
-  if (typeof indexedDB !== 'undefined') {
-    try {
-      return new IndexedDbOutboxStorage();
-    } catch {
-      // Some privacy modes throw on open — fall back to in-memory.
-    }
-  }
-  return new InMemoryOutboxStorage();
-}

package/src/offline/types.ts

@@ -1,77 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// @xemahq/ui-kernel/offline — types
-//
-// A generic offline field-capture kit: an IndexedDB-backed outbox that queues
-// mutations while disconnected and drains them (with retry + idempotency) on
-// reconnect. Provider-agnostic — any mutation (an app-forge record submit, a
-// status change, …) is enqueued by a stable `kind` whose executor is registered
-// once. The motivating case is field/trade-fair capture with no signal.
-// ═══════════════════════════════════════════════════════════════════════════
-
-/** Lifecycle of a queued mutation. */
-export enum OutboxEntryStatus {
-  /** Waiting to be sent (offline, or not yet attempted). */
-  Pending = 'pending',
-  /** Currently being sent. */
-  Inflight = 'inflight',
-  /** Failed transiently; will be retried (attempts < maxAttempts). */
-  Retrying = 'retrying',
-  /** Exhausted retries — needs manual retry or discard (dead-letter). */
-  Failed = 'failed',
-}
-
-/** One queued mutation. `payload` is opaque to the outbox; the executor for
- *  `kind` interprets it. */
-export interface OutboxEntry<TPayload = unknown> {
-  /** Stable entry id (also the default idempotency key). */
-  id: string;
-  /** Registered executor key (e.g. "app-forge:create-record"). */
-  kind: string;
-  payload: TPayload;
-  /** Sent to the backend so a redelivered mutation is not double-applied. */
-  idempotencyKey: string;
-  status: OutboxEntryStatus;
-  attempts: number;
-  createdAt: number;
-  updatedAt: number;
-  /** Last error message (for the dead-letter UI). */
-  lastError?: string;
-  /** Optional human label for the pending-items UI. */
-  label?: string;
-}
-
-/** Persistence backend for the outbox. IndexedDB in the browser; in-memory for
- *  SSR / tests. */
-export interface OutboxStorage {
-  getAll(): Promise<OutboxEntry[]>;
-  put(entry: OutboxEntry): Promise<void>;
-  delete(id: string): Promise<void>;
-  clear(): Promise<void>;
-}
-
-/** Context passed to an executor when a queued mutation is sent. */
-export interface OutboxExecuteContext {
-  /** Pass to the backend (e.g. as an `Idempotency-Key` header). */
-  idempotencyKey: string;
-  /** How many times this entry has now been attempted (1-based). */
-  attempt: number;
-  entryId: string;
-}
-
-/** Sends one queued mutation. Throwing schedules a retry (see
- *  {@link OutboxOptions.isRetriable}). */
-export type OutboxExecutor<TPayload = unknown> = (
-  payload: TPayload,
-  ctx: OutboxExecuteContext,
-) => Promise<void>;
-
-/** Snapshot of outbox state for UI (offline badge, pending count, dead-letter). */
-export interface OutboxSnapshot {
-  entries: OutboxEntry[];
-  pendingCount: number;
-  failedCount: number;
-  /** True while a drain is in progress. */
-  draining: boolean;
-  /** Current connectivity (from the outbox's online controller). */
-  online: boolean;
-}