deco-express 0.1.0

package/.prettierignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 80,
+  "tabWidth": 2
+}

package/README.md

@@ -0,0 +1,174 @@
+# deco-express
+
+> Decorator-based utilities for building Express.js REST APIs in TypeScript.
+
+`deco-express` reduces boilerplate when building Express applications by providing a small set of TypeScript decorators for defining controllers, routes, and request validation.
+
+---
+
+## Installation
+
+```bash
+npm install deco-express reflect-metadata
+```
+
+> `reflect-metadata` is a required peer dependency. Import it **once** at the entry point of your application before using any decorators.
+
+```ts
+// src/main.ts
+import "reflect-metadata";
+```
+
+Also ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+---
+
+## Quick Start
+
+```ts
+import "reflect-metadata";
+import express from "express";
+import Joi from "joi";
+import { Controller, Route, Validate, defineRoutes } from "deco-express";
+
+const createUserSchema = Joi.object({
+  name: Joi.string().required(),
+  email: Joi.string().email().required(),
+});
+
+@Controller("/users")
+class UserController {
+  @Route("get", "/list")
+  async list(req, res) {
+    res.json({ users: [] });
+  }
+
+  @Validate(createUserSchema)
+  @Route("post", "/create")
+  async create(req, res) {
+    res.status(201).json({ created: req.body });
+  }
+}
+
+const app = express();
+app.use(express.json());
+
+defineRoutes([UserController], app);
+// Registers:
+//   GET  /api/v1/users/list
+//   POST /api/v1/users/create
+
+app.listen(3000);
+```
+
+---
+
+## API Reference
+
+### `@Controller(baseRoute?)`
+
+Class decorator. Marks a class as a route controller and sets its base path.
+
+| Parameter   | Type     | Default | Description                     |
+| ----------- | -------- | ------- | ------------------------------- |
+| `baseRoute` | `string` | `''`    | Base path prefix for all routes |
+
+```ts
+@Controller('/products')
+class ProductController { ... }
+```
+
+---
+
+### `@Route(method, path?, ...middleware)`
+
+Method decorator. Maps a class method to an HTTP route.
+
+| Parameter    | Type               | Default | Description                          |
+| ------------ | ------------------ | ------- | ------------------------------------ |
+| `method`     | `keyof Express`    | —       | HTTP method (`get`, `post`, etc.)    |
+| `path`       | `string`           | `''`    | Route path (appended to base route)  |
+| `middleware` | `RequestHandler[]` | `[]`    | Optional Express middleware to apply |
+
+```ts
+@Route('get', '/list', authMiddleware)
+async list(req, res) { ... }
+```
+
+---
+
+### `@Validate(schema)`
+
+Method decorator. Validates `req.body` against a Joi schema before the handler runs.
+Returns `422 Unprocessable Entity` on validation failure with structured error details.
+
+| Parameter | Type         | Description                    |
+| --------- | ------------ | ------------------------------ |
+| `schema`  | `Joi.Schema` | Joi schema to validate against |
+
+```ts
+@Validate(Joi.object({ name: Joi.string().required() }))
+@Route('post', '/create')
+async create(req, res) { ... }
+```
+
+**Error response format (422):**
+
+```json
+{
+  "message": "Validation failed",
+  "details": [{ "field": "name", "message": "\"name\" is required" }]
+}
+```
+
+---
+
+### `defineRoutes(controllers, app, addApi?, version?)`
+
+Registers all decorated controller routes to an Express application.
+
+| Parameter     | Type            | Default | Description                            |
+| ------------- | --------------- | ------- | -------------------------------------- |
+| `controllers` | `Constructor[]` | —       | Array of controller class constructors |
+| `app`         | `Express`       | —       | Express application instance           |
+| `addApi`      | `boolean`       | `true`  | Prepend `/api` to all routes           |
+| `version`     | `number`        | `1`     | API version number (e.g. `/v1`)        |
+
+```ts
+defineRoutes([UserController, ProductController], app, true, 2);
+// Routes become: /api/v2/...
+
+defineRoutes([UserController], app, false);
+// Routes become: /users/...
+```
+
+---
+
+## Route Path Construction
+
+The final route path is built as:
+
+```
+/{api}/{version}/{baseRoute}/{path}
+```
+
+| `addApi` | `version` | Result prefix |
+| -------- | --------- | ------------- |
+| `true`   | `1`       | `/api/v1`     |
+| `true`   | `2`       | `/api/v2`     |
+| `false`  | any       | (no prefix)   |
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,135 @@
+import { Express, RequestHandler } from 'express';
+import Joi from 'joi';
+
+/**
+ * Method decorator that registers a route handler on the enclosing controller.
+ *
+ * The decorator stores the handler (and any preceding middleware) in
+ * `reflect-metadata` under the `"routeHandlers"` key so that
+ * {@link defineRoutes} can later mount them on an Express application.
+ *
+ * @param method - The HTTP method to register (must be a valid method key on
+ *   the Express application, e.g. `"get"`, `"post"`, `"put"`, `"delete"`).
+ * @param path - The route path relative to the controller's base route.
+ *   Defaults to `""` (i.e. the controller root).
+ * @param middleware - Zero or more Express middleware functions that are
+ *   executed **before** the decorated handler.
+ *
+ * @example
+ * ```ts
+ * class UserController {
+ *   \@Route('get', '/:id', authMiddleware)
+ *   getUser(req: Request, res: Response) {
+ *     res.json({ id: req.params.id });
+ *   }
+ * }
+ * ```
+ */
+declare function Route(method: keyof Express, path?: string, ...middleware: RequestHandler[]): (target: object, _key: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Class decorator that marks a class as an Express controller and sets its
+ * base route prefix.
+ *
+ * The base route is stored in `reflect-metadata` under the `"baseRoute"` key
+ * and is prepended to every route path registered by {@link Route} decorators
+ * on the class's methods.
+ *
+ * @param baseRoute - The base path prefix for all routes in the controller
+ *   (e.g. `"/users"`). Defaults to `""` (no prefix).
+ *
+ * @example
+ * ```ts
+ * \@Controller('/users')
+ * class UserController {
+ *   \@Route('get', '/:id')
+ *   getUser(req: Request, res: Response) { ... }
+ * }
+ * ```
+ */
+declare function Controller(baseRoute?: string): (target: object) => void;
+
+/**
+ * Method decorator that validates `req.body` against a Joi schema before the
+ * decorated handler is invoked.
+ *
+ * When validation fails the decorator short-circuits the request and responds
+ * with HTTP **422 Unprocessable Entity** and a structured error body:
+ *
+ * ```json
+ * {
+ *   "message": "Validation failed",
+ *   "details": [{ "field": "email", "message": "\"email\" must be a valid email" }]
+ * }
+ * ```
+ *
+ * Any non-validation error thrown by Joi is forwarded to the next Express
+ * error handler via `next(error)`.
+ *
+ * @param schema - A Joi schema used to validate `req.body`.
+ *
+ * @example
+ * ```ts
+ * const createUserSchema = Joi.object({ email: Joi.string().email().required() });
+ *
+ * class UserController {
+ *   \@Route('post', '/')
+ *   \@Validate(createUserSchema)
+ *   createUser(req: Request, res: Response) {
+ *     res.status(201).json({ email: req.body.email });
+ *   }
+ * }
+ * ```
+ */
+declare function Validate(schema: Joi.Schema): (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+
+/** Any class constructor that produces instances of type `T`. */
+type Constructor<T = object> = new (...args: unknown[]) => T;
+/**
+ * Registers routes from one or more controller classes onto an Express
+ * application.
+ *
+ * For each controller the function:
+ * 1. Instantiates the class with `new`.
+ * 2. Reads the `"baseRoute"` metadata set by {@link Controller}.
+ * 3. Reads the `"routeHandlers"` metadata set by {@link Route}.
+ * 4. Mounts each handler at the resolved full path on the Express app.
+ *
+ * The full path is built as:
+ * ```
+ * [/api][/v{version}]{baseRoute}{routePath}
+ * ```
+ *
+ * @param controllers - Array of controller class constructors to register.
+ * @param application - The Express application instance to mount routes on.
+ * @param addApi - When `true` (default), prepends `/api` to every route.
+ * @param version - API version number. When `addApi` is `true` and `version`
+ *   is non-zero, a `/v{version}` segment is inserted after `/api`.
+ *   Defaults to `1`.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { defineRoutes } from 'deco-express';
+ * import { UserController } from './controllers/user';
+ *
+ * const app = express();
+ * defineRoutes([UserController], app);
+ * // Routes are now available at /api/v1/...
+ * ```
+ */
+declare function defineRoutes(controllers: Constructor[], application: Express, addApi?: boolean, version?: number): void;
+
+/**
+ * A nested map that stores route handlers organised by HTTP method and path.
+ *
+ * Outer key – an HTTP method name that exists on the Express application
+ * (e.g. `"get"`, `"post"`, `"put"`, `"delete"`).
+ *
+ * Inner key – the route path string (e.g. `"/users/:id"`).
+ *
+ * Inner value – an ordered array of Express `RequestHandler` functions,
+ * where middleware precedes the actual route handler.
+ */
+type RouteHandlers = Map<keyof Express, Map<string, RequestHandler[]>>;
+
+export { Controller, Route, type RouteHandlers, Validate, defineRoutes };

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+import { Express, RequestHandler } from 'express';
+import Joi from 'joi';
+
+/**
+ * Method decorator that registers a route handler on the enclosing controller.
+ *
+ * The decorator stores the handler (and any preceding middleware) in
+ * `reflect-metadata` under the `"routeHandlers"` key so that
+ * {@link defineRoutes} can later mount them on an Express application.
+ *
+ * @param method - The HTTP method to register (must be a valid method key on
+ *   the Express application, e.g. `"get"`, `"post"`, `"put"`, `"delete"`).
+ * @param path - The route path relative to the controller's base route.
+ *   Defaults to `""` (i.e. the controller root).
+ * @param middleware - Zero or more Express middleware functions that are
+ *   executed **before** the decorated handler.
+ *
+ * @example
+ * ```ts
+ * class UserController {
+ *   \@Route('get', '/:id', authMiddleware)
+ *   getUser(req: Request, res: Response) {
+ *     res.json({ id: req.params.id });
+ *   }
+ * }
+ * ```
+ */
+declare function Route(method: keyof Express, path?: string, ...middleware: RequestHandler[]): (target: object, _key: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Class decorator that marks a class as an Express controller and sets its
+ * base route prefix.
+ *
+ * The base route is stored in `reflect-metadata` under the `"baseRoute"` key
+ * and is prepended to every route path registered by {@link Route} decorators
+ * on the class's methods.
+ *
+ * @param baseRoute - The base path prefix for all routes in the controller
+ *   (e.g. `"/users"`). Defaults to `""` (no prefix).
+ *
+ * @example
+ * ```ts
+ * \@Controller('/users')
+ * class UserController {
+ *   \@Route('get', '/:id')
+ *   getUser(req: Request, res: Response) { ... }
+ * }
+ * ```
+ */
+declare function Controller(baseRoute?: string): (target: object) => void;
+
+/**
+ * Method decorator that validates `req.body` against a Joi schema before the
+ * decorated handler is invoked.
+ *
+ * When validation fails the decorator short-circuits the request and responds
+ * with HTTP **422 Unprocessable Entity** and a structured error body:
+ *
+ * ```json
+ * {
+ *   "message": "Validation failed",
+ *   "details": [{ "field": "email", "message": "\"email\" must be a valid email" }]
+ * }
+ * ```
+ *
+ * Any non-validation error thrown by Joi is forwarded to the next Express
+ * error handler via `next(error)`.
+ *
+ * @param schema - A Joi schema used to validate `req.body`.
+ *
+ * @example
+ * ```ts
+ * const createUserSchema = Joi.object({ email: Joi.string().email().required() });
+ *
+ * class UserController {
+ *   \@Route('post', '/')
+ *   \@Validate(createUserSchema)
+ *   createUser(req: Request, res: Response) {
+ *     res.status(201).json({ email: req.body.email });
+ *   }
+ * }
+ * ```
+ */
+declare function Validate(schema: Joi.Schema): (_target: object, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+
+/** Any class constructor that produces instances of type `T`. */
+type Constructor<T = object> = new (...args: unknown[]) => T;
+/**
+ * Registers routes from one or more controller classes onto an Express
+ * application.
+ *
+ * For each controller the function:
+ * 1. Instantiates the class with `new`.
+ * 2. Reads the `"baseRoute"` metadata set by {@link Controller}.
+ * 3. Reads the `"routeHandlers"` metadata set by {@link Route}.
+ * 4. Mounts each handler at the resolved full path on the Express app.
+ *
+ * The full path is built as:
+ * ```
+ * [/api][/v{version}]{baseRoute}{routePath}
+ * ```
+ *
+ * @param controllers - Array of controller class constructors to register.
+ * @param application - The Express application instance to mount routes on.
+ * @param addApi - When `true` (default), prepends `/api` to every route.
+ * @param version - API version number. When `addApi` is `true` and `version`
+ *   is non-zero, a `/v{version}` segment is inserted after `/api`.
+ *   Defaults to `1`.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { defineRoutes } from 'deco-express';
+ * import { UserController } from './controllers/user';
+ *
+ * const app = express();
+ * defineRoutes([UserController], app);
+ * // Routes are now available at /api/v1/...
+ * ```
+ */
+declare function defineRoutes(controllers: Constructor[], application: Express, addApi?: boolean, version?: number): void;
+
+/**
+ * A nested map that stores route handlers organised by HTTP method and path.
+ *
+ * Outer key – an HTTP method name that exists on the Express application
+ * (e.g. `"get"`, `"post"`, `"put"`, `"delete"`).
+ *
+ * Inner key – the route path string (e.g. `"/users/:id"`).
+ *
+ * Inner value – an ordered array of Express `RequestHandler` functions,
+ * where middleware precedes the actual route handler.
+ */
+type RouteHandlers = Map<keyof Express, Map<string, RequestHandler[]>>;
+
+export { Controller, Route, type RouteHandlers, Validate, defineRoutes };

package/dist/index.js

@@ -0,0 +1,114 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Controller: () => Controller,
+  Route: () => Route,
+  Validate: () => Validate,
+  defineRoutes: () => defineRoutes
+});
+module.exports = __toCommonJS(index_exports);
+var import_reflect_metadata = require("reflect-metadata");
+
+// src/decorators/express.ts
+function Route(method, path = "", ...middleware) {
+  return (target, _key, descriptor) => {
+    const routeHandlers = Reflect.getMetadata("routeHandlers", target) || /* @__PURE__ */ new Map();
+    if (!routeHandlers.has(method)) {
+      routeHandlers.set(method, /* @__PURE__ */ new Map());
+    }
+    routeHandlers.get(method)?.set(path, [...middleware, descriptor.value]);
+    Reflect.defineMetadata("routeHandlers", routeHandlers, target);
+  };
+}
+__name(Route, "Route");
+function Controller(baseRoute = "") {
+  return (target) => {
+    Reflect.defineMetadata("baseRoute", baseRoute, target);
+  };
+}
+__name(Controller, "Controller");
+
+// src/decorators/validation.ts
+var import_joi = __toESM(require("joi"));
+function Validate(schema) {
+  return function(_target, _propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    descriptor.value = async function(req, res, next) {
+      try {
+        await schema.validateAsync(req.body);
+      } catch (error) {
+        if (error instanceof import_joi.default.ValidationError) {
+          return res.status(422).json({
+            message: "Validation failed",
+            details: error.details.map((d) => ({
+              field: d.path.join("."),
+              message: d.message
+            }))
+          });
+        }
+        return next(error);
+      }
+      return originalMethod.call(this, req, res, next);
+    };
+    return descriptor;
+  };
+}
+__name(Validate, "Validate");
+
+// src/functions/routes.ts
+function defineRoutes(controllers, application, addApi = true, version = 1) {
+  for (const ControllerClass of controllers) {
+    const controller = new ControllerClass();
+    const routeHandlers = Reflect.getMetadata(
+      "routeHandlers",
+      controller
+    );
+    const controllerPath = Reflect.getMetadata("baseRoute", controller.constructor) ?? "";
+    if (!routeHandlers) continue;
+    for (const [method, routes] of routeHandlers) {
+      for (const [routePath, handlers] of routes) {
+        const versionSegment = addApi && version ? `/v${version}` : "";
+        const fullPath = `${addApi ? "/api" : ""}${versionSegment}${controllerPath}${routePath}`;
+        application[method](fullPath, handlers);
+      }
+    }
+  }
+}
+__name(defineRoutes, "defineRoutes");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Controller,
+  Route,
+  Validate,
+  defineRoutes
+});

