lambder 1.0.125 → 1.0.127

package/Readme.md

@@ -485,6 +485,65 @@ const loadPageData = async () => {
 };
 ```
 
+## Type-Safe APIs (Optional)
+
+Want compile-time type checking for your APIs? It's incredibly simple!
+
+### 1. Define Your API Contract
+
+```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 Constructor
+
+```typescript
+import Lambder from 'lambder';
+import type { MyApiContract } from './shared/apiContract';
+
+const lambder = new Lambder<MyApiContract>({ publicPath: './public', apiPath: '/api' });
+
+// Now addApi is type-safe!
+lambder.addApi('getUserById', async (ctx, resolver) => {
+    // ctx.apiPayload is automatically typed as { userId: string } ✨
+    const user = await db.getUser(ctx.apiPayload.userId);
+    return resolver.api(user);
+});
+```
+
+### 3. Frontend - Pass Type to Constructor
+
+```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 with full autocomplete! ✨
+const user = await caller.api('getUserById', { userId: '123' });
+//                             ↑ IDE shows all available APIs
+//                                            ↑ Type-checked input
+// user is typed as User | null | undefined
+```
+
+### Benefits
+
+✅ **Simple** - Just pass type to constructor, that's it!  
+✅ **Autocomplete** - IDE suggests available APIs as you type  
+✅ **Type Safety** - Inputs and outputs are fully typed  
+✅ **No Wrappers** - Use existing `api()` and `addApi()` methods  
+✅ **Opt-In** - Add when you want, skip when you don't  
+✅ **Zero Overhead** - Pure TypeScript types, no runtime code  
+
+📖 **[Read the Quick Start Guide](docs/TYPE_SAFE_QUICK_START.md)** for more details 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/deploy

@@ -3,6 +3,11 @@
 # Exit immediately if a command exits with a non-zero status.
 set -e
 
