lambder 1.0.124 → 1.0.126

package/Readme.md

@@ -43,7 +43,7 @@ lambder.enableDdbSession({
 });
 
 // Enable Cors
-lambder.setIsCorsEnabled(true);
+lambder.enableCors(true);
 
 // Define a simple api
 lambder.addApi("getCompanyPage", async ({ apiPayload }, res) => {
@@ -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 = {
+    getUserById: { input: { userId: string }, output: User },
+    createUser: { input: CreateUserInput, output: User },
+    listUsers: { input: void, output: User[] }
+} satisfies ApiContract;
+```
+
+### 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/dist/Lambder.d.ts

@@ -4,6 +4,7 @@ import LambderResponseBuilder, { LambderResolverResponse } from "./LambderRespon
 import LambderUtils from "./LambderUtils.js";
 import { type LambderSessionContext } from "./LambderSessionManager.js";
 import LambderSessionController from "./LambderSessionController.js";
+import type { ApiContract } from "./LambderApiContract.js";
 type Path = `/${string}`;
 export type LambderRenderContext = {
     host: string;
@@ -17,6 +18,7 @@ export type LambderRenderContext = {
     apiPayload: any;
     headers: APIGatewayProxyEventHeaders;
     session: LambderSessionContext | null;
+    event: APIGatewayProxyEvent;
     lambdaContext: Context;
     _otherInternal: {
         isApiCall: boolean;
@@ -42,7 +44,7 @@ type GlobalErrorHandlerFunction = (err: Error, ctx: LambderRenderContext | null,
 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 {
+export default class Lambder<TContract extends ApiContract = any> {
     apiPath: string;
     apiVersion: null | string;
     isCorsEnabled: boolean;
@@ -63,7 +65,7 @@ export default class Lambder {
         ejsPath?: string;
         apiVersion?: string;
     });
-    setIsCorsEnabled(isCorsEnabled: boolean): void;
+    enableCors(isCorsEnabled: boolean): void;
     enableDdbSession({ tableName, tableRegion, sessionSalt }: {
         tableName: string;
         tableRegion: string;
@@ -85,8 +87,16 @@ 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 & {
+        apiPayload: 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 & {
+        apiPayload: 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>;

package/dist/Lambder.js

@@ -33,7 +33,7 @@ export const createContext = (event, lambdaContext, apiPath) => {
     const apiPayload = isApiCall ? post.payload : null;
     return {
         host, path, pathParams, method,
-        get, post, cookie,
+        get, post, cookie, event,
         apiName, apiPayload,
         headers, session, lambdaContext,
         _otherInternal: {
@@ -72,7 +72,7 @@ export default class Lambder {
         };
         this.utils = new LambderUtils({ ejsPath });
     }
-    setIsCorsEnabled(isCorsEnabled) {
+    enableCors(isCorsEnabled) {
         this.isCorsEnabled = isCorsEnabled;
     }
     enableDdbSession({ tableName, tableRegion, sessionSalt }, { partitionKey, sortKey } = { partitionKey: "pk", sortKey: "sk" }) {
@@ -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,42 @@
+/**
+ * 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
+ */
+export type ApiContract = {
+    [apiName: string]: {
+        input: any;
+        output: any;
+    };
+};
+/**
+ * Extract input type from contract for a specific API
+ */
+export type ApiInput<TContract extends ApiContract, TApiName extends keyof TContract> = TContract[TApiName]['input'];
+/**
+ * Extract output type from contract for a specific API
+ */
+export type ApiOutput<TContract extends ApiContract, 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 { ApiContract } 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 ApiContract = 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

@@ -51,10 +51,16 @@ export default class LambderCaller {
                 credentials: 'same-origin', redirect: 'follow', referrerPolicy: 'origin',
                 headers: { 'Content-Type': 'application/json', ...(headers || {}) },
                 body: JSON.stringify({ apiName, version, token, siteHost, payload, }),
-            }).then(res => {
+            }).then(async (res) => {
                 if (res.status >= 500)
                     throw new Error("Request failed: " + res.status + " - " + res.statusText);
-                return res.json();
+                if (res.headers.get("Content-Type")?.includes("application/lambder-json-stream")) {
+                    const decompressed = res.json();
+                    return decompressed;
+                }
+                else {
+                    return res.json();
+                }
             });
             fetchTracker.done = true;
             if (this.fetchEndedHandler) {
@@ -95,7 +101,7 @@ export default class LambderCaller {
                     await this.notAuthorizedHandler();
                 }
                 else if (this.errorHandler) {
-                    await this.errorHandler(new Error("Version Expired; Please refresh;"));
+                    await this.errorHandler(new Error("Not Authorized;"));
                 }
                 return null;
             }
@@ -125,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/LambderResponseBuilder.d.ts

@@ -47,4 +47,5 @@ export default class LambderResponseBuilder {
     ejsTemplate(template: string, pageData: Record<string, any>, headers?: Record<string, string | string[]>): Promise<LambderResolverResponse>;
     ejsFile(filePath: string, pageData: Record<string, any>, headers?: Record<string, string | string[]>): Promise<LambderResolverResponse>;
     api<T = any>(payload: T | null, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, }?: LambderApiResponseConfig, headers?: Record<string, string | string[]>): LambderResolverResponse;
+    private apiBinary;
 }

package/dist/LambderResponseBuilder.js

@@ -144,7 +144,11 @@ export default class LambderResponseBuilder {
         }
         const mimeType = mimeTypeResolver.lookup(filePath);
         const body = this.readPublicFileSync(filePath);
-        const bodyBase64 = Buffer.from(body).toString("base64");
+        if (body === "forbidden-public-path") {
+            throw { error: "Forbidden public path: " + filePath };
+        }
+        const bodyBuffer = Buffer.isBuffer(body) ? body : Buffer.from(body);
+        const bodyBase64 = bodyBuffer.toString("base64");
         console.log("bodyBase64.length", bodyBase64.length);
         return this.fileBase64(bodyBase64, mimeType || "", headers);
     }
@@ -186,5 +190,32 @@ export default class LambderResponseBuilder {
         }, headers);
     }
     ;
+    apiBinary(payload, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, } = {
+        versionExpired: undefined, sessionExpired: undefined, notAuthorized: undefined,
+        message: null, errorMessage: null, logList: undefined
+    }, headers) {
+        const finalLogList = logList || this.ctx?._otherInternal?.logToApiResponseAccumulator;
+        const result = {
+            apiVersion: this.apiVersion,
+            payload,
+            ...(versionExpired ? { versionExpired } : {}),
+            ...(sessionExpired ? { sessionExpired } : {}),
+            ...(notAuthorized ? { notAuthorized } : {}),
+            ...(message ? { message } : {}),
+            ...(errorMessage ? { errorMessage } : {}),
+            ...(finalLogList?.length ? { logList: finalLogList } : {}),
+        };
+        return this.raw({
+            statusCode: 200,
+            isBase64Encoded: true,
+            multiValueHeaders: {
+                "Content-Type": ["application/lambder-json-stream"],
+                "Content-Encoding": ["gzip"],
+                ...convertToMultiHeader(headers)
+            },
+            body: Buffer.from(JSON.stringify(result)).toString("base64"),
+        });
+    }
+    ;
 }
 ;

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 = {
+    getUserById: { input: { userId: string }, output: User },
+    createUser: { input: CreateUserInput, output: User },
+    listUsers: { input: void, output: User[] }
+} satisfies ApiContract;
+```
+
+### 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