codeweaver 2.0.0 → 2.1.0

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
 
@@ -134,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();
   })
 );
 
@@ -160,7 +160,8 @@ router.post(
 router.get(
   "/:id",
   asyncHandler(async (req: Request, res: Response) => {
-    const user = await userController.get(req.params.id);
+    const id = await userController.validateId(req.params.id);
+    const user = await userController.get(id);
     res.json(user);
   })
 );
@@ -190,136 +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.email(),
-  password: z.string().min(6),
-});
-
-export const ZodUserCreationDto = ZodUser.omit({ id: true });
-export const ZodUserDto = ZodUser.omit({ password: true });
-
-export type User = z.infer<typeof ZodUser>;
-export type UserCreationDto = z.infer<typeof ZodUserCreationDto>;
-export type UserDto = z.infer<typeof ZodUserDto>;
-```
-
-- **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,
   UserDto,
+  ZodUserDto,
 } from "./dto/user.dto";
 import { memoizeAsync, onError, rateLimit, timeout } from "utils-decorators";
-import { Validate, ZodInput } from "ts-zod4-decorators";
-import { ResponseError } from "@/types";
-import { parseId } from "@/utilities/error-handling";
+import { ResponseError } from "@/utilities/error-handling";
+import { convert, stringToInteger } from "@/utilities/conversion";
 import config from "@/config";
-
-// 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 { 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 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 ResponseError(message, 404, e?.message);
+}
+
+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
@@ -328,63 +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: 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 });
+  public async create(user: User): Promise<void> {
+    users.push(user);
+    await userCache.set(user.id.toString(), user as User);
+    await usersCache.delete("key");
   }
 
-  @memoizeAsync(config.memoizeTime)
-  @onError({
-    func: getUserErrorHandler,
+  @memoizeAsync({
+    cache: usersCache,
+    keyResolver: () => "key",
+    expirationTimeMs: config.memoizeTime,
   })
+  @timeout(config.timeout)
   @rateLimit({
     timeSpanMs: config.rateLimitTimeSpan,
     allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
-   * Get user by ID
-   * @param {string} id - User ID as string
-   * @returns {Promise<User>} 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<UserDto> {
-    const response = parseId(id);
-    const user = users.find((user) => user.id === response);
-    if (user == null) throw new ResponseError("User dose not exist.", 404);
-    return user satisfies User;
+  public async getAll(): Promise<UserDto[]> {
+    return users as UserDto[];
   }
 
-  @memoizeAsync(config.memoizeTime)
-  @timeout(config.timeout)
+  @memoizeAsync({
+    cache: userCache,
+    keyResolver: (id: number) => id.toString(),
+    expirationTimeMs: config.memoizeTime,
+  })
   @rateLimit({
     timeSpanMs: config.rateLimitTimeSpan,
     allowedCalls: config.rateLimitAllowedCalls,
     exceedHandler,
   })
   /**
-   * Get all users with masked passwords
-   * @returns {Promise<UserDto[]>} 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<UserDto[]> {
-    return users.map((user) => ({
-      ...user,
-      password: "?",
-    }));
+  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);
   }
 }
 ```
@@ -401,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,6 +1,6 @@
 {
   "name": "codeweaver",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "main": "src/main.ts",
   "bin": {
     "create-codeweaver-app": "./command.js"
@@ -26,21 +26,24 @@
     "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",
-    "ts-zod4-decorators": "^1.0.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",

package/src/app.ts

@@ -0,0 +1,3 @@
+// TODO:
+
+export = null;

package/src/config.ts

@@ -5,53 +5,10 @@ import {
   rateLimitAllowedCalls,
   timeout,
   portNumber,
+  cacheSize,
 } from "./constants";
-
-/**
- * Server configuration interface
- * @interface
- * @property {string} url - Base server URL
- */
-interface Server {
-  url: string;
-}
-
-/**
- * API information structure
- * @interface
- * @property {string} title - API title
- * @property {string} version - API version
- * @property {string} description - API description
- */
-interface Info {
-  title: string;
-  version: string;
-  description: string;
-}
-
-/**
- * Swagger definition structure
- * @interface
- * @property {string} openApi - OpenAPI specification version
- * @property {Info} info - API information
- * @property {Server[]} servers - List of server configurations
- */
-interface SwaggerDefinition {
-  openApi: string;
-  info: Info;
-  servers: Server[];
-}
-
-/**
- * Swagger configuration options
- * @interface
- * @property {SwaggerDefinition} swaggerDefinition - Swagger definition object
- * @property {string[]} apis - Paths to API documentation files
- */
-interface SwaggerOptions {
-  swaggerDefinition: SwaggerDefinition;
-  apis: string[];
-}
+import { SwaggerOptions } from "./swagger-options";
+import { stringToBoolean } from "./utilities/conversion";
 
 /**
  * Main application configuration
@@ -63,11 +20,13 @@ interface SwaggerOptions {
 interface Config {
   devMode: boolean;
   port: number;
+  swagger: boolean;
   swaggerOptions: SwaggerOptions;
   timeout: number;
   rateLimitTimeSpan: number;
   rateLimitAllowedCalls: number;
   memoizeTime: number;
+  cacheSize: number;
 }
 
 const port = Number(process.env.PORT) || portNumber;
@@ -75,6 +34,7 @@ const port = Number(process.env.PORT) || portNumber;
 let config: Config = {
   devMode: process.env.NODE_ENV !== productionEnvironment,
   port,
+  swagger: stringToBoolean(process.env.SWAGGER || "true"),
   swaggerOptions: {
     swaggerDefinition: {
       openApi: "3.0.0",
@@ -90,10 +50,10 @@ let config: Config = {
       ],
     },
     apis: [
-      "./src/routers/index.ts",
-      "./src/routers/**/*.ts",
-      "./src/routers/index.js",
-      "./src/routers/**/*.js",
+      "./src/routers/index.router.ts",
+      "./src/routers/**/*.router.ts",
+      "./src/routers/index.router.js",
+      "./src/routers/**/*.router.js",
     ], // Path to the API docs
   },
   timeout: Number(process.env.TIMEOUT) || timeout,