package/dist/index.mjs

@@ -0,0 +1,78 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import "reflect-metadata";
+
+// src/decorators/express.ts
+function Route(method, path = "", ...middleware) {
+  return (target, _key, descriptor) => {
+    const routeHandlers = Reflect.getMetadata("routeHandlers", target) || /* @__PURE__ */ new Map();
+    if (!routeHandlers.has(method)) {
+      routeHandlers.set(method, /* @__PURE__ */ new Map());
+    }
+    routeHandlers.get(method)?.set(path, [...middleware, descriptor.value]);
+    Reflect.defineMetadata("routeHandlers", routeHandlers, target);
+  };
+}
+__name(Route, "Route");
+function Controller(baseRoute = "") {
+  return (target) => {
+    Reflect.defineMetadata("baseRoute", baseRoute, target);
+  };
+}
+__name(Controller, "Controller");
+
+// src/decorators/validation.ts
+import Joi from "joi";
+function Validate(schema) {
+  return function(_target, _propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    descriptor.value = async function(req, res, next) {
+      try {
+        await schema.validateAsync(req.body);
+      } catch (error) {
+        if (error instanceof Joi.ValidationError) {
+          return res.status(422).json({
+            message: "Validation failed",
+            details: error.details.map((d) => ({
+              field: d.path.join("."),
+              message: d.message
+            }))
+          });
+        }
+        return next(error);
+      }
+      return originalMethod.call(this, req, res, next);
+    };
+    return descriptor;
+  };
+}
+__name(Validate, "Validate");
+
+// src/functions/routes.ts
+function defineRoutes(controllers, application, addApi = true, version = 1) {
+  for (const ControllerClass of controllers) {
+    const controller = new ControllerClass();
+    const routeHandlers = Reflect.getMetadata(
+      "routeHandlers",
+      controller
+    );
+    const controllerPath = Reflect.getMetadata("baseRoute", controller.constructor) ?? "";
+    if (!routeHandlers) continue;
+    for (const [method, routes] of routeHandlers) {
+      for (const [routePath, handlers] of routes) {
+        const versionSegment = addApi && version ? `/v${version}` : "";
+        const fullPath = `${addApi ? "/api" : ""}${versionSegment}${controllerPath}${routePath}`;
+        application[method](fullPath, handlers);
+      }
+    }
+  }
+}
+__name(defineRoutes, "defineRoutes");
+export {
+  Controller,
+  Route,
+  Validate,
+  defineRoutes
+};

package/eslint.config.mjs

@@ -0,0 +1,33 @@
+import js from "@eslint/js";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import prettierConfig from "eslint-config-prettier";
+
+export default [
+  js.configs.recommended,
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+    },
+    rules: {
+      ...tsPlugin.configs.recommended.rules,
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" },
+      ],
+    },
+  },
+  prettierConfig,
+  {
+    ignores: ["dist/**", "node_modules/**"],
+  },
+];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "deco-express",
+  "version": "0.1.0",
+  "author": "ndrolp",
+  "description": "Decorator-based utilities for building Express.js REST APIs in TypeScript",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src"
+  },
+  "keywords": [
+    "express",
+    "typescript",
+    "decorators",
+    "rest",
+    "api",
+    "controller",
+    "routing",
+    "joi",
+    "validation"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.1",
+    "@types/node": "^22.15.17",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "dependencies": {
+    "express": "^5.1.0",
+    "joi": "^17.13.3",
+    "reflect-metadata": "^0.2.2"
+  }
+}