@nlabs/metropolisjs 0.1.1 → 0.2.0

package/examples/factory-pattern-usage.ts

@@ -0,0 +1,283 @@
+/**
+ * Example: Using the Factory Pattern in MetropolisJS
+ * 
+ * This file demonstrates how to use the new consolidated action factory
+ * instead of individual createXxxActions functions.
+ */
+
+import type { FluxFramework } from '@nlabs/arkhamjs';
+import { createAction, createActions, createAllActions } from '../src/utils/actionFactory';
+
+// Example 1: Basic Usage
+export const basicUsage = (flux: FluxFramework) => {
+  // Create actions using consolidated factory functions
+  const userActions = createAction('user', flux) as any;
+  const postActions = createAction('post', flux) as any;
+  const eventActions = createAction('event', flux) as any;
+
+  // Use actions normally
+  const addUser = async () => {
+    const user = await userActions.add({
+      username: 'john_doe',
+      email: 'john@example.com',
+      firstName: 'John',
+      lastName: 'Doe'
+    });
+    return user;
+  };
+
+  const createPost = async () => {
+    const post = await postActions.add({
+      content: 'Hello, world!',
+      name: 'My First Post'
+    });
+    return post;
+  };
+
+  return {addUser, createPost};
+};
+
+// Example 2: Custom Adapter with Business Logic
+export const customAdapterUsage = (flux: FluxFramework) => {
+  // Custom user adapter that adds business logic
+  const businessUserAdapter = (input: unknown, options?: any) => {
+    const user = input as any;
+    
+    // Business validation
+    if (user.email && !user.email.includes('@company.com')) {
+      throw new Error('Only company emails are allowed');
+    }
+    
+    // Add computed fields
+    return {
+      ...user,
+      fullName: `${user.firstName || ''} ${user.lastName || ''}`.trim(),
+      isAdmin: user.userAccess >= 3,
+      department: user.email?.split('@')[0]?.split('.')[1] || 'general'
+    };
+  };
+
+  // Create actions with custom adapter
+  const userActions = createAction('user', flux, {
+    userAdapter: businessUserAdapter,
+    userAdapterOptions: {
+      strict: true,
+      environment: 'production'
+    }
+  });
+
+  return userActions;
+};
+
+// Example 3: Runtime Adapter Updates
+export const runtimeUpdates = (flux: FluxFramework) => {
+  const userActions = createAction('user', flux) as any;
+
+  // Update adapter at runtime
+  const updateToStrictMode = () => {
+    userActions.updateUserAdapterOptions({
+      strict: true,
+      environment: 'production'
+    });
+  };
+
+  // Add custom validation at runtime
+  const addCustomValidation = () => {
+    userActions.updateUserAdapter((input, options) => {
+      const user = input as any;
+      
+      // Additional runtime validation
+      if (user.age && user.age < 18) {
+        throw new Error('User must be 18 or older');
+      }
+      
+      return user;
+    });
+  };
+
+  return {updateToStrictMode, addCustomValidation, userActions};
+};
+
+// Example 4: Testing with Mock Adapters
+export const testingExample = (flux: FluxFramework) => {
+  // Mock adapter for testing
+  const mockUserAdapter = jest.fn((input: unknown) => ({
+    ...(input as Record<string, unknown>),
+    id: 'mock-user-id',
+    validated: true,
+    timestamp: new Date().toISOString()
+  }));
+
+  const userActions = createAction('user', flux, {
+    userAdapter: mockUserAdapter
+  }) as any;
+
+  // Test that adapter was called
+  const testUserCreation = async () => {
+    const user = await userActions.add({
+      username: 'test_user',
+      email: 'test@example.com'
+    });
+
+    expect(mockUserAdapter).toHaveBeenCalled();
+    expect(user.id).toBe('mock-user-id');
+    expect(user.validated).toBe(true);
+  };
+
+  return {userActions, testUserCreation};
+};
+
+// Example 5: Multiple Adapters with Different Configurations
+export const multipleAdapters = (flux: FluxFramework) => {
+  // User adapter with strict validation
+  const strictUserAdapter = (input: unknown) => {
+    const user = input as any;
+    if (!user.username || !user.email) {
+      throw new Error('Username and email are required');
+    }
+    return user;
+  };
+
+  // Post adapter with content validation
+  const contentPostAdapter = (input: unknown) => {
+    const post = input as any;
+    if (post.content && post.content.length > 1000) {
+      throw new Error('Post content too long');
+    }
+    return post;
+  };
+
+  // Create actions with different adapters
+  const userActions = createAction('user', flux, {
+    userAdapter: strictUserAdapter,
+    userAdapterOptions: {strict: true}
+  }) as any;
+
+  const postActions = createAction('post', flux, {
+    postAdapter: contentPostAdapter,
+    postAdapterOptions: {environment: 'development'}
+  }) as any;
+
+  return {userActions, postActions};
+};
+
+// Example 6: Error Handling
+export const errorHandling = (flux: FluxFramework) => {
+  const userActions = createAction('user', flux, {
+    userAdapterOptions: {
+      strict: true,
+      customValidation: (input) => {
+        const user = input as any;
+        
+        // Custom error handling
+        if (user.username && user.username.length < 3) {
+          throw new Error('Username must be at least 3 characters');
+        }
+        
+        if (user.email && !user.email.includes('@')) {
+          throw new Error('Invalid email format');
+        }
+        
+        return user;
+      }
+    }
+  }) as any;
+
+  const createUserWithErrorHandling = async (userData: any) => {
+    try {
+      const user = await userActions.add(userData);
+      return {success: true, user};
+    } catch (error) {
+      return {success: false, error: error.message};
+    }
+  };
+
+  return {createUserWithErrorHandling};
+};
+
+// Example 7: Multiple Actions Creation
+export const multipleActionsExample = (flux: FluxFramework) => {
+  // Create multiple actions at once
+  const actions = createActions(['user', 'post', 'message'], flux, {
+    user: {
+      userAdapterOptions: { strict: true }
+    },
+    post: {
+      postAdapter: (input: any) => {
+        if (input.content && input.content.length > 1000) {
+          throw new Error('Post content too long');
+        }
+        return input;
+      }
+    }
+  });
+
+  const createUserAndPost = async (userData: any, postData: any) => {
+    const user = await actions.user.add(userData);
+    const post = await actions.post.add({
+      ...postData,
+      userId: user.userId
+    });
+    return { user, post };
+  };
+
+  return { actions, createUserAndPost };
+};
+
+// Example 8: All Actions Creation
+export const allActionsExample = (flux: FluxFramework) => {
+  // Create all available actions
+  const allActions = createAllActions(flux, {
+    user: { userAdapterOptions: { strict: true } },
+    post: { postAdapterOptions: { environment: 'production' } },
+    image: { imageAdapterOptions: { allowPartial: true } }
+  });
+
+  const comprehensiveWorkflow = async () => {
+    // Create user
+    const user = await allActions.user.add({
+      username: 'jane_doe',
+      email: 'jane@example.com'
+    });
+
+    // Create post
+    const post = await allActions.post.add({
+      content: 'Hello world!',
+      name: 'My Post'
+    });
+
+    // Upload image
+    const image = await allActions.image.add({
+      base64: 'data:image/jpeg;base64,...',
+      description: 'Profile picture'
+    });
+
+    // Send message
+    await allActions.message.sendMessage({
+      content: 'Welcome!',
+      recipientId: user.userId
+    });
+
+    return { user, post, image };
+  };
+
+  return { allActions, comprehensiveWorkflow };
+};
+
+// Example 9: Migration from Old Pattern
+export const migrationExample = (flux: FluxFramework) => {
+  // New way (recommended)
+  const userActions = createAction('user', flux) as any;
+  const postActions = createAction('post', flux) as any;
+  const eventActions = createAction('event', flux) as any;
+
+  const createUser = async (userData: any) => {
+    return await userActions.add(userData);
+  };
+
+  const createPost = async (postData: any) => {
+    return await postActions.add(postData);
+  };
+
+  return { createUser, createPost };
+}; 

