lambder 1.0.128 → 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/examples/output-type-enforcement-example.ts

@@ -0,0 +1,218 @@
+/**
+ * Output Type Enforcement Example
+ * 
+ * This example demonstrates how Lambder now enforces output types
+ * in addition to input types for type-safe APIs.
+ */
+
+import Lambder from '../src/Lambder.js';
+import type { ApiContract } from '../src/index.js';
+
+// ============================================================================
+// Define Types
+// ============================================================================
+
+type User = {
+    id: string;
+    name: string;
+    email: string;
+    age: number;
+};
+
+type Product = {
+    id: string;
+    name: string;
+    price: number;
+    inStock: boolean;
+};
+
+type Stats = {
+    totalUsers: number;
+    totalProducts: number;
+    revenue: number;
+};
+
+// ============================================================================
+// Define API Contract
+// ============================================================================
+
+type MyApiContract = ApiContract<{
+    // Simple primitive outputs
+    getCount: { input: void, output: number },
+    getMessage: { input: { id: string }, output: string },
+    isActive: { input: void, output: boolean },
+    
+    // Complex object outputs
+    getUser: { input: { userId: string }, output: User },
+    getProduct: { input: { productId: string }, output: Product },
+    
+    // Array outputs
+    listUsers: { input: void, output: User[] },
+    listProducts: { input: { category: string }, output: Product[] },
+    
+    // Complex nested outputs
+    getStats: { input: void, output: Stats },
+    
+    // Nullable outputs
+    findUser: { input: { email: string }, output: User | null },
+}>;
+
+// ============================================================================
+// Setup Backend with Type Enforcement
+// ============================================================================
+
+const lambder = new Lambder<MyApiContract>({
+    publicPath: './public',
+    apiPath: '/api',
+});
+
+// ✅ EXAMPLE 1: Simple primitive outputs are enforced
+lambder.addApi('getCount', async (ctx, resolver) => {
+    const count = 42;
+    return resolver.api(count); // ✅ TypeScript validates this is a number
+});
+
+lambder.addApi('getMessage', async (ctx, resolver) => {
+    const message = `Message for ${ctx.apiPayload.id}`;
+    return resolver.api(message); // ✅ TypeScript validates this is a string
+});
+
+lambder.addApi('isActive', async (ctx, resolver) => {
+    const active = true;
+    return resolver.api(active); // ✅ TypeScript validates this is a boolean
+});
+
+// ✅ EXAMPLE 2: Complex objects must match the shape
+lambder.addApi('getUser', async (ctx, resolver) => {
+    const user: User = {
+        id: ctx.apiPayload.userId,
+        name: "John Doe",
+        email: "john@example.com",
+        age: 30,
+    };
+    return resolver.api(user); // ✅ All required fields are present
+});
+
+lambder.addApi('getProduct', async (ctx, resolver) => {
+    const product: Product = {
+        id: ctx.apiPayload.productId,
+        name: "Widget",
+        price: 99.99,
+        inStock: true,
+    };
+    return resolver.api(product); // ✅ Correct shape
+});
+
+// ✅ EXAMPLE 3: Arrays are type-checked
+lambder.addApi('listUsers', async (ctx, resolver) => {
+    const users: User[] = [
+        { id: "1", name: "Alice", email: "alice@example.com", age: 25 },
+        { id: "2", name: "Bob", email: "bob@example.com", age: 30 },
+    ];
+    return resolver.api(users); // ✅ Array of User objects
+});
+
+lambder.addApi('listProducts', async (ctx, resolver) => {
+    const category = ctx.apiPayload.category;
+    const products: Product[] = [
+        { id: "1", name: "Item 1", price: 10, inStock: true },
+        { id: "2", name: "Item 2", price: 20, inStock: false },
+    ];
+    return resolver.api(products); // ✅ Array of Product objects
+});
+
+// ✅ EXAMPLE 4: Nested objects are validated
+lambder.addApi('getStats', async (ctx, resolver) => {
+    const stats: Stats = {
+        totalUsers: 100,
+        totalProducts: 50,
+        revenue: 10000,
+    };
+    return resolver.api(stats); // ✅ Matches Stats shape
+});
+
+// ✅ EXAMPLE 5: Nullable types work correctly
+lambder.addApi('findUser', async (ctx, resolver) => {
+    const email = ctx.apiPayload.email;
+    
+    if (email === "john@example.com") {
+        // Found user
+        const user: User = {
+            id: "123",
+            name: "John",
+            email: email,
+            age: 30,
+        };
+        return resolver.api(user); // ✅ Can return User
+    } else {
+        // Not found
+        return resolver.api(null); // ✅ Can return null
+    }
+});
+
+// ✅ EXAMPLE 6: Using die.api() also enforces types
+lambder.addApi('getCount', async (ctx, resolver) => {
+    return resolver.die.api(42); // ✅ die.api() also type-checks
+});
+
+// ✅ EXAMPLE 7: Session APIs also enforce output types
+lambder.addSessionApi('getUser', async (ctx, resolver) => {
+    const user: User = {
+        id: ctx.apiPayload.userId,
+        name: "Jane Doe",
+        email: "jane@example.com",
+        age: 28,
+    };
+    return resolver.api(user); // ✅ Type-safe for session APIs too
+});
+
+// ============================================================================
+// What TypeScript Prevents (these would cause compile errors)
+// ============================================================================
+
+/*
+// ❌ ERROR: Wrong primitive type
+lambder.addApi('getCount', async (ctx, resolver) => {
+    return resolver.api("not a number"); // Error: string not assignable to number
+});
+
+// ❌ ERROR: Missing required field
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api({
+        id: "123",
+        name: "John",
+        email: "john@example.com",
+        // age is missing! - TypeScript error
+    });
+});
+
+// ❌ ERROR: Wrong field type
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api({
+        id: "123",
+        name: "John",
+        email: "john@example.com",
+        age: "30", // Error: string not assignable to number
+    });
+});
+
+// ❌ ERROR: Wrong array element type
+lambder.addApi('listUsers', async (ctx, resolver) => {
+    return resolver.api([
+        { id: "1", name: "Alice", email: "alice@example.com", age: 25 },
+        "not a user object", // Error: string not assignable to User
+    ]);
+});
+
+// ❌ ERROR: Returning wrong type when null is not allowed
+lambder.addApi('getUser', async (ctx, resolver) => {
+    return resolver.api(null); // Error: null not assignable to User (findUser allows null, but getUser doesn't)
+});
+*/
+
+console.log("✅ All examples demonstrate proper output type enforcement!");
+console.log("✅ TypeScript will catch type mismatches at compile time!");
+console.log("✅ This works with both resolver.api() and resolver.die.api()!");
+console.log("✅ Both addApi() and addSessionApi() enforce output types!");
+
+export default lambder;

