codeweaver 1.1.0 → 2.1.0

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "cSpell.words": ["microframework"]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**Codeweaver** is a lightweight microframework created with `Express`, `TypeScript`, and `Zod` (v4), seamlessly integrated with `Swagger` for comprehensive API documentation. Its modular architecture for routers promotes scalability and organized development, making it easy to expand and maintain.
+**Codeweaver** is an unopinionated microframework built with `Express`, `TypeScript`, and `Zod` (v4), seamlessly integrated with `Swagger` for comprehensive API documentation. Its modular architecture for routers promotes scalability and organized development, making it easy to expand and maintain. Routers are automatically discovered and wired up through a conventional folder structure, simplifying project organization and reducing boilerplate. Routers can be nested, allowing you to compose complex route trees by placing sub-routers inside parent router folders. It also uses `utils-decorators`, a collection of middleware utilities (throttling, caching, and error handling) designed to strengthen application resilience.
 
 ## Features and Technologies Used
 
@@ -13,8 +13,7 @@
 - **Swagger Integration**: Automatically generates interactive API documentation, facilitating easier understanding of available endpoints for developers and consumers.
 - **Async Handlers**: Utilizes async/await syntax for cleaner, more maintainable asynchronous code without callback nesting.
 - **Zod**: Implements schema validation for input data.
-- **ts-zod-decorators**: Enables validation using Zod schemas through decorators.
-- **utils-decorators**: Provides middleware utilities such as throttling and error handling for a more robust application.
+- **utils-decorators**: A collection of middleware utilities (throttling, caching, and error handling) designed to strengthen application resilience.
 
 ## Installation
 
@@ -53,34 +52,36 @@ To get started with the project, follow these steps:
 
 **/src**  
 ├── **/routers** `Directory containing all router files`  
-│ ├── **/user** `Routers for user-related endpoints`  
-│ │ ├── user_router1.ts `/user/user_router1`  
-│ │ ├── user_router2.ts `/user/user_router2`  
+│ ├── **/users** `Routers for user-related endpoints`  
+│ │ ├── index.router.ts `/users`  
+│ │ ├── user-router2.router.ts `/users/user-router2`  
 │ │ ├── user.controller.ts  
 │ │ ├── user.service.ts  
 │ │ └── user.dto.ts  
-│ ├── **/product** `Routers for product-related endpoints`  
-│ │ ├── index.ts `/product`  
-│ │ ├── product_test.spec.ts  
+│ ├── **/products** `Routers for product-related endpoints`  
+│ │ ├── index.router.ts `/products`  
 │ │ ├── product.controller.ts  
 │ │ ├── product.service.ts  
-│ │ ├── **/dto**  
+│ │ ├── **/dtos**  
 │ │ │ └── product.dto.ts  
-│ ├── **/order** `Routers for order-related endpoints`  
-│ │ ├── index.ts `/order`  
-│ │ ├── order_test.spec.ts  
+| | │ └── product-types.dto.ts  
+│ ├── **/orders** `Routers for order-related endpoints`  
+│ │ ├── index.router.ts `/orders`  
 │ │ ├── order.controller.ts  
-│ │ └── order.service.ts  
-│ └── index.ts `Home page`  
+│ │ ├── order.controller.spec.ts  
+│ │ ├── order.service.ts  
+│ │ └── order.service.spec.ts  
+│ └── index.router.ts `Home page`  
+│ └── app.controller.ts `Home page`  
 ├── app.ts `Main application file`  
 ├── config.ts `Application configuration file`  
 └── ... `Other files (middleware, models, etc.)`
 
 ### Router Directory
 
-Each router file in the `/routers` directory is organized to handle related endpoints. The `app.ts` file automatically imports all routers and mounts them to the main Express application, making it simple to add new routes without modifying central files.
+Each router file in the `/routers` directory is organized to handle related endpoints. The `app.ts` file automatically imports all routers and mounts them on the main Express application, making it straightforward to add new routes without touching central code.
 
-Files that end with `.controller`, `.service`, `.spec`, `.dto`, `.middleware`, `.error`, `.class`, or `.decorator`, as well as those that start with `_` or `@`, are excluded from the router list and can be utilized for various other purposes within the application.
+Files ending with `.router.ts` or `.router.js` are automatically included in the router list and can be reused for various purposes within the application.
 
 Example of a basic router:
 
@@ -88,7 +89,6 @@ Example of a basic router:
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
 import UserController from "./user.controller";
-import { sendError } from "@src/utilities";
 
 const router = Router();
 const userController = new UserController();
