lambder 1.0.147 → 2.0.2

package/docs/TYPE_SAFE_QUICK_START.md

@@ -1,200 +1,77 @@
-# Type-Safe API Quick Start
+# Type-Safe API Quick Start (v2.0)
 
 ## In 3 Simple Steps
 
-### 1. Define Your Contract Type
+### 1. Define & Implement APIs (Backend)
 
-```typescript
-// shared/apiContract.ts
-import type { ApiContract } from 'lambder';
-
-export type MyApiContract = ApiContract<{
-    getUserById: { input: { userId: string }, output: User },
-    createUser: { input: CreateUserInput, output: User },
-    listUsers: { input: void, output: User[] }
-}>;
-```
-
-### 2. Backend - Pass Type to Lambder
+Use Zod schemas to define your API contract inline. Lambder will automatically validate inputs at runtime and infer types for compile-time safety.
 
 ```typescript
-import Lambder from 'lambder';
-import type { MyApiContract } from './shared/apiContract';
-
-const lambder = new Lambder<MyApiContract>({
-    publicPath: './public',
-    apiPath: '/api'
+import { z } from "zod";
+import Lambder from "lambder";
+
+// Initialize
+const lambder = new Lambder({
+    publicPath: "./public",
+    apiPath: "/api"
+})
+// Chain APIs
+.addApi("getUser", {
+    input: z.object({ userId: z.string() }),
+    output: z.object({ id: z.string(), name: z.string() })
+}, async (ctx, resolver) => {
+    // ctx.apiPayload is typed as { userId: string }
+    // Runtime validation is already performed!
+    return resolver.api({ 
+        id: ctx.apiPayload.userId, 
+        name: "John Doe" 
+    });
 });
 
-// Now addApi is type-safe for both inputs AND outputs!
-lambder.addApi('getUserById', async (ctx, resolver) => {
-    // ✅ ctx.apiPayload is automatically typed as { userId: string }
-    const user = await db.getUser(ctx.apiPayload.userId);
-    
-    // ✅ resolver.api() enforces the output type (User)
-    return resolver.api(user); // TypeScript checks that user matches User type!
-});
-```
-
-### 3. Frontend - Pass Type to LambderCaller
-
-```typescript
-import { LambderCaller } from 'lambder';
-import type { MyApiContract } from './shared/apiContract';
-
-const caller = new LambderCaller<MyApiContract>({
-    apiPath: '/api',
-    isCorsEnabled: false
-});
-
-// Now api() is type-safe!
-const user = await caller.api('getUserById', { userId: '123' });
-// user is typed as User | null | undefined
-```
-
-## That's It!
-
-- ✅ **No wrapper functions needed**
-- ✅ **Use existing `api()` and `addApi()` methods**
-- ✅ **Full autocomplete in IDE**
-- ✅ **Type-safe inputs AND outputs**
-- ✅ **Compile-time validation**
-- ✅ **Backward compatible**
+// Export the inferred contract type
+export type AppContract = typeof lambder.ApiContractType;
 
-## Contract Type Format
-
-```typescript
-type MyApiContract = {
-    apiName: { input: InputType, output: OutputType }
-}
+export const handler = lambder.getHandler();
 ```
 
-## Examples
+### 2. Use in Frontend
 
-### API with parameters
-```typescript
-getUserById: { input: { userId: string }, output: User }
-```
+Import the type (not the code) and use `LambderCaller`.
 
-### API with no input
 ```typescript
-listAll: { input: void, output: Item[] }
-```
-
-### API with complex types
-```typescript
-updateUser: { 
-    input: { id: string } & Partial<User>, 
-    output: User 
-}
-```
-
-### API with conditional output
-```typescript
-login: { 
-    input: { email: string, password: string },
-    output: { success: boolean, user?: User, error?: string }
-}
-```
+import { LambderCaller } from "lambder";
+import type { AppContract } from "./backend"; // Type-only import
 
