@nexussdk/flags 0.0.1 → 0.0.3

package/src/sse-manager.ts

@@ -1,165 +0,0 @@
-/**
- * @fileoverview Singleton SSE Manager with ref-counting and auto-reconnect.
- * Ensures exactly one EventSource connection per API key across all flag subscribers.
- * @module @nexus/sdk-flags/sse-manager
- */
-
-import type { FlagStreamEvent } from '@nexussdk/contracts';
-import { computeBackoffMs } from '@nexussdk/core';
-
-/**
- * Options for creating an SSE connection.
- */
-export interface SSEManagerOptions {
-  /** Full SSE stream URL (e.g. "http://localhost:8080/api/v1/flags/stream"). */
-  url: string;
-  /** Public API key for authentication. */
-  apiKey: string;
-  /** Callback invoked for each received flag stream event. */
-  onEvent: (event: FlagStreamEvent) => void;
-  /** Callback invoked on connection state changes (optional). */
-  onStateChange?: (connected: boolean) => void;
-  /** Maximum reconnect attempts. Defaults to Infinity. */
-  maxReconnects?: number;
-}
-
-/**
- * Ref-counted Singleton SSE Manager.
- *
- * Multiple consumers sharing the same `apiKey` receive updates
- * from a single shared SSE connection. Connection is torn down when all
- * consumers have called `disconnect()`.
- *
- * Connection lifecycle:
- * 1. `connect()` → opens EventSource or streaming fetch
- * 2. On disconnect: exponential backoff reconnect (max 30s)
- * 3. `disconnect()` → decrements ref count; tears down on 0
- *
- * @example
- * const manager = new SSEManager({
- *   url: 'http://localhost:8080/api/v1/flags/stream',
- *   apiKey: 'pk_live_...',
- *   onEvent: (event) => updateCache(event),
- * });
- * manager.connect();
- * // Later:
- * manager.disconnect();
- */
-export class SSEManager {
-  private readonly options: SSEManagerOptions;
-  private eventSource: EventSource | null = null;
-  private connected = false;
-  private destroyed = false;
-  private reconnectAttempt = 0;
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-  private readonly maxReconnects: number;
-
-  constructor(options: SSEManagerOptions) {
-    this.options = options;
-    this.maxReconnects = options.maxReconnects ?? Infinity;
-  }
-
-  /**
-   * Returns whether the SSE connection is currently active.
-   *
-   * @returns `true` if EventSource is open and receiving events.
-   */
-  get isConnected(): boolean {
-    return this.connected;
-  }
-
-  /**
-   * Opens the SSE connection to the Go-Gin stream endpoint.
-   * Safe to call multiple times — no-op if already connected.
-   *
-   * @example
-   * manager.connect();
-   */
-  connect(): void {
-    if (this.destroyed || this.connected || this.eventSource) return;
-    this.openConnection();
-  }
-
-  /**
-   * Closes the SSE connection and cancels any pending reconnect timers.
-   *
-   * @example
-   * manager.disconnect();
-   */
-  disconnect(): void {
-    this.destroyed = true;
-    this.cleanup();
-  }
-
-  private openConnection(): void {
-    if (this.destroyed) return;
-
-    try {
-      // Append API key as query parameter for SSE (EventSource doesn't support custom headers)
-      const url = new URL(this.options.url);
-      url.searchParams.set('apiKey', this.options.apiKey);
-
-      this.eventSource = new EventSource(url.toString());
-
-      this.eventSource.addEventListener('open', () => {
-        this.connected = true;
-        this.reconnectAttempt = 0;
-        this.options.onStateChange?.(true);
-      });
-
-      this.eventSource.addEventListener('message', (evt: MessageEvent<string>) => {
-        this.handleMessage(evt.data);
-      });
-
-      // Go-Gin sends events with event type 'message' by default
-      // Also listen for explicitly typed events
-      this.eventSource.addEventListener('flag_update', (evt: MessageEvent<string>) => {
-        this.handleMessage(evt.data);
-      });
-
-      this.eventSource.addEventListener('error', () => {
-        this.connected = false;
-        this.options.onStateChange?.(false);
-        this.cleanup();
-        this.scheduleReconnect();
-      });
-    } catch {
-      this.scheduleReconnect();
-    }
-  }
-
-  private handleMessage(data: string): void {
-    try {
-      const event = JSON.parse(data) as FlagStreamEvent;
-      this.options.onEvent(event);
-    } catch {
-      // Ignore malformed SSE payloads — never crash the host application
-    }
-  }
-
-  private cleanup(): void {
-    if (this.eventSource) {
-      this.eventSource.close();
-      this.eventSource = null;
-    }
-    if (this.reconnectTimer !== null) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-  }
-
-  private scheduleReconnect(): void {
-    if (this.destroyed) return;
-    if (this.reconnectAttempt >= this.maxReconnects) return;
-
-    const delay = computeBackoffMs(this.reconnectAttempt, 1000, 30_000);
-    this.reconnectAttempt++;
-
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      if (!this.destroyed) {
-        this.openConnection();
-      }
-    }, delay);
-  }
-}

