@nexussdk/flags 0.0.1 → 0.0.4

package/README.md

@@ -0,0 +1,210 @@
+# @nexussdk/flags
+
+> Ultra-lightweight, production-grade feature flags and remote config client SDK for browsers and edge runtimes with MurmurHash3 bucketing, ABAC rule evaluation, real-time SSE hot-swapping, and zero-infra local dev server (< 8KB gzipped).
+
+[![npm version](https://img.shields.io/npm/v/@nexussdk/flags.svg)](https://www.npmjs.com/package/@nexussdk/flags)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/badge/bundle_size-<8KB_gzipped-success.svg)](https://bundlephobia.com)
+
+---
+
+## Key Features
+
+- **Deterministic Rollout**: Pure TypeScript MurmurHash3 32-bit algorithm guarantees deterministic 0–100% percentage bucketing matching server-side evaluation with zero network round-trips.
+- **ABAC Rule Engine**: Full attribute-based access control engine supporting string, number, array (`IN`, `NOT_IN`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`), comparison operators (`GREATER_THAN`, `LESS_THAN`), and semantic versioning (`SEMVER_GTE`, `SEMVER_LTE`).
+- **Real-Time Streaming (SSE)**: Built-in `SSEManager` with singleton connection pooling, exponential backoff reconnects, and instant `FLAG_UPDATE` / `FLAG_DELETE` live sync.
+- **Offline-First & Bootstrap**: Instant 0ms boot via `bootstrap` options (SSR pre-evaluation, local JSON file, or boolean dictionary) with background revalidation.
+- **Cross-Tab Synchronization**: In-memory cache backed by optional `localStorage` and `BroadcastChannel` for instant cross-tab state consistency.
+- **Built-in Local Dev Server & GUI**: `nexus-flags-dev` CLI provides a zero-dependency local server with single-file web dashboard, JSON file persistence (`nexus-flags.json`), and live SSE broadcasting.
+
+---
+
+## Installation
+
+```bash
+pnpm add @nexussdk/flags
+# or
+npm install @nexussdk/flags
+```
+
+*(If using React or Vue, install `@nexussdk/sdk` instead for built-in hooks like `useFeatureFlag` and `useVariant`).*
+
+---
+
+## Quickstart (Vanilla JS / TypeScript)
+
+```typescript
+import { NexusFlagsClient } from '@nexussdk/flags';
+
+// 1. Initialize client
+const flags = new NexusFlagsClient({
+  apiKey: 'pk_live_your_api_key',
+  baseUrl: 'https://api.nexus.dev',
+  user: {
+    id: 'usr_4829',
+    country: 'VN',
+    plan: 'enterprise',
+    appVersion: '2.4.0',
+  },
+  realtime: true, // Enable SSE live streaming
+});
+
+// 2. Synchronous evaluation (0ms from cache / bootstrap)
+if (flags.isEnabled('new_checkout_flow', false)) {
+  mountNewCheckout();
+} else {
+  mountLegacyCheckout();
+}
+
+// 3. Dynamic variant configurations
+const discountRate = flags.getVariant<number>('promo_banner_v2', 'discount_rate', 0);
+const layoutTheme = flags.getVariant<string>('checkout_v2', 'theme', 'standard');
+
+// 4. Listen for realtime hot-swap updates
+const unsubscribe = flags.onFlagChange('new_checkout_flow', (result) => {
+  console.log('Flag updated in realtime:', result.enabled, result.reason);
+  if (result.enabled) {
+    mountNewCheckout();
+  }
+});
+
+// 5. Update user identity (e.g. after login)
+await flags.identify({
+  id: 'usr_9981',
+  country: 'SG',
+  plan: 'pro',
+});
+
+// 6. Reset user on logout
+flags.reset();
+
+// 7. Cleanup on unmount
+unsubscribe();
+flags.destroy();
+```
+
+---
+
+## Configuration Options (`NexusFlagsOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `apiKey` | `string` | Env | Public API key (`pk_live_...` or `nxs_dev_...`) |
+| `baseUrl` | `string` | `https://api.nexus.dev` | Ingestion endpoint URL |
+| `user` | `UserContext` | Anonymous UUID | Initial user identity for ABAC rules and rollout bucketing |
+| `bootstrap` | `Record<string, ...>` | `undefined` | Pre-hydrated flags for 0ms SSR boot or offline JSON mode |
+| `realtime` | `boolean` | `true` | Enables Server-Sent Events (SSE) stream subscription |
+| `timeoutMs` | `number` | `3000` | Network timeout for background evaluation refresh |
+
+---
+
+## Offline & Bootstrap Mode (Local JSON)
+
+For small projects or offline development, you can completely bypass backend servers by bootstrapping flags from a local JSON file:
+
+```typescript
+import localFlags from './nexus-flags.json';
+
+const flags = new NexusFlagsClient({
+  bootstrap: localFlags,
+  realtime: false, // Optional: disable network calls completely
+});
+
+// Ready immediately without any network calls
+const isDarkMode = flags.isEnabled('dark_mode', false);
+```
+
+The `bootstrap` parameter accepts:
+- Simple boolean flags: `{ dark_mode: true, beta_ui: false }`
+- Standard `nexus-flags.json` objects created by the dev server
+- Full `FlagEvaluationResult` maps generated from SSR
+
+---
+
+## Local Dev Server (`nexus-flags-dev`)
+
+The `@nexussdk/flags` package includes a standalone local flag management CLI with an embedded Web GUI dashboard:
+
+```bash
+# Start local flag management server
+npx nexus-flags-dev
+# or in this monorepo
+pnpm --filter @nexussdk/flags flags-server
+```
+
+### CLI Options
+
+```bash
+nexus-flags-dev [options]
+
+Options:
+  -p, --port <number>   Port to listen on (default: 4568)
+  --host <string>       Host interface to bind (default: localhost)
+  -f, --file <path>     Path to JSON flags file (default: ./nexus-flags.json)
+  -h, --help            Show help message
+```
+
+### Endpoints
+
+| Method | Endpoint | Description |
+| :--- | :--- | :--- |
+| `GET` | `/` or `/gui` | Interactive Web GUI Dashboard |
+| `GET` | `/health` | Health status and connected clients count |
+| `GET` | `/api/v1/flags` | List all flags (JSON) |
+| `POST` | `/api/v1/flags` | Create a new flag |
+| `GET` | `/api/v1/flags/:key` | Retrieve a single flag definition |
+| `PATCH` | `/api/v1/flags/:key` | Update flag properties, rollout %, or variants |
+| `POST` | `/api/v1/flags/:key/toggle` | Toggle enabled switch & broadcast to clients |
+| `DELETE` | `/api/v1/flags/:key` | Delete flag & broadcast deletion |
+| `GET` | `/api/v1/flags/stream` | Real-time SSE stream for SDK live hot-swap |
+| `GET` | `/api/v1/flags/eval` | Evaluation snapshot for SDK background refresh |
+| `GET` | `/api/v1/flags/bootstrap` | Pre-load snapshot for SSR bootstrap |
+
+### Connecting SDK to Local Dev Server
+
+```typescript
+const client = new NexusFlagsClient({
+  apiKey: 'nxs_dev_local',
+  baseUrl: 'http://localhost:4568',
+  realtime: true, // Whenever you toggle a flag in the GUI, your app updates instantly!
+});
+```
+
+---
+
+## Programmatic Dev Server Export
+
+You can also embed the flags dev server programmatically in your test harness or Vite dev server:
+
+```typescript
+import { startFlagsDevServer } from '@nexussdk/flags/dev-server';
+
+const devServer = await startFlagsDevServer({
+  port: 4568,
+  flagsFile: './test-flags.json',
+  seed: true,
+});
+
+// Later in teardown:
+await devServer.close();
+```
+
+---
+
+## Framework Compatibility Matrix
+
+`@nexussdk/flags` is completely framework-agnostic with zero runtime dependencies. It supports modern and legacy frontends:
+
+| Framework | Supported Versions | Paradigm | Documentation |
+| :--- | :--- | :--- | :--- |
+| **React / Next.js** | React 16.8 – 19 / Next.js 13 – 16 | Server Components, Hooks, Context | [React Integration Guide](https://nexus.dev/sdk-flags/react-integration/) |
+| **Vue / Nuxt** | Vue 2.7 & 3.x / Nuxt 3 & 4 | Composition API, `<script setup>`, SSR | [Vue Integration Guide](https://nexus.dev/sdk-flags/frameworks/vue/) |
+| **Angular** | Angular 14 – 19+ / AngularJS | Signals (`@if`), Standalone, RxJS | [Angular Integration Guide](https://nexus.dev/sdk-flags/frameworks/angular/) |
+| **Svelte / SvelteKit** | Svelte 3 – 5 / SvelteKit 1 & 2 | Runes (`$state`), Stores (`writable`) | [Svelte Integration Guide](https://nexus.dev/sdk-flags/frameworks/svelte/) |
+| **Vanilla JS / Node.js** | Any ES2022+ runtime (Solid, Qwik, Lit) | Direct Class instance | [Vanilla JS Guide](https://nexus.dev/sdk-flags/frameworks/vanilla/) |
+
+---
+
+## License
+
+MIT © [Nexus Platform](https://github.com/Huynhdung295/NexusSDK)