-## Output Type Enforcement
-
-The type system now enforces that `resolver.api()` returns data matching your contract's output type:
-
-```typescript
-type MyContract = ApiContract<{
-    getNumber: { input: void, output: number },
-    getUser: { input: { id: string }, output: User }
-}>;
-
-const lambder = new Lambder<MyContract>({ ... });
-
-// ✅ CORRECT
-lambder.addApi('getNumber', async (ctx, resolver) => {
-    return resolver.api(42); // number - matches output type
-});
-
-// ❌ ERROR: Type 'string' is not assignable to type 'number'
-lambder.addApi('getNumber', async (ctx, resolver) => {
-    return resolver.api("wrong"); // TypeScript error!
+const lambderCaller = new LambderCaller<AppContract>({
+    apiPath: "/api"
 });
 
-// ✅ CORRECT
-lambder.addApi('getUser', async (ctx, resolver) => {
-    return resolver.api({ id: "123", name: "John", ... }); // User object
-});
-
-// ❌ ERROR: Missing required properties
-lambder.addApi('getUser', async (ctx, resolver) => {
-    return resolver.api({ id: "123" }); // TypeScript error - incomplete User!
-});
+// Fully typed!
+// TypeScript knows 'getUser' takes { userId: string } and returns { id: string, name: string }
+const user = await lambderCaller.api("getUser", { userId: "123" });
 ```
 
-This works with:
-- `resolver.api()` - typed return value
-- `resolver.die.api()` - typed return value
-- `addApi()` - typed for regular APIs
-- `addSessionApi()` - typed for session APIs
+### 3. Modular APIs (Optional)
 
-## Without Type Safety (Still Works!)
-
-Don't want type safety? Just don't pass the generic type:
+For larger apps, split your APIs into modules using `.use()`.
 
 ```typescript
-// Frontend
-const caller = new LambderCaller({ ... }); // No generic
-await caller.api('anyApi', { anything: true }); // Works, but untyped
-
-// Backend
-const lambder = new Lambder({ ... }); // No generic
-lambder.addApi('anyApi', async (ctx, resolver) => {
-    // ctx.apiPayload is any
-});
+// api.user.ts
+import { z } from "zod";
+import Lambder from "lambder";
+
+export const userApi = <T>(l: Lambder<T>) => {
+    return l.addApi("login", {
+        input: z.object({ email: z.string() }),
+        output: z.boolean()
+    }, async (ctx, resolver) => {
+        return resolver.api(true);
+    });
+};
+
+// index.ts
+import { userApi } from "./api.user";
+
+const lambder = new Lambder()
+    .use(userApi); // Types are preserved!
 ```
-
-## Full Example
-
-See [simplified-typed-api-example.ts](../examples/simplified-typed-api-example.ts) for a complete working example.
-
-## Testing Your Type-Safe APIs
-
-LambderMSW provides full type safety for testing your APIs with MSW (Mock Service Worker):
-
-```typescript
-import { LambderMSW } from 'lambder';
-import { setupServer } from 'msw/node';
-import type { MyApiContract } from './shared/apiContract';
-
-// Create type-safe MSW instance
-const lambderMSW = new LambderMSW<MyApiContract>({
-    apiPath: '/api'
-});
-
-// Mock with full type safety! ✨
-const handlers = [
-    lambderMSW.mockApi('getUserById', async (payload) => {
-        // payload is typed as { userId: string }
-        // Return value is type-checked against output
-        return {
-            id: payload.userId,
-            name: 'John Doe',
-            email: 'john@example.com'
-        };
-    })
-];
-
-const server = setupServer(...handlers);
-```
-
-📖 See [LAMBDER_MSW.md](./LAMBDER_MSW.md) for complete testing documentation.
-
-## Key Points
-
-- **Contract is just a TypeScript type** - No runtime code!
-- **Zero overhead** - All type checking happens at compile time
-- **Input AND output validation** - Both sides of your API are type-safe
-- **Compile-time safety** - Catch type mismatches before deployment
-- **Opt-in** - Use types when you want them
-- **Simple** - Just pass type to constructor
-- **Autocomplete** - IDE shows available APIs as you type
-- **Testing support** - LambderMSW provides type-safe mocking

package/examples/msw-testing-example.ts

@@ -17,27 +17,30 @@
 // @ts-nocheck - Example file, types may not be available
 import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
 import { setupServer } from 'msw/node';