package/src/storage.ts

@@ -1,187 +0,0 @@
-/**
- * @fileoverview In-memory flag storage with LocalStorage sync and incognito fallback.
- * @module @nexus/sdk-flags/storage
- */
-
-import type { FlagEvaluationResult } from '@nexussdk/contracts';
-
-const STORAGE_KEY_PREFIX = 'nexus_flags_';
-const ANON_ID_KEY = 'nexus_anon_id';
-
-/**
- * In-memory flag cache with optional LocalStorage persistence.
- * Falls back to pure in-memory storage in SSR / Incognito / Worker contexts.
- *
- * @example
- * const store = new FlagStorage('pk_live_abc123');
- * store.set('checkout_v2', { key: 'checkout_v2', enabled: true, variants: {}, reason: 'ROLLOUT_MATCH', version: 3 });
- * const result = store.get('checkout_v2');
- */
-export class FlagStorage {
-  private readonly memory = new Map<string, FlagEvaluationResult>();
-  private readonly storageKey: string;
-  private readonly localStorageAvailable: boolean;
-  private broadcastChannel: BroadcastChannel | null = null;
-
-  constructor(apiKeyPrefix: string) {
-    this.storageKey = `${STORAGE_KEY_PREFIX}${apiKeyPrefix}`;
-    this.localStorageAvailable = this.testLocalStorage();
-    this.hydrate();
-    this.setupBroadcastChannel();
-  }
-
-  /**
-   * Stores a flag evaluation result in memory (and localStorage if available).
-   *
-   * @param key - Flag programmatic key.
-   * @param result - Evaluation result to persist.
-   */
-  set(key: string, result: FlagEvaluationResult): void {
-    this.memory.set(key, result);
-    this.persist();
-    this.broadcastUpdate(key, result);
-  }
-
-  /**
-   * Retrieves a flag evaluation result by key.
-   *
-   * @param key - Flag programmatic key.
-   * @returns The cached evaluation result or `undefined`.
-   */
-  get(key: string): FlagEvaluationResult | undefined {
-    return this.memory.get(key);
-  }
-
-  /**
-   * Bulk-sets multiple flag results (e.g. after a batch fetch).
-   *
-   * @param flags - Record of flag key → evaluation result.
-   */
-  setAll(flags: Record<string, FlagEvaluationResult>): void {
-    for (const [key, value] of Object.entries(flags)) {
-      this.memory.set(key, value);
-    }
-    this.persist();
-  }
-
-  /**
-   * Removes a single flag from storage (e.g. on FLAG_DELETE SSE event).
-   *
-   * @param key - Flag programmatic key.
-   */
-  delete(key: string): void {
-    this.memory.delete(key);
-    this.persist();
-  }
-
-  /**
-   * Returns all cached flag results.
-   *
-   * @returns All stored flag results as a record.
-   */
-  getAll(): Record<string, FlagEvaluationResult> {
-    return Object.fromEntries(this.memory.entries());
-  }
-
-  /**
-   * Clears all cached flags from memory and localStorage.
-   */
-  clear(): void {
-    this.memory.clear();
-    if (this.localStorageAvailable) {
-      try {
-        window.localStorage.removeItem(this.storageKey);
-      } catch {
-        // Storage access denied
-      }
-    }
-    this.broadcastChannel?.close();
-  }
-
-  /**
-   * Retrieves or creates a persistent anonymous user ID.
-   *
-   * @returns Anonymous ID string (e.g. "anon_xyz123abc").
-   */
-  getOrCreateAnonymousId(): string {
-    if (typeof window === 'undefined') return 'anon-ssr-node';
-
-    if (this.localStorageAvailable) {
-      try {
-        let id = window.localStorage.getItem(ANON_ID_KEY);
-        if (!id) {
-          id = `anon_${Math.random().toString(36).substring(2, 11)}`;
-          window.localStorage.setItem(ANON_ID_KEY, id);
-        }
-        return id;
-      } catch {
-        // Incognito / locked storage
-      }
-    }
-
-    return `anon_${Math.random().toString(36).substring(2, 11)}`;
-  }
-
-  private testLocalStorage(): boolean {
-    try {
-      if (typeof window === 'undefined') return false;
-      const testKey = '__nexus_test__';
-      window.localStorage.setItem(testKey, '1');
-      window.localStorage.removeItem(testKey);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  private hydrate(): void {
-    if (!this.localStorageAvailable) return;
-    try {
-      const raw = window.localStorage.getItem(this.storageKey);
-      if (raw) {
-        const parsed = JSON.parse(raw) as Record<string, FlagEvaluationResult>;
-        for (const [key, value] of Object.entries(parsed)) {
-          this.memory.set(key, value);
-        }
-      }
-    } catch {
-      // Corrupt storage — start fresh
-    }
-  }
-
-  private persist(): void {
-    if (!this.localStorageAvailable) return;
-    try {
-      window.localStorage.setItem(
-        this.storageKey,
-        JSON.stringify(Object.fromEntries(this.memory.entries())),
-      );
-    } catch {
-      // Storage quota exceeded — in-memory only
-    }
-  }
-
-  private setupBroadcastChannel(): void {
-    try {
-      if (typeof BroadcastChannel !== 'undefined') {
-        this.broadcastChannel = new BroadcastChannel(`nexus_flags_${this.storageKey}`);
-        this.broadcastChannel.onmessage = (evt: MessageEvent<{ key: string; result: FlagEvaluationResult }>) => {
-          // Sync updates from other tabs into local memory cache
-          if (evt.data?.key && evt.data?.result) {
-            this.memory.set(evt.data.key, evt.data.result);
-          }
-        };
-      }
-    } catch {
-      // BroadcastChannel unavailable (e.g. Worker context)
-    }
-  }
-
-  private broadcastUpdate(key: string, result: FlagEvaluationResult): void {
-    try {
-      this.broadcastChannel?.postMessage({ key, result });
-    } catch {
-      // Broadcast failed — no-op
-    }
-  }
-}

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src"]
-}

package/tsup.config.ts

@@ -1,19 +0,0 @@
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: ['src/index.ts'],
-  format: ['esm', 'cjs', 'iife'],
-  globalName: 'NexusFlags',
-  dts: true,
-  splitting: false,
-  sourcemap: true,
-  clean: true,
-  minify: true,
-  treeshake: true,
-  target: 'es2022',
-  outExtension({ format }) {
-    return {
-      js: format === 'esm' ? '.mjs' : format === 'cjs' ? '.cjs' : '.global.js',
-    };
-  },
-});