package/examples/i18n-import-examples.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2025-Present, Nitrogen Labs, Inc.
+ * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
+ */
+
+// This file demonstrates different ways to import i18next functions
+// for consistency across MetropolisJS and GothamJS
+
+// Method 1: Direct import (original i18next way)
+import { t } from 'i18next';
+
+// Method 2: Aliased import for consistency (recommended)
+import { t as i18n } from 'i18next';
+
+// Method 3: Multiple imports with aliases
+import { t as translate } from 'i18next';
+
+// Example usage showing the difference:
+
+// Using the original 't' function
+const originalWay = () => {
+  const welcome = t('welcome');
+  const greeting = t('hello_user', {name: 'John'});
+  return {welcome, greeting};
+};
+
+// Using the aliased 'i18n' function (same as MetropolisJS)
+const consistentWay = () => {
+  const welcome = i18n('welcome');
+  const greeting = i18n('hello_user', {name: 'John'});
+  return {welcome, greeting};
+};
+
+// Using the 'translate' alias
+const alternativeWay = () => {
+  const welcome = translate('welcome');
+  const greeting = translate('hello_user', {name: 'John'});
+  return {welcome, greeting};
+};
+
+// Real-world example: GothamJS component
+const GothamJSComponent = () => {
+  // In GothamJS, you would use:
+  // import {t as i18n} from 'i18next';
+
+  // This gives you the same function name as MetropolisJS
+  const title = i18n('gotham_title');
+  const description = i18n('gotham_description');
+  const buttonText = i18n('gotham_button');
+
+  return {
+    title,
+    description,
+    buttonText
+  };
+};
+
+// MetropolisJS component (for comparison)
+const MetropolisJSComponent = () => {
+  // In MetropolisJS, you would use:
+  // import {i18n} from './utils/i18n';
+  // (which internally uses i18next)
+
+  const title = i18n('metropolis_title');
+  const description = i18n('metropolis_description');
+  const buttonText = i18n('metropolis_button');
+
+  return {
+    title,
+    description,
+    buttonText
+  };
+};
+
+// Benefits of using {t as i18n}:
+const benefits = {
+  consistency: 'Same function name across libraries',
+  familiarity: 'Developers know what i18n() does',
+  maintainability: 'Easier to switch between libraries',
+  clarity: 'Clear that it\'s for internationalization'
+};
+
+export {
+    alternativeWay, benefits, consistentWay, GothamJSComponent,
+    MetropolisJSComponent, originalWay
+};

