@nexussdk/flags 0.0.1 → 0.0.4

package/src/evaluator.ts

@@ -1,268 +0,0 @@
-/**
- * @fileoverview MurmurHash3 32-bit implementation and ABAC rule evaluator.
- * Pure TypeScript — no external dependencies. Implements deterministic rollout bucketing.
- * @module @nexus/sdk-flags/evaluator
- */
-
-import type { FeatureFlag, FlagEvaluationResult, TargetingRule, UserContext } from '@nexussdk/contracts';
-
-// ---------------------------------------------------------------------------
-// MurmurHash3 32-bit Implementation (Pure TypeScript)
-// Used for deterministic user-to-bucket mapping without server round-trips.
-// ---------------------------------------------------------------------------
-
-/**
- * Converts a string to a Uint32 MurmurHash3 hash.
- * Implements the MurmurHash3 32-bit algorithm (x86 variant).
- *
- * @param key - Input string to hash.
- * @param seed - Optional seed value. Defaults to 0.
- * @returns Unsigned 32-bit integer hash value.
- *
- * @example
- * const hash = murmur3('user123:checkout_v2', 0);
- * const bucket = hash % 100; // 0-99 deterministic bucket
- */
-export function murmur3(key: string, seed = 0): number {
-  let h = seed >>> 0;
-  const c1 = 0xcc9e2d51;
-  const c2 = 0x1b873593;
-
-  let i = 0;
-  // Process 4-byte chunks
-  const length4 = Math.floor(key.length / 4) * 4;
-  while (i < length4) {
-    let k =
-      ((key.charCodeAt(i) & 0xff)) |
-      ((key.charCodeAt(i + 1) & 0xff) << 8) |
-      ((key.charCodeAt(i + 2) & 0xff) << 16) |
-      ((key.charCodeAt(i + 3) & 0xff) << 24);
-
-    k = Math.imul(k, c1);
-    k = (k << 15) | (k >>> 17);
-    k = Math.imul(k, c2);
-
-    h ^= k;
-    h = (h << 13) | (h >>> 19);
-    h = (Math.imul(h, 5) + 0xe6546b64) >>> 0;
-    i += 4;
-  }
-
-  // Process remaining bytes
-  let k2 = 0;
-  const rem = key.length & 3;
-  if (rem >= 3) k2 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
-  if (rem >= 2) k2 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
-  if (rem >= 1) {
-    k2 ^= key.charCodeAt(i) & 0xff;
-    k2 = Math.imul(k2, c1);
-    k2 = (k2 << 15) | (k2 >>> 17);
-    k2 = Math.imul(k2, c2);
-    h ^= k2;
-  }
-
-  // Finalization mix
-  h ^= key.length;
-  h ^= h >>> 16;
-  h = Math.imul(h, 0x85ebca6b);
-  h ^= h >>> 13;
-  h = Math.imul(h, 0xc2b2ae35);
-  h ^= h >>> 16;
-
-  return h >>> 0; // Ensure unsigned
-}
-
-/**
- * Computes the deterministic rollout bucket (0-99) for a given user+flag combination.
- * Uses MurmurHash3 for even distribution without server state.
- *
- * @param userId - User's unique identifier (anonymous ID if not authenticated).
- * @param flagKey - Flag programmatic key.
- * @returns Bucket value between 0 and 99 (inclusive).
- *
- * @example
- * const bucket = computeRolloutBucket('usr_12345', 'checkout_v2');
- * // isEnabled = bucket < flag.rolloutPercentage
- */
-export function computeRolloutBucket(userId: string, flagKey: string): number {
-  const hashInput = `${userId}:${flagKey}`;
-  return murmur3(hashInput) % 100;
-}
-
-// ---------------------------------------------------------------------------
-// ABAC Rule Evaluator
-// ---------------------------------------------------------------------------
-
-/**
- * Performs a simple semantic version comparison.
- * Compares two semver strings in "MAJOR.MINOR.PATCH" format.
- *
- * @param a - First version string.
- * @param b - Second version string.
- * @returns Positive if a > b, negative if a < b, 0 if equal.
- */
-function compareSemver(a: string, b: string): number {
-  const partsA = a.replace(/^v/, '').split('.').map(Number);
-  const partsB = b.replace(/^v/, '').split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
-    if (diff !== 0) return diff;
-  }
-  return 0;
-}
-
-/**
- * Extracts a nested attribute value from the UserContext by dot-notation path.
- *
- * @param ctx - UserContext object.
- * @param attributePath - Dot-separated path (e.g. "custom.tier", "country").
- * @returns The attribute value or `undefined` if not found.
- */
-function resolveAttribute(ctx: UserContext, attributePath: string): unknown {
-  const parts = attributePath.split('.');
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let current: any = ctx;
-  for (const part of parts) {
-    if (current == null || typeof current !== 'object') return undefined;
-    current = current[part];
-  }
-  return current;
-}
-
-/**
- * Evaluates a single targeting rule against the user context.
- *
- * @param rule - The ABAC targeting rule to evaluate.
- * @param userCtx - The current user context.
- * @returns `true` if the rule passes for this user.
- */
-function evaluateSingleRule(rule: TargetingRule, userCtx: UserContext): boolean {
-  const userValue = resolveAttribute(userCtx, rule.attribute);
-  const targets = rule.values;
-
-  switch (rule.operator) {
-    case 'EQUALS':
-      return userValue === targets[0];
-    case 'NOT_EQUALS':
-      return userValue !== targets[0];
-    case 'IN':
-      return targets.includes(userValue as string | number | boolean);
-    case 'NOT_IN':
-      return !targets.includes(userValue as string | number | boolean);
-    case 'CONTAINS':
-      return typeof userValue === 'string' && userValue.includes(String(targets[0]));
-    case 'NOT_CONTAINS':
-      return typeof userValue === 'string' && !userValue.includes(String(targets[0]));
-    case 'STARTS_WITH':
-      return typeof userValue === 'string' && userValue.startsWith(String(targets[0]));
-    case 'ENDS_WITH':
-      return typeof userValue === 'string' && userValue.endsWith(String(targets[0]));
-    case 'GREATER_THAN':
-      return typeof userValue === 'number' && userValue > Number(targets[0]);
-    case 'LESS_THAN':
-      return typeof userValue === 'number' && userValue < Number(targets[0]);
-    case 'SEMVER_GTE':
-      return (
-        typeof userValue === 'string' &&
-        typeof targets[0] === 'string' &&
-        compareSemver(userValue, String(targets[0])) >= 0
-      );
-    case 'SEMVER_LTE':
-      return (
-        typeof userValue === 'string' &&
-        typeof targets[0] === 'string' &&
-        compareSemver(userValue, String(targets[0])) <= 0
-      );
-    default:
-      return false;
-  }
-}
-
-/**
- * Evaluates a FeatureFlag against a UserContext using the full ABAC + rollout engine.
- *
- * Evaluation Order:
- * 1. Kill-switch check (`isEnabled === false` → KILL_SWITCH)
- * 2. All targeting rules must pass (ABAC evaluation)
- * 3. Percentage rollout via MurmurHash3 bucketing
- * 4. Default enabled state
- *
- * @param flag - The feature flag definition from the cache.
- * @param userCtx - Current user context for targeting evaluation.
- * @returns Full {@link FlagEvaluationResult} with reason explanation.
- *
- * @example
- * const result = evaluateFlag(flag, { id: 'usr_12345', country: 'VN' });
- * if (result.enabled) {
- *   console.log(result.variants.discount_rate); // 20
- * }
- */
-export function evaluateFlag(flag: FeatureFlag, userCtx: UserContext): FlagEvaluationResult {
-  // Step 1: Kill-switch
-  if (!flag.isEnabled) {
-    return {
-      key: flag.key,
-      enabled: false,
-      variants: {},
-      reason: 'KILL_SWITCH',
-      version: flag.version,
-    };
-  }
-
-  // Step 2: ABAC targeting rules — all must pass (AND logic)
-  if (flag.targetingRules.length > 0) {
-    const allRulesPass = flag.targetingRules.every((rule) =>
-      evaluateSingleRule(rule, userCtx),
-    );
-    if (!allRulesPass) {
-      return {
-        key: flag.key,
-        enabled: false,
-        variants: {},
-        reason: 'FALLBACK',
-        version: flag.version,
-      };
-    }
-    // All targeting rules matched
-    if (flag.rolloutPercentage >= 100) {
-      return {
-        key: flag.key,
-        enabled: true,
-        variants: flag.variants,
-        reason: 'TARGETING_MATCH',
-        version: flag.version,
-      };
-    }
-  }
-
-  // Step 3: Percentage rollout (MurmurHash3)
-  if (flag.rolloutPercentage > 0) {
-    const userId = userCtx.id ?? 'anon';
-    const bucket = computeRolloutBucket(userId, flag.key);
-    if (bucket < flag.rolloutPercentage) {
-      return {
-        key: flag.key,
-        enabled: true,
-        variants: flag.variants,
-        reason: flag.targetingRules.length > 0 ? 'TARGETING_MATCH' : 'ROLLOUT_MATCH',
-        version: flag.version,
-      };
-    }
-    return {
-      key: flag.key,
-      enabled: false,
-      variants: {},
-      reason: 'FALLBACK',
-      version: flag.version,
-    };
-  }
-
-  // Step 4: Full kill-switch off (rolloutPercentage === 0 with no rules)
-  return {
-    key: flag.key,
-    enabled: false,
-    variants: {},
-    reason: 'KILL_SWITCH',
-    version: flag.version,
-  };
-}

package/src/index.ts

@@ -1,14 +0,0 @@
-/**
- * @fileoverview Public export interface for @nexussdk/flags.
- *
- * @example
- * import { NexusFlagsClient } from '@nexussdk/flags';
- * const client = new NexusFlagsClient({ apiKey: 'pk_live_...' });
- */
-
-export { NexusFlagsClient } from './client.js';
-export type { NexusFlagsOptions, INexusFlagsClient } from './client.js';
-export { evaluateFlag, murmur3, computeRolloutBucket } from './evaluator.js';
-export { SSEManager } from './sse-manager.js';
-export type { SSEManagerOptions } from './sse-manager.js';
-export { FlagStorage } from './storage.js';

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',
-    };
-  },
-});