@lovart-open/flags 0.0.1-canary.pr4.7b8e2dd

package/README.md

@@ -0,0 +1,279 @@
+# @lovart-open/flags
+
+[![CI](https://github.com/lovartai/statsig/actions/workflows/ci.yml/badge.svg)](https://github.com/lovartai/statsig/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@lovart-open/flags.svg)](https://www.npmjs.com/package/@lovart-open/flags)
+
+Type-safe Feature Flag and Parameter Store library built on Statsig, with a fully synchronous architecture.
+
+## Installation
+
+```bash
+npm install @lovart-open/flags
+# or
+pnpm add @lovart-open/flags
+```
+
+## Initialize Statsig
+
+Initialize the Statsig client at your app entry point:
+
+```ts
+import { initStatsigClient } from '@lovart-open/flags/statsig';
+
+initStatsigClient('your-statsig-client-key', { userID: 'user-123' }, {
+  environment: { tier: 'production' },
+});
+```
+
+---
+
+# Feature Flags
+
+## Core Features
+
+- **Type-safe**: Full TypeScript type inference and autocomplete
+- **Synchronous**: No loading states, no skeleton screens
+- **Multi-layer priority**: `URL > testOverride > override > remote > fallback(false)`
+
+## Define and Create
+
+```ts
+import { createFlagStore, type FlagDefinition } from '@lovart-open/flags/statsig';
+
+// 1. Define your flags
+const MY_FLAGS = {
+  dark_mode: { 
+    description: 'Dark mode toggle' 
+  },
+  new_checkout: { 
+    description: 'New checkout flow',
+    testOverride: true,  // Force enable in E2E tests
+  },
+  beta_feature: {
+    description: 'Beta feature',
+    override: false,     // Static override, ignores remote
+  },
+} as const satisfies Record<string, FlagDefinition>;
+
+// 2. Create type-safe store and hooks
+export const { 
+  flagStore, 
+  useFlag, 
+  useFlagState 
+} = createFlagStore(MY_FLAGS);
+
+// 3. Export types (optional)
+export type MyFlagKey = keyof typeof MY_FLAGS;
+```
+
+## React Usage
+
+```tsx
+import { useFlag, useFlagState } from './my-flags';
+
+function App() {
+  // Get boolean value directly
+  const isDark = useFlag('dark_mode');  // ✓ autocomplete
+  
+  // Get full state with source info
+  const state = useFlagState('new_checkout');
+  console.log(state.flag, state.source);  // true, 'remote'
+  
+  return isDark ? <DarkTheme /> : <LightTheme />;
+}
+```
+
+## Non-React Usage
+
+```ts
+import { flagStore } from './my-flags';
+
+// Get single flag
+const enabled = flagStore.getFlag('dark_mode');
+
+// Get snapshot of all flags
+const snapshot = flagStore.snapshot;
+```
+
+## URL Override for Debugging
+
+```
+?ff.dark_mode=1    → Force enable
+?ff.dark_mode=0    → Force disable
+```
+
+---
+
+# Parameter Store
+
+## Core Features
+
+- **Type-safe**: Zod schema validation + TypeScript inference
+- **Synchronous**: Same as Feature Flags
+- **Multi-layer priority**: `URL > testOverride > override > remote > fallback`
+
+## Define and Create
+
+```ts
+import { z } from 'zod';
+import { 
+  createParamStore, 
+  defineParam, 
+  type ParamStoreDefinition 
+} from '@lovart-open/flags/statsig';
+
+// 1. Define your param stores
+const MY_PARAMS = {
+  homepage_cta: {
+    description: 'Homepage CTA button',
+    params: {
+      text: defineParam({
+        schema: z.enum(['Learn More', 'Get Started', 'Sign Up']),
+        fallback: 'Learn More',
+        description: 'Button text',
+      }),
+      color: defineParam({
+        schema: z.enum(['gray', 'red', 'blue']),
+        fallback: 'gray',
+        testOverride: 'blue',  // Use in E2E tests
+      }),
+      visible: defineParam({
+        schema: z.boolean(),
+        fallback: true,
+      }),
+    },
+  },
+  pricing: {
+    description: 'Pricing config',
+    params: {
+      discount: defineParam({
+        schema: z.number().min(0).max(100),
+        fallback: 0,
+      }),
+      currency: defineParam({
+        schema: z.enum(['USD', 'CNY', 'EUR']),
+        fallback: 'USD',
+      }),
+    },
+  },
+} as const satisfies Record<string, ParamStoreDefinition<any>>;
+
+// 2. Create type-safe store and hooks
+export const { 
+  paramStore, 
+  useParam, 
+  useParamState, 
+  useParamStore 
+} = createParamStore(MY_PARAMS);
+```
+
+## React Usage
+
+```tsx
+import { useParam, useParamStore } from './my-params';
+
+function CTAButton() {
+  // Get value directly (with full type hints)
+  const text = useParam('homepage_cta', 'text');   // 'Learn More' | 'Get Started' | 'Sign Up'
+  const color = useParam('homepage_cta', 'color'); // 'gray' | 'red' | 'blue'
+
+  // Or get entire store handle
+  const store = useParamStore('homepage_cta');
+  const visible = store.get('visible');  // boolean
+
+  if (!visible) return null;
+  return <button style={{ color }}>{text}</button>;
+}
+```
+
+## Non-React Usage
+
+```ts
+import { paramStore } from './my-params';
+
+// Get single param
+const discount = paramStore.getParam('pricing', 'discount');  // number
+
+// Get store handle
+const store = paramStore.getStore('pricing');
+store.get('currency');  // 'USD' | 'CNY' | 'EUR'
+```
+
+## URL Override for Debugging
+
+```
+# Single param override
+?fp.homepage_cta.text=Get Started
+?fp.pricing.discount=20
+
+# Entire store JSON override
+?fp.homepage_cta={"text":"Get Started","visible":false}
+```
+
+---
+
+# Advanced Configuration
+
+## Custom Logger
+
+```ts
+import { initStatsigClient, setLogger } from '@lovart-open/flags/statsig';
+
+// Option 1: Pass during init
+initStatsigClient('client-xxx', { userID: 'user-123' }, {
+  logger: (message) => myLogger.info(message),
+});
+
+// Option 2: Set globally
+setLogger((message) => myLogger.info(message));
+```
+
+## E2E Test Support
+
+Configure `isTestEnv` in initialization to enable `testOverride` values:
+
+```ts
+initStatsigClient('client-xxx', { userID: 'user-123' }, {
+  isTestEnv: () => Boolean(window.__E2E__),
+});
+
+// playwright/cypress tests
+await page.addInitScript(() => {
+  window.__E2E__ = true;
+});
+```
+
+## Server-Side Bootstrap (Zero-Network Init)
+
+```ts
+initStatsigClient('client-xxx', { userID: 'user-123' }, {
+  bootstrap: {
+    data: bootstrapDataFromServer,  // Pre-fetched from BFF
+  },
+});
+```
+
+## FlagDefinition Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `description` | `string` | Human-readable description |
+| `testOverride` | `boolean` | Fixed value in E2E tests |
+| `override` | `boolean` | Static override (priority over remote) |
+| `keep` | `boolean` | Mark as kept locally (no remote needed) |
+
+## ParamDefinition Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `schema` | `z.ZodType` | Zod schema (required) |
+| `fallback` | `T` | Default value (required) |
+| `description` | `string` | Human-readable description |
+| `testOverride` | `T` | Fixed value in E2E tests |
+| `override` | `T` | Static override |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lovart-open/flags",
+  "version": "0.0.1-canary.pr4.7b8e2dd",
+  "description": "Feature flag management with multi-layer priority system (client-side)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./statsig": {
+      "types": "./src/statsig/index.ts",
+      "default": "./src/statsig/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "feature-flag",
+    "statsig",
+    "parameter-store"
+  ],
+  "author": "huxingyu@liblib.ai",
+  "license": "MIT",
+  "dependencies": {
+    "@statsig/js-client": "^3.30.0",
+    "@statsig/react-bindings": "^3.30.2",
+    "lodash": "^4.17.21",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/lodash": "^4.17.0",
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "jsdom": "^23.0.1",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lovartai/flags.git"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/flag-store.test.ts

@@ -0,0 +1,102 @@
+// Mock external dependencies
+const mockGetFeatureGate = vi.fn();
+const mockIsTestEnv = vi.fn(() => false);
+vi.mock('../statsig/client', () => ({
+  getStatsigClientSync: vi.fn(() => ({
+    getFeatureGate: mockGetFeatureGate,
+  })),
+  isTestEnv: () => mockIsTestEnv(),
+}));
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { createFlagStore, type FlagDefinition } from '../statsig';
+
+describe('FlagStore', () => {
+  const mockFlags = {
+    feature_a: { description: 'Feature A' },
+    feature_b: { description: 'Feature B', testOverride: true },
+    feature_c: { description: 'Feature C', override: false },
+  } as const satisfies Record<string, FlagDefinition>;
+
+  const { flagStore } = createFlagStore(mockFlags);
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    mockGetFeatureGate.mockReturnValue({
+      value: false,
+      idType: '',
+    });
+    mockIsTestEnv.mockReturnValue(false);
+    vi.stubGlobal('location', {
+      search: '',
+      pathname: '/',
+      hash: '',
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe('Initial State', () => {
+    it('should initialize with fallback state', () => {
+      const state = flagStore.getFlagState('feature_a');
+      expect(state.flag).toBe(false);
+      expect(state.source).toBe('fallback');
+    });
+  });
+
+  describe('Priority Logic', () => {
+    it('Priority 1: URL Override should win', () => {
+      vi.stubGlobal('location', {
+        search: '?ff.feature_a=1',
+        href: 'http://localhost/?ff.feature_a=1',
+      });
+      const urlState = flagStore.resolve('feature_a', { search: '?ff.feature_a=1' });
+      expect(urlState.flag).toBe(true);
+      expect(urlState.source).toBe('url');
+    });
+
+    it('Priority 2: Test Override should win over code static override', () => {
+      mockIsTestEnv.mockReturnValue(true);
+      const state = flagStore.getFlagState('feature_b');
+      expect(state.flag).toBe(true);
+      expect(state.source).toBe('test');
+    });
+
+    it('Priority 3: Code Static Override should win over remote', () => {
+      mockGetFeatureGate.mockReturnValue({ value: true, idType: 'userID' });
+      const state = flagStore.getFlagState('feature_c');
+      expect(state.flag).toBe(false);
+      expect(state.source).toBe('override');
+    });
+
+    it('Priority 4: Remote Value should win over fallback', () => {
+      mockGetFeatureGate.mockReturnValue({ value: true, idType: 'userID' });
+      const state = flagStore.getFlagState('feature_a');
+      expect(state.source).toBe('remote');
+      expect(state.flag).toBe(true);
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('should have type-safe keys', () => {
+      // These calls should have type hints
+      flagStore.getFlag('feature_a');
+      flagStore.getFlag('feature_b');
+      flagStore.getFlag('feature_c');
+
+      // Uncommenting below should cause compile error
+      // flagStore.getFlag('unknown_key');
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should support explicit remoteValue passed to resolve', () => {
+      const state = flagStore.resolve('feature_a', { gate: { value: true, idType: 'useID' } as any });
+      expect(state.flag).toBe(true);
+      expect(state.source).toBe('remote');
+    });
+  });
+});

package/src/__tests__/param-store.test.ts

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+
+// Mock statsig
+const mockIsTestEnv = vi.fn(() => false);
+vi.mock('../statsig/client', () => ({
+  getStatsigClientSync: vi.fn(() => ({
+    getParameterStore: vi.fn(),
+  })),
+  isTestEnv: () => mockIsTestEnv(),
+}));
+
+import { createParamStore, defineParam, type ParamStoreDefinition, getStatsigClientSync } from '../statsig';
+
+describe('ParamStore', () => {
+  const testStores = {
+    test_store: {
+      description: 'Test store',
+      params: {
+        text: defineParam({ schema: z.string(), fallback: 'default text' }),
+        count: defineParam({ schema: z.number(), fallback: 0 }),
+        enabled: defineParam({ schema: z.boolean(), fallback: false }),
+        color: defineParam({
+          schema: z.enum(['red', 'blue', 'green']),
+          fallback: 'red' as const,
+          testOverride: 'blue' as const,
+        }),
+        size: defineParam({
+          schema: z.number(),
+          fallback: 10,
+          override: 20,
+        }),
+      },
+    },
+  } as const satisfies Record<string, ParamStoreDefinition<any>>;
+
+  const { paramStore } = createParamStore(testStores);
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    mockIsTestEnv.mockReturnValue(false);
+    vi.stubGlobal('location', { search: '' });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe('getParam / getParamState', () => {
+    it('returns fallback value when remote has no config', () => {
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: vi.fn(() => ({
+          get: (_key: string, fallback: unknown) => fallback,
+        })),
+      } as any);
+
+      const value = paramStore.getParam('test_store', 'text');
+      expect(value).toBe('default text');
+
+      const state = paramStore.getParamState('test_store', 'text');
+      expect(state.value).toBe('default text');
+      expect(state.source).toBe('fallback');
+    });
+
+    it('returns remote value when remote has data', () => {
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: vi.fn(() => ({
+          __configuration: {
+            text: { value: 'remote text' },
+          },
+          get: (key: string) => (key === 'text' ? 'remote text' : undefined),
+        })),
+      } as any);
+
+      const state = paramStore.getParamState('test_store', 'text');
+      expect(state.value).toBe('remote text');
+      expect(state.source).toBe('remote');
+    });
+
+    it('URL override has highest priority', () => {
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: vi.fn(() => ({
+          __configuration: { text: { value: 'remote text' } },
+          get: () => 'remote text',
+        })),
+      } as any);
+
+      const state = paramStore.getParamState('test_store', 'text', {
+        search: '?fp.test_store.text=URL text',
+      });
+      expect(state.value).toBe('URL text');
+      expect(state.source).toBe('url');
+    });
+
+    it('testOverride works in E2E environment', () => {
+      mockIsTestEnv.mockReturnValue(true);
+
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: vi.fn(() => ({
+          get: () => 'green',
+        })),
+      } as any);
+
+      const state = paramStore.getParamState('test_store', 'color');
+      expect(state.value).toBe('blue');
+      expect(state.source).toBe('test');
+    });
+
+    it('override has priority over remote', () => {
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: vi.fn(() => ({
+          get: () => 30,
+        })),
+      } as any);
+
+      const state = paramStore.getParamState('test_store', 'size');
+      expect(state.value).toBe(20);
+      expect(state.source).toBe('override');
+    });
+
+    it('URL number type coercion', () => {
+      const state = paramStore.getParamState('test_store', 'count', {
+        search: '?fp.test_store.count=42',
+      });
+      expect(state.value).toBe(42);
+      expect(state.source).toBe('url');
+    });
+
+    it('URL boolean type coercion', () => {
+      const state = paramStore.getParamState('test_store', 'enabled', {
+        search: '?fp.test_store.enabled=true',
+      });
+      expect(state.value).toBe(true);
+      expect(state.source).toBe('url');
+    });
+  });
+
+  describe('getStore', () => {
+    it('returns handle object with { get, getState }', () => {
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: vi.fn(() => ({
+          get: (_key: string, fallback: unknown) => fallback,
+        })),
+      } as any);
+
+      const store = paramStore.getStore('test_store');
+
+      expect(typeof store.get).toBe('function');
+      expect(typeof store.getState).toBe('function');
+
+      expect(store.get('text')).toBe('default text');
+      expect(store.getState('count')).toEqual({ value: 0, source: 'fallback' });
+    });
+
+    it('handle reuses same statsigStore', () => {
+      const mockGetParameterStore = vi.fn(() => ({
+        get: (_key: string, fallback: unknown) => fallback,
+      }));
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: mockGetParameterStore,
+      } as any);
+
+      const store = paramStore.getStore('test_store');
+      store.get('text');
+      store.get('count');
+      store.getState('enabled');
+
+      // getParameterStore should only be called once (closure reuse)
+      expect(mockGetParameterStore).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('Priority Order', () => {
+    it('URL > test > override > remote > fallback', () => {
+      mockIsTestEnv.mockReturnValue(true);
+
+      vi.mocked(getStatsigClientSync).mockReturnValue({
+        getParameterStore: vi.fn(() => ({
+          get: () => 'green',
+        })),
+      } as any);
+
+      // color has testOverride='blue', remote='green'
+      // URL override should take priority
+      const state = paramStore.getParamState('test_store', 'color', {
+        search: '?fp.test_store.color=red',
+      });
+      expect(state.value).toBe('red');
+      expect(state.source).toBe('url');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('throws error for unknown store', () => {
+      expect(() => {
+        (paramStore as any).getParamState('unknown_store', 'text');
+      }).toThrow('[ParamStore] Unknown store: unknown_store');
+    });
+
+    it('throws error for unknown param', () => {
+      expect(() => {
+        (paramStore as any).getParamState('test_store', 'unknown_param');
+      }).toThrow('[ParamStore] Unknown param: test_store.unknown_param');
+    });
+
+    it('logs warning when URL value schema mismatch', () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      // count expects number, passing non-numeric string 'abc'
+      paramStore.getParamState('test_store', 'count', {
+        search: '?fp.test_store.count=abc',
+      });
+
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Schema mismatch'), 'abc', expect.anything());
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('should have type-safe store and param keys', () => {
+      // These calls should have type hints
+      paramStore.getParam('test_store', 'text'); // string
+      paramStore.getParam('test_store', 'count'); // number
+      paramStore.getParam('test_store', 'enabled'); // boolean
+      paramStore.getParam('test_store', 'color'); // 'red' | 'blue' | 'green'
+
+      // Uncommenting below should cause compile error
+      // paramStore.getParam('unknown_store', 'text');
+      // paramStore.getParam('test_store', 'unknown_param');
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @lovart-open/flags
+ *
+ * This package uses subpath exports. Import from:
+ * - @lovart-open/flags/statsig - Statsig-based feature flags and parameter stores
+ *
+ * @example
+ * import { createFlagStore, createParamStore } from '@lovart-open/flags/statsig';
+ */
+
+// No exports from root path - use subpath imports
+export {};