@shamilovtim/react-native-nitro-sse 2.3.0

package/src/NitroSseClient.ts

@@ -0,0 +1,297 @@
+import type { NitroSse } from './NitroSse.nitro';
+import type {
+  SseClient,
+  SseConfig,
+  SseEvent,
+  SseListener,
+  SseStats,
+} from './SseInterface';
+
+declare const __DEV__: boolean | undefined;
+
+export class NitroSseClient implements SseClient {
+  private _native: NitroSse;
+  private _listeners: Map<string, Set<SseListener>> = new Map();
+  private _legacyCallback?: (events: SseEvent[]) => void;
+  private _config?: SseConfig;
+  private _mockIntervalId?: any;
+  private _mockIndex: number = 0;
+
+  constructor(native: NitroSse) {
+    this._native = native;
+  }
+
+  setup(config: SseConfig, onEvent?: (events: SseEvent[]) => void): void {
+    this._config = { ...config };
+    this._legacyCallback = onEvent;
+
+    const isDev = typeof __DEV__ !== 'undefined' ? __DEV__ === true : false;
+    if (!isDev) {
+      delete this._config.mock;
+    }
+
+    if (this._config.mock) {
+      console.warn(
+        '\n' +
+          '=================================================================\n' +
+          '⚠️  [react-native-nitro-sse] WARNING: MOCK STREAMING IS ENABLED! ⚠️\n' +
+          `   Mode: ${this._config.mock.mode.toUpperCase()} | Speed: ${
+            this._config.mock.eventsPerSecond ?? 1
+          } events/sec\n` +
+          '   Please ensure mocking is disabled before building for production!\n' +
+          '=================================================================\n'
+      );
+    }
+
+    if (this._mockIntervalId) {
+      clearTimeout(this._mockIntervalId);
+      this._mockIntervalId = undefined;
+    }
+
+    // We wrap the native setup to dispatch events to typed listeners
+    this._native.setup(this._config, (events) => {
+      // 1. Call legacy batch callback if provided
+      this._legacyCallback?.(events);
+
+      // 2. Dispatch individual events to registered listeners
+      for (const event of events) {
+        // Dispatch basic types: 'open', 'message', 'error', 'close', 'heartbeat'
+        this._emit(event.type, event);
+
+        // Dispatch by SSE event name if it's different from the type
+        // e.g., if type is 'message' but event name is 'update'
+        if (event.event && event.event !== event.type) {
+          this._emit(event.event, event);
+        }
+      }
+    });
+  }
+
+  addEventListener(type: string, listener: SseListener): void {
+    if (!this._listeners.has(type)) {
+      this._listeners.set(type, new Set());
+    }
+    this._listeners.get(type)!.add(listener);
+  }
+
+  removeEventListener(type: string, listener: SseListener): void {
+    this._listeners.get(type)?.delete(listener);
+  }
+
+  private _emit(type: string, event: SseEvent): void {
+    const listeners = this._listeners.get(type);
+    if (listeners) {
+      listeners.forEach((listener) => {
+        try {
+          listener(event);
+        } catch (e) {
+          console.error(`[NitroSse] Error in event listener for "${type}":`, e);
+        }
+      });
+    }
+  }
+
+  private _createSseEvent(rawMock: any): SseEvent {
+    return {
+      type: rawMock.type ?? 'message',
+      data: rawMock.data,
+      parsedData: rawMock.parsedData,
+      id: rawMock.id,
+      event: rawMock.event,
+      message: rawMock.message,
+      statusCode: rawMock.statusCode ?? 200,
+      retry: rawMock.retry,
+    };
+  }
+
+  start(): void {
+    if (this._mockIntervalId) {
+      clearTimeout(this._mockIntervalId);
+      this._mockIntervalId = undefined;
+    }
+
+    if (this._config?.mock) {
+      const {
+        mode,
+        data,
+        eventsPerSecond = 1,
+        loop = false,
+        errorRate = 0,
+      } = this._config.mock;
+      this._mockIndex = 0;
+
+      // Validate and normalize eventsPerSecond (must be a finite positive number, default to 1)
+      let validatedEventsPerSecond = Number(eventsPerSecond);
+      if (
+        Number.isNaN(validatedEventsPerSecond) ||
+        !Number.isFinite(validatedEventsPerSecond) ||
+        validatedEventsPerSecond <= 0
+      ) {
+        validatedEventsPerSecond = 1;
+      }
+
+      // Validate and normalize errorRate (must be a finite number within [0,1], default to 0)
+      let validatedErrorRate = Number(errorRate);
+      if (
+        Number.isNaN(validatedErrorRate) ||
+        !Number.isFinite(validatedErrorRate)
+      ) {
+        validatedErrorRate = 0;
+      } else {
+        validatedErrorRate = Math.max(0, Math.min(1, validatedErrorRate));
+      }
+
+      const delayMs = 1000 / validatedEventsPerSecond;
+      // Safeguard: if eventsPerSecond is huge (e.g. 1000), setInterval/setTimeout is too slow.
+      // We batch events together in chunks if the calculated interval is under 10ms.
+      const batchSize = Math.max(1, Math.round(validatedEventsPerSecond / 100)); // chunk size for 10ms intervals
+      const intervalMs = Math.max(10, delayMs * batchSize);
+
+      const scheduleNext = () => {
+        if (this._mockIndex >= data.length) {
+          if (loop && data.length > 0) {
+            this._mockIndex = 0;
+          } else {
+            if (this._mockIntervalId) {
+              clearTimeout(this._mockIntervalId);
+              this._mockIntervalId = undefined;
+            }
+            const closeEvent: SseEvent = { type: 'close', statusCode: 200 };
+            this._legacyCallback?.([closeEvent]);
+            this._emit('close', closeEvent);
+            return;
+          }
+        }
+
+        // Simulate connection drops
+        if (validatedErrorRate && Math.random() < validatedErrorRate) {
+          const errorEvent: SseEvent = {
+            type: 'error',
+            message: 'Mock Connection Drop (Simulated Error)',
+            statusCode: 500,
+          };
+          this._legacyCallback?.([errorEvent]);
+          this._emit('error', errorEvent);
+
+          // Retry / reconnect delay simulator (e.g. 2000ms)
+          this._mockIntervalId = setTimeout(scheduleNext, 2000);
+          return;
+        }
+
+        const currentItem = data[this._mockIndex];
+        const hasCustomDelay =
+          currentItem && typeof currentItem.delayMs === 'number';
+
+        const batch: SseEvent[] = [];
+        if (hasCustomDelay) {
+          const rawMock = data[this._mockIndex++];
+          if (rawMock) {
+            batch.push(this._createSseEvent(rawMock));
+          }
+        } else {
+          for (let i = 0; i < batchSize && this._mockIndex < data.length; i++) {
+            const nextItem = data[this._mockIndex];
+            if (nextItem && typeof nextItem.delayMs === 'number') {
+              break;
+            }
+            const rawMock = data[this._mockIndex++];
+            if (rawMock) {
+              batch.push(this._createSseEvent(rawMock));
+            }
+          }
+        }
+
+        if (batch.length > 0) {
+          // 1. Call legacy batch callback if provided
+          this._legacyCallback?.(batch);
+
+          // 2. Dispatch individual events to registered listeners
+          for (const event of batch) {
+            this._emit(event.type, event);
+            if (event.event && event.event !== event.type) {
+              this._emit(event.event, event);
+            }
+          }
+        }
+
+        const nextDelay = hasCustomDelay ? currentItem.delayMs! : intervalMs;
+        this._mockIntervalId = setTimeout(scheduleNext, nextDelay);
+      };
+
+      const firstItem = data[0];
+      const firstDelay =
+        firstItem && typeof firstItem.delayMs === 'number'
+          ? firstItem.delayMs
+          : intervalMs;
+
+      if (mode === 'replace') {
+        // Emit simulated open event
+        const openEvent: SseEvent = { type: 'open', statusCode: 200 };
+        this._legacyCallback?.([openEvent]);
+        this._emit('open', openEvent);
+
+        this._mockIntervalId = setTimeout(scheduleNext, firstDelay);
+        return; // Skip native start
+      } else if (mode === 'inject') {
+        this._mockIntervalId = setTimeout(scheduleNext, firstDelay);
+      }
+    }
+
+    this._native.start();
+  }
+
+  stop(): void {
+    if (this._mockIntervalId) {
+      clearTimeout(this._mockIntervalId);
+      this._mockIntervalId = undefined;
+    }
+    this._native.stop();
+  }
+
+  restart(): void {
+    if (this._config?.mock) {
+      this.stop();
+      this.start();
+    } else {
+      this._native.restart();
+    }
+  }
+
+  flush(): void {
+    this._native.flush();
+  }
+
+  isConnected(): boolean {
+    if (this._config?.mock?.mode === 'replace' && this._mockIntervalId) {
+      return true;
+    }
+    return this._native.isConnected();
+  }
+
+  getStats(): SseStats {
+    if (this._config?.mock?.mode === 'replace') {
+      return {
+        totalBytesReceived: this._mockIndex * 150,
+        reconnectCount: 0,
+      };
+    }
+    return this._native.getStats();
+  }
+
+  updateHeaders(headers: Record<string, string>): void {
+    this._native.updateHeaders(headers);
+  }
+
+  setLastProcessedId(id: string): void {
+    this._native.setLastProcessedId(id);
+  }
+
+  injectMockEvent(event: Partial<SseEvent>): void {
+    const sseEvent = this._createSseEvent(event);
+    this._legacyCallback?.([sseEvent]);
+    this._emit(sseEvent.type, sseEvent);
+    if (sseEvent.event && sseEvent.event !== sseEvent.type) {
+      this._emit(sseEvent.event, sseEvent);
+    }
+  }
+}

