lambder 1.0.129 → 1.0.131

package/docs/MSW_MOCKING.md

@@ -0,0 +1,606 @@
+# MSW Mocking for Lambder
+
+This guide explains how to use Mock Service Worker (MSW) with Lambder to mock API endpoints in your tests and development environment.
+
+## Installation
+
+MSW is an optional peer dependency. Install it in your project:
+
+```bash
+npm install --save-dev msw
+```
+
+## Important Note
+
+Lambder's `mockLambderApi` functions return MSW's `RequestHandler` type directly (via `http.post()`). This means they work seamlessly with MSW's `setupWorker` and `setupServer`:
+
+```typescript
+import { setupWorker } from 'msw/browser';
+import { mockLambderApi } from 'lambder';
+
+// ✅ These are proper MSW RequestHandler instances
+const handlers = [
+  mockLambderApi('api.getName', () => ({ name: 'Test' }))
+];
+
+export const worker = setupWorker(...handlers); // Works perfectly!
+```
+
+## Overview
+
+Lambder provides type-safe mocking utilities that work seamlessly with MSW to mock your Lambder API endpoints. This is especially useful for:
+
+- **Testing**: Write unit and integration tests without hitting real APIs
+- **Development**: Develop frontend features before backend APIs are ready
+- **Storybook**: Create isolated component stories with mocked data
+- **Offline Development**: Work without a network connection
+
+## Quick Start
+
+### 1. Define Your API Contract
+
+First, ensure you have your API contract defined:
+
+```typescript
+// api-contract.ts
+import { ApiContract } from 'lambder';
+
+export const myApiContract = {
+  'user.getProfile': {
+    input: { userId: '' as string },
+    output: { name: '' as string, email: '' as string }
+  },
+  'user.updateProfile': {
+    input: { userId: '' as string, name: '' as string },
+    output: { success: true as boolean }
+  },
+  'admin.deleteUser': {
+    input: { userId: '' as string },
+    output: { success: true as boolean }
+  }
+} satisfies ApiContract;
+
+export type MyApiContract = typeof myApiContract;
+```
+
+### 2. Set Up MSW
+
+Create mock handlers using Lambder's mocking utilities:
+
+```typescript
+// mocks/handlers.ts
+import { mockLambderApi } from 'lambder';
+import type { MyApiContract } from './api-contract';
+
+export const handlers = [
+  // Basic mock with static data
+  mockLambderApi<MyApiContract, 'user.getProfile'>(
+    'user.getProfile',
+    () => ({
+      name: 'John Doe',
+      email: 'john@example.com'
+    })
+  ),
+
+  // Mock with dynamic response based on input
+  mockLambderApi<MyApiContract, 'user.updateProfile'>(
+    'user.updateProfile',
+    (input) => ({
+      success: true
+    }),
+    {
+      delay: 500 // Simulate network delay
+    }
+  )
+];
+```
+
+### 3. Initialize MSW
+
+#### For Node.js (Tests)
+
+```typescript
+// mocks/server.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+```
+
+```typescript
+// vitest.setup.ts or jest.setup.ts
+import { server } from './mocks/server';
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+#### For Browser (Development/Storybook)
+
+```typescript
+// mocks/browser.ts
+import { setupWorker } from 'msw/browser';
+import { handlers } from './handlers';
+
+export const worker = setupWorker(...handlers);
+```
+
+```typescript
+// main.tsx or index.tsx
+if (process.env.NODE_ENV === 'development') {
+  const { worker } = await import('./mocks/browser');
+  worker.start();
+}
+```
+
+## API Reference
+
+### `mockLambderApi`
+
+Creates a mock handler for a successful API response.
+
+```typescript
+mockLambderApi<TContract, TApiName>(
+  apiName: TApiName,
+  responseFactory: (input) => output | Promise<output>,
+  options?: {
+    apiPath?: string;      // Default: '/api'
+    delay?: number;        // Delay in ms
+    apiVersion?: string;   // Custom API version
+  }
+)
+```
+
+**Example:**
+```typescript
+mockLambderApi<MyApiContract, 'user.getProfile'>(
+  'user.getProfile',
+  (input) => {
+    // Access input with full type safety
+    console.log('Fetching profile for:', input.userId);
+    
+    return {
+      name: 'John Doe',
+      email: 'john@example.com'
+    };
+  },
+  {
+    delay: 300, // Simulate 300ms network delay
+    apiPath: '/api' // Custom API path
+  }
+)
+```
+
+### `mockLambderApiError`
+
+Creates a mock handler that returns an error response.
+
+```typescript
+mockLambderApiError<TContract, TApiName>(
+  apiName: TApiName,
+  errorMessage: string,
+  options?: {
+    apiPath?: string;
+    delay?: number;
+    apiVersion?: string;
+  }
+)
+```
+
+**Example:**
+```typescript
+mockLambderApiError<MyApiContract, 'user.updateProfile'>(
+  'user.updateProfile',
+  'Failed to update profile',
+  { delay: 500 }
+)
+```
+
+### `mockLambderSessionExpired`
+
+Simulates a session expired error.
+
+```typescript
+mockLambderSessionExpired<TContract, TApiName>(
+  apiName: TApiName,
+  options?: {
+    apiPath?: string;
+    apiVersion?: string;
+  }
+)
+```
+
+**Example:**
+```typescript
+mockLambderSessionExpired<MyApiContract, 'user.updateProfile'>(
+  'user.updateProfile'
+)
+```
+
+### `mockLambderNotAuthorized`
+
+Simulates a "not authorized" error.
+
+```typescript
+mockLambderNotAuthorized<TContract, TApiName>(
+  apiName: TApiName,
+  options?: {
+    apiPath?: string;
+    apiVersion?: string;
+  }
+)
+```
+
+**Example:**
+```typescript
+mockLambderNotAuthorized<MyApiContract, 'admin.deleteUser'>(
+  'admin.deleteUser'
+)
+```
+
+### `mockLambderVersionExpired`
+
+Simulates a version expired error.
+
+```typescript
+mockLambderVersionExpired<TContract, TApiName>(
+  apiName: TApiName,
+  options?: {
+    apiPath?: string;
+    apiVersion?: string;
+  }
+)
+```
+
+**Example:**
+```typescript
+mockLambderVersionExpired<MyApiContract, 'user.getProfile'>(
+  'user.getProfile'
+)
+```
+
+### `createLambderApiHandler`
+
+Helper function to group multiple handlers for the same API path.
+
+```typescript
+createLambderApiHandler(
+  apiPath: string,
+  handlers: HttpHandler[]
+)
+```
+
+**Example:**
+```typescript
+import { setupServer } from 'msw/node';
+import { createLambderApiHandler, mockLambderApi } from 'lambder';
+
+const server = setupServer(
+  createLambderApiHandler('/api', [
+    mockLambderApi<MyApiContract, 'user.getProfile'>('user.getProfile', () => ({
+      name: 'Test User',
+      email: 'test@example.com'
+    })),
+    mockLambderApi<MyApiContract, 'user.updateProfile'>('user.updateProfile', (input) => ({
+      success: true
+    }))
+  ])
+);
+```
+
+## Testing Examples
+
+### Vitest
+
+```typescript
+// user-profile.test.ts
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
+import { server } from './mocks/server';
+import { mockLambderApi } from 'lambder';
+import type { MyApiContract } from './api-contract';
+
+describe('User Profile', () => {
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it('should fetch user profile', async () => {
+    // Test with mocked data
+    const result = await caller.api('user.getProfile', { userId: '123' });
+    
+    expect(result).toEqual({
+      name: 'John Doe',
+      email: 'john@example.com'
+    });
+  });
+
+  it('should handle errors', async () => {
+    // Override handler for this test
+    server.use(
+      mockLambderApiError<MyApiContract, 'user.getProfile'>(
+        'user.getProfile',
+        'User not found'
+      )
+    );
+
+    const result = await caller.api('user.getProfile', { userId: '999' });
+    
+    expect(result).toBeNull();
+  });
+
+  it('should handle session expiry', async () => {
+    server.use(
+      mockLambderSessionExpired<MyApiContract, 'user.updateProfile'>(
+        'user.updateProfile'
+      )
+    );
+
+    const result = await caller.api('user.updateProfile', {
+      userId: '123',
+      name: 'New Name'
+    });
+    
+    expect(result).toBeNull();
+  });
+});
+```
+
+### React Testing Library
+
+```typescript
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { server } from './mocks/server';
+import { mockLambderApi } from 'lambder';
+import UserProfile from './UserProfile';
+
+test('displays user profile', async () => {
+  render(<UserProfile userId="123" />);
+
+  await waitFor(() => {
+    expect(screen.getByText('John Doe')).toBeInTheDocument();
+    expect(screen.getByText('john@example.com')).toBeInTheDocument();
+  });
+});
+
+test('handles update', async () => {
+  const user = userEvent.setup();
+  render(<UserProfile userId="123" />);
+
+  const nameInput = screen.getByLabelText('Name');
+  await user.clear(nameInput);
+  await user.type(nameInput, 'Jane Doe');
+  
+  await user.click(screen.getByText('Save'));
+
+  await waitFor(() => {
+    expect(screen.getByText('Profile updated successfully')).toBeInTheDocument();
+  });
+});
+```
+
+## Advanced Usage
+
+### Dynamic Responses Based on Input
+
+```typescript
+mockLambderApi<MyApiContract, 'user.getProfile'>(
+  'user.getProfile',
+  (input) => {
+    // Return different data based on input
+    const profiles = {
+      '1': { name: 'John Doe', email: 'john@example.com' },
+      '2': { name: 'Jane Smith', email: 'jane@example.com' }
+    };
+    
+    return profiles[input.userId] || { name: 'Unknown', email: '' };
+  }
+)
+```
+
+### Simulating Loading States
+
+```typescript
+mockLambderApi<MyApiContract, 'user.getProfile'>(
+  'user.getProfile',
+  async (input) => {
+    // Simulate slow network
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    
+    return {
+      name: 'John Doe',
+      email: 'john@example.com'
+    };
+  },
+  {
+    delay: 2000 // Alternative way to add delay
+  }
+)
+```
+
+### Conditional Error Responses
+
+```typescript
+mockLambderApi<MyApiContract, 'user.updateProfile'>(
+  'user.updateProfile',
+  (input) => {
+    // Validate input and throw if needed
+    if (!input.name || input.name.length < 2) {
+      throw new Error('Name must be at least 2 characters');
+    }
+    
+    return { success: true };
+  }
+)
+```
+
+### Multiple API Paths
+
+```typescript
+// For different environments or API versions
+export const devHandlers = [
+  mockLambderApi<MyApiContract, 'user.getProfile'>(
+    'user.getProfile',
+    () => ({ name: 'Dev User', email: 'dev@example.com' }),
+    { apiPath: '/dev/api' }
+  )
+];
+
+export const prodHandlers = [
+  mockLambderApi<MyApiContract, 'user.getProfile'>(
+    'user.getProfile',
+    () => ({ name: 'Prod User', email: 'prod@example.com' }),
+    { apiPath: '/api' }
+  )
+];
+```
+
+## Storybook Integration
+
+```typescript
+// .storybook/preview.tsx
+import { initialize, mswLoader } from 'msw-storybook-addon';
+import { handlers } from '../mocks/handlers';
+
+initialize();
+
+export const loaders = [mswLoader];
+
+export const parameters = {
+  msw: {
+    handlers
+  }
+};
+```
+
+```typescript
+// UserProfile.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { mockLambderApi, mockLambderApiError } from 'lambder';
+import type { MyApiContract } from './api-contract';
+import UserProfile from './UserProfile';
+
+const meta: Meta<typeof UserProfile> = {
+  component: UserProfile,
+};
+
+export default meta;
+type Story = StoryObj<typeof UserProfile>;
+
+export const Default: Story = {
+  args: {
+    userId: '123'
+  },
+  parameters: {
+    msw: {
+      handlers: [
+        mockLambderApi<MyApiContract, 'user.getProfile'>(
+          'user.getProfile',
+          () => ({
+            name: 'John Doe',
+            email: 'john@example.com'
+          })
+        )
+      ]
+    }
+  }
+};
+
+export const LoadingState: Story = {
+  args: {
+    userId: '123'
+  },
+  parameters: {
+    msw: {
+      handlers: [
+        mockLambderApi<MyApiContract, 'user.getProfile'>(
+          'user.getProfile',
+          () => ({
+            name: 'John Doe',
+            email: 'john@example.com'
+          }),
+          { delay: 3000 }
+        )
+      ]
+    }
+  }
+};
+
+export const ErrorState: Story = {
+  args: {
+    userId: '123'
+  },
+  parameters: {
+    msw: {
+      handlers: [
+        mockLambderApiError<MyApiContract, 'user.getProfile'>(
+          'user.getProfile',
+          'Failed to load user profile'
+        )
+      ]
+    }
+  }
+};
+```
+
+## Best Practices
+
+1. **Keep Handlers in a Separate Directory**: Organize your mocks in a `mocks/` folder for easy maintenance.
+
+2. **Use Type Safety**: Always specify your API contract types to get full IntelliSense support.
+
+3. **Reset Handlers Between Tests**: Use `server.resetHandlers()` in `afterEach` to prevent test pollution.
+
+4. **Mock Realistic Data**: Use realistic data in your mocks to catch potential issues early.
+
+5. **Test Error Cases**: Don't just test happy paths - use error mocks to test error handling.
+
+6. **Use Delays Sparingly**: Only add delays when testing loading states to keep tests fast.
+
+7. **Version Your Mocks**: If using API versions, include them in your mock setup.
+
+## Troubleshooting
+
+### MSW Not Working
+
+If MSW handlers aren't being called:
+
+1. Ensure MSW is properly initialized before your tests/app
+2. Check that the API path matches your configuration
+3. Verify the API name in the handler matches what you're calling
+4. Check browser console for MSW logs
+
+### TypeScript Errors
+
+If you see TypeScript errors about missing MSW types:
+
+```bash
+npm install --save-dev @types/msw
+```
+
+Or use the built-in `HttpHandler` type from Lambder:
+
+```typescript
+import type { HttpHandler } from 'lambder';
+```
+
+### Handlers Not Matching
+
+MSW handlers are checked in order. If a handler isn't matching:
+
+1. Put more specific handlers before generic ones
+2. Use `server.listHandlers()` to debug which handlers are registered
+3. Add console.log statements in your response factories
+
+## Resources
+
+- [MSW Documentation](https://mswjs.io/)
+- [MSW Storybook Addon](https://storybook.js.org/addons/msw-storybook-addon)
+- [Lambder API Contract Documentation](./TYPE_SAFE_QUICK_START.md)
+
+## Support
+
+For issues or questions:
+- Open an issue on [GitHub](https://github.com/nesovera/lambder)
+- Check existing documentation in the `/docs` folder