ExFrame

ExFrame is a lightweight library that streamlines web API development with Express.js by offering improved organization, error handling, middleware management, and enhanced Dependency Injection (DI) capabilities. It simplifies controller-based routing, boosts maintainability, and promotes best practices for scalable applications. By tightly integrating with Express.js, ExFrame ensures cleaner code and better separation of concerns.

---

📌 Installation

1npm install @d3vtool/ex-frame

---

• Contents
  • Getting Started
  • Dependency Injection
  • Ex-Frame Utilities

---

🚀 Getting Started

1️⃣ Setting Up

✅ Prerequisites

Before using ExFrame, ensure the following:

1. TypeScript is being used.
2. The following options are enabled in tsconfig.json:

   1{
   2  "compilerOptions": {
   3    "experimentalDecorators": true,
   4    "emitDecoratorMetadata": true
   5  }
   6}

---

✅ Basic Setup

Create an entry point (index.ts) and initialize the framework:

1import { ExFrame } from "@d3vtool/ex-frame";
2import express from "express";
3import { UsersController } from "./src/controllers/UsersController";
4
5const app = express();
6const frame = new ExFrame(app);
7
8frame.controller(UsersController); // Registers the controller
9
10frame.listen(3000, () => {
11    console.log("Server is running on port 3000");
12});

---

✅ Dependency Injection

Create an entry point (index.ts), initialize the framework, and configure the Dependency Injection (DI) system:

1import express, { type Request, type Response } from "express";
2import { ExFrame, Get, InjectScoped } from "@d3vtool/ex-frame"; 
3
4const app = express();
5const frame = new ExFrame(app);
6
7// (test-service.ts) Define Services with different lifetimes
8class TestService {
9    doesWork() {
10        console.log("it works in test service...");
11    }
12}
13frame.addTransient(TestService); // Adds TestService as a Transient service
14
15// (user-service.ts)
16class UserService {
17    getUser(id: string) {
18        console.log(`fetching data for ${id}...`);        
19    }
20}
21frame.addScoped(UserService); // Adds UserService as a Scoped service
22
23// (db-service.ts)
24class DBService {
25    static query(stmt: string) {
26        console.log(`query ${stmt}...`);        
27    }
28}
29frame.addSingleton(DBService); // Adds DBService as a Singleton service
30
31
32// Controller with Dependency Injection
33class UserController {
34    @Get("/")
35    @InjectScoped() // scoped lifetime
36    static async getUser(
37        // [ the variable name should be same as configuring Class name. ]
38        userService: UserService,
39        req: Request,
40        res: Response
41    ) {
42        const user =  await userService.getUser(req.params.id);
43        res.send({
44            status: "success",
45            user
46        });
47    }
48}
49frame.controller(UserController); // Registers the controller
50
51// Start the server
52frame.listen(3000, () => {
53    console.log("Server is running on port 3000");
54});

🛠️ Key Concepts:

• Transient Service: A new instance of TestService is created each time it is requested.
• Scoped Service: A single instance of UserService is shared within the request's scope.
• Singleton Service: DBService is a shared instance across the entire application.

🔄 Dependency Injection:

• The @InjectTransient() decorator automatically injects TestService as a transient dependency.
• The @InjectScoped() decorator automatically injects UserService as a transient dependency.
• The @InjectSingleton() decorator automatically injects DBService as a transient dependency.
• The frame.addTransient(), frame.addScoped(), and frame.addSingleton() methods configure the DI container with the appropriate service lifetime.

---

📌 Controllers and Decorators

2️⃣ Creating a Controller

1. A controller defines the logic for handling incoming requests. Decorators help in structuring routes, managing middleware, and handling errors.

2. Controller methods must be declared as static.

✅ Example

1export class UsersController {
2    @Get("/")
3    @Middlewares(authMiddleware)
4    static getAll(req: Request, res: Response) {
5        res.send("Hello");
6    }
7}

---

3️⃣ @ParentRoute (Class Decorator)

Defines a parent route for all methods inside a controller.

1@ParentRoute("/users") // applied to this controller only
2export class UsersController {
3    // All methods inside this class will be prefixed with "/users"
4}

📌 Notes

• All methods inside the class will be grouped under /users.
• Methods inside the controller must be static.

---

4️⃣ @ErrorHandler (Class | Method Decorator)

Handles errors within a specific route or acts as a fallback if an explicit error handler is not set.

1/* 
2 It will also act as a fallback if some method throws error 
3 and you didn't declare '@ErrorHandler' over that method, 
4 then this will catch it. 
5*/
6@ErrorHandler(controllerErrorHandler) // applied to this controller only
7export class UsersController {
8    @Get("/:id")
9    @ErrorHandler(routeErrorHandler) // Can be applied to specific methods
10    static getUser(req: Request, res: Response) {
11        throw new Error("Something went wrong");
12    }
13}

📌 Notes