package/src/SseInterface.ts

@@ -0,0 +1,248 @@
+import type { AnyMap } from 'react-native-nitro-modules';
+/**
+ * HTTP method to use for the SSE connection.
+ */
+export type HttpMethod = 'get' | 'post';
+
+/**
+ * Type of event received from the SSE stream.
+ * - `open`: Connection established.
+ * - `message`: Standard data message.
+ * - `error`: Connection error or other failure.
+ * - `close`: Connection closed (not typical for SSE, but used for cleanup).
+ * - `heartbeat`: Ping/Keep-alive signal.
+ */
+export type SseEventType = 'open' | 'message' | 'error' | 'close' | 'heartbeat';
+
+/**
+ * Configuration for the SSE connection.
+ */
+export interface SseConfig {
+  /** The URL of the SSE endpoint. */
+  url: string;
+  /** HTTP method (default: 'GET'). */
+  method?: HttpMethod;
+  /** Custom HTTP headers to include in the request. */
+  headers?: Record<string, string>;
+  /** Body for POST requests. */
+  body?: string;
+  /**
+   * Whether to continue processing events when the app is in the background.
+   * Note: On iOS, this uses background tasks which are limited in time by the OS.
+   * @default false
+   */
+  backgroundExecution?: boolean;
+  /**
+   * How long (in ms) to wait and group multiple events before sending them to the JS side.
+   * High-frequency streams should use this to reduce JS bridge overhead and improve UI performance.
+   * Set to 0 to deliver events immediately one-by-one.
+   * @default 0
+   */
+  batchingIntervalMs?: number;
+  /**
+   * Maximum number of events to keep in the native buffer before forcing a flush to JS,
+   * regardless of the `batchingIntervalMs`. Prevents memory pressure.
+   * @default 1000
+   */
+  maxBufferSize?: number;
+  /**
+   * Maximum time (in ms) to wait for the initial server connection and handshake to complete.
+   * Effectively the \"Connect Timeout\".
+   * @default 15000
+   */
+  connectionTimeoutMs?: number;
+  /**
+   * Maximum idle time (in ms) allowed between receiving data packets or heartbeats.
+   * If the server remains silent longer than this, the connection is considered stalled and will reconnect.
+   * Increase this for streams that transmit data infrequently.
+   * @default 300000
+   */
+  readTimeoutMs?: number;
+  /**
+   * Initial delay (in ms) for reconnection attempts.
+   * Subsequent attempts use exponential backoff.
+   * @default 1000
+   */
+  retryIntervalMs?: number;
+  /**
+   * Maximum delay (in ms) for reconnection attempts.
+   * @default 30000
+   */
+  maxRetryIntervalMs?: number;
+  /**
+   * Factor to randomize reconnection attempts (0.0 to 1.0).
+   * 0 means no jitter, 1.0 means up to 100% randomization.
+   * @default 0.5
+   */
+  jitterFactor?: number;
+  /**
+   * Maximum number of reconnection attempts before giving up.
+   * Use -1 for infinite (default), 0 to disable auto-reconnection.
+   * @default -1
+   */
+  maxReconnectAttempts?: number;
+  /**
+   * Whether to automatically parse message data as JSON in a background native thread.
+   * If true, and parsing succeeds, the result will be available in the 'parsedData' field.
+   * @default false
+   */
+  autoParseJSON?: boolean;
+  /**
+   * Whether to automatically monitor network connectivity changes.
+   * If true, the client will proactively reconnect when switching networks (WiFi <-> Cellular)
+   * and pause/resume based on internet availability.
+   * @default true
+   */
+  monitorNetwork?: boolean;
+  /**
+   * Async interceptor called before every connection attempt (including auto-reconnects).
+   * Use this to refresh tokens or calculate dynamic headers.
+   * Note: This is protected by a native timeout to prevent the app from hanging.
+   */
+  onBeforeRequest?: () => Promise<Record<string, string>>;
+  /**
+   * Configuration for mock streaming data.
+   * Used for local testing and debugging.
+   */
+  mock?: SseMockConfig;
+}
+
+export type SseMockMode = 'replace' | 'inject';
+
+/**
+ * Represents a single mock SSE event configuration.
+ */
+export interface SseMockEvent {
+  /** The type of the event. */
+  type?: SseEventType;
+  /** The data payload of the event as a raw string. */
+  data?: string;
+  /** The parsed JSON data, if autoParseJSON is enabled and parsing succeeds. */
+  parsedData?: AnyMap;
+  /** The event ID, if provided. */
+  id?: string;
+  /** The event name, if provided (internal 'event' field in SSE). */
+  event?: string;
+  /** System message or error description. */
+  message?: string;
+  /** HTTP status code if applicable. */
+  statusCode?: number;
+  /** Server-requested retry delay in milliseconds. */
+  retry?: number;
+  /** Custom delay in milliseconds before this event is dispatched. */
+  delayMs?: number;
+}
+
+/**
+ * Configuration for mock streaming data.
+ */
+export interface SseMockConfig {
+  /**
+   * - 'replace': Simulates the stream completely in JavaScript without any native network connection.
+   * - 'inject': Establishes the real server connection and injects mock events alongside it.
+   */
+  mode: SseMockMode;
+  /**
+   * The list of mock events to be streamed.
+   */
+  data: SseMockEvent[];
+  /**
+   * The frequency at which mock events are dispatched.
+   * Represented in events per second.
+   * @default 1
+   */
+  eventsPerSecond?: number;
+  /**
+   * Whether to loop the mock stream indefinitely.
+   * @default false
+   */
+  loop?: boolean;
+  /**
+   * Probability of simulated connection drop/error events (0.0 to 1.0).
+   * @default 0
+   */
+  errorRate?: number;
+}
+
+/**
+ * Represents a single SSE event.
+ */
+export interface SseEvent {
+  /** The type of the event. */
+  type: SseEventType;
+  /** The data payload of the event as a raw string. */
+  data?: string;
+  /** The parsed JSON data, if autoParseJSON is enabled and parsing succeeds. */
+  parsedData?: AnyMap;
+  /** The event ID, if provided. */
+  id?: string;
+  /** The event name, if provided (internal 'event' field in SSE). */
+  event?: string;
+  /** System message or error description. */
+  message?: string;
+  /** HTTP status code if applicable. */
+  statusCode?: number;
+  /** Server-requested retry delay in milliseconds. */
+  retry?: number;
+}
+
+/**
+ * Statistics about the SSE connection.
+ */
+export interface SseStats {
+  /** Total bytes received so far. */
+  totalBytesReceived: number;
+  /** Number of times the connection has been re-established. */
+  reconnectCount: number;
+  /** Timestamp of the last error event. */
+  lastErrorTime?: number;
+  /** Error code of the last error. */
+  lastErrorCode?: string;
+}
+
+/**
+ * Listener for a specific SSE event.
+ */
+export type SseListener = (event: SseEvent) => void;
+
+/**
+ * Public interface for the NitroSse client, supporting typed event listeners.
+ */
+export interface SseClient {
+  /**
+   * Configure SSE and setup event callback.
+   * @param config The SSE configuration.
+   * @param onEvent Optional legacy batch callback for all events.
+   */
+  setup(config: SseConfig, onEvent?: (events: SseEvent[]) => void): void;
+
+  /**
+   * Register a listener for a specific event type ('message', 'open', etc.)
+   * or a custom SSE event name (from the 'event:' field).
+   */
+  addEventListener(type: string, listener: SseListener): void;
+
+  /**
+   * Unregister a listener.
+   */
+  removeEventListener(type: string, listener: SseListener): void;
+
+  /** Start the connection. */
+  start(): void;
+  /** Stop the connection. */
+  stop(): void;
+  /** Restart the connection (stop + start). */
+  restart(): void;
+  /** Force flush buffered events to JS. */
+  flush(): void;
+  /** Check if active. */
+  isConnected(): boolean;
+  /** Get stats. */
+  getStats(): SseStats;
+  /** Manually update headers. */
+  updateHeaders(headers: Record<string, string>): void;
+  /** Set last event ID. */
+  setLastProcessedId(id: string): void;
+  /** Manually inject a mock event into the stream (for testing/debugging). */
+  injectMockEvent(event: Partial<SseEvent>): void;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type { NitroSse } from './NitroSse.nitro';
+import { NitroSseClient } from './NitroSseClient';
+import type { SseClient } from './SseInterface';
+
+export * from './SseInterface';
+export * from './NitroSse.nitro';
+
+/**
+ * Creates a high-performance SSE client that supports typed event listeners (`addEventListener`) and legacy batching.
+ *
+ * @returns An SseClient instance wrapping the native NitroSse implementation.
+ * @throws If the native NitroSse module cannot be found. Ensure the library is linked and the app is built for iOS/Android.
+ */
+export function createNitroSse(): SseClient {
+  let nativeSse: NitroSse | undefined;
+  try {
+    nativeSse = NitroModules.createHybridObject<NitroSse>('NitroSse');
+  } catch {
+    console.debug(
+      'Native NitroSse not found. This might be a test environment or web.'
+    );
+  }
+
+  if (!nativeSse) {
+    throw new Error(
+      'NitroSse: Native module not found. Ensure you have linked the library and built the app for iOS/Android.'
+    );
+  }
+  return new NitroSseClient(nativeSse);
+}