lambder 1.0.131 → 1.0.133

package/src/LambderMSW.ts

@@ -1,295 +1,186 @@
-import type { ApiContractShape } from './LambderApiContract.js';
-
-/**
- * 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
-    }
-) {
-    const apiPath = options?.apiPath ?? '/api';
-    const delay = options?.delay ?? 0;
-    const apiVersion = options?.apiVersion ?? null;
-
-    // @ts-ignore - MSW is an optional peer dependency
-    const { http, HttpResponse } = require('msw');
-
-    return http.post(apiPath, async ({ request }: any) => {
-        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));
+import type { ApiContractShape } from './LambderApiContract';
+import type { LambderApiResponse } from './LambderResponseBuilder';
+
+// MSW types - these will be resolved at runtime when msw is installed
+type RequestHandler = any;
+
+type MockApiOptions = {
+    versionExpired?: boolean;
+    sessionExpired?: boolean;
+    notAuthorized?: boolean;
+    message?: any;
+    errorMessage?: any;
+    logList?: any[];
+    delay?: number; // Add artificial delay to simulate network latency
+};
+
+// Extended response type that includes apiVersion
+type MockApiResponse<T> = {
+    apiVersion?: string;
+} & LambderApiResponse<T>;
+
+export default class LambderMSW<TContract extends ApiContractShape = any> {
+    private apiPath: string;
+    private apiVersion?: string;
+    private http: any;
+    private HttpResponse: any;
+
+    constructor({
+        apiPath,
+        apiVersion,
+    }: {
+        apiPath: string;
+        apiVersion?: string;
+    }) {
+        this.apiPath = apiPath;
+        this.apiVersion = apiVersion;
+        
+        // Dynamically import MSW - it needs to be installed by the user
+        try {
+            const msw = require('msw');
+            this.http = msw.http;
+            this.HttpResponse = msw.HttpResponse;
+        } catch (err) {
+            throw new Error('MSW (Mock Service Worker) is required. Install it with: npm install msw --save-dev');
         }
-
-        // 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,
-        });
-    });
-}
-
-/**
- * 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;
     }
-) {
-    const apiPath = options?.apiPath ?? '/api';
-    const delay = options?.delay ?? 0;
-    const apiVersion = options?.apiVersion ?? null;
-
-    // @ts-ignore - MSW is an optional peer dependency
-    const { http, HttpResponse } = require('msw');
-
-    return http.post(apiPath, async ({ request }: any) => {
-        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,
+    /**
+     * Mock an API endpoint with MSW
+     * @param apiName - The name of the API to mock
+     * @param handler - Function that returns the mock payload
+     * @param options - Additional response options (session expired, version expired, etc.)
+     */
+    mockApi<TApiName extends keyof TContract & string>(
+        apiName: TApiName,
+        handler: (payload?: TContract[TApiName]['input']) => Promise<TContract[TApiName]['output']> | TContract[TApiName]['output'],
+        options?: MockApiOptions
+    ): RequestHandler {
+        return this.http.post(this.apiPath, async ({ request }: any) => {
+            let body: any;
+            
+            try {
+                body = await request.json();
+            } catch (parseErr) {
+                // If JSON parsing fails, return undefined to let other handlers try
+                console.warn("LambderMSW: Failed to parse request body as JSON");
+                return;
+            }
+            
+            // Check if body is valid and has apiName
+            if (!body || typeof body.apiName !== 'string') {
+                // Invalid request format, let other handlers try
+                return;
+            }
+            
+            console.log("LambderMSW called for:", body.apiName, "matching against:", apiName);
+            
+            // Check if this is the API we're mocking
+            if (body.apiName !== apiName) {
+                // If this handler doesn't match, return undefined to let MSW try other handlers
+                return;
+            }
+            
+            try {
+                // Add artificial delay if specified
+                if (options?.delay) {
+                    await new Promise(resolve => setTimeout(resolve, options.delay));
+                }
+
+                // Call the handler with the payload from the request
+                const payload = await handler(body.payload as TContract[TApiName]['input']);
+                
+                console.log("Matched! Returning payload for:", apiName);
+
+                const response: MockApiResponse<TContract[TApiName]['output']> = {
+                    apiVersion: this.apiVersion,
+                    payload,
+                    ...(options?.versionExpired ? { versionExpired: options.versionExpired } : {}),
+                    ...(options?.sessionExpired ? { sessionExpired: options.sessionExpired } : {}),
+                    ...(options?.notAuthorized ? { notAuthorized: options.notAuthorized } : {}),
+                    ...(options?.message ? { message: options.message } : {}),
+                    ...(options?.errorMessage ? { errorMessage: options.errorMessage } : {}),
+                    ...(options?.logList?.length ? { logList: options.logList } : {}),
+                };
+
+                return this.HttpResponse.json(response);
+            } catch (err: any) {
+                // Only handle errors that occur during handler execution for matched APIs
+                console.error("Error in LambderMSW handler for", apiName, ":", err);
+                
+                const errorResponse: MockApiResponse<null> = {
+                    apiVersion: this.apiVersion,
+                    payload: null,
+                    errorMessage: err.message || "Unknown error",
+                };
+
+                return this.HttpResponse.json(errorResponse, { status: 500 });
+            }
         });
-    });
-}
-
-/**
- * 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;
     }
-) {
-    const apiPath = options?.apiPath ?? '/api';
-    const apiVersion = options?.apiVersion ?? null;
-
-    // @ts-ignore - MSW is an optional peer dependency
-    const { http, HttpResponse } = require('msw');
 
-    return http.post(apiPath, async ({ request }: any) => {
-        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',
-        });
-    });
-}
-
-/**
- * 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;
+    /**
+     * Mock an API endpoint that returns a session expired error
+     */
+    mockSessionExpired<TApiName extends keyof TContract & string>(
+        apiName: TApiName
+    ): RequestHandler {
+        return this.mockApi(
+            apiName,
+            async () => null as any,
+            { sessionExpired: true }
+        );
     }