package/examples/i18n-namespace-usage.ts

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2025-Present, Nitrogen Labs, Inc.
+ * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
+ */
+import { i18n, initI18n, updateI18nResources } from '../src/utils/i18n';
+
+const translations = {
+  'welcome:en': {
+    key: 'welcome',
+    locale: 'en',
+    value: 'Welcome {{name}}!',
+    namespace: 'common'
+  },
+  'save:en': {
+    key: 'save',
+    locale: 'en',
+    value: 'Save',
+    namespace: 'buttons'
+  },
+  'cancel:en': {
+    key: 'cancel',
+    locale: 'en',
+    value: 'Cancel',
+    namespace: 'buttons'
+  },
+  'login:en': {
+    key: 'login',
+    locale: 'en',
+    value: 'Login to your account',
+    namespace: 'auth'
+  },
+  'welcome:es': {
+    key: 'welcome',
+    locale: 'es',
+    value: '¡Bienvenido {{name}}!',
+    namespace: 'common'
+  },
+  'save:es': {
+    key: 'save',
+    locale: 'es',
+    value: 'Guardar',
+    namespace: 'buttons'
+  }
+};
+
+const initializeTranslations = () => {
+  initI18n(translations);
+  console.log('i18n initialized with namespaces');
+};
+
+const demonstrateNamespaceUsage = () => {
+  console.log('\n=== Namespace Usage Examples ===');
+
+  console.log('Default namespace (translations):');
+  console.log(i18n('welcome', {name: 'World'}));
+  console.log(i18n('welcome', {name: 'World'}, 'en'));
+
+  console.log('\nCommon namespace:');
+  console.log(i18n('welcome', {name: 'World'}, 'en', 'common'));
+  console.log(i18n('welcome', {name: 'Mundo'}, 'es', 'common'));
+
+  console.log('\nButtons namespace:');
+  console.log(i18n('save', {}, 'en', 'buttons'));
+  console.log(i18n('cancel', {}, 'en', 'buttons'));
+  console.log(i18n('save', {}, 'es', 'buttons'));
+
+  console.log('\nAuth namespace:');
+  console.log(i18n('login', {}, 'en', 'auth'));
+};
+
+const demonstrateDynamicUpdates = () => {
+  console.log('\n=== Dynamic Updates ===');
+
+  const newTranslations = {
+    'delete:en': {
+      key: 'delete',
+      locale: 'en',
+      value: 'Delete',
+      namespace: 'buttons'
+    },
+    'edit:en': {
+      key: 'edit',
+      locale: 'en',
+      value: 'Edit {{item}}',
+      namespace: 'actions'
+    }
+  };
+
+  updateI18nResources(newTranslations);
+
+  console.log('New button translation:');
+  console.log(i18n('delete', {}, 'en', 'buttons'));
+
+  console.log('New action translation:');
+  console.log(i18n('edit', {item: 'profile'}, 'en', 'actions'));
+};
+
+const demonstrateFallbacks = () => {
+  console.log('\n=== Fallback Behavior ===');
+
+  console.log('Missing key (returns key):');
+  console.log(i18n('missing-key', {}, 'en', 'common'));
+
+  console.log('Missing namespace (uses default):');
+  console.log(i18n('welcome', {name: 'World'}, 'en', 'missing-ns'));
+
+  console.log('Missing language (uses fallback):');
+  console.log(i18n('welcome', {name: 'World'}, 'fr', 'common'));
+};
+
+const runExamples = () => {
+  initializeTranslations();
+  demonstrateNamespaceUsage();
+  demonstrateDynamicUpdates();
+  demonstrateFallbacks();
+};
+
+export { demonstrateNamespaceUsage, initializeTranslations, runExamples };

