codeweaver 1.0.15 → 2.0.0

package/.vscode/settings.json

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

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,63 +46,139 @@ To get started with the project, follow these steps:
 
    ```bash
    npm run build
+   npm run serve
    ```
 
 ## Sample Project Structure
 
 **/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`, 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:
 
 ```typescript
 import { Router, Request, Response } from "express";
 import asyncHandler from "express-async-handler";
+import UserController from "./user.controller";
 
 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 the home page
- *     description: Returns the home page.
+ *     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: home page
+ *         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);
+    res.json(user);
+  })
+);
+
+/**
+ * @swagger
+ * /users:
+ *   get:
+ *     summary: Get users
+ *     description: Returns a list of user objects.
+ *     responses:
+ *       200:
+ *         description: A list of user objects
  */
 router.get(
   "/",
   asyncHandler(async (req: Request, res: Response) => {
-    res.send("Home");
+    res.json(await userController.getAll());
   })
 );
 
@@ -131,13 +202,27 @@ 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(),
+  email: z.email(),
   password: z.string().min(6),
 });
 
-export type CreateUser = z.infer<typeof createUserDto>;
+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.
@@ -149,37 +234,157 @@ 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,
+  UserDto,
+} 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 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",
+  },
+];
 
 function exceedHandler() {
-  throw new Error("Too much call in allowed window");
+  const message = "Too much call in allowed window";
+  throw new ResponseError(message, 429);
 }
 
-function errorHandler(e: Error): void {
-  console.error(e);
+function getUserErrorHandler(e: Error) {
+  const message = "User not found.";
+  throw new ResponseError(message, 404, e.message);
 }
 
+/**
+ * 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,
+    timeSpanMs: config.rateLimitTimeSpan,
+    allowedCalls: config.rateLimitAllowedCalls,
     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 });
+  }
+
+  @memoizeAsync(config.memoizeTime)
   @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: 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
+   */
+  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;
+  }
+
+  @memoizeAsync(config.memoizeTime)
+  @timeout(config.timeout)
+  @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
+   */
+  public async getAll(): Promise<UserDto[]> {
+    return users.map((user) => ({
+      ...user,
+      password: "?",
+    }));
   }
 }
 ```

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "codeweaver",
-  "version": "1.0.15",
-  "main": "src/app.ts",
+  "version": "2.0.0",
+  "main": "src/main.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/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/main.js"
   },
   "keywords": [
     "codeweaver",
@@ -27,23 +28,28 @@
     "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",
+    "dotenv": "^17.2.3",
+    "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"
+    "swagger-jsdoc": "^3.7.0",
+    "ts-zod4-decorators": "^1.0.0",
+    "utils-decorators": "^2.10.0",
+    "zod": "^4.0.14"
   },
   "devDependencies": {
-    "@types/express": "^5.0.0",
-    "@types/node": "^22.10.7",
-    "nodemon": "^3.1.7",
-    "swagger-jsdoc": "^6.2.8",
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.1.0",
+    "copyfiles": "^2.4.1",
+    "cross-env": "^10.0.0",
+    "nodemon": "^3.1.10",
     "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/config.ts

@@ -1,32 +1,79 @@
+import {
+  memoizeTime,
+  productionEnvironment,
+  rateLimitTimeSpan,
+  rateLimitAllowedCalls,
+  timeout,
+  portNumber,
+} 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[];
 }
 
+/**
+ * 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;
+  port: number;
   swaggerOptions: SwaggerOptions;
+  timeout: number;
+  rateLimitTimeSpan: number;
+  rateLimitAllowedCalls: number;
+  memoizeTime: number;
 }
-const port = process.env.PORT || "3000";
-const config: Config = {
-  devMode: process.env.NODE_ENV !== "production",
+
+const port = Number(process.env.PORT) || portNumber;
+
+let config: Config = {
+  devMode: process.env.NODE_ENV !== productionEnvironment,
   port,
   swaggerOptions: {
     swaggerDefinition: {
@@ -49,17 +96,11 @@ const config: Config = {
       "./src/routers/**/*.js",
     ], // Path to the API docs
   },
+  timeout: Number(process.env.TIMEOUT) || timeout,
+  rateLimitTimeSpan: Number(process.env.RATE_LIMIT) || rateLimitTimeSpan,
+  rateLimitAllowedCalls:
+    Number(process.env.RATE_LIMIT) || rateLimitAllowedCalls,
+  memoizeTime: Number(process.env.MEMOIZE_TIME) || memoizeTime,
 };
 
-// Other configurations:
-//
-// config.jwt_key = config.devMode ? "" : "";
-// config.jwt_expiration = config.devMode ? 360000 : 360000;
-// config.dbConnectionString = config.devMode ? `mongoDb url` : `mongoDb url`;
-// config.mongoDebug = config.devMode;
-// config.port = config.devMode ? 3000 : 3000;
-// config.host = config.devMode ? "localhost" : "localhost";
-// config.env = config.devMode ? "development" : "production";
-// config.mongoUrl = config.devMode ? "mongodb://localhost:27017/test" : "mongodb://localhost:27017/test";
-
 export default config;

package/src/constants.ts

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

package/src/main.ts

@@ -0,0 +1,82 @@
+import express, { NextFunction, Request, Response } from "express";
+import fs from "fs";
+import path from "path";
+import config from "./config";
+
+/**
+ * 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 = "") {
+  // Read entries with their type info
+  const entries = fs.readdirSync(routerPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(routerPath, entry.name);
+
+    if (entry.isDirectory()) {
+      // Recurse into subdirectories
+      const subRoutePath = path
+        .join(basePath, entry.name)
+        .replace(/\\/g, "/")
+        .replace(/\/?index$/g, "");
+      loadRouters(fullPath, subRoutePath);
+      continue;
+    }
+
+    // Only handle router files
+    if (
+      !entry.name.endsWith(".router.ts") &&
+      !entry.name.endsWith(".router.js")
+    ) {
+      continue;
+    }
+
+    // Build route path safely
+    const routePath = path
+      .join(basePath, entry.name.replace(/\.router\.[tj]s$/, ""))
+      .replace(/\\/g, "/")
+      .replace(/\/?index$/g, "");
+
+    // Optional: skip if the target path would be empty (maps to /)
+    const mountPath = "/" + (routePath || "");
+
+    // Import and mount
+    const router = require(fullPath);
+    app.use(mountPath, router);
+    console.log(`Mounted ${entry.name} at ${mountPath}`);
+  }
+}
+
+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`
+    );
+});

package/src/routers/{index.ts → index.router.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!");
   })
 );