codeweaver 1.0.15 → 1.1.0

package/README.md

@@ -2,25 +2,19 @@
 
 ## Overview
 
-**Codeweaver** is a lightweight framework built on top of `Express` and `TypeScript`, integrating `Swagger` for API documentation. The application utilizes `async handlers` for improved error management and follows a modular structure for routers, enabling easy expansion and organization of the application.
+**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.
 
-## Features
-
-- **Modular Router Structure**: Each router is automatically imported and mounted, providing clean separation of endpoints and logic.
-- **Express Framework**: A lightweight web application framework for building web applications in Node.js.
-- **TypeScript**: Provides strong typing for better development experience and less runtime errors.
-- **Swagger Integration**: Automatically generates interactive API documentation, making it easy for developers and consumers to understand the available endpoints.
-- **Async Handlers**: Supports async/await syntax for writing cleaner and more maintainable asynchronous code without deeply nested callbacks.
-
-## Technologies Used
+## Features and Technologies Used
 
 - **Node.js**
-- **Express**
-- **TypeScript**
-- **Zod** (for input validation)
-- **ts-zod-decorators** (for validation using Zod with decorators)
-- **utils-decorators** (for middleware utilities like throttling and error handling)
-- **Swagger** (for API documentation)
+- **Express**: A lightweight web framework for building server-side applications in Node.js.
+- **TypeScript**: Adds strong typing for enhanced development experience and reduced runtime errors.
+- **Modular Router Structure**: Automates importing and mounting routers, ensuring a clean separation of endpoints and logic for easier scalability.
+- **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.
 
 ## Installation
 
@@ -29,6 +23,7 @@ To get started with the project, follow these steps:
 1. **Clone the repository**:
 
    ```bash
+   npm install -g codeweaver
    npx create-codeweaver-app my-app
    cd my-app
    ```
@@ -51,6 +46,7 @@ To get started with the project, follow these steps:
 
    ```bash
    npm run build
+   npm run serve
    ```
 
 ## Sample Project Structure
@@ -84,30 +80,106 @@ To get started with the project, follow these steps:
 
 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.
 
-Files that end with `.controller`, `.service`, `.spec`, `.dto`, `.middleware`, `.error`, 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 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.
 
 Example of a basic router:
 
 ```typescript
 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();
+
+/**
+ * @swagger
+ * /users:
+ *   post:
+ *     summary: Create a user
+ *     description: Create a new user.
+ *     consumes:
+ *       - application/json
+ *     produces:
+ *       - application/json
+ *     parameters:
+ *       - in: body
+ *         name: user
+ *         required: true
+ *         schema:
+ *           type: object
+ *           required:
+ *             - username
+ *             - email
+ *             - password
+ *           properties:
+ *             username:
+ *               type: string
+ *               minLength: 3
+ *               example: JessicaSmith
+ *             email:
+ *               type: string
+ *               format: email
+ *               example: user@example.com
+ *             password:
+ *               type: string
+ *               minLength: 6
+ *               example: securePassword123
+ *     responses:
+ *       201:
+ *         description: User created
+ */
+router.post(
+  "/",
+  asyncHandler(async (req: Request, res: Response) => {
+    const user = await userController.create(req.body);
+    res.status(201).json(user);
+  })
+);
+
+/**
+ * @swagger
+ * /users/{id}:
+ *   get:
+ *     summary: Get a user by ID
+ *     parameters:
+ *       - name: id
+ *         in: path
+ *         required: true
+ *         description: The ID of the product
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: A user object
+ *       404:
+ *         description: user not found
+ */
+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);
+  })
+);
 
 /**
  * @swagger
- * /:
+ * /users:
  *   get:
- *     summary: Get the home page
- *     description: Returns the home page.
+ *     summary: Get users
+ *     description: Returns a list of user objects.
  *     responses:
  *       200:
- *         description: home page
+ *         description: A list of user objects
  */
 router.get(
   "/",
   asyncHandler(async (req: Request, res: Response) => {
-    res.send("Home");
+    res.json(await userController.getAll());
   })
 );
 
@@ -131,13 +203,25 @@ Here’s a brief breakdown of key components used in the `UserController`:
 ```typescript
 import { z } from "zod";
 
