@xemahq/ui-kernel 0.11.0 → 0.11.2

package/src/offline/outbox.test.ts

@@ -1,172 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { OnlineController } from './online-controller';
-import { Outbox, type OutboxOptions } from './outbox';
-import { InMemoryOutboxStorage } from './storage';
-import { OutboxEntryStatus, type OutboxExecuteContext } from './types';
-
-const KIND = 'test:mutation';
-
-function makeOutbox(overrides: Partial<OutboxOptions> = {}): {
-  outbox: Outbox;
-  online: OnlineController;
-} {
-  const online = new OnlineController(); // node: navigator undefined ⇒ online
-  const outbox = new Outbox({
-    storage: new InMemoryOutboxStorage(),
-    online,
-    // Immediate scheduler: retries are driven synchronously within `drain()`.
-    scheduler: (fn) => fn(),
-    ...overrides,
-  });
-  return { outbox, online };
-}
-
-describe('Outbox', () => {
-  it('queues while offline and delivers on reconnect', async () => {
-    const { outbox, online } = makeOutbox();
-    const send = vi.fn(() => Promise.resolve());
-    outbox.registerExecutor(KIND, send);
-
-    online.reportOffline();
-    await outbox.enqueue(KIND, { a: 1 });
-    expect(send).not.toHaveBeenCalled();
-    expect(outbox.getSnapshot().pendingCount).toBe(1);
-
-    online.reportOnline();
-    await outbox.drain();
-    expect(send).toHaveBeenCalledTimes(1);
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('delivers immediately when online and removes the entry; idempotency key is stable', async () => {
-    const { outbox } = makeOutbox();
-    const keys: string[] = [];
-    outbox.registerExecutor(KIND, (_p, ctx: OutboxExecuteContext) => {
-      keys.push(ctx.idempotencyKey);
-      return Promise.resolve();
-    });
-    await outbox.enqueue(KIND, { a: 1 });
-    await outbox.drain();
-    expect(keys).toHaveLength(1);
-    expect(keys[0]).toMatch(/[0-9a-f-]{36}/);
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('retries a 5xx and eventually succeeds', async () => {
-    const { outbox } = makeOutbox();
-    let calls = 0;
-    outbox.registerExecutor(KIND, () => {
-      calls += 1;
-      if (calls < 3) {
-        return Promise.reject({ status: 503, message: 'unavailable' });
-      }
-      return Promise.resolve();
-    });
-    await outbox.enqueue(KIND, { a: 1 });
-    await outbox.drain();
-    expect(calls).toBe(3);
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('dead-letters a 4xx immediately (no pointless retries)', async () => {
-    const { outbox } = makeOutbox();
-    const send = vi.fn(() =>
-      Promise.reject({ status: 400, message: 'bad request' }),
-    );
-    outbox.registerExecutor(KIND, send);
-    await outbox.enqueue(KIND, { a: 1 });
-    await outbox.drain();
-    expect(send).toHaveBeenCalledTimes(1);
-    const snap = outbox.getSnapshot();
-    expect(snap.failedCount).toBe(1);
-    expect(snap.entries[0]?.status).toBe(OutboxEntryStatus.Failed);
-  });
-
-  it('dead-letters after exhausting retries on persistent 5xx', async () => {
-    const { outbox } = makeOutbox({ maxAttempts: 3 });
-    let calls = 0;
-    outbox.registerExecutor(KIND, () => {
-      calls += 1;
-      return Promise.reject({ status: 503 });
-    });
-    await outbox.enqueue(KIND, { a: 1 });
-    await outbox.drain();
-    expect(calls).toBe(3);
-    expect(outbox.getSnapshot().entries[0]?.status).toBe(
-      OutboxEntryStatus.Failed,
-    );
-  });
-
-  it('a network failure never advances the attempt counter or dead-letters', async () => {
-    // Captured scheduler so the offline-retry loop does not run forever.
-    const timers: Array<() => void> = [];
-    const { outbox } = makeOutbox({ scheduler: (fn) => void timers.push(fn) });
-    let succeed = false;
-    outbox.registerExecutor(KIND, () => {
-      if (!succeed) {
-        return Promise.reject({
-          name: 'TypeError',
-          message: 'Failed to fetch',
-        });
-      }
-      return Promise.resolve();
-    });
-
-    await outbox.enqueue(KIND, { a: 1 });
-    await outbox.drain();
-    const parked = outbox.getSnapshot().entries[0];
-    if (!parked) {
-      throw new Error(
-        'the offline entry was dropped from the outbox instead of parked',
-      );
-    }
-    expect(parked.status).toBe(OutboxEntryStatus.Pending);
-    expect(parked.attempts).toBe(0); // offline is not the payload's fault
-    expect(outbox.getSnapshot().failedCount).toBe(0);
-
-    // Reconnect + retry drains it.
-    succeed = true;
-    await outbox.drain();
-    expect(outbox.getSnapshot().entries).toHaveLength(0);
-  });
-
-  it('delivers queued entries in FIFO order', async () => {
-    const { outbox, online } = makeOutbox();
-    const order: number[] = [];
-    outbox.registerExecutor(KIND, (p: { n: number }) => {
-      order.push(p.n);
-      return Promise.resolve();
-    });
-    online.reportOffline();
-    await outbox.enqueue(KIND, { n: 1 });
-    await outbox.enqueue(KIND, { n: 2 });
-    await outbox.enqueue(KIND, { n: 3 });
-    online.reportOnline();
-    await outbox.drain();
-    expect(order).toEqual([1, 2, 3]);
-  });
-
-  it('recovers crash-orphaned inflight entries to pending on start', async () => {
-    const storage = new InMemoryOutboxStorage();
-    const ts = 1;
-    await storage.put({
-      id: 'orphan',
-      kind: KIND,
-      payload: { a: 1 },
-      idempotencyKey: 'k',
-      status: OutboxEntryStatus.Inflight, // died mid-send
-      attempts: 1,
-      createdAt: ts,
-      updatedAt: ts,
-    });
-    const online = new OnlineController();
-    online.reportOffline(); // keep it queued so we can observe the recovery
-    const outbox = new Outbox({ storage, online, scheduler: (fn) => fn() });
-    await outbox.start();
-    expect(outbox.getSnapshot().entries[0]?.status).toBe(
-      OutboxEntryStatus.Pending,
-    );
-    outbox.stop();
-  });
-});

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();
-}