lambder 1.0.129 → 1.0.130

package/examples/msw-mocking-example.ts

@@ -0,0 +1,241 @@
+/**
+ * Example: Using MSW to mock Lambder API endpoints
+ * 
+ * This example demonstrates how to use Mock Service Worker (MSW) with Lambder
+ * to create type-safe mocks for your API endpoints.
+ * 
+ * Prerequisites:
+ * - Install MSW: npm install --save-dev msw
+ * - Define your API contract
+ */
+
+import { 
+  mockLambderApi, 
+  mockLambderApiError,
+  mockLambderSessionExpired,
+  mockLambderNotAuthorized,
+  mockLambderVersionExpired,
+  type ApiContractShape 
+} from '../src/index.js';
+
+// 1. Define your API contract
+const myApiContract = {
+  'user.getProfile': {
+    input: { userId: '' as string },
+    output: { name: '' as string, email: '' as string, role: '' as string }
+  },
+  'user.updateProfile': {
+    input: { userId: '' as string, name: '' as string, email: '' as string },
+    output: { success: true as boolean, message: '' as string }
+  },
+  'user.deleteAccount': {
+    input: { userId: '' as string },
+    output: { success: true as boolean }
+  },
+  'admin.listUsers': {
+    input: { page: 0 as number, limit: 0 as number },
+    output: { users: [] as Array<{ id: string; name: string }>, total: 0 as number }
+  }
+} satisfies ApiContractShape;
+
+type MyApiContract = typeof myApiContract;
+
+// 2. Create mock handlers
+
+// Basic success mock
+export const getUserProfileHandler = mockLambderApi<MyApiContract, 'user.getProfile'>(
+  'user.getProfile',
+  (input) => {
+    console.log('Mocking user.getProfile for userId:', input.userId);
+    
+    // Return mock data with full type safety
+    return {
+      name: 'John Doe',
+      email: 'john@example.com',
+      role: 'user'
+    };
+  }
+);
+
+// Mock with dynamic response based on input
+export const updateProfileHandler = mockLambderApi<MyApiContract, 'user.updateProfile'>(
+  'user.updateProfile',
+  (input) => {
+    console.log('Mocking user.updateProfile:', input);
+    
+    // Validate input
+    if (!input.name || input.name.length < 2) {
+      throw new Error('Name must be at least 2 characters');
+    }
+    
+    return {
+      success: true,
+      message: `Profile updated for ${input.name}`
+    };
+  },
+  {
+    delay: 500 // Simulate network delay
+  }
+);
+
+// Mock with error response
+export const updateProfileErrorHandler = mockLambderApiError<MyApiContract, 'user.updateProfile'>(
+  'user.updateProfile',
+  'Failed to update profile due to server error',
+  {
+    delay: 300
+  }
+);
+
+// Mock session expired
+export const deleteAccountSessionExpiredHandler = mockLambderSessionExpired<MyApiContract, 'user.deleteAccount'>(
+  'user.deleteAccount'
+);
+
+// Mock not authorized
+export const listUsersNotAuthorizedHandler = mockLambderNotAuthorized<MyApiContract, 'admin.listUsers'>(
+  'admin.listUsers'
+);
+
+// Mock version expired
+export const getProfileVersionExpiredHandler = mockLambderVersionExpired<MyApiContract, 'user.getProfile'>(
+  'user.getProfile'
+);
+
+// Mock with pagination
+export const listUsersHandler = mockLambderApi<MyApiContract, 'admin.listUsers'>(
+  'admin.listUsers',
+  (input) => {
+    // Generate mock paginated data
+    const allUsers = Array.from({ length: 50 }, (_, i) => ({
+      id: `user-${i + 1}`,
+      name: `User ${i + 1}`
+    }));
+    
+    const start = input.page * input.limit;
+    const end = start + input.limit;
+    const users = allUsers.slice(start, end);
+    
+    return {
+      users,
+      total: allUsers.length
+    };
+  }
+);
+
+// 3. Set up MSW handlers
+
+// For Node.js testing (Vitest, Jest, etc.)
+/**
+ * Setup example for Node.js tests:
+ * 
+ * ```typescript
+ * // test-setup.ts
+ * import { setupServer } from 'msw/node';
+ * import { getUserProfileHandler, updateProfileHandler } from './msw-example';
+ * 
+ * export const server = setupServer(
+ *   getUserProfileHandler,
+ *   updateProfileHandler,
+ *   listUsersHandler
+ * );
+ * 
+ * // vitest.setup.ts
+ * beforeAll(() => server.listen());
+ * afterEach(() => server.resetHandlers());
+ * afterAll(() => server.close());
+ * ```
+ */
+
+// For browser development/Storybook
+/**
+ * Setup example for browser:
+ * 
+ * ```typescript
+ * // mocks/browser.ts
+ * import { setupWorker } from 'msw/browser';
+ * import { getUserProfileHandler, updateProfileHandler } from './msw-example';
+ * 
+ * export const worker = setupWorker(
+ *   getUserProfileHandler,
+ *   updateProfileHandler,
+ *   listUsersHandler
+ * );
+ * 
+ * // main.tsx
+ * if (import.meta.env.DEV) {
+ *   const { worker } = await import('./mocks/browser');
+ *   worker.start();
+ * }
+ * ```
+ */
+
+// 4. Using in tests
+
+/**
+ * Test example:
+ * 
+ * ```typescript
+ * import { describe, it, expect } from 'vitest';
+ * import { server } from './test-setup';
+ * import { caller } from './api-client';
+ * 
+ * describe('User Profile', () => {
+ *   it('should get user profile', async () => {
+ *     const profile = await caller.api('user.getProfile', { userId: '123' });
+ *     
+ *     expect(profile).toEqual({
+ *       name: 'John Doe',
+ *       email: 'john@example.com',
+ *       role: 'user'
+ *     });
+ *   });
+ * 
+ *   it('should handle update errors', async () => {
+ *     // Override handler for this test
+ *     server.use(updateProfileErrorHandler);
+ *     
+ *     const result = await caller.api('user.updateProfile', {
+ *       userId: '123',
+ *       name: 'New Name',
+ *       email: 'new@example.com'
+ *     });
+ *     
+ *     expect(result).toBeNull(); // Error handler returns null
+ *   });
+ * 
+ *   it('should handle session expiry', async () => {
+ *     server.use(deleteAccountSessionExpiredHandler);
+ *     
+ *     const result = await caller.api('user.deleteAccount', { userId: '123' });
+ *     
+ *     expect(result).toBeNull();
+ *     // Verify sessionExpiredHandler was called if configured
+ *   });
+ * 
+ *   it('should handle not authorized', async () => {
+ *     server.use(listUsersNotAuthorizedHandler);
+ *     
+ *     const result = await caller.api('admin.listUsers', { page: 0, limit: 10 });
+ *     
+ *     expect(result).toBeNull();
+ *     // Verify notAuthorizedHandler was called if configured
+ *   });
+ * });
+ * ```
+ */
+
+// Export all handlers for easy setup
+export const handlers = [
+  getUserProfileHandler,
+  updateProfileHandler,
+  listUsersHandler,
+];
+
+// Export error handlers separately
+export const errorHandlers = [
+  updateProfileErrorHandler,
+  deleteAccountSessionExpiredHandler,
+  listUsersNotAuthorizedHandler,
+  getProfileVersionExpiredHandler,
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "1.0.129",
+  "version": "1.0.130",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,14 @@
     "path-to-regexp": "^6.2.1",
     "querystring": "^0.2.1"
   },
