@nlabs/metropolisjs 0.1.1 → 0.2.0

package/examples/translation-types.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.
+ */
+
+// Define the types directly to avoid JSX compilation issues
+type SimpleTranslations = Record<string, string>;
+
+interface ComplexTranslation {
+  readonly value: string;
+  readonly locale: string;
+  readonly namespace?: string;
+}
+
+type ComplexTranslations = Record<string, ComplexTranslation>;
+
+// Test simple translations type
+const simpleTranslations: SimpleTranslations = {
+  'welcome': 'Welcome to MetropolisJS!',
+  'hello': 'Hello {{name}}!',
+  'goodbye': 'Goodbye'
+};
+
+// Test complex translations type
+const complexTranslations: ComplexTranslations = {
+  'welcome:en': {
+    value: 'Welcome to MetropolisJS!',
+    locale: 'en',
+    namespace: 'common'
+  },
+  'hello:en': {
+    value: 'Hello {{name}}!',
+    locale: 'en',
+    namespace: 'common'
+  },
+  'save:en': {
+    value: 'Save',
+    locale: 'en',
+    namespace: 'buttons'
+  }
+};
+
+// Test individual complex translation type
+const singleTranslation: ComplexTranslation = {
+  value: 'Test translation',
+  locale: 'en',
+  namespace: 'test'
+};
+
+// Function to demonstrate type safety
+function processTranslations(translations: SimpleTranslations | ComplexTranslations): void {
+  if (Object.keys(translations).length === 0) {
+    console.log('No translations provided');
+    return;
+  }
+
+  const firstKey = Object.keys(translations)[0];
+  const firstValue = translations[firstKey];
+
+  if (typeof firstValue === 'string') {
+    // TypeScript knows this is SimpleTranslations
+    console.log('Processing simple translations');
+    Object.entries(translations as SimpleTranslations).forEach(([key, value]) => {
+      console.log(`${key}: ${value}`);
+    });
+  } else if (typeof firstValue === 'object' && firstValue !== null && 'value' in firstValue) {
+    // TypeScript knows this is ComplexTranslations
+    console.log('Processing complex translations');
+    Object.entries(translations as ComplexTranslations).forEach(([key, translation]) => {
+      console.log(`${key}: ${translation.value} (${translation.locale}${translation.namespace ? `, ${translation.namespace}` : ''})`);
+    });
+  }
+}
+
+// Test the function with both types
+console.log('Testing simple translations:');
+processTranslations(simpleTranslations);
+
+console.log('\nTesting complex translations:');
+processTranslations(complexTranslations);
+
+console.log('\nType test completed successfully!');
+
+// Export for use in other files
+export { complexTranslations, processTranslations, simpleTranslations, singleTranslation };
+export type { ComplexTranslation, ComplexTranslations, SimpleTranslations };

package/examples/translation-usage.tsx

