@nlabs/metropolisjs 0.1.1 → 0.1.2

package/FACTORY_PATTERN_GUIDE.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/README.md

@@ -0,0 +1,332 @@
+# MetropolisJS: Seamless Frontend-Backend Integration Framework
+
+> **The Ultimate Frontend Integration Library for Modern Web Applications**
+
+[![npm version](https://img.shields.io/npm/v/@nlabs/metropolisjs.svg?style=flat-square)](https://www.npmjs.com/package/@nlabs/metropolisjs)
+[![npm downloads](https://img.shields.io/npm/dm/@nlabs/metropolisjs.svg?style=flat-square)](https://www.npmjs.com/package/@nlabs/metropolisjs)
+[![Issues](http://img.shields.io/github/issues/nitrogenlabs/metropolisjs.svg?style=flat-square)](https://github.com/nitrogenlabs/metropolisjs/issues)
+[![TypeScript](https://badges.frapsoft.com/typescript/version/typescript-next.svg?v=101)](https://github.com/ellerbrock/typescript-badges/)
+[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](http://opensource.org/licenses/MIT)
+[![Chat](https://img.shields.io/discord/446122412715802649.svg)](https://discord.gg/Ttgev58)
+
+MetropolisJS is the bridge that connects your frontend dreams to backend reality. Built on the powerful combination of **Reaktor** (backend services) and **ArkhamJS** (frontend data store), MetropolisJS provides a seamless, real-time integration layer that handles everything from user authentication to real-time messaging and notifications.
+
+## 🚀 Why MetropolisJS?
+
+### ✨ **Seamless Integration**
+
+Connect your React frontend to Reaktor-powered backend services with zero configuration headaches. MetropolisJS handles all the complex data flow, state management, and real-time communication.
+
+### 🔄 **Real-Time Everything**
+
+Built-in WebSocket and Server-Sent Events (SSE) support for instant messaging, live notifications, and real-time data synchronization. Your users will never miss a beat.
+
+### 🛡️ **Type-Safe & Reliable**
+
+Full TypeScript support with comprehensive type definitions. Catch errors at compile time, not runtime.
+
+### 🎯 **Developer Experience First**
+
+Clean, intuitive APIs that make complex operations feel simple. Focus on building features, not boilerplate.
+
+## 🎯 What Can You Build?
+
+MetropolisJS powers applications that need:
+
+- **🔐 User Authentication & Authorization**
+- **💬 Real-Time Messaging Systems**
+- **🔔 Live Notifications**
+- **📱 Social Media Features** (posts, reactions, tags)
+- **📍 Location-Based Services**
+- **🖼️ Media Management** (images, files)
+- **📅 Event Management**
+- **👥 User Connections & Relationships**
+
+## 🛠️ Quick Start
+
+### Installation
+
+```bash
+npm install @nlabs/metropolisjs @nlabs/arkhamjs @nlabs/arkhamjs-utils-react
+```
+
+### Basic Setup
+
+```tsx
+import React from 'react';
+import {Metropolis} from '@nlabs/metropolisjs';
+import {useMetropolis} from '@nlabs/metropolisjs';
+
+const App = () => {
+  return (
+    <Metropolis config={{
+      environment: 'development',
+      // Your configuration here
+    }}>
+      <YourApp />
+    </Metropolis>
+  );
+};
+
+const YourApp = () => {
+  const {userActions, messageActions, websocketActions} = useMetropolis();
+
+  // Start building amazing features!
+  return <div>Your app content</div>;
+};
+```
+
+### User Authentication Example
+
+```tsx
+const LoginForm = () => {
+  const {userActions} = useMetropolis();
+  const [username, setUsername] = useState('');
+  const [password, setPassword] = useState('');
+
+  const handleLogin = async () => {
+    try {
+      const session = await userActions.signIn(username, password);
+      console.log('User logged in successfully!', session);
+    } catch (error) {
+      console.error('Login failed:', error);
+    }
+  };
+
+  return (
+    <form onSubmit={handleLogin}>
+      <input
+        value={username}
+        onChange={(e) => setUsername(e.target.value)}
+        placeholder="Username"
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="Password"
+      />
+      <button type="submit">Sign In</button>
+    </form>
+  );
+};
+```
+
+### Real-Time Messaging
+
+```tsx
+const ChatComponent = () => {
+  const {messageActions, websocketActions} = useMetropolis();
+  const [messages, setMessages] = useState([]);
+
+  useEffect(() => {
+    // Initialize WebSocket connection
+    websocketActions.wsInit();
+
+    // Load existing messages
+    messageActions.list().then(setMessages);
+  }, []);
+
+  const sendMessage = async (content) => {
+    await messageActions.add({ content });
+    // Message automatically appears in real-time for all connected users!
+  };
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.messageId}>{message.content}</div>
+      ))}
+      <button onClick={() => sendMessage('Hello World!')}>
+        Send Message
+      </button>
+    </div>
+  );
+};
+```
+
+## 🏗️ Architecture
+
+MetropolisJS is built on a powerful three-layer architecture:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   React App     │    │   MetropolisJS  │    │   Reaktor       │
+│                 │◄──►│                 │◄──►│   Backend       │
+│   UI Layer      │    │   Integration   │    │   Services      │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                              │
+                              ▼
+                       ┌─────────────────┐
+                       │   ArkhamJS      │
+                       │   Data Store    │
+                       │                 │
+                       └─────────────────┘
+```
+
+### 🔧 Core Components
+
+- **Actions**: Handle all API interactions and business logic
+- **Adapters**: Transform data between frontend and backend formats
+- **Stores**: Manage application state with ArkhamJS
+- **WebSocket Actions**: Handle real-time communication
+- **Configuration**: Flexible setup for any environment
+
+## 📚 Available Actions
+
+MetropolisJS provides comprehensive action classes for all your needs:
+
+- **userActions**: Authentication, profiles, user management
+- **messageActions**: Real-time messaging and conversations
+- **postActions**: Social media posts and content
+- **reactionActions**: Likes, reactions, and interactions
+- **tagActions**: Content categorization and discovery
+- **eventActions**: Event management and scheduling
+- **imageActions**: Media upload and management
+- **locationActions**: Geolocation and location-based features
+- **websocketActions**: Real-time communication setup
+
+## 🔌 Adapters
+
+Customize data transformation with powerful adapters:
+
+- **userAdapter**: User profiles and authentication data
+- **messageAdapter**: Chat and messaging data
+- **postAdapter**: Social media content
+- **eventAdapter**: Event and scheduling data
+- **imageAdapter**: Media and file data
+- **locationAdapter**: Geolocation data
+- **tagAdapter**: Categorization data
+- **reactionAdapter**: User interaction data
+
+## ⚡ Real-Time Features
+
+### WebSocket Integration
+
+```tsx
+const {websocketActions} = useMetropolis();
+
+// Initialize real-time connections
+websocketActions.wsInit();
+
+// Messages, notifications, and data updates
+// are automatically synchronized across all clients
+```
+
+### Server-Sent Events
+
+Built-in SSE support for lightweight real-time updates without the overhead of WebSocket connections.
+
+## 🎨 Customization
+
+### Custom Adapters
+
+```tsx
+class CustomUserAdapter extends User {
+  // Override methods to customize data transformation
+  toJson() {
+    const data = super.toJson();
+    return {
+      ...data,
+      displayName: `${data.firstName} ${data.lastName}`,
+      customField: 'custom value'
+    };
+  }
+}
+
+// Use custom adapter
+const {userActions} = useMetropolis({
+  adapters: {
+    User: CustomUserAdapter
+  }
+});
+```
+
+### Configuration
+
+```tsx
+const config = {
+  environment: 'production',
+  app: {
+    session: {
+      maxMinutes: 1440, // 24 hours
+      minMinutes: 15
+    }
+  },
+  isAuth: () => {
+    // Custom authentication logic
+    return true;
+  }
+};
+```
+
+## 🚀 Performance Features
+
+- **Debounced API calls** to prevent excessive requests
+- **Intelligent caching** with ArkhamJS
+- **Optimistic updates** for instant UI feedback
+- **Connection pooling** for WebSocket efficiency
+- **Lazy loading** support for large datasets
+
+## 🔒 Security
+
+- **Automatic token refresh** for seamless sessions
+- **Secure WebSocket connections** with authentication
+- **Input validation** and sanitization
+- **CSRF protection** built-in
+- **Session management** with configurable timeouts
+
+## 📦 Installation & Setup
+
+### Prerequisites
+
+- Node.js 16+
+- React 18+
+- TypeScript 4.5+
+
+### Full Installation
+
+```bash
+# Install MetropolisJS and dependencies
+npm install @nlabs/metropolisjs @nlabs/arkhamjs @nlabs/arkhamjs-utils-react
+
+# For development
+npm install --save-dev @types/react @types/node
+```
+
+### Environment Setup
+
+```bash
+# Set your environment variables
+export NODE_ENV=development
+export REAKTOR_API_URL=your-reaktor-backend-url
+```
+
+## 🤝 Contributing
+
+We love contributions! Here's how you can help:
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
+4. **Push** to the branch (`git push origin feature/amazing-feature`)
+5. **Open** a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- **Documentation**: [Coming Soon]
+- **Issues**: [GitHub Issues](https://github.com/nitrogenlabs/metropolisjs/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/nitrogenlabs/metropolisjs/discussions)
+- **Email**: <giraldo@nitrogenlabs.com>
+
+## 🏢 About Nitrogen Labs
+
+MetropolisJS is proudly developed by [Nitrogen Labs](http://nitrogenlabs.com), a team passionate about building powerful, developer-friendly tools that make web development faster, more reliable, and more enjoyable.
+
+---
+
+**Ready to build the future?** Start with MetropolisJS today and experience the power of seamless frontend-backend integration! 🚀