lambder 1.0.65 → 1.0.67

package/Readme.md

@@ -1,58 +1,135 @@
 # Lambder
 
-Lambder provides a simplified way to handle AWS Lambda functions with HTTP triggers, offering a clear structure for managing API endpoints, static file serving, hooks, and error handling.
+Lambder is a dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
 ## Features
 
-- Easy setup of API paths with conditions and actions.
-- Support for hooks at different stages of the request lifecycle.
-- Integrated cookie and query string parsing.
-- Customizable error handling and fallback mechanisms.
-- CORS support and easy configuration for public paths.
-- Response helpers for JSON, HTML, XML, files, and more.
+- **Simple API & Route Declaration**: Define your APIs and routes using concise and expressive syntax.
+- **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.
+- **Seamless Integration**: Designed to work effortlessly with AWS Lambda and API Gateway, providing a straightforward path to deploy serverless applications.
 
 ## Installation
 
+To include Lambder in your TypeScript project, you can install it using npm or yarn. First, ensure that you have TypeScript set up in your project.
+
 ```bash
 npm install lambder
+# or
+yarn add lambder
 ```
 
-## Quick Start
+## Backend Usage
+
+### Basic Setup
 
 ```typescript
 import Lambder from 'lambder';
-import { APIGatewayProxyEvent, Context } from 'aws-lambda';
+import * as path from 'path';
 
-const app = new Lambder({
-    apiPath: '/api',
-    publicPath: '/public',
+const lambder = new Lambder({
+    apiPath: "/secure",
     isCorsEnabled: true,
+    publicPath: path.resolve(`./public`),
+});
+
+// Define a simple api
+lambder.addApi("fetchData", async (ctx, res) => {
+    const data = await fetchDataSomehow();
+    return res.api({ payload: data });
+});
+
+// Define a simple route
+lambder.addRoute("/hello-world", (ctx, res) => {
+    return res.json({ message: "Hello World" });
+});
+
+// Match all other paths and serve static files from publicPath, if not found, serve index.html
+lambder.addRoute("*", (ctx, res)=>{
+    return res.file(ctx.path, {}, "index.html");
+});
+
+
+// Set a fallback handler for unmatched routes
+lambder.setRouteFallbackHandler((ctx, res) => {
+    return res.status404("Not Found");
 });
 
-// Define a simple API endpoint
-app.addApi('/hello', async (ctx) => {
-    return ctx.resolver.json({ message: 'Hello, World!' });
+// Global error handler
+lambder.setGlobalErrorHandler((err, ctx, res) => {
+    console.error("Error:", err);
+    return res.status500("Internal Server Error");
+});
+
+export const handler = (event, context) => {
+    return lambder.render(event, context);
+};
+```
+
+### Adding Hooks
+
+```typescript
+// Before render hook example
+lambder.addHook("beforeRender", async (ctx, res) => {
+    // Perform actions before rendering
+    if(ctx.method === "POST") {
+        // Validate CSRF token, for example
+    }
+    return ctx; // Return modified context or throw an Error
 });
+```
+
+## Frontend Usage with LambderCaller
+
+LambderCaller is a frontend companion library for Lambder, designed to simplify making API requests to your Lambder backend services. 
 
