TIDE • MCP & Tools

Tide Core API Specifications

Comprehensive API specifications for createTide, useTideWS, mutate, and TideProvider.

Tide Core API Reference

Comprehensive specifications of all exported primitives, hooks, and types in @uikode/tide.

createTide<T>(options)

Creates a reactive query resource backed by local in-memory LRU cache, optional sessionStorage persistence, and WebSocket push stream synchronization.

Options Signature

TypeScript 
export interface TideOptions<T> {
  // Required
  key: string | (() => string);

  // Data source (provide url shorthand OR custom fetcher)
  url?: string | (() => string);
  fetcher?: (ctx: { signal: AbortSignal }) => Promise<T>;

  // Response transformation
  transform?: (raw: unknown) => T;

  // Real-time synchronization
  wsPath?: string;
  ws?: (message: unknown) => T | null;

  // Cache & Network Behavior
  etag?: boolean;                // Send If-None-Match header; skip update on 304
  staleTime?: number;            // Milliseconds before data is marked stale (default: 30_000)
  cacheTime?: number;            // In-memory retention after unmount (default: 300_000)
  pollInterval?: number;         // HTTP polling interval in ms (default: 0 / disabled)
  retries?: number;              // Failed request retry attempts (default: 3)
  persist?: boolean;             // Persist to sessionStorage for 0ms revisit (default: true)
  hashCompare?: boolean;         // Use djb2 content hash to prevent duplicate signal updates
  enabled?: () => boolean;       // Reactive boolean gate to pause/resume queries
}

Return Value (TideResult<T>)

TypeScript 
export interface TideResult<T> {
  data: Accessor<T | null>;
  loading: Accessor<boolean>;    // True during initial fetch without cache
  refreshing: Accessor<boolean>; // True during background SWR revalidation
  stale: Accessor<boolean>;      // True if cached data has exceeded staleTime
  error: Accessor<string | null>;
  refetch: () => Promise<void>;
  mutate: (updater: (prev: T | null) => T) => void;
  pause: () => void;             // Stop polling and abort inflight requests
  resume: () => void;            // Restart polling and trigger fresh fetch
  prefetch: () => void;
}

<TideProvider>

Top-level provider component supplying global defaults and managing the shared WebSocket connection pool.

tsx 
<TideProvider
  ws={{
    url: 'wss://api.uikode.com/ws',
    topics: ['notifications', 'system-status'],
  }}
  defaults={{
    staleTime: 30_000,
    cacheTime: 300_000,
    pollInterval: 10_000,
    retries: 3,
    persist: true,
  }}
  reconnect={{
    baseMs: 1_000,
    maxMs: 30_000,
  }}
  heartbeat={25_000}
>
  <App />
</TideProvider>

WebSocket Hooks

useTideWS(channel?: string)

Subscribes to server-sent WebSocket events on a specific channel via the shared TideProvider connection.

TypeScript 
import { useTideWS } from '@uikode/tide';

const lastMessage = useTideWS('system-alerts');
// returns Accessor<unknown>

useTideWSConnected()

Returns a reactive boolean accessor tracking whether the WebSocket socket is currently connected.

TypeScript 
import { useTideWSConnected } from '@uikode/tide';

const isOnline = useTideWSConnected();