@@ -133,8 +133,9 @@ const userController = new UserController();
 router.post(
   "/",
   asyncHandler(async (req: Request, res: Response) => {
-    const user = await userController.create(req.body);
-    res.status(201).json(user);
+    const user = await userController.validateUserCreationDto(req.body);
+    await userController.create(user);
+    res.status(201).send();
   })
 );
 
@@ -159,10 +160,9 @@ router.post(
 router.get(
   "/:id",
   asyncHandler(async (req: Request, res: Response) => {
-    const user = await userController.get(req.params.id);
-
-    if ("id" in user == false) sendError(res, user);
-    else res.json(user);
+    const id = await userController.validateId(req.params.id);
+    const user = await userController.get(id);
+    res.json(user);
   })
 );
 
@@ -191,134 +191,44 @@ export = router;
 **Controllers** in this Express TypeScript framework act as the intermediary between the incoming HTTP requests and the application logic. Each controller is responsible for handling specific routes and defining the behavior associated with those routes. This organization promotes a clean architecture by separating business logic, validation, and routing concerns.
 
 Controllers can be organized within the router folders, allowing them to stay closely related to their respective routes. However, they are not limited to this structure and can be placed anywhere within the `src` folder as needed, providing flexibility in organizing the codebase.
-
-Controllers leverage decorators from the `ts-zod-decorators` package to implement input validation and error handling gracefully. With validators like `@Validate`, controllers can ensure that incoming data adheres to defined schemas before any processing occurs, preventing invalid data from reaching the service layer. This capability enhances data integrity and application reliability.
-
-For example, in the provided `UserController`, the `createUser` method demonstrates how to apply input validation and error handling through decorators. It employs `@rateLimit` to restrict the number of allowed requests within a specified timeframe, effectively guarding against too many rapid submissions. When an error arises, the `@onError` decorator provides a systematic way to handle exceptions, allowing for logging or other error management processes to be performed centrally.
+Controllers leverage decorators from the `utils-decorators` package to implement throttling, caching, and error handling gracefully.
+For example, in the provided `UserController`, the `createUser` method demonstrates how to apply error handling through decorators. It also employs `@rateLimit` to restrict the number of allowed requests within a specified timeframe, effectively guarding against too many rapid submissions. When an error arises, the `@onError` decorator provides a systematic way to handle exceptions, allowing for logging or other error management processes to be performed centrally.
 
 Here’s a brief breakdown of key components used in the `UserController`:
 
-- **Validation**: The `CreateUserDto` is validated against incoming data using the `@ZodInput` decorator, ensuring that only well-formed data is passed to the business logic, which is crucial for maintaining application stability.
-
 ```typescript
-import { z } from "zod";
-
-/**
- * Zod schema for User entity
- * @typedef {Object} ZodUser
- * @property {number} id - Unique identifier (min 1)
- * @property {string} username - Username (min 3 chars)
- * @property {string} email - Valid email format
- * @property {string} password - Password (min 6 chars)
- */
-export const ZodUser = z.object({
-  id: z.number().min(1).int(),
-  username: z.string().min(3),
-  email: z.string().email(),
-  password: z.string().min(6),
-});
-
-export const ZodUserCreationDto = ZodUser.omit({ id: true });
-
-export type User = z.infer<typeof ZodUser>;
-export type UserCreationDto = z.infer<typeof ZodUserCreationDto>;
-```
-
-- **Throttling and Rate Limiting**: The `@rateLimit` decorator is applied to safeguard the application's endpoints from abuse by limiting how frequently a particular method can be invoked.
-
-- **Error Handling**: The `@onError` decorator captures any exceptions that occur during the execution of the createUser method, allowing for centralized error management, which can greatly simplify debugging and improve maintainability.
-
-By using a well-organized controller structure, this project makes it easier to add, modify, and manage endpoints as the application grows. Developers can focus on implementing business logic while the controllers handle the intricacies of request parsing, validation, and response formatting. Additionally, this separation of concerns improves unit testing, as controllers can be tested independently from the rest of the application logic, ensuring robust and reliable API behavior.
-
-Here is a quick reference to the UserController in practice:
-
-```typescript
-import { User, ZodUserCreationDto, UserCreationDto } from "./dto/user.dto";
-import { onError, rateLimit, timeout } from "utils-decorators";
-import { Validate, ZodInput } from "@pkg/ts-zod-decorators";
-import { ResponseError } from "@src/types";
-import { tryParseId } from "@src/utilities";
-
-// Array to store users (as a mock database)
-const users = [
-  {
-    id: 1,
-    username: "johndoe",
-    email: "johndoe@gmail.com",
-    password: "S3cur3P@ssw0rd",
-  },
-  {
-    id: 2,
-    username: "janesmith",
-    email: "janesmith@yahoo.com",
-    password: "P@ssw0rd2024",
-  },
-  {
-    id: 3,
-    username: "michael89",
-    email: "michael89@hotmail.com",
-    password: "M1chael!2024",
-  },
-  {
-    id: 4,
-    username: "lisa.wong",
-    email: "lisa.wong@example.com",
-    password: "L1saW0ng!2024",
-  },
-  {
-    id: 5,
-    username: "alex_k",
-    email: "alex.k@gmail.com",
-    password: "A1ex#Key2024",
-  },
-  {
-    id: 6,
-    username: "emilyj",
-    email: "emilyj@hotmail.com",
-    password: "Em!ly0101",
-  },
-  {
-    id: 7,
-    username: "davidparker",
-    email: "david.parker@yahoo.com",
-    password: "D@v!d2024",
-  },
-  {
-    id: 8,
-    username: "sophia_m",
-    email: "sophia.m@gmail.com",
-    password: "Sophi@2024",
-  },
-  {
-    id: 9,
-    username: "chrisw",
-    email: "chrisw@outlook.com",
-    password: "Chri$Wong21",
-  },
-  {
-    id: 10,
-    username: "natalie_b",
-    email: "natalie_b@gmail.com",
-    password: "N@talie#B2024",
-  },
-];
+import {
+  ZodUserCreationDto,
+  UserCreationDto,
+  UserDto,
+  ZodUserDto,
+} from "./dto/user.dto";
+import { memoizeAsync, onError, rateLimit, timeout } from "utils-decorators";
+import { ResponseError } from "@/utilities/error-handling";
+import { convert, stringToInteger } from "@/utilities/conversion";
+import config from "@/config";
+import { users } from "@/db";
+import { User } from "@/entities/user.entity";
+import { MapAsyncCache } from "@/utilities/cache/memory-cache";
 
 function exceedHandler() {
   const message = "Too much call in allowed window";
-
-  throw new Error(message, {
-    cause: { status: 500, message } satisfies ResponseError,
-  });
+  throw new ResponseError(message, 429);
 }
 
-function getUserErrorHandler(e: Error) {
+function userNotFoundHandler(e: ResponseError) {
   const message = "User not found.";
+  throw new ResponseError(message, 404, e?.message);
+}
 
-  throw new Error(message, {
-    cause: { status: 404, message, details: e.message } satisfies ResponseError,
-  });
+function invalidInputHandler(e: ResponseError) {
+  const message = "Invalid input";
+  throw new ResponseError(message, 400, e?.message);
 }
 
+const usersCache = new MapAsyncCache<UserDto[]>(config.cacheSize);
+const userCache = new MapAsyncCache<UserDto>(config.cacheSize);
+
 /**
  * Controller for handling user-related operations
  * @class UserController
@@ -327,71 +237,94 @@ function getUserErrorHandler(e: Error) {
 export default class UserController {
   // constructor(private readonly userService: UserService) { }
 
+  @onError({
+    func: invalidInputHandler,
+  })
+  /**
+   * Validates a string ID and converts it to a number.
+   *
+   * @param {string} id - The ID to validate and convert.
+   * @returns {number} The numeric value of the provided ID.
+   */
+  public async validateId(id: string): Promise<number> {
+    return stringToInteger(id);
+  }
+
+  @onError({
+    func: invalidInputHandler,
+  })
+  /**
+   * Validates and creates a new User from the given DTO.
+   *
+   * @param {UserCreationDto} user - The incoming UserCreationDto to validate and transform.
+   * @returns {User} A fully formed User object ready for persistence.
+   */
+  public async validateUserCreationDto(user: UserCreationDto): Promise<User> {
+    const newUser = await ZodUserCreationDto.parseAsync(user);
+    return { ...newUser, id: users.length + 1 };
+  }
+
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
-  @Validate
   /**
    * Create a new user
-   * @param {UserCreationDto} user - User creation data validated by Zod schema
+   * @param {User} user - User creation data validated by Zod schema
    * @returns {Promise<void>}
    * @throws {ResponseError} 500 - When rate limit exceeded
    * @throws {ResponseError} 400 - Invalid input data
    */
-  public async create(@ZodInput(ZodUserCreationDto) user: UserCreationDto) {
-    users.push({ ...user, id: users.length + 1 } satisfies User);
+  public async create(user: User): Promise<void> {
+    users.push(user);
+    await userCache.set(user.id.toString(), user as User);
+    await usersCache.delete("key");
   }
 
-  @onError({
-    func: getUserErrorHandler,
+  @memoizeAsync({
+    cache: usersCache,
+    keyResolver: () => "key",
+    expirationTimeMs: config.memoizeTime,
   })
+  @timeout(config.timeout)
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
-   * Get user by ID
-   * @param {string} id - User ID as string
-   * @returns {Promise<User | ResponseError>} User details or error object
-   * @throws {ResponseError} 404 - User not found
-   * @throws {ResponseError} 400 - Invalid ID format
+   * Get all users
+   * @returns {Promise<UserDto[]>} List of users with hidden password fields
+   * @throws {ResponseError} 500 - When rate limit exceeded
    */
-  public async get(id: string): Promise<User | ResponseError> {
-    const userId = tryParseId(id);
-    if (typeof userId != "number") return userId satisfies ResponseError;
-    const user = users.find((user) => user.id === userId);
-
-    if (!user)
-      return {
-        status: 404,
-        message: "User dose not exist.",
-      } satisfies ResponseError;
-
-    return user satisfies User;
+  public async getAll(): Promise<UserDto[]> {
+    return users as UserDto[];
   }
 
-  @timeout(20000)
+  @memoizeAsync({
+    cache: userCache,
+    keyResolver: (id: number) => id.toString(),
+    expirationTimeMs: config.memoizeTime,
+  })
   @rateLimit({
-    timeSpanMs: 60000,
-    allowedCalls: 300,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
-   * Get all users with masked passwords
-   * @returns {Promise<User[]>} List of users with hidden password fields
-   * @throws {ResponseError} 500 - When rate limit exceeded
+   * Get user by ID
+   * @param {number} id - User ID as string
+   * @returns {Promise<UserDto>} User details or error object
+   * @throws {ResponseError} 404 - User not found
+   * @throws {ResponseError} 400 - Invalid ID format
    */
-  public async getAll(): Promise<User[]> {
-    return users.map(
-      (user) =>
-        ({
-          ...user,
-          password: "?",
-        } satisfies User)
-    );
+  public async get(id: number): Promise<UserDto> {
+    const user = users.find((user) => user.id === id);
+    if (user == null) {
+      throw new ResponseError("Product not found");
+    }
+    return convert(user!, ZodUserDto);
   }
 }
 ```
@@ -408,7 +341,7 @@ Once the application is running, visit the Swagger UI at http://localhost:3000/a
 
 ### Decorators
 
-To prevent abuse of your API, you can utilize throttling, and validation decorators from the `utils-decorators` and `ts-zod-decorators` packages respectively. This packages provides decorators that can be applied directly to your service and controller classes.
+To prevent abuse of your API, you can utilize throttling, caching, and error handling decorators from the `utils-decorators` packages respectively. This packages provides decorators that can be applied directly to your service and controller classes.
 
 ### Contributing
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "codeweaver",
-  "version": "1.1.0",
-  "main": "src/app.ts",
+  "version": "2.1.0",
+  "main": "src/main.ts",
   "bin": {
     "create-codeweaver-app": "./command.js"
   },
   "scripts": {
-    "start": "nodemon -r tsconfig-paths/register src/app.ts",
-    "dev": "nodemon -r tsconfig-paths/register src/app.ts",
+    "start": "nodemon -r tsconfig-paths/register src/main.ts",
+    "dev": "nodemon -r tsconfig-paths/register src/main.ts",
     "build": "tsc && tsc-alias && copyfiles -u 1 \"src/**/*.{json,env,sqlite,db,sql,yaml,yml,xml,txt,md}\" dist",
-    "serve": "cross-env TSCONFIG_PATH=tsconfig.paths.json node -r tsconfig-paths/register dist/app.js"
+    "serve": "cross-env TSCONFIG_PATH=tsconfig.paths.json node -r tsconfig-paths/register dist/main.js"
   },
   "keywords": [
     "codeweaver",
@@ -26,24 +26,29 @@
     "nested routers",
     "decorator",
     "swagger",
-    "zod"
+    "zod",
+    "utils-decorators"
   ],
   "author": "js-code-crafter",
   "license": "MIT",
   "description": "A lightweight framework built on top of Express and TypeScript",
   "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
     "express": "^5.1.0",
     "express-async-handler": "^1.2.0",
+    "ioredis": "^5.8.2",
+    "swagger-jsdoc": "^3.7.0",
     "utils-decorators": "^2.10.0",
     "zod": "^4.0.14"
   },
   "devDependencies": {
+    "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/node": "^24.1.0",
     "copyfiles": "^2.4.1",
     "cross-env": "^10.0.0",
     "nodemon": "^3.1.10",
-    "swagger-jsdoc": "^6.2.8",
     "swagger-ui-express": "^5.0.1",
     "ts-node": "^10.9.2",
     "tsc-alias": "^1.8.16",

package/src/app.ts

@@ -1,113 +1,3 @@
-import express, {
-  ErrorRequestHandler,
-  NextFunction,
-  Request,
-  Response,
-} from "express";
-import fs from "fs";
-import path from "path";
-import config from "./config";
+// TODO:
 
-/**
- * Recursively loads Express routers from directory
- * @param {string} routerPath - Directory path to scan
- * @param {string} [basePath=""] - Base route path
- */
-function loadRouters(routerPath: string, basePath: string = "") {
-  fs.readdirSync(routerPath).forEach((file) => {
-    // Check if the filename should be excluded based on certain criteria
-    if (
-      // Exclude files that start with an underscore (_)
-      file.startsWith("_") ||
-      // Exclude files that start with an at symbol (@)
-      file.startsWith("@") ||
-      // Exclude JavaScript controller files
-      file.endsWith(".controller.js") ||
-      // Exclude TypeScript controller files
-      file.endsWith(".controller.ts") ||
-      // Exclude JavaScript service files
-      file.endsWith(".service.js") ||
-      // Exclude TypeScript service files
-      file.endsWith(".service.ts") ||
-      // Exclude JavaScript middleware files
-      file.endsWith(".middleware.js") ||
-      // Exclude TypeScript middleware files
-      file.endsWith(".middleware.ts") ||
-      // Exclude JavaScript error middleware files
-      file.endsWith(".error.js") ||
-      // Exclude TypeScript error middleware files
-      file.endsWith(".error.ts") ||
-      // Exclude JavaScript service files
-      file.endsWith(".decorator.js") ||
-      // Exclude TypeScript service files
-      file.endsWith(".decorator.ts") ||
-      // Exclude JavaScript DTO files
-      file.endsWith(".dto.js") ||
-      // Exclude TypeScript DTO files
-      file.endsWith(".dto.ts") ||
-      // Exclude JavaScript test specification files
-      file.endsWith(".spec.js") ||
-      // Exclude TypeScript test specification files
-      file.endsWith(".spec.ts") ||
-      // Exclude JavaScript test specification files
-      file.endsWith(".class.js") ||
-      // Exclude TypeScript test specification files
-      file.endsWith(".class.ts")
-    )
-      // If any of the above conditions are true, exit the function early
-      return;
-
-    const fullPath = path.join(routerPath, file);
-
-    // Construct a route path by combining the base path with the filename
-    const routePath = path
-      // Join the base path and the filename, removing the file extension (.js or .ts)
-      .join(basePath, file.replace(/(\.js|\.ts)/g, ""))
-      // Replace all backslashes with forward slashes for consistent file path formatting
-      .replaceAll("\\", "/")
-      // Remove the trailing '/index' if it exists, to clean up the route
-      .replace(/\/?index$/g, "");
-
-    if (fs.lstatSync(fullPath).isDirectory()) {
-      // If the file is a directory, call the function again
-      loadRouters(fullPath, routePath);
-    } else if (file.endsWith(".ts") || file.endsWith(".js")) {
-      // Import the router module and mount it to the app
-      const router = require(fullPath);
-      app.use("/" + routePath, router);
-      console.log(`Mounted ${file} at ${"/" + routePath}`);
-    }
-  });
-}
-
-const app = express();
-app.use(express.json());
-app.use(express.urlencoded({ extended: true }));
-
-//app.use(cors());
-
-// Automatically import all routers from the /src/routers directory
-const routersPath = path.join(__dirname, "/routers");
-loadRouters(routersPath);
-
-// Swagger setup
-if (config.devMode) {
-  const swaggerJsDoc = require("swagger-jsdoc");
-  const swaggerUi = require("swagger-ui-express");
-  const swaggerDocs = swaggerJsDoc(config.swaggerOptions);
-  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs));
-}
-
-// General error handler
-app.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
-  res.status(500).json(err);
-});
-
-// Start the server
-app.listen(config.port, () => {
-  console.log(`Server is running on http://localhost:${config.port}`);
-  if (config.devMode)
-    console.log(
-      `Swagger UI is available at http://localhost:${config.port}/api-docs`
-    );
-});
+export = null;