+echo "Running tests..."
+npm run test
+
+echo "Tests passed! Proceeding with deployment..."
+
 # Update the version, build the project, and publish
 rm -rf ./dist/*
 npm version patch --no-git-tag-version

package/dist/Lambder.d.ts

@@ -4,8 +4,9 @@ import LambderResponseBuilder, { LambderResolverResponse } from "./LambderRespon
 import LambderUtils from "./LambderUtils.js";
 import { type LambderSessionContext } from "./LambderSessionManager.js";
 import LambderSessionController from "./LambderSessionController.js";
+import type { ApiContractShape } from "./LambderApiContract.js";
 type Path = `/${string}`;
-export type LambderRenderContext = {
+export type LambderRenderContext<TApiPayload = any> = {
     host: string;
     path: string;
     pathParams: Record<string, any> | null;
@@ -14,7 +15,7 @@ export type LambderRenderContext = {
     post: Record<string, any>;
     cookie: Record<string, any>;
     apiName: string;
-    apiPayload: any;
+    apiPayload: TApiPayload;
     headers: APIGatewayProxyEventHeaders;
     session: LambderSessionContext | null;
     event: APIGatewayProxyEvent;
@@ -33,17 +34,17 @@ export type LambderRenderContext = {
     };
 };
 type LambderModuleFunction = (lambderInstance: Lambder) => void | Promise<void>;
-type ConditionFunction = (ctx: LambderRenderContext) => boolean;
-type ActionFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>;
+type ConditionFunction = (ctx: LambderRenderContext<any>) => boolean;
+type ActionFunction = (ctx: LambderRenderContext<any>, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>;
 type HookCreatedFunction = (lambderInstance: Lambder) => Promise<void>;
-type HookBeforeRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderRenderContext | Error | Promise<LambderRenderContext | Error>;
-type HookAfterRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver, response: LambderResolverResponse) => LambderResolverResponse | Error | Promise<LambderResolverResponse | Error>;
-type HookFallbackFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => void | Promise<void>;
-type GlobalErrorHandlerFunction = (err: Error, ctx: LambderRenderContext | null, response: LambderResponseBuilder, logListToApiResponse?: any[]) => LambderResolverResponse | Promise<LambderResolverResponse>;
-type RouteFallbackHandlerFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse;
-type ApiFallbackHandlerFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse;
-export declare const createContext: (event: APIGatewayProxyEvent, lambdaContext: Context, apiPath: string) => LambderRenderContext;
-export default class Lambder {
+type HookBeforeRenderFunction = (ctx: LambderRenderContext<any>, resolver: LambderResolver) => LambderRenderContext<any> | Error | Promise<LambderRenderContext<any> | Error>;
+type HookAfterRenderFunction = (ctx: LambderRenderContext<any>, resolver: LambderResolver, response: LambderResolverResponse) => LambderResolverResponse | Error | Promise<LambderResolverResponse | Error>;
+type HookFallbackFunction = (ctx: LambderRenderContext<any>, resolver: LambderResolver) => void | Promise<void>;
+type GlobalErrorHandlerFunction = (err: Error, ctx: LambderRenderContext<any> | null, response: LambderResponseBuilder, logListToApiResponse?: any[]) => LambderResolverResponse | Promise<LambderResolverResponse>;
+type RouteFallbackHandlerFunction = (ctx: LambderRenderContext<any>, resolver: LambderResolver) => LambderResolverResponse;
+type ApiFallbackHandlerFunction = (ctx: LambderRenderContext<any>, resolver: LambderResolver) => LambderResolverResponse;
+export declare const createContext: (event: APIGatewayProxyEvent, lambdaContext: Context, apiPath: string) => LambderRenderContext<any>;
+export default class Lambder<TContract extends ApiContractShape = any> {
     apiPath: string;
     apiVersion: null | string;
     isCorsEnabled: boolean;
@@ -86,13 +87,17 @@ export default class Lambder {
     }>): Promise<void>;
     addRoute(condition: Path | ConditionFunction | RegExp, actionFn: ActionFunction): void;
     addSessionRoute(condition: Path | ConditionFunction | RegExp, actionFn: ActionFunction): void;
-    addApi(apiName: string | ConditionFunction | RegExp, actionFn: ActionFunction): void;
-    addSessionApi(apiName: string | ConditionFunction | RegExp, actionFn: ActionFunction): void;
+    addApi(apiName: ConditionFunction | RegExp, actionFn: ActionFunction): void;
+    addApi<TApiName extends keyof TContract & string>(apiName: TApiName, actionFn: (ctx: LambderRenderContext<TContract[TApiName]['input']>, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>): void;
+    addApi(apiName: string, actionFn: ActionFunction): void;
+    addSessionApi(apiName: ConditionFunction | RegExp, actionFn: ActionFunction): void;
+    addSessionApi<TApiName extends keyof TContract & string>(apiName: TApiName, actionFn: (ctx: LambderRenderContext<TContract[TApiName]['input']>, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>): void;
+    addSessionApi(apiName: string, actionFn: ActionFunction): void;
     addHook(hookEvent: 'created', hookFn: HookCreatedFunction, priority?: number): Promise<void>;
     addHook(hookEvent: 'beforeRender', hookFn: HookBeforeRenderFunction, priority?: number): Promise<void>;
     addHook(hookEvent: 'afterRender', hookFn: HookAfterRenderFunction, priority?: number): Promise<void>;
     addHook(hookEvent: 'fallback', hookFn: HookFallbackFunction, priority?: number): Promise<void>;
-    getSessionController(ctx: LambderRenderContext): LambderSessionController;
+    getSessionController(ctx: LambderRenderContext<any>): LambderSessionController;
     getResponseBuilder(): LambderResponseBuilder;
     private getResolver;
     render(event: APIGatewayProxyEvent, lambdaContext: Context): Promise<LambderResolverResponse>;

package/dist/Lambder.js

@@ -163,6 +163,7 @@ export default class Lambder {
         });
     }
     ;
+    // Implementation
     addApi(apiName, actionFn) {
         this.actionList.push({
             conditionFn: (ctx) => (!!ctx.apiName && ((typeof apiName === "string" && ctx.apiName === apiName) ||
@@ -172,6 +173,7 @@ export default class Lambder {
         });
     }
     ;
+    // Implementation
     addSessionApi(apiName, actionFn) {
         this.actionList.push({
             conditionFn: (ctx) => (!!ctx.apiName && ((typeof apiName === "string" && ctx.apiName === apiName) ||

package/dist/LambderApiContract.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Type-safe API Contract System
+ *
+ * Define your API contract as a TypeScript type to get full type safety
+ * across frontend and backend with no runtime overhead.
+ *
+ * Example:
+ *
+ * export type MyApiContract = {
+ *     getUserById: { input: { userId: string }, output: User },
+ *     createUser: { input: CreateUserInput, output: User },
+ *     listUsers: { input: void, output: User[] }
+ * }
+ *
+ * Frontend:
+ * const caller = new LambderCaller<MyApiContract>({ ... });
+ * const user = await caller.api('getUserById', { userId: '123' }); // typed!
+ *
+ * Backend:
+ * const lambder = new Lambder<MyApiContract>({ ... });
+ * lambder.addApi('getUserById', async (ctx, resolver) => {
+ *     // ctx.apiPayload is typed as { userId: string }
+ *     return resolver.api(user); // user is typed as User
+ * });
+ */
+/**
+ * Base type for API contracts
+ *
+ * Use this as a constraint when defining your API contract:
+ *
+ * export type MyApiContract = {
+ *     echo: { input: { message: string }, output: { echo: string } }
+ * } satisfies ApiContract;
+ *
+ * Or for backward compatibility without satisfies:
+ *
+ * export type MyApiContract = ApiContract & {
+ *     echo: { input: { message: string }, output: { echo: string } }
+ * }
+ */
+export type ApiContractShape = Record<string, {
+    input: any;
+    output: any;
+}>;
+export type ApiContract<T extends ApiContractShape> = T;
+/**
+ * Extract input type from contract for a specific API
+ */
+export type ApiInput<TContract extends ApiContractShape, TApiName extends keyof TContract> = TContract[TApiName]['input'];
+/**
+ * Extract output type from contract for a specific API
+ */
+export type ApiOutput<TContract extends ApiContractShape, TApiName extends keyof TContract> = TContract[TApiName]['output'];