-import { LambderMSW, LambderCaller, type ApiContract } from '../src/index.ts';
-
-// Define your API contract
-type TestApiContract = ApiContract<{
-    getUserById: {
-        input: { userId: string };
-        output: { id: string; name: string; email: string } | null;
-    };
-    createUser: {
-        input: { name: string; email: string };
-        output: { id: string; name: string; email: string };
-    };
-    getUsers: {
-        input: { limit?: number };
-        output: Array<{ id: string; name: string; email: string }>;
-    };
-    deleteUser: {
-        input: { userId: string };
-        output: { success: boolean };
-    };
-}>;
+import { z } from 'zod';
+import { LambderMSW, LambderCaller } from '../src/index.ts';
+import Lambder from '../src/Lambder.js';
+
+// Define your API contract using Lambder chaining
+const lambder = new Lambder()
+    .addApi('getUserById', {
+        input: z.object({ userId: z.string() }),
+        output: z.object({ id: z.string(), name: z.string(), email: z.string() }).nullable()
+    }, async () => ({} as any)) // Dummy handler for type inference
+    .addApi('createUser', {
+        input: z.object({ name: z.string(), email: z.string() }),
+        output: z.object({ id: z.string(), name: z.string(), email: z.string() })
+    }, async () => ({} as any))
+    .addApi('getUsers', {
+        input: z.object({ limit: z.number().optional() }),
+        output: z.array(z.object({ id: z.string(), name: z.string(), email: z.string() }))
+    }, async () => ({} as any))
+    .addApi('deleteUser', {
+        input: z.object({ userId: z.string() }),
+        output: z.object({ success: z.boolean() })
+    }, async () => ({} as any));
+
+type TestApiContract = typeof lambder.ApiContractType;
 
 // Setup LambderMSW with type safety
 const lambderMSW = new LambderMSW<TestApiContract>({
@@ -89,7 +92,7 @@ const handlers = [
 const server = setupServer(...handlers);
 
 // Setup LambderCaller
-const caller = new LambderCaller<TestApiContract>({
+const lambderCaller = new LambderCaller<TestApiContract>({
     apiPath: '/secure',
     isCorsEnabled: false,
 });
@@ -109,7 +112,7 @@ describe('LambderMSW Testing Example', () => {
     });
 
     it('should fetch user by id', async () => {
-        const user = await caller.api('getUserById', { userId: '1' });
+        const user = await lambderCaller.api('getUserById', { userId: '1' });
         
         expect(user).toEqual({
             id: '1',
@@ -119,7 +122,7 @@ describe('LambderMSW Testing Example', () => {
     });
 
     it('should return null for non-existent user', async () => {
-        const user = await caller.api('getUserById', { userId: '999' });
+        const user = await lambderCaller.api('getUserById', { userId: '999' });
         
         expect(user).toBeNull();
     });
@@ -127,7 +130,7 @@ describe('LambderMSW Testing Example', () => {
     it('should create a new user with delay', async () => {
         const startTime = Date.now();
         
-        const newUser = await caller.api('createUser', {
+        const newUser = await lambderCaller.api('createUser', {
             name: 'Alice Wonder',
             email: 'alice@example.com',
         });
@@ -143,7 +146,7 @@ describe('LambderMSW Testing Example', () => {
     });
 
     it('should fetch list of users', async () => {
-        const users = await caller.api('getUsers', { limit: 2 });
+        const users = await lambderCaller.api('getUsers', { limit: 2 });
         
         expect(users).toHaveLength(2);
         expect(users?.[0]?.name).toBe('John Doe');
@@ -154,7 +157,7 @@ describe('LambderMSW Testing Example', () => {
         let errorCaught = false;
         
         try {
-            await caller.api('deleteUser', { userId: '1' });
+            await lambderCaller.api('deleteUser', { userId: '1' });
         } catch (error: any) {
             errorCaught = true;
             expect(error.notAuthorized).toBe(true);
@@ -175,7 +178,7 @@ describe('LambderMSW Testing Example', () => {
             })
         );
 
-        const user = await caller.api('getUserById', { userId: '999' });
+        const user = await lambderCaller.api('getUserById', { userId: '999' });
         
         expect(user?.name).toBe('Override User');
     });
@@ -189,7 +192,7 @@ describe('LambderMSW Testing Example', () => {
         let errorCaught = false;
         
         try {
-            await caller.api('getUserById', { userId: '1' });
+            await lambderCaller.api('getUserById', { userId: '1' });
         } catch (error: any) {
             errorCaught = true;
             expect(error.sessionExpired).toBe(true);
@@ -206,7 +209,7 @@ describe('LambderMSW Testing Example', () => {
         let errorCaught = false;
         
         try {
-            await caller.api('createUser', {
+            await lambderCaller.api('createUser', {
                 name: 'Duplicate',
                 email: 'john@example.com',
             });
@@ -239,10 +242,10 @@ describe('Dynamic Response Testing', () => {
             })
         );
 
-        const users3 = await caller.api('getUsers', { limit: 3 });
+        const users3 = await lambderCaller.api('getUsers', { limit: 3 });
         expect(users3).toHaveLength(3);
 
-        const users5 = await caller.api('getUsers', { limit: 5 });
+        const users5 = await lambderCaller.api('getUsers', { limit: 5 });
         expect(users5).toHaveLength(5);
     });
 });
@@ -263,7 +266,7 @@ describe('Error Handling', () => {
         let errorCaught = false;
         
         try {
-            await caller.api('getUserById', { userId: '1' });
+            await lambderCaller.api('getUserById', { userId: '1' });
         } catch (error: any) {
             errorCaught = true;
             expect(error.errorMessage).toBe('Database connection failed');

package/examples/secure-session-example.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import Lambder from "../src/Lambder.js";
 
 // Example: Secure session handling with all security fixes applied
@@ -6,10 +7,9 @@ const lambder = new Lambder({
     publicPath: "/public",
     apiPath: "/api",
     ejsPath: "/views",
-});
-
+})
 // Enable session management with sliding expiration
-lambder.enableDdbSession(
+.enableDdbSession(
     {
         tableName: process.env.SESSION_TABLE || "sessions",
         tableRegion: process.env.AWS_REGION || "us-east-1",
@@ -17,10 +17,12 @@ lambder.enableDdbSession(
         enableSlidingExpiration: true, // Sessions extend on each access
     },
     { partitionKey: "pk", sortKey: "sk" }
-);
-
+)
 // Example: Login API with session regeneration
-lambder.addApi("user.login", async (ctx, resolver) => {
+.addApi("user.login", {
+    input: z.object({ username: z.string(), password: z.string() }),
+    output: z.object({ success: z.boolean(), csrfToken: z.string().optional(), error: z.string().optional() })
+}, async (ctx, resolver) => {
     const { username, password } = ctx.apiPayload;
 
     // Validate credentials (implement your own logic)
@@ -41,10 +43,12 @@ lambder.addApi("user.login", async (ctx, resolver) => {
         success: true,
         csrfToken: session.csrfToken,
     });
-});
-
+})
 // Example: Protected API that requires session
-lambder.addSessionApi("user.profile", async (ctx, resolver) => {
+.addSessionApi("user.profile", {
+    input: z.void(),
+    output: z.object({ userId: z.string(), username: z.string(), role: z.string() })
+}, async (ctx, resolver) => {
     // Session is automatically fetched and validated
     const sessionData = ctx.session.data;
 
@@ -53,10 +57,12 @@ lambder.addSessionApi("user.profile", async (ctx, resolver) => {
         username: sessionData.username,
         role: sessionData.role,
     });
-});
-
+})
 // Example: Sensitive operation that regenerates session
-lambder.addSessionApi("user.changePassword", async (ctx, resolver) => {
+.addSessionApi("user.changePassword", {
+    input: z.object({ oldPassword: z.string(), newPassword: z.string() }),
+    output: z.object({ success: z.boolean(), message: z.string().optional(), csrfToken: z.string().optional(), error: z.string().optional() })
+}, async (ctx, resolver) => {
     const { oldPassword, newPassword } = ctx.apiPayload;
     const sessionController = lambder.getSessionController(ctx);
 
@@ -83,10 +89,12 @@ lambder.addSessionApi("user.changePassword", async (ctx, resolver) => {
         message: "Password changed successfully",
         csrfToken: newSession.csrfToken, // Send new CSRF token
     });
-});
-
+})
 // Example: Update session data
-lambder.addSessionApi("user.updatePreferences", async (ctx, resolver) => {
+.addSessionApi("user.updatePreferences", {
+    input: z.object({ theme: z.string(), language: z.string() }),
+    output: z.object({ success: z.boolean(), message: z.string() })
+}, async (ctx, resolver) => {
     const { theme, language } = ctx.apiPayload;
     const sessionController = lambder.getSessionController(ctx);
 
@@ -100,10 +108,12 @@ lambder.addSessionApi("user.updatePreferences", async (ctx, resolver) => {
         success: true,
         message: "Preferences updated",
     });
-});
-
+})
 // Example: Logout
-lambder.addSessionApi("user.logout", async (ctx, resolver) => {
+.addSessionApi("user.logout", {
+    input: z.void(),
+    output: z.object({ success: z.boolean(), message: z.string() })
+}, async (ctx, resolver) => {
     const sessionController = lambder.getSessionController(ctx);
 
     // End current session
@@ -113,10 +123,12 @@ lambder.addSessionApi("user.logout", async (ctx, resolver) => {
         success: true,
         message: "Logged out successfully",
     });
-});
-
+})
 // Example: Logout from all devices
-lambder.addSessionApi("user.logoutAll", async (ctx, resolver) => {
+.addSessionApi("user.logoutAll", {
+    input: z.void(),
+    output: z.object({ success: z.boolean(), message: z.string() })
+}, async (ctx, resolver) => {
     const sessionController = lambder.getSessionController(ctx);
 
     // End all sessions for this user (same sessionKey)
@@ -126,10 +138,16 @@ lambder.addSessionApi("user.logoutAll", async (ctx, resolver) => {
         success: true,
         message: "Logged out from all devices",
     });
-});
-
+})
 // Example: Optional session (check if logged in)
-lambder.addApi("user.checkAuth", async (ctx, resolver) => {
+.addApi("user.checkAuth", {
+    input: z.object({}),
+    output: z.object({
+        authenticated: z.boolean(),
+        userId: z.string().optional(),
+        username: z.string().optional(),
+    })
+}, async (ctx, resolver) => {
     const sessionController = lambder.getSessionController(ctx);
 
     // Try to fetch session without throwing error
@@ -141,15 +159,14 @@ lambder.addApi("user.checkAuth", async (ctx, resolver) => {
             userId: session.data.userId,
             username: session.data.username,
         });
+    } else {
+        return resolver.api({
+            authenticated: false,
+        });
     }
-
-    return resolver.api({
-        authenticated: false,
-    });
-});
-
+})
 // Example: Route with session
-lambder.addSessionRoute("/dashboard", async (ctx, resolver) => {
+.addSessionRoute("/dashboard", async (ctx, resolver) => {
     // Session is automatically fetched and validated
     const userData = ctx.session.data;
 
@@ -157,10 +174,9 @@ lambder.addSessionRoute("/dashboard", async (ctx, resolver) => {
         user: userData,
         csrfToken: ctx.session.csrfToken,
     });
-});
-
+})
 // Example: Route with optional session
-lambder.addRoute("/", async (ctx, resolver) => {
+.addRoute("/", async (ctx, resolver) => {
     const sessionController = lambder.getSessionController(ctx);
     const session = await sessionController.fetchSessionIfExists();
 

package/examples/zod-chained-api-example.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import Lambder from "../src/index.js";
+
+// 1. Define reusable schemas
+const UserSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+});
+
+const CreateUserSchema = z.object({
+    name: z.string(),
+    email: z.string().email(),
+});
+
+// 2. Initialize Lambder and chain APIs
+const lambder = new Lambder({ 
+    publicPath: "./public",
+    apiPath: "/api" 
+})
+    .addApi("getUser", {
+        input: z.object({ userId: z.string() }),
+        output: UserSchema
+    }, async (ctx, resolver) => {
+        // ctx.apiPayload is typed as { userId: string }
+        const { userId } = ctx.apiPayload;
+        
+        return resolver.api({
+            id: userId,
+            name: "John Doe",
+            email: "john@example.com"
+        });
+    })
+    .addApi("createUser", {
+        input: CreateUserSchema,
+        output: UserSchema
+    }, async (ctx, resolver) => {
+        // ctx.apiPayload is typed as { name: string, email: string }
+        const { name, email } = ctx.apiPayload;
+        
+        return resolver.api({
+            id: "123",
+            name,
+            email
+        });
+    });
+
+// 3. Export the inferred contract type for Frontend
+export type AppContract = typeof lambder.ApiContractType;
+
+// 4. Modular example using .use()
+const authApi = <T>(l: Lambder<T>) => {
+    return l.addApi("login", {
+        input: z.object({ username: z.string(), password: z.string() }),
+        output: z.object({ token: z.string() })
+    }, async (ctx, resolver) => {
+        return resolver.api({ token: "abc-123" });
+    });
+};
+
+const lambderWithAuth = lambder.use(authApi);
+
+export type AuthContract = typeof lambderWithAuth.ApiContractType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "1.0.147",
+  "version": "2.0.2",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,7 +35,8 @@
     "js-cookie": "^3.0.5",
     "mime-types": "^2.1.35",
     "path-to-regexp": "^6.2.1",
-    "querystring": "^0.2.1"
+    "querystring": "^0.2.1",
+    "zod": "^4.1.12"
   },
   "peerDependencies": {
     "msw": "^2.0.0"