pulse-js-framework 1.10.4 → 1.11.1

package/types/sse.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Pulse SSE (Server-Sent Events) Type Definitions
+ * @module pulse-js-framework/runtime/sse
+ */
+
+import { Pulse } from './pulse';
+
+// ============================================================================
+// SSE Connection State
+// ============================================================================
+
+/** SSE connection state */
+export type SSEState = 'connecting' | 'open' | 'closed';
+
+// ============================================================================
+// SSE Error
+// ============================================================================
+
+/** SSE error code */
+export type SSEErrorCode =
+  | 'CONNECT_FAILED'
+  | 'TIMEOUT'
+  | 'MAX_RETRIES'
+  | 'CLOSED'
+  | 'UNKNOWN';
+
+/**
+ * SSE-specific error with structured codes
+ */
+export declare class SSEError extends Error {
+  readonly name: 'SSEError';
+  readonly sseCode: SSEErrorCode;
+
+  constructor(message: string, options?: {
+    sseCode?: SSEErrorCode;
+    suggestion?: string;
+  });
+
+  /** Check if an error is an SSEError */
+  static isSSEError(error: unknown): error is SSEError;
+
+  /** Check if this is a connection failure */
+  isConnectFailed(): boolean;
+
+  /** Check if this is a timeout error */
+  isTimeout(): boolean;
+
+  /** Check if max retries were exhausted */
+  isMaxRetries(): boolean;
+
+  /** Check if connection was closed */
+  isClosed(): boolean;
+}
+
+// ============================================================================
+// createSSE Options
+// ============================================================================
+
+/** Event handler for SSE messages */
+export type SSEMessageHandler = (data: unknown, event: MessageEvent) => void;
+
+/** Options for createSSE */
+export interface CreateSSEOptions {
+  /** Include credentials in the request (default: false) */
+  withCredentials?: boolean;
+
+  /** Enable auto-reconnect on connection loss (default: true) */
+  reconnect?: boolean;
+
+  /** Maximum number of reconnection attempts (default: 5) */
+  maxRetries?: number;
+
+  /** Base delay for exponential backoff in ms (default: 1000) */
+  baseDelay?: number;
+
+  /** Maximum delay between reconnection attempts in ms (default: 30000) */
+  maxDelay?: number;
+
+  /** Event types to listen for (default: ['message']) */
+  events?: string[];
+
+  /** Auto-parse JSON message data (default: true) */
+  parseJSON?: boolean;
+
+  /** Connect immediately on creation (default: true) */
+  immediate?: boolean;
+
+  /** Callback invoked on each message */
+  onMessage?: SSEMessageHandler | null;
+
+  /** Callback invoked when connection opens */
+  onOpen?: (() => void) | null;
+
+  /** Callback invoked on error */
+  onError?: ((error: SSEError) => void) | null;
+}
+
+// ============================================================================
+// createSSE Return Type
+// ============================================================================
+
+/** Return type of createSSE */
+export interface SSEInstance {
+  /** Reactive connection state ('connecting' | 'open' | 'closed') */
+  state: Pulse<SSEState>;
+
+  /** Reactive connected flag (true when state is 'open') */
+  connected: Pulse<boolean>;
+
+  /** Reactive reconnecting state */
+  reconnecting: Pulse<boolean>;
+
+  /** Reactive current reconnection attempt number */
+  reconnectAttempt: Pulse<number>;
+
+  /** Reactive last error */
+  error: Pulse<SSEError | null>;
+
+  /** Reactive last event ID from the server */
+  lastEventId: Pulse<string | null>;
+
+  /** Manually initiate a connection (resets reconnection state) */
+  connect(): void;
+
+  /** Close the connection and stop reconnecting */
+  close(): void;
+
+  /** Add an event listener for a specific event type */
+  addEventListener(event: string, handler: SSEMessageHandler): void;
+
+  /** Remove an event listener */
+  removeEventListener(event: string, handler: SSEMessageHandler): void;
+
+  /** Permanently dispose the SSE instance and clean up all resources */
+  dispose(): void;
+
+  /** Alias for addEventListener */
+  on(event: string, handler: SSEMessageHandler): void;
+
+  /** Alias for removeEventListener */
+  off(event: string, handler: SSEMessageHandler): void;
+}
+
+/**
+ * Create a low-level SSE connection with auto-reconnect and exponential backoff.
+ *
+ * @param url SSE endpoint URL
+ * @param options Configuration options
+ * @returns SSE instance with reactive state and control methods
+ *
+ * @example
+ * const sse = createSSE('https://api.example.com/events', {
+ *   reconnect: true,
+ *   maxRetries: 5,
+ *   events: ['message', 'update'],
+ *   onMessage: (data) => console.log('Received:', data),
+ * });
+ *
+ * sse.on('update', (data) => handleUpdate(data));
+ * sse.close();
+ */
+export declare function createSSE(url: string, options?: CreateSSEOptions): SSEInstance;
+
+// ============================================================================
+// useSSE Options and Return Type
+// ============================================================================
+
+/** Options for useSSE hook */
+export interface UseSSEOptions extends CreateSSEOptions {
+  /** Number of messages to keep in history (default: 0 = disabled) */
+  messageHistorySize?: number;
+}
+
+/** Return type of useSSE (without message history) */
+export interface UseSSEReturnBase {
+  /** Reactive last received message data */
+  data: Pulse<unknown>;
+
+  /** Reactive connected flag */
+  connected: Pulse<boolean>;
+
+  /** Reactive last error */
+  error: Pulse<SSEError | null>;
+
+  /** Reactive reconnecting state */
+  reconnecting: Pulse<boolean>;
+
+  /** Reactive last event ID */
+  lastEventId: Pulse<string | null>;
+
+  /** Close the SSE connection */
+  close(): void;
+
+  /** Reconnect to the SSE endpoint */
+  reconnect(): void;
+
+  /** Underlying SSE instance */
+  sse: SSEInstance;
+}
+
+/** Return type of useSSE (with message history) */
+export interface UseSSEReturnWithHistory extends UseSSEReturnBase {
+  /** Reactive message history array */
+  messages: Pulse<unknown[]>;
+
+  /** Clear the message history */
+  clearMessages(): void;
+}
+
+/** Return type of useSSE */
+export type UseSSEReturn = UseSSEReturnBase | UseSSEReturnWithHistory;
+
+/**
+ * Reactive SSE hook with automatic lifecycle management.
+ * Automatically disposes the connection when the enclosing effect is cleaned up.
+ *
+ * @param url SSE endpoint URL
+ * @param options Configuration options
+ * @returns Reactive SSE state and control methods
+ *
+ * @example
+ * const { data, connected, error, close } = useSSE(
+ *   'https://api.example.com/stream',
+ *   {
+ *     parseJSON: true,
+ *     messageHistorySize: 50,
+ *     onMessage: (data) => console.log('New event:', data),
+ *   }
+ * );
+ *
+ * effect(() => {
+ *   if (connected.get()) console.log('SSE connected');
+ *   if (data.get()) console.log('Latest:', data.get());
+ * });
+ */
+export declare function useSSE(url: string, options?: UseSSEOptions): UseSSEReturn;
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+declare const _default: {
+  createSSE: typeof createSSE;
+  useSSE: typeof useSSE;
+  SSEError: typeof SSEError;
+};
+
+export default _default;