package/examples/secure-session-example.ts

@@ -0,0 +1,191 @@
+import Lambder from "../src/Lambder.js";
+
+// Example: Secure session handling with all security fixes applied
+
+const lambder = new Lambder({
+    publicPath: "/public",
+    apiPath: "/api",
+    ejsPath: "/views",
+});
+
+// Enable session management with sliding expiration
+lambder.enableDdbSession(
+    {
+        tableName: process.env.SESSION_TABLE || "sessions",
+        tableRegion: process.env.AWS_REGION || "us-east-1",
+        sessionSalt: process.env.SESSION_SALT || "change-this-to-a-secure-random-string",
+        enableSlidingExpiration: true, // Sessions extend on each access
+    },
+    { partitionKey: "pk", sortKey: "sk" }
+);
+
+// Example: Login API with session regeneration
+lambder.addApi("user.login", async (ctx, resolver) => {
+    const { username, password } = ctx.apiPayload;
+
+    // Validate credentials (implement your own logic)
+    const user = await authenticateUser(username, password);
+    if (!user) {
+        return resolver.api({ success: false, error: "Invalid credentials" });
+    }
+
+    // Create new session
+    const sessionController = lambder.getSessionController(ctx);
+    await sessionController.createSession(user.id, {
+        userId: user.id,
+        username: user.username,
+        role: user.role,
+    });
+
+    return resolver.api({
+        success: true,
+        csrfToken: ctx.session?.csrfToken,
+    });
+});
+
+// Example: Protected API that requires session
+lambder.addSessionApi("user.profile", async (ctx, resolver) => {
+    // Session is automatically fetched and validated
+    const sessionData = ctx.session?.data;
+
+    return resolver.api({
+        userId: sessionData.userId,
+        username: sessionData.username,
+        role: sessionData.role,
+    });
+});
+
+// Example: Sensitive operation that regenerates session
+lambder.addSessionApi("user.changePassword", async (ctx, resolver) => {
+    const { oldPassword, newPassword } = ctx.apiPayload;
+    const sessionController = lambder.getSessionController(ctx);
+
+    // Validate old password
+    const isValid = await validatePassword(
+        ctx.session?.data.userId,
+        oldPassword
+    );
+    if (!isValid) {
+        return resolver.api({ success: false, error: "Invalid password" });
+    }
+
+    // Update password
+    await updatePassword(ctx.session?.data.userId, newPassword);
+
+    // IMPORTANT: Regenerate session after password change to prevent session fixation
+    await sessionController.regenerateSession();
+
+    // OPTIONAL: End all other sessions for this user
+    await sessionController.endSessionAll();
+
+    return resolver.api({
+        success: true,
+        message: "Password changed successfully",
+        csrfToken: ctx.session?.csrfToken, // Send new CSRF token
+    });
+});
+
+// Example: Update session data
+lambder.addSessionApi("user.updatePreferences", async (ctx, resolver) => {
+    const { theme, language } = ctx.apiPayload;
+    const sessionController = lambder.getSessionController(ctx);
+
+    // Update session data (also extends expiration if sliding is enabled)
+    await sessionController.updateSessionData({
+        ...ctx.session?.data,
+        preferences: { theme, language },
+    });
+
+    return resolver.api({
+        success: true,
+        message: "Preferences updated",
+    });
+});
+
+// Example: Logout
+lambder.addSessionApi("user.logout", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+
+    // End current session
+    await sessionController.endSession();
+
+    return resolver.api({
+        success: true,
+        message: "Logged out successfully",
+    });
+});
+
+// Example: Logout from all devices
+lambder.addSessionApi("user.logoutAll", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+
+    // End all sessions for this user (same sessionKey)
+    await sessionController.endSessionAll();
+
+    return resolver.api({
+        success: true,
+        message: "Logged out from all devices",
+    });
+});
+
+// Example: Optional session (check if logged in)
+lambder.addApi("user.checkAuth", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+
+    // Try to fetch session without throwing error
+    const session = await sessionController.fetchSessionIfExists();
+
+    if (session) {
+        return resolver.api({
+            authenticated: true,
+            userId: session.data.userId,
+            username: session.data.username,
+        });
+    }
+
+    return resolver.api({
+        authenticated: false,
+    });
+});
+
+// Example: Route with session
+lambder.addSessionRoute("/dashboard", async (ctx, resolver) => {
+    // Session is automatically fetched and validated
+    const userData = ctx.session?.data;
+
+    return resolver.ejsFile("dashboard.ejs", {
+        user: userData,
+        csrfToken: ctx.session?.csrfToken,
+    });
+});
+
+// Example: Route with optional session
+lambder.addRoute("/", async (ctx, resolver) => {
+    const sessionController = lambder.getSessionController(ctx);
+    const session = await sessionController.fetchSessionIfExists();
+
+    return resolver.ejsFile("home.ejs", {
+        isLoggedIn: !!session,
+        user: session?.data,
+        csrfToken: session?.csrfToken,
+    });
+});
+
+// Dummy functions (implement these)
+async function authenticateUser(username: string, password: string) {
+    // Implement your authentication logic
+    return { id: "user123", username, role: "user" };
+}
+
+async function validatePassword(userId: string, password: string) {
+    // Implement password validation
+    return true;
+}
+
+async function updatePassword(userId: string, newPassword: string) {
+    // Implement password update
+}
+
+export const handler = async (event: any, context: any) => {
+    return await lambder.render(event, context);
+};