@@ -0,0 +1,336 @@
+/**
+ * Copyright (c) 2025-Present, Nitrogen Labs, Inc.
+ * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
+ */
+
+import React from 'react';
+import { ComplexTranslations, Metropolis, SimpleTranslations } from '../src/index';
+import { i18n } from '../src/utils/i18n';
+
+// Example translations object with simple key-value pairs
+const simpleTranslations: SimpleTranslations = {
+  'welcome': 'Welcome to MetropolisJS!',
+  'hello': 'Hello {{name}}!',
+  'goodbye': 'Goodbye',
+  'loading': 'Loading...',
+  'error': 'An error occurred',
+  'success': 'Operation completed successfully',
+  'cancel': 'Cancel',
+  'save': 'Save',
+  'delete': 'Delete',
+  'edit': 'Edit',
+  'create': 'Create',
+  'update': 'Update',
+  'search': 'Search',
+  'filter': 'Filter',
+  'sort': 'Sort',
+  'refresh': 'Refresh',
+  'back': 'Back',
+  'next': 'Next',
+  'previous': 'Previous',
+  'submit': 'Submit',
+  'reset': 'Reset',
+  'confirm': 'Confirm',
+  'yes': 'Yes',
+  'no': 'No',
+  'ok': 'OK',
+  'close': 'Close',
+  'open': 'Open',
+  'show': 'Show',
+  'hide': 'Hide',
+  'expand': 'Expand',
+  'collapse': 'Collapse',
+  'minimize': 'Minimize',
+  'maximize': 'Maximize',
+  'fullscreen': 'Fullscreen',
+  'settings': 'Settings',
+  'profile': 'Profile',
+  'account': 'Account',
+  'logout': 'Logout',
+  'login': 'Login',
+  'register': 'Register',
+  'forgot_password': 'Forgot Password?',
+  'remember_me': 'Remember Me',
+  'email': 'Email',
+  'password': 'Password',
+  'username': 'Username',
+  'first_name': 'First Name',
+  'last_name': 'Last Name',
+  'phone': 'Phone',
+  'address': 'Address',
+  'city': 'City',
+  'state': 'State',
+  'country': 'Country',
+  'zip_code': 'ZIP Code',
+  'birth_date': 'Birth Date',
+  'gender': 'Gender',
+  'male': 'Male',
+  'female': 'Female',
+  'other': 'Other',
+  'prefer_not_to_say': 'Prefer not to say'
+};
+
+// Example complex translations with locale and namespace support
+const complexTranslations: ComplexTranslations = {
+  'welcome:en': {
+    value: 'Welcome to MetropolisJS!',
+    locale: 'en',
+    namespace: 'common'
+  },
+  'hello:en': {
+    value: 'Hello {{name}}!',
+    locale: 'en',
+    namespace: 'common'
+  },
+  'save:en': {
+    value: 'Save',
+    locale: 'en',
+    namespace: 'buttons'
+  },
+  'cancel:en': {
+    value: 'Cancel',
+    locale: 'en',
+    namespace: 'buttons'
+  },
+  'welcome:es': {
+    value: '¡Bienvenido a MetropolisJS!',
+    locale: 'es',
+    namespace: 'common'
+  },
+  'hello:es': {
+    value: '¡Hola {{name}}!',
+    locale: 'es',
+    namespace: 'common'
+  },
+  'save:es': {
+    value: 'Guardar',
+    locale: 'es',
+    namespace: 'buttons'
+  }
+};
+
+// Example React component using Metropolis with simple translations
+const SimpleTranslationApp: React.FC = () => {
+  return (
+    <Metropolis
+      translations={simpleTranslations}
+      config={{
+        development: {
+          app: {
+            api: {
+              url: 'https://api.example.com'
+            },
+            urls: {
+              websocket: 'wss://ws.example.com'
+            }
+          }
+        }
+      }}
+    >
+      <div>
+        <h1>{i18n('welcome')}</h1>
+        <p>{i18n('hello', {name: 'John'})}</p>
+        <button>{i18n('save')}</button>
+        <button>{i18n('cancel')}</button>
+        <p>{i18n('loading')}</p>
+      </div>
+    </Metropolis>
+  );
+};
+
+// Example React component using Metropolis with complex translations
+const ComplexTranslationApp: React.FC = () => {
+  return (
+    <Metropolis
+      translations={complexTranslations}
+      config={{
+        development: {
+          app: {
+            api: {
+              url: 'https://api.example.com'
+            },
+            urls: {
+              websocket: 'wss://ws.example.com'
+            }
+          }
+        }
+      }}
+    >
+      <div>
+        <h1>{i18n('welcome', {}, 'en', 'common')}</h1>
+        <p>{i18n('hello', {name: 'John'}, 'en', 'common')}</p>
+        <button>{i18n('save', {}, 'en', 'buttons')}</button>
+        <button>{i18n('cancel', {}, 'en', 'buttons')}</button>
+        <p>{i18n('loading')}</p>
+      </div>
+    </Metropolis>
+  );
+};
+
+// Example of using translations in a component
+const UserProfile: React.FC = () => {
+  const [isLoading, setIsLoading] = React.useState(false);
+  const [user, setUser] = React.useState({name: 'John Doe'});
+
+  return (
+    <div>
+      <h2>{i18n('profile')}</h2>
+      {isLoading ? (
+        <p>{i18n('loading')}</p>
+      ) : (
+        <div>
+          <p>{i18n('hello', {name: user.name})}</p>
+          <button>{i18n('edit')}</button>
+          <button>{i18n('delete')}</button>
+        </div>
+      )}
+    </div>
+  );
+};
+
+// Example of a form component with translations
+const LoginForm: React.FC = () => {
+  const [formData, setFormData] = React.useState({
+    email: '',
+    password: '',
+    rememberMe: false
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    // Handle form submission
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <h2>{i18n('login')}</h2>
+
+      <div>
+        <label htmlFor="email">{i18n('email')}:</label>
+        <input
+          id="email"
+          type="email"
+          value={formData.email}
+          onChange={(e) => setFormData({...formData, email: e.target.value})}
+          required
+        />
+      </div>
+
+      <div>
+        <label htmlFor="password">{i18n('password')}:</label>
+        <input
+          id="password"
+          type="password"
+          value={formData.password}
+          onChange={(e) => setFormData({...formData, password: e.target.value})}
+          required
+        />
+      </div>
+
+      <div>
+        <label>
+          <input
+            type="checkbox"
+            checked={formData.rememberMe}
+            onChange={(e) => setFormData({...formData, rememberMe: e.target.checked})}
+          />
+          {i18n('remember_me')}
+        </label>
+      </div>
+
+      <div>
+        <button type="submit">{i18n('login')}</button>
+        <button type="button">{i18n('cancel')}</button>
+      </div>
+
+      <div>
+        <a href="#forgot-password">{i18n('forgot_password')}</a>
+      </div>
+    </form>
+  );
+};
+
+// Example of a multilingual app that can switch between simple and complex translations
+const MultilingualApp: React.FC = () => {
+  const [useComplexTranslations, setUseComplexTranslations] = React.useState(false);
+  const [currentLocale, setCurrentLocale] = React.useState<'en' | 'es'>('en');
+
+  const selectedTranslations = useComplexTranslations ? complexTranslations : simpleTranslations;
+
+  return (
+    <Metropolis
+      translations={selectedTranslations}
+      config={{
+        development: {
+          app: {
+            api: {
+              url: 'https://api.example.com'
+            },
+            urls: {
+              websocket: 'wss://ws.example.com'
+            }
+          }
+        }
+      }}
+    >
+      <div>
+        <div style={{marginBottom: '20px'}}>
+          <label>
+            <input
+              type="checkbox"
+              checked={useComplexTranslations}
+              onChange={(e) => setUseComplexTranslations(e.target.checked)}
+            />
+            Use Complex Translations
+          </label>
+
+          {useComplexTranslations && (
+            <div style={{marginLeft: '20px'}}>
+              <label>
+                Locale:
+                <select value={currentLocale} onChange={(e) => setCurrentLocale(e.target.value as 'en' | 'es')}>
+                  <option value="en">English</option>
+                  <option value="es">Español</option>
+                </select>
+              </label>
+            </div>
+          )}
+        </div>
+
+        <h1>
+          {useComplexTranslations
+            ? i18n('welcome', {}, currentLocale, 'common')
+            : i18n('welcome')
+          }
+        </h1>
+
+        <p>
+          {useComplexTranslations
+            ? i18n('hello', {name: 'World'}, currentLocale, 'common')
+            : i18n('hello', {name: 'World'})
+          }
+        </p>
+
+        <div>
+          <button>
+            {useComplexTranslations
+              ? i18n('save', {}, currentLocale, 'buttons')
+              : i18n('save')
+            }
+          </button>
+          <button>
+            {useComplexTranslations
+              ? i18n('cancel', {}, currentLocale, 'buttons')
+              : i18n('cancel')
+            }
+          </button>
+        </div>
+
+        <UserProfile />
+        <LoginForm />
+      </div>
+    </Metropolis>
+  );
+};
+
+export default MultilingualApp;

package/factoryPatternGuide.md

@@ -0,0 +1,244 @@
+# MetropolisJS Factory Pattern Guide
+
+## Overview
+
+MetropolisJS has been refactored to use a **factory function pattern** for actions instead of class-based approaches. This provides better functional programming practices, improved testability, and enhanced flexibility through dependency injection.
+
+## Key Benefits
+
+1. **Functional Programming**: Pure functions instead of classes with side effects
+2. **Better Testability**: Easier to mock and test individual functions
+3. **Composability**: Actions can be easily combined and extended
+4. **Dependency Injection**: Custom adapters can be injected and merged with defaults
+5. **Backward Compatibility**: Legacy class wrappers maintain existing API compatibility
+
+## Basic Usage
+
+### Before (Class-based)
+
+```typescript
+import {userActions} from '../actions/userActions';
+
+const userActions = new userActions(flux);
+const user = await userActions.add(userData);
+```
+
+### After (Factory Pattern)
+
+```typescript
+import {createUserActions} from '../actions/userActions';
+
+const userActions = createUserActions(flux);
+const user = await userActions.add(userData);
+```
+
+## Advanced Usage with Custom Adapters
+
+### Custom Validation Adapter
+
+```typescript
+// Custom adapter that extends default behavior
+const customUserAdapter = (input: unknown, options?: UserAdapterOptions) => {
+  // input is already validated by default adapter
+  const user = input as any;
+
+  // Add business-specific validation
+  if (user.email && !user.email.includes('@company.com')) {
+    throw new Error('Only company emails allowed');
+  }
+
+  // Add computed fields
+  return {
+    ...user,
+    fullName: `${user.firstName || ''} ${user.lastName || ''}`.trim(),
+    isAdmin: user.userAccess >= 3
+  };
+};
+
+const userActions = createUserActions(flux, {
+  userAdapter: customUserAdapter
+});
+```
+
+### Configuration-based Adapters
+
+```typescript
+const userActions = createUserActions(flux, {
+  userAdapterOptions: {
+    strict: true,
+    environment: 'production',
+    customValidation: (input) => {
+      // Additional validation logic
+      return input;
+    }
+  }
+});
+```
+
+### Runtime Adapter Updates
+
+```typescript
+const userActions = createUserActions(flux);
+
+// Update adapter at runtime
+userActions.updateUserAdapter(customUserAdapter);
+
+// Update options at runtime
+userActions.updateUserAdapterOptions({
+  strict: true,
+  environment: 'production'
+});
+```
+
+## Available Actions
+
+All action files now export factory functions:
+
+- `createUserActions(flux, options?)` - User management
+- `createPostActions(flux, options?)` - Post management
+- `createEventActions(flux, options?)` - Event management
+- `createMessageActions(flux, options?)` - Messaging
+- `createImageActions(flux, options?)` - Image handling
+- `createLocationActions(flux, options?)` - Location services
+- `createReactionActions(flux, options?)` - Reactions
+- `createTagActions(flux, options?)` - Tag management
+- `createWebsocketActions(flux)` - WebSocket connections
+
+## Adapter Options Interface
+
+All adapters support the same options interface:
+
+```typescript
+interface AdapterOptions {
+  strict?: boolean;                    // Enable strict validation
+  allowPartial?: boolean;              // Allow partial data
+  environment?: 'development' | 'production' | 'test';
+  customValidation?: (input: unknown) => unknown;
+}
+```
+
+## Migration Guide
+
+### Step 1: Update Imports
+
+```typescript
+// Old
+import {userActions} from '../actions/userActions';
+
+// New
+import {createUserActions} from '../actions/userActions';
+```
+
+### Step 2: Update Instantiation
+
+```typescript
+// Old
+const userActions = new userActions(flux, customAdapter);
+
+// New
+const userActions = createUserActions(flux, {
+  userAdapter: customAdapter
+});
+```
+
+### Step 3: Update useMetropolis Hook
+
+The `useMetropolis` hook has been updated to use the factory pattern:
+
+```typescript
+// Old
+return useMemo(() => ({
+  userActions: new userActions(flux, UserAdapter),
+  postActions: new PostActions(flux, PostAdapter),
+  // ...
+}), [flux, UserAdapter, PostAdapter]);
+
+// New
+return useMemo(() => ({
+  userActions: createUserActions(flux, {
+    userAdapter: UserAdapter
+  }),
+  postActions: createPostActions(flux, {
+    postAdapter: PostAdapter
+  }),
+  // ...
+}), [flux, UserAdapter, PostAdapter]);
+```
+
+## Backward Compatibility
+
+Legacy class wrappers are provided for backward compatibility:
+
+```typescript
+// Still works
+import {userActionsClass} from '../actions/userActions';
+const userActions = new userActionsClass(flux, options);
+```
+
+## Testing Examples
+
+### Unit Testing Actions
+
+```typescript
+import {createUserActions} from '../actions/userActions';
+
+describe('userActions', () => {
+  let flux: FluxFramework;
+  let userActions: userActions;
+
+  beforeEach(() => {
+    flux = createMockFlux();
+    userActions = createUserActions(flux);
+  });
+
+  it('should add user with validation', async () => {
+    const userData = {username: 'test', email: 'test@example.com'};
+    const result = await userActions.add(userData);
+    expect(result).toBeDefined();
+  });
+});
+```
+
+### Testing with Custom Adapters
+
+```typescript
+const mockAdapter = jest.fn((input) => ({
+  ...input,
+  validated: true
+}));
+
+const userActions = createUserActions(flux, {
+  userAdapter: mockAdapter
+});
+
+expect(mockAdapter).toHaveBeenCalled();
+```
+
+## Best Practices
+
+1. **Use Factory Functions**: Prefer `createXxxActions()` over class constructors
+2. **Leverage Adapter Injection**: Use custom adapters for business logic
+3. **Runtime Updates**: Use update methods for dynamic behavior changes
+4. **Type Safety**: Always use TypeScript interfaces for better type checking
+5. **Error Handling**: Custom adapters should throw meaningful errors
+
+## Performance Considerations
+
+- Factory functions are lightweight and create minimal overhead
+- Adapter validation is only performed when needed
+- Options are merged efficiently without deep cloning
+- Legacy wrappers have minimal performance impact
+
+## Future Enhancements
+
+The factory pattern enables future enhancements:
+
+- **Middleware Support**: Chain multiple adapters
+- **Plugin System**: Load adapters dynamically
+- **Caching**: Cache validated results
+- **Async Adapters**: Support async validation logic
+- **Schema Evolution**: Handle multiple adapter versions
+
+## Conclusion
+
+The factory pattern provides a more functional, testable, and flexible approach to action management in MetropolisJS. While maintaining backward compatibility, it opens up new possibilities for customization and extension.

package/index.js

@@ -2,4 +2,5 @@
  * Copyright (c) 2018-Present, Nitrogen Labs, Inc.
  * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
  */
+export { i18n, initI18n, updateI18nResources } from './src/utils/i18n';
 module.exports = require('./lib');

package/jest.config.mjs

@@ -0,0 +1,28 @@
+/**
+ * Jest configuration for MetropolisJS tests.
+ * Pulls the default Lex Jest config (which includes TS/Babel transforms)
+ * and overlays the project-specific settings from lex.config.mjs.
+ */
+import lexConfig from './lex.config.mjs';
+import baseConfig from './node_modules/@nlabs/lex/jest.config.mjs';
+
+const projectJest = lexConfig?.jest || {};
+
+export default {
+  ...baseConfig,
+  ...projectJest,
+  testPathIgnorePatterns: [
+    'lib/__tests__/e2e/helpers/testGraphQLServer.d.ts',
+    'lib/__tests__/e2e/helpers/testGraphQLServerSimple.d.ts'
+  ],
+  transformIgnorePatterns: [
+    '/node_modules/(?!(?:@nlabs/utils|@nlabs/rip-hunter)/)'
+  ],
+  moduleNameMapper: {
+    ...baseConfig.moduleNameMapper,
+    ...projectJest.moduleNameMapper
+  },
+  transform: {
+    ...baseConfig.transform
+  }
+};