+  "peerDependencies": {
+    "msw": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "msw": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/aws-lambda": "^8.10.136",
     "@types/cookie": "^0.6.0",

package/src/LambderMSW.ts

@@ -0,0 +1,330 @@
+import type { ApiContractShape } from './LambderApiContract.js';
+
+// Type for MSW HttpHandler (defined locally to avoid hard dependency on msw types)
+export type HttpHandler = (info: any) => Promise<Response | undefined> | Response | undefined;
+
+// Dynamic imports to avoid requiring MSW as a hard dependency
+let http: any;
+let HttpResponse: any;
+
+/**
+ * Initialize MSW dependencies dynamically
+ * This allows the module to be imported even if MSW is not installed
+ */
+async function ensureMSW() {
+    if (!http || !HttpResponse) {
+        try {
+            // @ts-ignore - MSW is an optional peer dependency
+            const msw = await import('msw');
+            http = msw.http;
+            HttpResponse = msw.HttpResponse;
+        } catch (err) {
+            throw new Error(
+                'MSW is required to use Lambder mocking utilities. ' +
+                'Install it with: npm install --save-dev msw'
+            );
+        }
+    }
+}
+
+/**
+ * Creates a mock handler for a Lambder API endpoint
+ * 
+ * @example
+ * ```typescript
+ * mockLambderApi('public.getInitialPageData', () => ({
+ *   userLocationData: { ... },
+ *   sessionUser: null
+ * }))
+ * ```
+ * 
+ * @example with dynamic response based on input
+ * ```typescript
+ * mockLambderApi('user.updateProfile', (input) => ({
+ *   success: true,
+ *   userId: input.userId
+ * }))
+ * ```
+ */
+export function mockLambderApi<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    responseFactory: (
+        input: TContract[TApiName]['input']
+    ) => TContract[TApiName]['output'] | Promise<TContract[TApiName]['output']>,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string
+        /** Delay in ms before responding (for testing loading states) */
+        delay?: number
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null
+    }
+): HttpHandler {
+    const apiPath = options?.apiPath ?? '/api';
+    const delay = options?.delay ?? 0;
+    const apiVersion = options?.apiVersion ?? null;
+
+    // Return a handler that will be initialized when MSW is available
+    return (async ({ request }: any) => {
+        await ensureMSW();
+
+        const body = (await request.json()) as {
+            apiName: string;
+            payload?: TContract[TApiName]['input'];
+            version?: string;
+            token?: string;
+            siteHost?: string;
+        };
+
+        // Only handle this specific API
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking ${apiName}`, body.payload);
+
+        // Apply delay if specified
+        if (delay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+
+        // Generate the response
+        const payload = await responseFactory(body.payload as TContract[TApiName]['input']);
+
+        // Return in Lambder API response format
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload,
+        });
+    }) as any;
+}
+
+/**
+ * Creates a mock handler that returns an error for a Lambder API endpoint
+ * 
+ * @example
+ * ```typescript
+ * mockLambderApiError('user.deleteAccount', 'Account deletion failed')
+ * ```
+ */
+export function mockLambderApiError<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    errorMessage: string,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Delay in ms before responding */
+        delay?: number;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+): HttpHandler {
+    const apiPath = options?.apiPath ?? '/api';
+    const delay = options?.delay ?? 0;
+    const apiVersion = options?.apiVersion ?? null;
+
+    return (async ({ request }: any) => {
+        await ensureMSW();
+
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking error for ${apiName}:`, errorMessage);
+
+        if (delay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            errorMessage,
+        });
+    }) as any;
+}
+
+/**
+ * Creates a mock handler that simulates a session expired error
+ * 
+ * @example
+ * ```typescript
+ * mockLambderSessionExpired('user.updateProfile')
+ * ```
+ */
+export function mockLambderSessionExpired<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+): HttpHandler {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+
+    return (async ({ request }: any) => {
+        await ensureMSW();
+
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking session expired for ${apiName}`);
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            sessionExpired: true,
+            errorMessage: 'Session expired',
+        });
+    }) as any;
+}
+
+/**
+ * Creates a mock handler that simulates a "not authorized" error
+ * 
+ * @example
+ * ```typescript
+ * mockLambderNotAuthorized('admin.deleteUser')
+ * ```
+ */
+export function mockLambderNotAuthorized<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+): HttpHandler {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+
+    return (async ({ request }: any) => {
+        await ensureMSW();
+
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking not authorized for ${apiName}`);
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            notAuthorized: true,
+            errorMessage: 'Not authorized',
+        });
+    }) as any;
+}
+
+/**
+ * Creates a mock handler that simulates a version expired error
+ * 
+ * @example
+ * ```typescript
+ * mockLambderVersionExpired('user.updateProfile')
+ * ```
+ */
+export function mockLambderVersionExpired<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+): HttpHandler {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+
+    return (async ({ request }: any) => {
+        await ensureMSW();
+
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking version expired for ${apiName}`);
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            versionExpired: true,
+            errorMessage: 'Version expired',
+        });
+    }) as any;
+}
+
+/**
+ * Helper function to create the MSW http.post handler with proper path matching
+ * This is useful when you need to set up multiple handlers with the same path
+ * 
+ * @example
+ * ```typescript
+ * import { setupServer } from 'msw/node';
+ * 
+ * const server = setupServer(
+ *   createLambderApiHandler('/api', [
+ *     mockLambderApi('user.getProfile', () => ({ name: 'Test User' })),
+ *     mockLambderApi('user.updateProfile', (input) => ({ success: true }))
+ *   ])
+ * );
+ * ```
+ */
+export function createLambderApiHandler(
+    apiPath: string,
+    handlers: HttpHandler[]
+): HttpHandler {
+    return (async (info: any) => {
+        await ensureMSW();
+
+        // Call each handler in sequence until one handles the request
+        for (const handler of handlers) {
+            const result = await handler(info);
+            if (result) {
+                return result;
+            }
+        }
+
+        // No handler matched
+        return;
+    }) as any;
+}

package/src/index.ts

@@ -13,3 +13,14 @@ export {
     type ApiInput,
     type ApiOutput,
 } from "./LambderApiContract.js";
+
+// MSW mocking utilities (optional - requires msw to be installed)
+export {
+    mockLambderApi,
+    mockLambderApiError,
+    mockLambderSessionExpired,
+    mockLambderNotAuthorized,
+    mockLambderVersionExpired,
+    createLambderApiHandler,
+    type HttpHandler,
+} from "./LambderMSW.js";