-) {
-    const apiPath = options?.apiPath ?? '/api';
-    const apiVersion = options?.apiVersion ?? null;
-
-    // @ts-ignore - MSW is an optional peer dependency
-    const { http, HttpResponse } = require('msw');
-
-    return http.post(apiPath, async ({ request }: any) => {
-        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',
-        });
-    });
-}
-
-/**
- * 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;
+    /**
+     * Mock an API endpoint that returns a version expired error
+     */
+    mockVersionExpired<TApiName extends keyof TContract & string>(
+        apiName: TApiName
+    ): RequestHandler {
+        return this.mockApi(
+            apiName,
+            async () => null as any,
+            { versionExpired: true }
+        );
     }
-) {
-    const apiPath = options?.apiPath ?? '/api';
-    const apiVersion = options?.apiVersion ?? null;
 
-    // @ts-ignore - MSW is an optional peer dependency
-    const { http, HttpResponse } = require('msw');
-
-    return http.post(apiPath, async ({ request }: any) => {
-        const body = (await request.json()) as { 
-            apiName: string; 
-            payload?: any;
-        };
-
-        if (body.apiName !== apiName) {
-            return;
-        }
+    /**
+     * Mock an API endpoint that returns a not authorized error
+     */
+    mockNotAuthorized<TApiName extends keyof TContract & string>(
+        apiName: TApiName
+    ): RequestHandler {
+        return this.mockApi(
+            apiName,
+            async () => null as any,
+            { notAuthorized: true }
+        );
+    }
 
-        console.log(`[MSW Lambder] Mocking version expired for ${apiName}`);
+    /**
+     * Mock an API endpoint that returns an error message
+     */
+    mockError<TApiName extends keyof TContract & string>(
+        apiName: TApiName,
+        errorMessage: string
+    ): RequestHandler {
+        return this.mockApi(
+            apiName,
+            async () => null as any,
+            { errorMessage }
+        );
+    }
 
-        return HttpResponse.json({
-            ...(apiVersion !== null ? { apiVersion } : {}),
-            payload: null,
-            versionExpired: true,
-            errorMessage: 'Version expired',
-        });
-    });
+    /**
+     * Mock an API endpoint with a custom message
+     */
+    mockWithMessage<TApiName extends keyof TContract & string>(
+        apiName: TApiName,
+        handler: (payload?: TContract[TApiName]['input']) => Promise<TContract[TApiName]['output']> | TContract[TApiName]['output'],
+        message: any
+    ): RequestHandler {
+        return this.mockApi(apiName, handler, { message });
+    }
 }
 