-export const createUserDto = z.object({
+/**
+ * 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 type CreateUser = z.infer<typeof createUserDto>;
+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.
@@ -149,37 +233,165 @@ By using a well-organized controller structure, this project makes it easier to
 Here is a quick reference to the UserController in practice:
 
 ```typescript
-import { Validate, ZodInput } from "ts-zod-decorators";
-import { createUserDto, CreateUser } from "./dto/user.dto";
-import { onError, rateLimit } from "utils-decorators";
+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",
+  },
+];
 
 function exceedHandler() {
-  throw new Error("Too much call in allowed window");
+  const message = "Too much call in allowed window";
+
+  throw new Error(message, {
+    cause: { status: 500, message } satisfies ResponseError,
+  });
 }
 
-function errorHandler(e: Error): void {
-  console.error(e);
+function getUserErrorHandler(e: Error) {
+  const message = "User not found.";
+
+  throw new Error(message, {
+    cause: { status: 404, message, details: e.message } satisfies ResponseError,
+  });
 }
 
+/**
+ * Controller for handling user-related operations
+ * @class UserController
+ * @desc Provides methods for user management including CRUD operations
+ */
 export default class UserController {
-  //constructor(private readonly userService: UserService) { }
+  // constructor(private readonly userService: UserService) { }
 
-  // Throttle the createUser method to 1 request per 200 milliseconds
   @rateLimit({
     timeSpanMs: 60000,
     allowedCalls: 300,
     exceedHandler,
   })
+  @Validate
+  /**
+   * Create a new user
+   * @param {UserCreationDto} 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);
+  }
+
   @onError({
-    func: errorHandler,
+    func: getUserErrorHandler,
   })
-  @Validate
-  public async createUser(
-    @ZodInput(CreateUserDto) data: CreateUser
-  ): Promise<string> {
-    // Here you can include logic to save user to database
-    console.log("Creating user:", data);
-    return "User created successfully";
+  @rateLimit({
+    timeSpanMs: 60000,
+    allowedCalls: 300,
+    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
+   */
+  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;
+  }
+
+  @timeout(20000)
+  @rateLimit({
+    timeSpanMs: 60000,
+    allowedCalls: 300,
+    exceedHandler,
+  })
+  /**
+   * Get all users with masked passwords
+   * @returns {Promise<User[]>} List of users with hidden password fields
+   * @throws {ResponseError} 500 - When rate limit exceeded
+   */
+  public async getAll(): Promise<User[]> {
+    return users.map(
+      (user) =>
+        ({
+          ...user,
+          password: "?",
+        } satisfies User)
+    );
   }
 }
 ```

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "codeweaver",
-  "version": "1.0.15",
+  "version": "1.1.0",
   "main": "src/app.ts",
   "bin": {
     "create-codeweaver-app": "./command.js"
   },
   "scripts": {
-    "start": "nodemon src/app.ts",
-    "build": "tsc",
-    "serve": "node dist/app.js"
+    "start": "nodemon -r tsconfig-paths/register src/app.ts",
+    "dev": "nodemon -r tsconfig-paths/register src/app.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"
   },
   "keywords": [
     "codeweaver",
@@ -27,23 +28,26 @@
     "swagger",
     "zod"
   ],
-  "author": "Ehsan Afzali",
+  "author": "js-code-crafter",
   "license": "MIT",
   "description": "A lightweight framework built on top of Express and TypeScript",
   "dependencies": {
-    "express": "^4.21.1",
+    "express": "^5.1.0",
     "express-async-handler": "^1.2.0",
-    "ts-zod-decorators": "^1.7.1",
-    "utils-decorators": "^2.0.9",
-    "zod": "^3.23.8"
+    "utils-decorators": "^2.10.0",
+    "zod": "^4.0.14"
   },
   "devDependencies": {
-    "@types/express": "^5.0.0",
-    "@types/node": "^22.10.7",
-    "nodemon": "^3.1.7",
+    "@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",
-    "typescript": "^5.6.3"
+    "tsc-alias": "^1.8.16",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.2"
   }
 }

package/src/app.ts

@@ -1,9 +1,18 @@
-import express from "express";
+import express, {
+  ErrorRequestHandler,
+  NextFunction,
+  Request,
+  Response,
+} from "express";
 import fs from "fs";
 import path from "path";
 import config from "./config";
 
-// Function to load routers recursively
+/**
+ * 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
@@ -39,7 +48,11 @@ function loadRouters(routerPath: string, basePath: string = "") {
       // Exclude JavaScript test specification files
       file.endsWith(".spec.js") ||
       // Exclude TypeScript test specification files
-      file.endsWith(".spec.ts")
+      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;
@@ -85,6 +98,11 @@ if (config.devMode) {
   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}`);

package/src/config.ts

@@ -1,29 +1,62 @@
+/**
+ * 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[];
 }
 
+/**
+ * Main application configuration
+ * @interface
+ * @property {boolean} devMode - Development mode flag
+ * @property {string} port - Server port
+ * @property {SwaggerOptions} swaggerOptions - Swagger configuration
+ */
 interface Config {
   devMode: boolean;
   port: string;
   swaggerOptions: SwaggerOptions;
 }