-// Handle 404 Not Found
-app.setGlobalErrorHandler((err: Error) => {
-    return { statusCode: 404, body: 'Not Found' };
+### Installing LambderCaller
+
+LambderCaller is included in the same `lambder` package. Ensure you have `lambder` available in your frontend project.
+
+### Basic Setup
+
+Begin by initializing LambderCaller with your API configuration. This setup assumes your project structure accommodates a place for initiating and configuring API handlers, possibly within a dedicated JavaScript module or directly in your main application file.
+
+```javascript
+import LambderCaller from "lambder/dist/LambderCaller";
+
+const lambderCaller = new LambderCaller({
+    isCorsEnabled: false,
+    apiPath: "/secure", // Your Lambder API endpoint, must be the same as in your backend
+    fetchStartedHandler: ({ activeFetchList }) => {
+        // When any api call starts
+    },
+    fetchEndedHandler: ({ activeFetchList }) => {
+        // When any api call ends
+    },
+    errorMessageHandler: (message) => {
+        console.error("LambderCaller:", message); // Handle error messages
+    },
 });
 
-// Lambda handler
-exports.handler = async (event: APIGatewayProxyEvent, context: Context) => {
-    return app.render(event, context);
+
+const loadPageData = async () => {
+    try {
+        const response = await lambderCaller.api("getCompanyPage", {
+            subdomain: "example", // Pass necessary parameters for your API call
+        });
+    } catch (error) {
+        console.error("Failed to fetch page data:", error);
+    }
 };
+
 ```
 
-## Documentation
+## Advanced Configuration
 
-For more details on how to use Lambder, including the full API reference, visit [Lambder Documentation](#).
+Lambder is designed to be flexible and extensible, allowing for customized behaviors through hooks and custom error handling mechanisms. 
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+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.
 
 ## License
 
-MIT License
+This project is licensed under the [MIT License](LICENSE).

package/dist/Lambder.d.ts

@@ -2,7 +2,7 @@ import type { APIGatewayProxyEvent, APIGatewayProxyEventHeaders, Context } from
 import LambderResolver from "./LambderResolver.js";
 import LambderResponseBuilder, { LambderResolverResponse } from "./LambderResponseBuilder.js";
 type Path = `/${string}`;
-type Session = {
+type LambderSession = {
     userId: string;
     userIdHash: string;
     sessionHash: string;
@@ -11,7 +11,7 @@ type Session = {
     expiresTimeStamp: number;
     data: Record<string, any>;
 };
-type RenderContext = {
+type LambderRenderContext = {
     host: string;
     path: string;
     pathParams: Record<string, any> | null;
@@ -21,19 +21,19 @@ type RenderContext = {
     cookie: Record<string, any>;
     apiName: string;
     headers: APIGatewayProxyEventHeaders;
-    session: Session | null;
+    session: LambderSession | null;
     lambdaContext: Context;
 };
-type ConditionFunction = (ctx: RenderContext) => boolean;
-type ActionFunction = (ctx: RenderContext, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>;
+type ConditionFunction = (ctx: LambderRenderContext) => boolean;
+type ActionFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>;
 type HookCreatedFunction = (lambderInstance: Lambder) => Promise<void>;
-type HookBeforeRenderFunction = (ctx: RenderContext, resolver: LambderResolver) => RenderContext | Error | Promise<RenderContext | Error>;
-type HookAfterRenderFunction = (ctx: RenderContext, resolver: LambderResolver, response: LambderResolverResponse) => LambderResolverResponse | Error | Promise<LambderResolverResponse | Error>;
-type HookFallbackFunction = (ctx: RenderContext, resolver: LambderResolver) => void | Promise<void>;
-type GlobalErrorHandlerFunction = (err: Error, ctx: RenderContext | null, response: LambderResponseBuilder) => LambderResolverResponse | Promise<LambderResolverResponse>;
-type RouteFallbackHandlerFunction = (ctx: RenderContext, resolver: LambderResolver) => LambderResolverResponse;
-type ApiFallbackHandlerFunction = (ctx: RenderContext, resolver: LambderResolver) => LambderResolverResponse;
-export declare const createContext: (event: APIGatewayProxyEvent, lambdaContext: Context, apiPath?: string | null) => RenderContext;
+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) => 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 | null) => LambderRenderContext;
 export default class Lambder {
     private apiPath;
     private apiVersion;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "1.0.65",
+  "version": "1.0.67",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/Lambder.ts

@@ -8,7 +8,7 @@ import LambderResponseBuilder, { LambderResolverResponse } from "./LambderRespon
 
 type Path = `/${string}`;
 
-type Session = {
+type LambderSession = {
     userId: string,
     userIdHash: string;
     sessionHash: string;
@@ -18,7 +18,7 @@ type Session = {
     data: Record<string, any>;
 };
 
-type RenderContext = {
+type LambderRenderContext = {
     host: string;
     path: string;
     pathParams: Record<string, any> | null;
@@ -28,30 +28,30 @@ type RenderContext = {
     cookie: Record<string, any>;
     apiName: string;
     headers: APIGatewayProxyEventHeaders;
-    session: Session|null;
+    session: LambderSession|null;
     lambdaContext: Context;
 };
 
-type ConditionFunction = (ctx: RenderContext) => boolean;
-type ActionFunction = (ctx: RenderContext, resolver: LambderResolver) => LambderResolverResponse|Promise<LambderResolverResponse>;
+type ConditionFunction = (ctx: LambderRenderContext) => boolean;
+type ActionFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse|Promise<LambderResolverResponse>;
 type ActionObject = { conditionFn: ConditionFunction, actionFn: ActionFunction };
 
+type HookEventType = "created"|"beforeRender"|"afterRender"|"fallback";
 type HookCreatedFunction = (lambderInstance: Lambder) => Promise<void>;
-type HookBeforeRenderFunction = (ctx: RenderContext, resolver: LambderResolver) => RenderContext|Error|Promise<RenderContext|Error>;
-type HookAfterRenderFunction = (ctx: RenderContext, resolver: LambderResolver, response: LambderResolverResponse) => LambderResolverResponse|Error|Promise<LambderResolverResponse|Error>;
-type HookFallbackFunction = (ctx: RenderContext, resolver: LambderResolver) => void|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: RenderContext|null, response: LambderResponseBuilder) => LambderResolverResponse|Promise<LambderResolverResponse>;
-type RouteFallbackHandlerFunction = (ctx:RenderContext, resolver: LambderResolver) => LambderResolverResponse;
-type ApiFallbackHandlerFunction = (ctx:RenderContext, resolver: LambderResolver) => LambderResolverResponse;
+type GlobalErrorHandlerFunction = (err: Error, ctx: LambderRenderContext|null, response: LambderResponseBuilder) => LambderResolverResponse|Promise<LambderResolverResponse>;
+type RouteFallbackHandlerFunction = (ctx:LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse;
+type ApiFallbackHandlerFunction = (ctx:LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse;
 
-type HookEventType = "created"|"beforeRender"|"afterRender"|"fallback";
 
 export const createContext = (
     event: APIGatewayProxyEvent, 
     lambdaContext: Context,
     apiPath: string|null = null
-):RenderContext => {
+):LambderRenderContext => {
     const host = event.headers.Host || event.headers.host || "";
     const path = event.path;
     const pathParams = null;
@@ -123,7 +123,7 @@ export default class Lambder {
         return (match(pattern, { decode: decodeURIComponent }))(path) !== false;
     }
 
-    private async validateSession (ctx: RenderContext): Promise<boolean>{
+    private async validateSession (ctx: LambderRenderContext): Promise<boolean>{
         const { session, apiName, post, cookie } = ctx;
         if(!session) return false;
         if(!session.userId || !session.userIdHash || !session.sessionHash || !session.csrfToken) return false;
@@ -139,7 +139,7 @@ export default class Lambder {
         return false;
     };
 
-    private async handleNoMatchedAction(ctx: RenderContext, resolver: LambderResolver){
+    private async handleNoMatchedAction(ctx: LambderRenderContext, resolver: LambderResolver){
         for(const hook of this.hookList["fallback"]){  await hook.hookFn(ctx, resolver); }
 
         const isAPI = ctx.path === this.apiPath;
@@ -159,7 +159,7 @@ export default class Lambder {
     }
     addRoute(condition: Path|ConditionFunction|RegExp, actionFn: ActionFunction):void{
         this.actionList.push({ 
-            conditionFn: (ctx:RenderContext) => (
+            conditionFn: (ctx:LambderRenderContext) => (
                 ctx.method === "GET" && 
                 (
                     (typeof condition === "string" && this.testPatternMatch(condition, ctx.path)) ||
@@ -167,7 +167,7 @@ export default class Lambder {
                     (condition?.constructor == RegExp && condition.test(ctx.path))
                 )
             ), 
-            actionFn: async (ctx:RenderContext, resolver: LambderResolver) => {
+            actionFn: async (ctx:LambderRenderContext, resolver: LambderResolver) => {
                 if(typeof condition === "string"){
                     ctx.pathParams = this.getPatternMatch(condition, ctx.path);
                 }else if(condition?.constructor == RegExp){
@@ -181,7 +181,7 @@ export default class Lambder {
 
     addSessionRoute(condition: Path|ConditionFunction|RegExp, actionFn: ActionFunction):void{
         this.actionList.push({ 
-            conditionFn: (ctx:RenderContext) => (
+            conditionFn: (ctx:LambderRenderContext) => (
                 ctx.method === "GET" &&
                 (
                     (typeof condition === "string" && this.testPatternMatch(condition, ctx.path)) ||
@@ -189,7 +189,7 @@ export default class Lambder {
                     (condition?.constructor == RegExp && condition.test(ctx.path))
                 )
             ), 
-            actionFn: async (ctx:RenderContext, resolver: LambderResolver) => {
+            actionFn: async (ctx:LambderRenderContext, resolver: LambderResolver) => {
                 const isSessionValid = this.validateSession(ctx);
                 if(!isSessionValid) throw new Error("Session not found");
                 if(typeof condition === "string"){
@@ -204,23 +204,23 @@ export default class Lambder {
     
     addApi(apiName: string|ConditionFunction|RegExp, actionFn: ActionFunction):void{
         this.actionList.push({ 
-            conditionFn: (ctx:RenderContext) =>  (
+            conditionFn: (ctx:LambderRenderContext) =>  (
                 (typeof apiName === "string" && ctx.apiName === apiName) ||
                 (typeof apiName === "function" && apiName(ctx)) ||
                 (apiName?.constructor == RegExp && apiName.test(ctx.apiName))
             ), 
-            actionFn: async (ctx:RenderContext, resolver: LambderResolver) => await actionFn(ctx, resolver),
+            actionFn: async (ctx:LambderRenderContext, resolver: LambderResolver) => await actionFn(ctx, resolver),
         });
     };
 
     addSessionApi(apiName: string|ConditionFunction|RegExp, actionFn: ActionFunction):void{
         this.actionList.push({ 
-            conditionFn: (ctx:RenderContext) =>  (
+            conditionFn: (ctx:LambderRenderContext) =>  (
                 (typeof apiName === "string" && ctx.apiName === apiName) ||
                 (typeof apiName === "function" && apiName(ctx)) ||
                 (apiName?.constructor == RegExp && apiName.test(ctx.apiName))
             ), 
-            actionFn: async (ctx:RenderContext, resolver: LambderResolver) => {
+            actionFn: async (ctx:LambderRenderContext, resolver: LambderResolver) => {
                 const isSessionValid = this.validateSession(ctx);
                 if(!isSessionValid) throw new Error("Session not found");
                 return await actionFn(ctx, resolver);
@@ -266,7 +266,7 @@ export default class Lambder {
         event: APIGatewayProxyEvent,
         lambdaContext: Context
     ): Promise<LambderResolverResponse>{
-        let eventRenderContext:RenderContext|null = null;
+        let eventRenderContext:LambderRenderContext|null = null;
         
         try {
             let ctx = createContext(event, lambdaContext);