package/dist/LambderApiContract.js

@@ -0,0 +1,26 @@
+/**
+ * Type-safe API Contract System
+ *
+ * Define your API contract as a TypeScript type to get full type safety
+ * across frontend and backend with no runtime overhead.
+ *
+ * Example:
+ *
+ * export type MyApiContract = {
+ *     getUserById: { input: { userId: string }, output: User },
+ *     createUser: { input: CreateUserInput, output: User },
+ *     listUsers: { input: void, output: User[] }
+ * }
+ *
+ * Frontend:
+ * const caller = new LambderCaller<MyApiContract>({ ... });
+ * const user = await caller.api('getUserById', { userId: '123' }); // typed!
+ *
+ * Backend:
+ * const lambder = new Lambder<MyApiContract>({ ... });
+ * lambder.addApi('getUserById', async (ctx, resolver) => {
+ *     // ctx.apiPayload is typed as { userId: string }
+ *     return resolver.api(user); // user is typed as User
+ * });
+ */
+export {};

package/dist/LambderCaller.d.ts

@@ -1,4 +1,5 @@
 import { LambderApiResponse } from './LambderResponseBuilder';
+import type { ApiContractShape } from './LambderApiContract';
 type VoidFunction = () => void | Promise<void>;
 type FetchTracker = {
     apiName: string;
@@ -21,7 +22,7 @@ type FetchEndEventHandler = (params: {
 }) => void | Promise<void>;
 type ErrorHandler = (err: Error) => void | Promise<void>;
 type MessageHandler = (message: any) => void | Promise<void>;
-export default class LambderCaller {
+export default class LambderCaller<TContract extends ApiContractShape = any> {
     private isCorsEnabled;
     private apiPath;
     private apiVersion?;
@@ -51,7 +52,7 @@ export default class LambderCaller {
         fetchEndedHandler?: FetchEndEventHandler;
     });
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
-    apiRaw<T = any>(apiName: string, payload?: any, options?: {
+    apiRaw<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: {
         headers?: Record<string, any>;
         versionExpiredHandler?: VoidFunction;
         sessionExpiredHandler?: VoidFunction;
@@ -61,7 +62,17 @@ export default class LambderCaller {
         errorHandler?: ErrorHandler;
         fetchStartedHandler?: FetchStartEventHandler;
         fetchEndedHandler?: FetchEndEventHandler;
-    }): Promise<LambderApiResponse<T> | null | undefined>;
-    api<T = any>(...params: Parameters<typeof LambderCaller.prototype.apiRaw>): Promise<T | null | undefined>;
+    }): Promise<LambderApiResponse<TOutput> | null | undefined>;
+    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: {
+        headers?: Record<string, any>;
+        versionExpiredHandler?: VoidFunction;
+        sessionExpiredHandler?: VoidFunction;
+        messageHandler?: MessageHandler;
+        errorMessageHandler?: MessageHandler;
+        notAuthorizedHandler?: VoidFunction;
+        errorHandler?: ErrorHandler;
+        fetchStartedHandler?: FetchStartEventHandler;
+        fetchEndedHandler?: FetchEndEventHandler;
+    }): Promise<TOutput | null | undefined>;
 }
 export {};