+
 const port = process.env.PORT || "3000";
 const config: Config = {
   devMode: process.env.NODE_ENV !== "production",

package/src/packages/ts-zod-decorators/index.ts

@@ -0,0 +1,3 @@
+export * from './validate.decorator';
+export * from './zod-output.decorator';
+export * from './zod-input.decorator';

package/src/packages/ts-zod-decorators/validate.decorator.ts

@@ -0,0 +1,20 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import ZodValidator from './validator.class';
+
+export const Validate: MethodDecorator = (
+	target: Object,
+	propertyKey: string | symbol,
+	descriptor: PropertyDescriptor,
+) => {
+	const originalMethod = descriptor.value;
+	descriptor.value = async function (...args: unknown[]) {
+		ZodValidator.validateInput(target, propertyKey as string, args);
+		const result = originalMethod.apply(this, args);
+		let resultValue = result;
+		if (result instanceof Promise) {
+			resultValue = await result;
+			ZodValidator.validateOutput(target, propertyKey as string, resultValue);
+		}
+		return resultValue;
+	};
+};

package/src/packages/ts-zod-decorators/validator.class.ts

@@ -0,0 +1,72 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import * as z from "zod";
+
+type Target = Object;
+type MethodName = string;
+type Metadata = {
+  paramsIndex: number[];
+  inputSchema?: z.ZodObject<any, any>;
+  outputSchema?: z.ZodObject<any, any>;
+};
+
+export default class ZodValidator {
+  private static methodValidatorMap: Map<Target, Map<MethodName, Metadata>> =
+    new Map();
+
+  static registerInputParameterValidationSchema(
+    target: Object,
+    methodName: MethodName,
+    paramIndex: number,
+    schema: z.ZodObject<any, any>
+  ) {
+    let paramMap = this.methodValidatorMap.get(target)!;
+    if (!paramMap) {
+      paramMap = new Map();
+      this.methodValidatorMap.set(target, paramMap);
+    }
+    let metadata = paramMap.get(methodName)!;
+    if (!metadata) {
+      metadata = { paramsIndex: [], inputSchema: schema };
+      paramMap.set(methodName, metadata);
+    }
+    metadata.paramsIndex.push(paramIndex);
+  }
+
+  static registerMethodValidationOutputSchema(
+    target: Object,
+    methodName: MethodName,
+    schema: z.ZodObject<any, any>
+  ) {
+    let paramMap = this.methodValidatorMap.get(target)!;
+    if (!paramMap) {
+      paramMap = new Map();
+      this.methodValidatorMap.set(target, paramMap);
+    }
+    let metadata = paramMap.get(methodName)!;
+    if (!metadata) {
+      metadata = { paramsIndex: [], outputSchema: schema };
+      paramMap.set(methodName, metadata);
+    }
+    metadata.outputSchema = schema;
+  }
+
+  static validateInput(
+    target: Object,
+    methodName: string,
+    paramValues: unknown[]
+  ) {
+    const methodMetadataMap = this.methodValidatorMap.get(target)!;
+    const metadata = methodMetadataMap.get(methodName)!;
+    for (const [index, input] of paramValues.entries()) {
+      if (metadata.paramsIndex.indexOf(index) != -1) {
+        metadata.inputSchema?.parse(input);
+      }
+    }
+  }
+
+  static validateOutput(target: Object, methodName: string, output: unknown) {
+    const methodMetadataMap = this.methodValidatorMap.get(target)!;
+    const metadata = methodMetadataMap.get(methodName)!;
+    metadata.outputSchema?.parse(output);
+  }
+}

package/src/packages/ts-zod-decorators/zod-input.decorator.ts

@@ -0,0 +1,12 @@
+import { ZodObject } from "zod";
+import ZodValidator from "./validator.class";
+
+export const ZodInput =
+  <T extends ZodObject<any, any>>(schema: T): ParameterDecorator =>
+  (target, propertyKey, parameterIndex) =>
+    ZodValidator.registerInputParameterValidationSchema(
+      target,
+      propertyKey as string,
+      parameterIndex,
+      schema
+    );

package/src/packages/ts-zod-decorators/zod-output.decorator.ts

@@ -0,0 +1,11 @@
+import { ZodObject } from "zod";
+import ZodValidator from "./validator.class";
+
+export const ZodOutput =
+  <T extends ZodObject<any, any>>(schema: T): MethodDecorator =>
+  (target, propertyKey) =>
+    ZodValidator.registerMethodValidationOutputSchema(
+      target,
+      propertyKey as string,
+      schema
+    );

package/src/routers/index.ts

@@ -11,12 +11,12 @@ const router = Router();
  *     description: Returns the home page.
  *     responses:
  *       200:
- *         description: home page
+ *         description: Hi there!
  */
 router.get(
   "/",
   asyncHandler(async (req: Request, res: Response) => {
-    res.send("Home");
+    res.send("Hi there!");
   })
 );