lambder 1.0.129 → 1.0.130

package/Readme.md

@@ -5,9 +5,11 @@ Lambder is a highly opinionated dynamic serverless framework designed to facilit
 ## Features
 
 - **Simple API & Route Declaration**: Define your APIs and routes using concise and expressive syntax.
+- **Type-Safe API Contracts**: Full TypeScript type safety across frontend and backend with zero runtime overhead.
 - **Session Management**: Built-in session management to secure and personalize user experiences.
 - **Flexible Hooks System**: Employ hooks to execute code at different stages of the request lifecycle, enabling fine-grained control over the application flow.
 - **Error Handling**: Comprehensive error handling capabilities, including global error handlers and route-specific fallbacks.
+- **MSW Mocking Support**: Optional Mock Service Worker integration for easy API mocking in tests and development.
 - **Seamless Integration**: Designed to work effortlessly with AWS Lambda and API Gateway, providing a straightforward path to deploy serverless applications.
 
 ## Installation
@@ -544,6 +546,53 @@ const user = await caller.api('getUserById', { userId: '123' });
 
 📖 **[Read the Quick Start Guide](docs/TYPE_SAFE_QUICK_START.md)** for more details and examples!
 
+## Testing & Mocking with MSW
+
+Lambder provides optional integration with [Mock Service Worker (MSW)](https://mswjs.io/) for easy API mocking in tests and development.
+
+### Installation
+
+```bash
+npm install --save-dev msw
+```
+
+### Quick Example
+
+```typescript
+import { mockLambderApi } from 'lambder';
+import { setupServer } from 'msw/node';
+import type { MyApiContract } from './apiContract';
+
+// Create type-safe mock handlers
+const handlers = [
+  mockLambderApi<MyApiContract, 'getUserById'>(
+    'getUserById',
+    (input) => ({
+      id: input.userId,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  )
+];
+
+// Set up MSW server
+const server = setupServer(...handlers);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+### Benefits
+
+✅ **Type-Safe Mocking** - Full TypeScript support for mock responses  
+✅ **Easy Setup** - Simple functions that match your API contract  
+✅ **Test Scenarios** - Mock errors, session expired, not authorized, etc.  
+✅ **Development Mode** - Use mocks while developing frontend features  
+✅ **Storybook Ready** - Perfect for component stories  
+
+📖 **[Read the MSW Mocking Guide](docs/MSW_MOCKING.md)** for detailed setup and examples!
+
 ## Contributing
 
 Contributions are welcome! Especially for documentation. If you have an idea for an improvement or have found a bug, please open an issue or submit a pull request.

package/dist/LambderMSW.d.ts

@@ -0,0 +1,104 @@
+import type { ApiContractShape } from './LambderApiContract.js';
+export type HttpHandler = (info: any) => Promise<Response | undefined> | Response | undefined;
+/**
+ * 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 declare 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;
+/**
+ * Creates a mock handler that returns an error for a Lambder API endpoint
+ *
+ * @example
+ * ```typescript
+ * mockLambderApiError('user.deleteAccount', 'Account deletion failed')
+ * ```
+ */
+export declare 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;
+/**
+ * Creates a mock handler that simulates a session expired error
+ *
+ * @example
+ * ```typescript
+ * mockLambderSessionExpired('user.updateProfile')
+ * ```
+ */
+export declare 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;
+/**
+ * Creates a mock handler that simulates a "not authorized" error
+ *
+ * @example
+ * ```typescript
+ * mockLambderNotAuthorized('admin.deleteUser')
+ * ```
+ */
+export declare 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;
+/**
+ * Creates a mock handler that simulates a version expired error
+ *
+ * @example
+ * ```typescript
+ * mockLambderVersionExpired('user.updateProfile')
+ * ```
+ */
+export declare 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;
+/**
+ * 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 declare function createLambderApiHandler(apiPath: string, handlers: HttpHandler[]): HttpHandler;

package/dist/LambderMSW.js

@@ -0,0 +1,203 @@
+// Dynamic imports to avoid requiring MSW as a hard dependency
+let http;
+let HttpResponse;
+/**
+ * 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(apiName, responseFactory, options) {
+    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 }) => {
+        await ensureMSW();
+        const body = (await request.json());
+        // 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);
+        // 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(apiName, errorMessage, options) {
+    const apiPath = options?.apiPath ?? '/api';
+    const delay = options?.delay ?? 0;
+    const apiVersion = options?.apiVersion ?? null;
+    return (async ({ request }) => {
+        await ensureMSW();
+        const body = (await request.json());
+        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,
+        });
+    });
+}
+/**
+ * Creates a mock handler that simulates a session expired error
+ *
+ * @example
+ * ```typescript
+ * mockLambderSessionExpired('user.updateProfile')
+ * ```
+ */
+export function mockLambderSessionExpired(apiName, options) {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+    return (async ({ request }) => {
+        await ensureMSW();
+        const body = (await request.json());
+        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(apiName, options) {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+    return (async ({ request }) => {
+        await ensureMSW();
+        const body = (await request.json());
+        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(apiName, options) {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+    return (async ({ request }) => {
+        await ensureMSW();
+        const body = (await request.json());
+        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',
+        });
+    });
+}
+/**
+ * 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, handlers) {
+    return (async (info) => {
+        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;
+    });
+}

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";
 export { type ApiContractShape, type ApiContract, type ApiInput, type ApiOutput, } from "./LambderApiContract.js";
+export { mockLambderApi, mockLambderApiError, mockLambderSessionExpired, mockLambderNotAuthorized, mockLambderVersionExpired, createLambderApiHandler, type HttpHandler, } from "./LambderMSW.js";

package/dist/index.js

@@ -4,3 +4,5 @@ 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";
+// MSW mocking utilities (optional - requires msw to be installed)
+export { mockLambderApi, mockLambderApiError, mockLambderSessionExpired, mockLambderNotAuthorized, mockLambderVersionExpired, createLambderApiHandler, } from "./LambderMSW.js";