-/**
- * Helper to combine multiple Lambder mock handlers
- * Since each handler checks for its specific apiName, you can just spread them into setupWorker/setupServer
- * 
- * @deprecated This helper is not needed - just spread handlers directly into setupWorker/setupServer
- * @example
- * ```typescript
- * import { setupServer } from 'msw/node';
- * 
- * const server = setupServer(
- *   mockLambderApi('user.getProfile', () => ({ name: 'Test User' })),
- *   mockLambderApi('user.updateProfile', (input) => ({ success: true }))
- * );
- * ```
- */
-export function createLambderApiHandler(
-    apiPath: string,
-    handlers: any[]
-) {
-    // This is deprecated - users should just spread handlers directly
-    // Kept for backward compatibility
-    return handlers;
-}

package/src/index.ts

@@ -5,6 +5,7 @@ export { default as LambderCaller } from "./LambderCaller.js";
 export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";
+export { default as LambderMSW } from "./LambderMSW.js";
 
 // Type-safe API contract utilities
 export { 
@@ -13,13 +14,3 @@ export {
     type ApiInput,
     type ApiOutput,
 } from "./LambderApiContract.js";
-
-// MSW mocking utilities (optional - requires msw to be installed)
-export {
-    mockLambderApi,
-    mockLambderApiError,
-    mockLambderSessionExpired,
-    mockLambderNotAuthorized,
-    mockLambderVersionExpired,
-    createLambderApiHandler,
-} from "./LambderMSW.js";

package/docs/MSW_IMPLEMENTATION_COMPLETE.md

@@ -1,191 +0,0 @@
-# MSW Integration - Complete Implementation Summary
-
-## What Was Done
-
-Added Mock Service Worker (MSW) integration to Lambder as an optional peer dependency, allowing developers to easily mock Lambder API endpoints for testing and development.
-
-## Files Created/Modified
-
-### 1. Core Implementation
-- **`src/LambderMSW.ts`** - New file with MSW mocking utilities
-  - `mockLambderApi()` - Mock successful API responses
-  - `mockLambderApiError()` - Mock error responses
-  - `mockLambderSessionExpired()` - Mock session expiry
-  - `mockLambderNotAuthorized()` - Mock authorization errors
-  - `mockLambderVersionExpired()` - Mock version expiry
-  - All functions use `require('msw')` to dynamically load MSW
-  - Each function calls `http.post()` and returns a proper MSW `RequestHandler`
-
-### 2. Package Configuration
-- **`package.json`** - Added MSW as optional peer dependency
-  ```json
-  "peerDependencies": {
-    "msw": "^2.0.0"
-  },
-  "peerDependenciesMeta": {
-    "msw": {
-      "optional": true
-    }
-  }
-  ```
-
-### 3. Exports
-- **`src/index.ts`** - Exported all MSW utilities from main entry point
-
-### 4. Documentation
-- **`docs/MSW_MOCKING.md`** - Comprehensive guide (591 lines)
-  - Installation instructions
-  - Quick start with examples
-  - API reference for all functions
-  - Testing examples (Vitest, Jest, React Testing Library)
-  - Storybook integration
-  - Advanced usage patterns
-  - Best practices and troubleshooting
-
-- **`docs/MSW_QUICK_FIX.md`** - Quick reference for the fix
-  - Explains the solution to type compatibility
-  - Shows correct usage patterns
-  - Provides working examples
-
-- **`docs/MSW_INTEGRATION_SUMMARY.md`** - High-level overview
-  - Lists all changes made
-  - Explains benefits
-  - Shows usage examples
-
-### 5. Examples
-- **`examples/msw-mocking-example.ts`** - Detailed example with comments
-  - API contract definition
-  - Various mock handlers
-  - Setup for Node.js tests
-  - Setup for browser development
-
-- **`examples/msw-correct-usage.ts`** - Shows the correct way to use handlers
-  - Demonstrates proper MSW integration
-  - TypeScript type verification
-
-### 6. Tests
-- **`tests/msw-integration.test.ts`** - Basic test to verify exports
-  - Tests run without MSW installed
-  - Includes commented examples for when MSW is installed
-
-### 7. README Update
-- **`Readme.md`** - Added MSW to features and created new section
-  - Added MSW to features list
-  - New "Testing & Mocking with MSW" section
-  - Links to detailed documentation
-
-## How It Works
-
-### The Fix for Type Compatibility
-
-**Problem**: Custom `HttpHandler` type didn't match MSW's `RequestHandler`
-
-**Solution**: Each Lambder MSW function now:
-
-1. Dynamically requires MSW: `const { http, HttpResponse } = require('msw')`
-2. Calls MSW's `http.post()` with the handler logic
-3. Returns the `RequestHandler` that `http.post()` creates
-4. Uses `@ts-ignore` for the require statement since MSW is optional
-
-This means the return type is automatically compatible with MSW's `setupWorker` and `setupServer`.
-
-### Example Flow
-
-```typescript
-// User code
-mockLambderApi('user.getProfile', () => ({ name: 'Test' }))
-
-// Internally:
-// 1. require('msw') → gets http and HttpResponse
-// 2. http.post('/api', async ({ request }) => { ... })
-// 3. Returns: RequestHandler from MSW
-
-// Result: Perfect type compatibility!
-```
-
-## Usage Example
-
-```typescript
-// 1. Define API contract
-const ApiContract = {
-  'user.getProfile': {
-    input: { userId: string },
-    output: { name: string, email: string }
-  }
-} satisfies ApiContractShape
-
-type MyApiContract = typeof ApiContract
-
-// 2. Create handlers
-import { mockLambderApi } from 'lambder'
-
-const handlers = [
-  mockLambderApi<MyApiContract, 'user.getProfile'>(
-    'user.getProfile',
-    () => ({
-      name: 'Test User',
-      email: 'test@example.com'
-    })
-  )
-]
-
-// 3. Setup MSW
-import { setupWorker } from 'msw/browser'
-export const worker = setupWorker(...handlers) // ✅ Works!
-```
-
-## Key Features
-
-✅ **Type-Safe**: Full TypeScript support with API contracts
-✅ **Optional**: No hard dependency - only needed for testing  
-✅ **Easy**: Simple functions matching Lambder's API pattern
-✅ **Comprehensive**: Covers all error scenarios  
-✅ **Compatible**: Returns proper MSW `RequestHandler` types
-
-## Benefits
-
-1. **No Breaking Changes**: Existing code continues to work
-2. **Opt-In**: Only developers who want mocking need to install MSW
-3. **Type Safety**: Full IntelliSense and type checking
-4. **Developer Experience**: Works with popular testing frameworks
-5. **Production Ready**: Well-documented with examples
-
-## Testing
-
-- All tests pass without MSW installed
-- Build compiles successfully
-- No TypeScript errors
-- Example files demonstrate correct usage
-
-## Installation for Users
-
-```bash
-# Install lambder (already done)
-npm install lambder
-
-# Install MSW (only if you want mocking)
-npm install --save-dev msw
-```
-
-## Next Steps for Users
-
-1. Read [MSW_MOCKING.md](./MSW_MOCKING.md) for detailed guide
-2. Check [msw-correct-usage.ts](../examples/msw-correct-usage.ts) for example
-3. Install MSW: `npm install --save-dev msw`
-4. Create handlers using `mockLambderApi`
-5. Set up MSW worker/server
-6. Start mocking!
-
-## Technical Details
-
-- Uses CommonJS `require()` for dynamic import
-- `@ts-ignore` suppresses optional dependency errors
-- Each handler checks `body.apiName` for routing
-- Supports all Lambder API response formats
-- Compatible with MSW v2.0.0+
-
----
-
-**Status**: ✅ Complete and tested
-**Compatibility**: MSW v2.0.0+, TypeScript 5.9+
-**Breaking Changes**: None