servcraft 0.1.0 → 0.1.3

package/docs/modules/FEATURE-FLAG.md

@@ -0,0 +1,291 @@
+# Feature Flag Module
+
+Feature flags for A/B testing, progressive rollouts, and feature management.
+
+## Features
+
+- **Multiple Strategies** - Boolean, percentage, user list, user attributes, date range
+- **User Targeting** - Target specific users or user segments
+- **Overrides** - Per-user or per-session overrides
+- **Analytics** - Track flag evaluations and usage statistics
+- **Environment Support** - Different flags per environment
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                   Feature Flag Service                       │
+├──────────────────────────────────────────────────────────────┤
+│  Flag CRUD  │  Evaluation Engine  │  Override Mgmt  │  Stats │
+└──────┬──────┴─────────┬───────────┴────────┬────────┴───┬────┘
+       │                │                    │            │
+       ▼                ▼                    ▼            ▼
+┌──────────────────────────────────────────────────────────────┐
+│               Prisma (Flags & Overrides)                     │
+│               Redis (Statistics)                             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| `boolean` | Simple on/off | Kill switches |
+| `percentage` | Percentage rollout | Gradual releases |
+| `user-list` | Specific user IDs | Beta testers |
+| `user-attribute` | User property rules | Segment targeting |
+| `date-range` | Time-based activation | Scheduled features |
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { createFeatureFlagService } from 'servcraft/modules/feature-flag';
+
+const flagService = createFeatureFlagService({
+  defaultEnvironment: 'production',
+  analytics: true,
+  cacheTtl: 300,
+});
+```
+
+### Creating Flags
+
+```typescript
+// Boolean flag
+await flagService.createFlag({
+  key: 'new-dashboard',
+  name: 'New Dashboard',
+  description: 'Enable the redesigned dashboard',
+  strategy: 'boolean',
+  config: { value: false },
+  status: 'active',
+  environment: 'production',
+});
+
+// Percentage rollout
+await flagService.createFlag({
+  key: 'new-checkout',
+  name: 'New Checkout Flow',
+  strategy: 'percentage',
+  config: { percentage: 25 }, // 25% of users
+  status: 'active',
+});
+
+// User list (beta testers)
+await flagService.createFlag({
+  key: 'beta-features',
+  name: 'Beta Features',
+  strategy: 'user-list',
+  config: { userIds: ['user-1', 'user-2', 'user-3'] },
+  status: 'active',
+});
+
+// User attributes
+await flagService.createFlag({
+  key: 'premium-features',
+  name: 'Premium Features',
+  strategy: 'user-attribute',
+  config: {
+    userAttributes: [
+      { attribute: 'plan', operator: 'in', value: ['pro', 'enterprise'] },
+      { attribute: 'accountAge', operator: 'gte', value: 30 },
+    ],
+  },
+  status: 'active',
+});
+
+// Date range
+await flagService.createFlag({
+  key: 'holiday-theme',
+  name: 'Holiday Theme',
+  strategy: 'date-range',
+  config: {
+    dateRange: {
+      start: '2024-12-20T00:00:00Z',
+      end: '2025-01-02T23:59:59Z',
+    },
+  },
+  status: 'active',
+});
+```
+
+### Evaluating Flags
+
+```typescript
+// Simple check
+const isEnabled = await flagService.isEnabled('new-dashboard', {
+  userId: 'user-123',
+  environment: 'production',
+});
+
+// Full evaluation with reason
+const result = await flagService.evaluateFlag('new-checkout', {
+  userId: 'user-123',
+  sessionId: 'session-456',
+  environment: 'production',
+  userAttributes: {
+    plan: 'pro',
+    accountAge: 45,
+    country: 'US',
+  },
+});
+// {
+//   key: 'new-checkout',
+//   enabled: true,
+//   reason: 'Percentage rollout: 25%',
+//   strategy: 'percentage',
+//   evaluatedAt: Date
+// }
+
+// Evaluate multiple flags
+const flags = await flagService.evaluateFlags(
+  ['new-dashboard', 'new-checkout', 'beta-features'],
+  { userId: 'user-123' }
+);
+// { 'new-dashboard': {...}, 'new-checkout': {...}, 'beta-features': {...} }
+```
+
+### Managing Flags
+
+```typescript
+// Update flag
+await flagService.updateFlag('new-checkout', {
+  config: { percentage: 50 }, // Increase to 50%
+});
+
+// Get flag
+const flag = await flagService.getFlag('new-checkout');
+
+// List flags
+const allFlags = await flagService.listFlags({
+  status: 'active',
+  environment: 'production',
+});
+
+// Delete flag
+await flagService.deleteFlag('old-feature');
+```
+
+### Overrides
+
+```typescript
+// Set user override (for testing/support)
+await flagService.setOverride(
+  'new-checkout',
+  'user-123',
+  'user',
+  true, // force enabled
+  new Date('2024-02-01') // expires
+);
+
+// Set session override
+await flagService.setOverride('new-checkout', 'session-456', 'session', false);
+
+// Remove override
+await flagService.removeOverride('new-checkout', 'user-123');
+```
+
+### Statistics
+
+```typescript
+const stats = await flagService.getStats('new-checkout');
+// {
+//   totalEvaluations: 10000,
+//   enabledCount: 2500,
+//   disabledCount: 7500,
+//   uniqueUsers: 5000,
+//   lastEvaluatedAt: Date
+// }
+
+// Get events for a flag
+const events = await flagService.getEvents('new-checkout', 100);
+```
+
+## Attribute Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equals | `{ attribute: 'plan', operator: 'eq', value: 'pro' }` |
+| `ne` | Not equals | `{ attribute: 'status', operator: 'ne', value: 'banned' }` |
+| `in` | In array | `{ attribute: 'country', operator: 'in', value: ['US', 'CA'] }` |
+| `nin` | Not in array | `{ attribute: 'role', operator: 'nin', value: ['guest'] }` |
+| `gt` | Greater than | `{ attribute: 'age', operator: 'gt', value: 18 }` |
+| `gte` | Greater or equal | `{ attribute: 'score', operator: 'gte', value: 100 }` |
+| `lt` | Less than | `{ attribute: 'failedLogins', operator: 'lt', value: 5 }` |
+| `lte` | Less or equal | `{ attribute: 'cart', operator: 'lte', value: 1000 }` |
+| `contains` | String contains | `{ attribute: 'email', operator: 'contains', value: '@company.com' }` |
+| `starts-with` | String starts with | `{ attribute: 'name', operator: 'starts-with', value: 'Admin' }` |
+| `ends-with` | String ends with | `{ attribute: 'domain', operator: 'ends-with', value: '.edu' }` |
+
+## Types
+
+```typescript
+interface FeatureFlag {
+  key: string;
+  name: string;
+  description?: string;
+  strategy: 'boolean' | 'percentage' | 'user-list' | 'user-attribute' | 'date-range';
+  config: FlagConfig;
+  status: 'active' | 'disabled' | 'archived';
+  environment?: string;
+  tags?: string[];
+  createdBy?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface FlagEvaluationContext {
+  userId?: string;
+  sessionId?: string;
+  environment?: string;
+  userAttributes?: Record<string, string | number | boolean>;
+}
+
+interface FlagEvaluationResult {
+  key: string;
+  enabled: boolean;
+  reason: string;
+  strategy: string;
+  evaluatedAt: Date;
+}
+```
+
+## React Integration Example
+
+```typescript
+// Hook
+function useFeatureFlag(key: string): boolean {
+  const [enabled, setEnabled] = useState(false);
+  const user = useUser();
+
+  useEffect(() => {
+    flagService.isEnabled(key, {
+      userId: user.id,
+      userAttributes: {
+        plan: user.plan,
+        country: user.country,
+      },
+    }).then(setEnabled);
+  }, [key, user]);
+
+  return enabled;
+}
+
+// Usage
+function Dashboard() {
+  const showNewDashboard = useFeatureFlag('new-dashboard');
+
+  return showNewDashboard ? <NewDashboard /> : <OldDashboard />;
+}
+```
+
+## Best Practices
+
+1. **Naming Convention** - Use kebab-case: `new-feature`, `beta-checkout`
+2. **Short-lived Flags** - Remove flags after full rollout
+3. **Default Off** - New flags should default to disabled
+4. **Documentation** - Add descriptions to all flags
+5. **Cleanup** - Archive unused flags regularly
+6. **Testing** - Use overrides for testing specific states

package/docs/modules/I18N.md

@@ -0,0 +1,294 @@
+# I18n Module
+
+Internationalization and localization support for multi-language applications.
+
+## Features
+
+- **Translation Management** - Load and manage translations from files or programmatically
+- **Variable Interpolation** - Dynamic values in translations
+- **Pluralization** - Proper plural forms using Intl.PluralRules
+- **Date/Number/Currency Formatting** - Locale-aware formatting
+- **Relative Time** - Human-readable relative time (e.g., "2 hours ago")
+- **RTL Support** - Right-to-left language support
+
+## Supported Locales (Built-in)
+
+| Code | Language | Direction | Currency |
+|------|----------|-----------|----------|
+| `en` | English | LTR | USD |
+| `fr` | Français | LTR | EUR |
+| `es` | Español | LTR | EUR |
+| `de` | Deutsch | LTR | EUR |
+| `ar` | العربية | RTL | SAR |
+| `zh` | 中文 | LTR | CNY |
+| `ja` | 日本語 | LTR | JPY |
+
+## Usage
+
+### Configuration
+
+```typescript
+import { I18nService } from 'servcraft/modules/i18n';
+
+const i18n = new I18nService({
+  defaultLocale: 'en',
+  supportedLocales: ['en', 'fr', 'es', 'de'],
+  fallbackLocale: 'en',
+  translationsDir: './locales',
+  cache: true,
+  debug: false,
+});
+
+// Load translations from files
+await i18n.loadTranslations('en', 'common');
+await i18n.loadTranslations('fr', 'common');
+```
+
+### File Structure
+
+```
+locales/
+├── en/
+│   ├── common.json
+│   └── errors.json
+├── fr/
+│   ├── common.json
+│   └── errors.json
+└── es/
+    ├── common.json
+    └── errors.json
+```
+
+### Translation File Format
+
+```json
+// locales/en/common.json
+{
+  "welcome": "Welcome, {{name}}!",
+  "items": "You have {{count}} item{s}",
+  "user": {
+    "profile": {
+      "title": "User Profile",
+      "settings": "Settings"
+    }
+  }
+}
+```
+
+### Basic Translation
+
+```typescript
+// Simple translation
+const text = i18n.t('welcome');
+// "Welcome, {{name}}!"
+
+// With locale
+const frText = i18n.t('welcome', { locale: 'fr' });
+
+// With namespace
+const errorText = i18n.t('notFound', { namespace: 'errors' });
+
+// Nested keys
+const title = i18n.t('user.profile.title');
+// "User Profile"
+```
+
+### Variable Interpolation
+
+```typescript
+const welcome = i18n.t('welcome', {
+  variables: { name: 'John' }
+});
+// "Welcome, John!"
+```
+
+### Pluralization
+
+```typescript
+// Translation: "You have {{count}} item{s}"
+const items1 = i18n.t('items', { count: 1 });
+// "You have 1 item"
+
+const items5 = i18n.t('items', { count: 5 });
+// "You have 5 items"
+```
+
+### Formatting
+
+```typescript
+// Date formatting
+const date = i18n.formatDate(new Date(), 'en', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+});
+// "December 20, 2024"
+
+// Number formatting
+const number = i18n.formatNumber(1234567.89, 'de');
+// "1.234.567,89"
+
+// Currency formatting
+const price = i18n.formatCurrency(99.99, 'en', 'USD');
+// "$99.99"
+
+const euroPrice = i18n.formatCurrency(99.99, 'fr', 'EUR');
+// "99,99 €"
+
+// Relative time
+const relative = i18n.formatRelativeTime(new Date(Date.now() - 3600000), 'en');
+// "1 hour ago"
+```
+
+### Programmatic Translations
+
+```typescript
+// Add translations at runtime
+i18n.addTranslations({
+  locale: 'en',
+  namespace: 'common',
+  data: {
+    newFeature: 'Check out our new feature!',
+    button: {
+      save: 'Save',
+      cancel: 'Cancel',
+    },
+  },
+});
+```
+
+### Locale Information
+
+```typescript
+// Get locale info
+const info = i18n.getLocaleInfo('ar');
+// {
+//   code: 'ar',
+//   name: 'العربية',
+//   englishName: 'Arabic',
+//   direction: 'rtl',
+//   dateFormat: 'DD/MM/YYYY',
+//   currency: 'SAR'
+// }
+
+// Check if locale is supported
+if (i18n.isLocaleSupported('fr')) {
+  // Use French
+}
+
+// Get supported locales
+const locales = i18n.getSupportedLocales();
+// ['en', 'fr', 'es', 'de']
+```
+
+### Translation Metadata
+
+```typescript
+// Get translation statistics
+const metadata = await i18n.getTranslationMetadata('fr', 'common');
+// {
+//   totalKeys: 50,
+//   translatedKeys: 45,
+//   completionPercentage: 90
+// }
+
+// Find missing translations
+const missing = i18n.getMissingTranslations('en', 'fr', 'common');
+// ['newFeature', 'button.help']
+```
+
+### Cache Management
+
+```typescript
+// Clear translation cache
+i18n.clearCache();
+
+// Export translations for backup/editing
+const translations = i18n.exportTranslations('en', 'common');
+```
+
+## Configuration Types
+
+```typescript
+interface I18nConfig {
+  defaultLocale: string;
+  supportedLocales: string[];
+  fallbackLocale?: string;
+  translationsDir?: string;
+  cache?: boolean;
+  debug?: boolean;
+}
+
+interface TranslationOptions {
+  locale?: string;
+  namespace?: string;
+  variables?: Record<string, string | number>;
+  count?: number;
+  defaultValue?: string;
+}
+```
+
+## Fastify Integration
+
+```typescript
+// Detect locale from request
+fastify.addHook('preHandler', async (request) => {
+  const acceptLanguage = request.headers['accept-language'];
+  const locale = parseAcceptLanguage(acceptLanguage) || 'en';
+
+  if (i18n.isLocaleSupported(locale)) {
+    request.locale = locale;
+  } else {
+    request.locale = 'en';
+  }
+});
+
+// Use in routes
+fastify.get('/api/welcome', async (request, reply) => {
+  const message = i18n.t('welcome', {
+    locale: request.locale,
+    variables: { name: request.user?.name },
+  });
+
+  return { message };
+});
+```
+
+## React Integration Example
+
+```typescript
+// Create hook
+function useTranslation(namespace = 'common') {
+  const locale = useLocale();
+
+  return {
+    t: (key: string, options?: TranslationOptions) =>
+      i18n.t(key, { locale, namespace, ...options }),
+    formatDate: (date: Date, options?: DateFormatOptions) =>
+      i18n.formatDate(date, locale, options),
+    formatCurrency: (value: number, currency?: string) =>
+      i18n.formatCurrency(value, locale, currency),
+  };
+}
+
+// Usage
+function Welcome({ user }) {
+  const { t, formatCurrency } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t('welcome', { variables: { name: user.name } })}</h1>
+      <p>{t('balance')}: {formatCurrency(user.balance)}</p>
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+1. **Key Naming** - Use dot notation for namespacing: `user.profile.title`
+2. **Variables** - Use meaningful variable names: `{{userName}}` not `{{n}}`
+3. **Fallback** - Always configure a fallback locale
+4. **Lazy Loading** - Load translations on demand for large apps
+5. **Missing Keys** - Log missing translations in development
+6. **RTL** - Test with RTL languages early in development