package/types/sw.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Pulse Service Worker Utilities Type Definitions
+ * @module pulse-js-framework/sw
+ */
+
+// ============================================================================
+// Cache Strategy Types
+// ============================================================================
+
+/** Supported cache strategy names */
+export type CacheStrategyName =
+  | 'cache-first'
+  | 'network-first'
+  | 'stale-while-revalidate'
+  | 'network-only'
+  | 'cache-only';
+
+/** URL matcher: regex pattern or predicate function */
+export type URLMatcher = RegExp | ((url: string) => boolean);
+
+/** Options for createCacheStrategy */
+export interface CacheStrategyOptions {
+  /** Cache storage name (required) */
+  cacheName: string;
+
+  /** URL matching pattern or function (default: matches all) */
+  match?: URLMatcher | null;
+
+  /** Maximum cache age in ms (default: 0 = no expiry) */
+  maxAge?: number;
+
+  /** Maximum number of cached entries (default: 0 = unlimited) */
+  maxEntries?: number;
+
+  /** Network timeout in ms for network-first strategy (default: 5000) */
+  timeout?: number;
+}
+
+/** Cache strategy instance returned by createCacheStrategy */
+export interface CacheStrategy {
+  /** Strategy name */
+  readonly name: CacheStrategyName;
+
+  /** Cache storage name */
+  readonly cacheName: string;
+
+  /**
+   * Handle a fetch event with this strategy.
+   * Calls event.respondWith() if the request matches.
+   *
+   * @param event The service worker FetchEvent
+   * @returns True if this strategy handled the event, false if the request did not match
+   */
+  handle(event: FetchEvent): boolean;
+
+  /**
+   * Fetch a request using this strategy (without FetchEvent).
+   *
+   * @param request The request URL string or Request object
+   * @returns Response promise
+   */
+  fetch(request: Request | string): Promise<Response>;
+
+  /**
+   * Precache a list of URLs into this strategy's cache.
+   *
+   * @param urls Array of URLs to precache
+   */
+  precache(urls: string[]): Promise<void>;
+
+  /**
+   * Delete this strategy's entire cache.
+   *
+   * @returns True if the cache was successfully deleted
+   */
+  clearCache(): Promise<boolean>;
+}
+
+/**
+ * Create a cache strategy for handling service worker fetch events.
+ *
+ * @param name Strategy type
+ * @param options Strategy configuration
+ * @returns Cache strategy instance with handle(), fetch(), precache(), and clearCache() methods
+ * @throws Error if cacheName is not provided or strategy name is unknown
+ *
+ * @example
+ * // In your sw.js:
+ * import { createCacheStrategy } from 'pulse-js-framework/sw';
+ *
+ * const staticCache = createCacheStrategy('cache-first', {
+ *   cacheName: 'static-v1',
+ *   match: /\.(js|css|png|woff2)$/,
+ *   maxEntries: 100,
+ * });
+ *
+ * const apiCache = createCacheStrategy('network-first', {
+ *   cacheName: 'api-v1',
+ *   match: /\/api\//,
+ *   timeout: 3000,
+ *   maxAge: 5 * 60 * 1000, // 5 minutes
+ * });
+ *
+ * const swrCache = createCacheStrategy('stale-while-revalidate', {
+ *   cacheName: 'swr-v1',
+ *   match: /\/assets\//,
+ * });
+ *
+ * self.addEventListener('fetch', (event) => {
+ *   if (staticCache.handle(event)) return;
+ *   if (apiCache.handle(event)) return;
+ *   if (swrCache.handle(event)) return;
+ * });
+ */
+export declare function createCacheStrategy(
+  name: CacheStrategyName,
+  options: CacheStrategyOptions
+): CacheStrategy;
+
+// ============================================================================
+// Skip Waiting
+// ============================================================================
+
+/**
+ * Install a message listener for SKIP_WAITING messages.
+ * Call this in your service worker to enable skipWaiting from the main thread.
+ *
+ * When the main thread sends `{ type: 'SKIP_WAITING' }` via postMessage,
+ * the service worker will call self.skipWaiting() to activate immediately.
+ *
+ * @example
+ * // In your sw.js:
+ * import { enableSkipWaiting } from 'pulse-js-framework/sw';
+ * enableSkipWaiting();
+ *
+ * // In your main thread:
+ * navigator.serviceWorker.controller?.postMessage({ type: 'SKIP_WAITING' });
+ */
+export declare function enableSkipWaiting(): void;
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+declare const _default: {
+  createCacheStrategy: typeof createCacheStrategy;
+  enableSkipWaiting: typeof enableSkipWaiting;
+};
+
+export default _default;