package/dist/LambderCaller.js

@@ -131,8 +131,8 @@ export default class LambderCaller {
     }
     ;
     // Use the same type for api but adjust the return type
-    async api(...params) {
-        const result = await this.apiRaw(...params);
+    async api(apiName, payload, options) {
+        const result = await this.apiRaw(apiName, payload, options);
         return result?.payload;
     }
 }

package/dist/LambderResolver.d.ts

@@ -25,7 +25,7 @@ export default class LambderResolver extends LambderResponseBuilder {
         publicPath: string;
         apiVersion?: string | null;
         lambderUtils: LambderUtils;
-        ctx: LambderRenderContext;
+        ctx: LambderRenderContext<any>;
         resolve: (response: LambderResolverResponse) => void;
         reject: (err: Error) => void;
     });

package/dist/LambderResponseBuilder.d.ts

@@ -28,7 +28,7 @@ export default class LambderResponseBuilder {
         publicPath: string;
         apiVersion?: string | null;
         lambderUtils: LambderUtils;
-        ctx?: LambderRenderContext;
+        ctx?: LambderRenderContext<any>;
     });
     private readPublicFileSync;
     private checkPublicFileExist;

package/dist/LambderSessionController.d.ts

@@ -5,12 +5,12 @@ export default class LambderSessionController {
     lambderSessionManager: LambderSessionManager;
     sessionTokenCookieKey: string;
     sessionCsrfCookieKey: string;
-    ctx: LambderRenderContext;
+    ctx: LambderRenderContext<any>;
     constructor({ lambderSessionManager, sessionTokenCookieKey, sessionCsrfCookieKey, ctx, }: {
         lambderSessionManager: LambderSessionManager;
         sessionTokenCookieKey: string;
         sessionCsrfCookieKey: string;
-        ctx: LambderRenderContext;
+        ctx: LambderRenderContext<any>;
     });
     private areRequestSessionTokensValid;
     createSession(sessionKey: string, data?: any, ttlInSeconds?: number): Promise<LambderSessionContext>;

package/dist/index.d.ts

@@ -4,3 +4,4 @@ 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 { type ApiContract, type ApiInput, type ApiOutput, } from "./LambderApiContract.js";

package/docs/TYPE_SAFE_QUICK_START.md

@@ -0,0 +1,123 @@
+# Type-Safe API Quick Start
+
+## In 3 Simple Steps
+
+### 1. Define Your Contract Type
+
+```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
+
+```typescript
+import Lambder from 'lambder';
+import type { MyApiContract } from './shared/apiContract';
+
+const lambder = new Lambder<MyApiContract>({
+    publicPath: './public',
+    apiPath: '/api'
+});
+
+// Now addApi is type-safe!
+lambder.addApi('getUserById', async (ctx, resolver) => {
+    // ctx.apiPayload is automatically typed as { userId: string }
+    const user = await db.getUser(ctx.apiPayload.userId);
+    return resolver.api(user);
+});
+```
+
+### 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**
+- ✅ **Backward compatible**
+
+## Contract Type Format
+
+```typescript
+type MyApiContract = {
+    apiName: { input: InputType, output: OutputType }
+}
+```
+
+## Examples
+
+### API with parameters
+```typescript
+getUserById: { input: { userId: string }, output: User }
+```
+
+### 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 }
+}
+```
+
+## Without Type Safety (Still Works!)
+
+Don't want type safety? Just don't pass the generic type:
+
+```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
+});
+```
+
+## Full Example
+
+See [simplified-typed-api-example.ts](../examples/simplified-typed-api-example.ts) for a complete working example.
+
+## Key Points
+
+- **Contract is just a TypeScript type** - No runtime code!
+- **Zero overhead** - All type checking happens at compile time
+- **Opt-in** - Use types when you want them
+- **Simple** - Just pass type to constructor
+- **Autocomplete** - IDE shows available APIs as you type