package/examples/i18next-singleton-demo.ts

@@ -0,0 +1,187 @@
+/**
+ * Copyright (c) 2025-Present, Nitrogen Labs, Inc.
+ * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
+ */
+
+// This file demonstrates how i18next works as a singleton
+// and how GothamJS can share the same instance as MetropolisJS
+
+import { changeLanguage, init, t } from 'i18next';
+
+// Step 1: MetropolisJS initializes i18next (this happens in Metropolis component)
+const initializeMetropolisI18n = () => {
+  console.log('🔵 MetropolisJS: Initializing i18next...');
+
+  init({
+    resources: {
+      en: {
+        translations: {
+          'welcome': 'Welcome to MetropolisJS!',
+          'save': 'Save',
+          'cancel': 'Cancel',
+          'shared_text': 'This text is shared between libraries',
+          'hello_user': 'Hello {{name}}!'
+        }
+      },
+      es: {
+        translations: {
+          'welcome': '¡Bienvenido a MetropolisJS!',
+          'save': 'Guardar',
+          'cancel': 'Cancelar',
+          'shared_text': 'Este texto se comparte entre bibliotecas',
+          'hello_user': '¡Hola {{name}}!'
+        }
+      }
+    },
+    lng: 'en',
+    fallbackLng: 'en',
+    interpolation: {
+      escapeValue: false
+    }
+  });
+
+  console.log('🔵 MetropolisJS: i18next initialized successfully');
+};
+
+// Step 2: GothamJS can use the same i18next instance
+const gothamJSComponent = () => {
+  console.log('🟢 GothamJS: Using the same i18next instance');
+
+  // GothamJS can import {t as i18n} from 'i18next' for consistency
+  // This gives the same function name as MetropolisJS uses
+  // import {t as i18n} from 'i18next';
+
+  const gothamTitle = t('gotham_title', 'GothamJS Component'); // with fallback
+  const sharedText = t('shared_text'); // uses the same translation
+  const helloUser = t('hello_user', {name: 'Gotham User'}); // with interpolation
+
+  console.log('🟢 GothamJS translations:', {
+    gothamTitle,
+    sharedText,
+    helloUser
+  });
+
+  return {
+    title: gothamTitle,
+    description: sharedText,
+    greeting: helloUser
+  };
+};
+
+// Step 3: Demonstrate language switching affects both libraries
+const demonstrateLanguageSwitching = async () => {
+  console.log('\n🌍 Demonstrating language switching...');
+
+  // Both MetropolisJS and GothamJS will see this change
+  await changeLanguage('es');
+
+  console.log('🔄 Language changed to Spanish');
+
+  // MetropolisJS component
+  const metropolisText = t('welcome');
+  console.log('🔵 MetropolisJS (Spanish):', metropolisText);
+
+  // GothamJS component - automatically uses Spanish now
+  const gothamText = t('shared_text');
+  console.log('🟢 GothamJS (Spanish):', gothamText);
+
+  // Switch back to English
+  await changeLanguage('en');
+  console.log('🔄 Language changed back to English');
+
+  console.log('🔵 MetropolisJS (English):', t('welcome'));
+  console.log('🟢 GothamJS (English):', t('shared_text'));
+};
+
+// Step 4: Show how namespaces work across libraries
+const demonstrateNamespaces = () => {
+  console.log('\n📚 Demonstrating namespaces...');
+
+  // MetropolisJS might use 'metropolis' namespace
+  const metropolisText = t('dashboard_title', {ns: 'metropolis'});
+
+  // GothamJS might use 'gotham' namespace
+  const gothamText = t('widget_title', {ns: 'gotham'});
+
+  // Both can use 'common' namespace for shared translations
+  const commonText = t('shared_button', {ns: 'common'});
+
+  console.log('🔵 MetropolisJS namespace:', metropolisText);
+  console.log('🟢 GothamJS namespace:', gothamText);
+  console.log('🟡 Common namespace:', commonText);
+};
+
+// Step 5: Real-world usage example
+const realWorldExample = () => {
+  console.log('\n🏗️ Real-world usage example:');
+
+  // In a real React app:
+
+  // MetropolisJS component
+  const MetropolisComponent = () => {
+    // This would be in a MetropolisJS component
+    const title = t('dashboard_title');
+    const saveButton = t('save');
+
+    console.log('🔵 MetropolisJS component:', {title, saveButton});
+
+    return {title, saveButton};
+  };
+
+  // GothamJS component
+  const GothamComponent = () => {
+    // This would be in a GothamJS component
+    // import {t} from 'i18next'; // Same i18next instance!
+
+    const widgetTitle = t('widget_title');
+    const sharedButton = t('shared_button');
+
+    console.log('🟢 GothamJS component:', {widgetTitle, sharedButton});
+
+    return {widgetTitle, sharedButton};
+  };
+
+  const metropolis = MetropolisComponent();
+  const gotham = GothamComponent();
+
+  console.log('✅ Both components use the same i18next instance!');
+  console.log('✅ Language changes affect both components!');
+  console.log('✅ Namespaces keep translations organized!');
+
+  return {metropolis, gotham};
+};
+
+// Run the demonstration
+const runDemo = () => {
+  console.log('🚀 i18next Singleton Demonstration');
+  console.log('=====================================\n');
+
+  // Initialize i18next (MetropolisJS does this)
+  initializeMetropolisI18n();
+
+  // GothamJS uses the same instance
+  const gothamResult = gothamJSComponent();
+
+  // Demonstrate language switching
+  demonstrateLanguageSwitching();
+
+  // Demonstrate namespaces
+  demonstrateNamespaces();
+
+  // Real-world example
+  const realWorld = realWorldExample();
+
+  console.log('\n✅ Demonstration complete!');
+  console.log('✅ GothamJS can fully share i18next with MetropolisJS');
+  console.log('✅ Both libraries benefit from the same translation system');
+
+  return {
+    gothamResult,
+    realWorld
+  };
+};
+
+export {
+    demonstrateLanguageSwitching,
+    demonstrateNamespaces, gothamJSComponent, initializeMetropolisI18n, realWorldExample, runDemo
+};