@@ -101,6 +61,7 @@ let config: Config = {
   rateLimitAllowedCalls:
     Number(process.env.RATE_LIMIT) || rateLimitAllowedCalls,
   memoizeTime: Number(process.env.MEMOIZE_TIME) || memoizeTime,
+  cacheSize: Number(process.env.CACHE_SIZE) || cacheSize,
 };
 
 export default config;

package/src/constants.ts

@@ -2,5 +2,6 @@ export const timeout = 20000;
 export const rateLimitTimeSpan = 60000;
 export const rateLimitAllowedCalls = 300;
 export const memoizeTime = 1000 * 60 * 60;
+export const cacheSize = 1000;
 export const productionEnvironment = "production";
 export const portNumber = 3000;

package/src/db.ts

@@ -0,0 +1,183 @@
+import { Order } from "@/entities/order.entity";
+import { Product } from "@/entities/product.entity";
+import { User } from "@/entities/user.entity";
+
+// Array to store users (as a mock database)
+export const users: User[] = [
+  {
+    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",
+  },
+];
+
+// Array to store products (as a mock database)
+export const products: Product[] = [
+  {
+    id: 1,
+    name: "ASUS ROG Zephyrus G15",
+    price: 45000000,
+    description: "Gaming laptop with AMD Ryzen 9 5900HS and RTX 3080 GPU",
+    category: "Electronics",
+    stock: 15,
+  },
+  {
+    id: 2,
+    name: "Sony WH-1000XM5 Wireless Headphones",
+    price: 12000000,
+    description:
+      "Premium noise-canceling over-ear headphones with 30hr battery",
+    category: "Electronics",
+    stock: 8,
+  },
+  {
+    id: 3,
+    name: "LG Smart Inverter Microwave",
+    price: 25000000,
+    description: "1.7 cu.ft countertop microwave with smart sensor cooking",
+    category: "Appliances",
+    stock: 5,
+  },
+  {
+    id: 4,
+    name: "Trek Marlin 5 Mountain Bike",
+    price: 18000000,
+    description: "Entry-level mountain bike with aluminum frame and 21 speeds",
+    category: "Sports",
+    stock: 3,
+  },
+  {
+    id: 5,
+    name: "DeLonghi Espresso Machine",
+    price: 6500000,
+    description: "Compact espresso maker with manual milk frother",
+    category: "Kitchen",
+    stock: 12,
+  },
+  {
+    id: 6,
+    name: "Anker Wireless Charger",
+    price: 1200000,
+    description: "15W fast wireless charger with anti-slip surface",
+    category: "Mobile Accessories",
+    stock: 30,
+  },
+  {
+    id: 7,
+    name: "Logitech MX Master 3 Mouse",
+    price: 4500000,
+    description: "Ergonomic wireless mouse with Darkfield tracking",
+    category: "Computer Accessories",
+    stock: 18,
+  },
+  {
+    id: 8,
+    name: "Kindle Paperwhite",
+    price: 3800000,
+    description: 'Waterproof e-reader with 6.8" 300ppi display',
+    category: "Electronics",
+    stock: 9,
+  },
+  {
+    id: 9,
+    name: "Dyson V11 Vacuum Cleaner",
+    price: 32000000,
+    description: "Cordless stick vacuum with LCD screen and 60min runtime",
+    category: "Home Appliances",
+    stock: 7,
+  },
+];
+
+// Array to store orders (as a mock database)
+export const orders: Order[] = [
+  {
+    id: 1,
+    userId: 1,
+    products: [
+      { productId: 2, quantity: 1 },
+      { productId: 6, quantity: 2 },
+    ],
+    status: "Delivered",
+    total: 14400,
+    createdAt: new Date("2024-01-15"),
+    deliveredAt: new Date("2024-02-10"),
+  },
+  {
+    id: 2,
+    userId: 3,
+    products: [
+      { productId: 9, quantity: 1 },
+      { productId: 7, quantity: 1 },
+    ],
+    status: "Processing",
+    total: 36500,
+    createdAt: new Date("2024-03-20"),
+  },
+  {
+    id: 3,
+    userId: 2,
+    products: [
+      { productId: 1, quantity: 1 },
+      { productId: 4, quantity: 2 },
+    ],
+    status: "Canceled",
+    total: 81000,
+    createdAt: new Date("2024-05-01"),
+    canceledAt: new Date("2024-05-03"),
+  },
+];