• If an error occurs inside getUser, the method-level @ErrorHandler will handle it.
• If no method-level error handler is defined, the class-level handler will take over.

---

5️⃣ @Middlewares (Class | Method Decorator)

Registers middleware functions for a specific route.

1// this will run for before any controller method execute.
2@Middlewares(userControllerMiddleware)
3export class UsersController {
4    @Get("/:id")
5    @Middlewares(authMiddleware) // Middleware for this specific route
6    static getUser(req: Request, res: Response) {
7        res.send("User details");
8    }
9}

📌 Notes

• Middleware functions are executed before the route handler.
• Multiple middleware functions can be applied.

---

6️⃣ Route Method Decorators (@Get, @Post, etc.)

Defines routes for handling different HTTP methods.

1@Get("/:id")
2static getUser(req: Request, res: Response) {
3    res.send("User details");
4}

📌 Notes

• Decorators like @Get, @Post, @Put, and @Delete associate methods with specific HTTP methods.

---

7️⃣ Static Methods in Controllers

All controller methods must be static.

1export class UsersController {
2    @Get("/:id")
3    static getUser(req: Request, res: Response) {
4        res.send("User details");
5    }
6}

📌 Notes

• Static methods ensure proper route registration and execution.

---

Ex-Frame Utilities

✅ @Memoize

Caches the result of a function call, preventing unnecessary recomputation.

Example:

1import { Memoize } from "@d3vtool/ex-frame";
2
3class UserService {
4    @Memoize()
5    static getUser(id: number) {
6        console.log("Fetching user from DB...");
7        return { id, name: "John Doe" };
8    }
9}
10
11console.log(UserService.getUser(1)); // Fetches from DB
12console.log(UserService.getUser(1)); // Returns cached result

---

✅ @Cache(ttl: number)

Caches the result of a function for a specified time-to-live (TTL).

Example:

1import { Cache } from "@d3vtool/ex-frame";
2
3class DataService {
4    @Cache(5000) // Cache for 5 seconds
5    static fetchData() {
6        console.log("Fetching data...");
7        return "data";
8    }
9}
10
11console.log(DataService.fetchData()); // Fetches new data
12setTimeout(() => console.log(DataService.fetchData()), 2000); // Returns cached data
13setTimeout(() => console.log(DataService.fetchData()), 6000); // Fetches fresh data

---

✅ @OnError(fn: (error: unknown) => void)

Catches errors from a function and handles them using the provided error handler.

Example:

1import { OnError } from "@d3vtool/ex-frame";
2
3function logError(error: unknown) {
4    console.error("Caught error:", error);
5}
6
7class ExampleService {
8    @OnError(logError)
9    static riskyOperation() {
10        throw new Error("Something went wrong!");
11    }
12}
13
14ExampleService.riskyOperation(); // Logs error instead of crashing

---

✅ @Pipe<T>(fn: (arg: T) => void)

Passes the return value of a function to the provided callback.

Example:

1import { Pipe } from "@d3vtool/ex-frame";
2
3function logOutput(data: number) {
4    console.log("Processed data:", data);
5}
6
7class UsersController {
8    @Pipe<number>(logOutput)
9    static getUserId(username: string) {
10        return 1001;
11    }
12}
13
14UsersController.getUserId("Alice"); // Logs: "Processed data: 1001"

---

✅ @MeasureTime(fn?: (time: number) => void)

Measures execution time and optionally reports it, else it will log to console.

Example:

1import { MeasureTime } from "@d3vtool/ex-frame";
2
3function reportTime(ms: number) {
4    console.log(`Execution time: ${ms}ms`);
5}
6
7class PerformanceService {
8    @MeasureTime(reportTime)
9    static compute() {
10        for (let i = 0; i < 1e6; i++); // Simulate work
11    }
12}
13
14PerformanceService.compute(); // Logs execution time

---

✅ @Throttle(limit: number)

Limits function execution to at most once per specified time interval.

Example:

1import { Throttle } from "@d3vtool/ex-frame";
2
3class ClickHandler {
4    @Throttle(2000) // Allow execution every 2 seconds
5    static handleClick() {
6        console.log("Button clicked!");
7    }
8}
9
10// Simulate rapid clicks
11ClickHandler.handleClick();
12ClickHandler.handleClick(); // Ignored
13setTimeout(() => ClickHandler.handleClick(), 2500); // Executed

---

✅ @Debounce(delay: number, fn?: (data: T) => void)

Ensures that a function is executed only after a specified delay, preventing excessive calls.

Example:

1import { Debounce } from "@d3vtool/ex-frame";
2
3function logSearch(data: string) {
4    console.log("Searching for:", data);
5}
6
7class SearchBar {
8    @Debounce(500, logSearch) // Wait 500ms before execution
9    static search(query: string) {
10        return query;
11    }
12}
13
14// Simulate rapid typing
15SearchBar.search("A");
16SearchBar.search("Ap");
17SearchBar.search("App"); // Executes only once after 500ms