feat: init

packages/decorators/.eslintignore

@@ -0,0 +1,4 @@
+node_modules
+build/*
+dist/*
+out/*

packages/decorators/.eslintrc.js

@@ -0,0 +1,4 @@
+module.exports = {
+  root: true,
+  extends: ["@plane/eslint-config/library.js"],
+};

packages/decorators/.prettierignore

@@ -0,0 +1,2 @@
+# Ignore generated build artifacts
+dist/

packages/decorators/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}

packages/decorators/README.md

@@ -0,0 +1,95 @@
+# @plane/decorators
+
+A lightweight TypeScript decorator library for building Express.js controllers with a clean, declarative syntax.
+
+## Features
+
+- TypeScript-first design
+- Decorators for HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- WebSocket support
+- Middleware support
+- No build step required - works directly with TypeScript files
+
+## Installation
+
+This package is part of the Plane workspace and can be used by adding it to your project's dependencies:
+
+```json
+{
+  "dependencies": {
+    "@plane/decorators": "workspace:*"
+  }
+}
+```
+
+## Usage
+
+### Basic REST Controller
+
+```typescript
+import { Controller, Get, Post, BaseController } from "@plane/decorators";
+import { Router, Request, Response } from "express";
+
+@Controller("/api/users")
+class UserController extends BaseController {
+  @Get("/")
+  async getUsers(req: Request, res: Response) {
+    return res.json({ users: [] });
+  }
+
+  @Post("/")
+  async createUser(req: Request, res: Response) {
+    return res.json({ success: true });
+  }
+}
+
+// Register routes
+const router = Router();
+const userController = new UserController();
+userController.registerRoutes(router);
+```
+
+### WebSocket Controller
+
+```typescript
+import { Controller, WebSocket, BaseWebSocketController } from "@plane/decorators";
+import { Request } from "express";
+import { WebSocket as WS } from "ws";
+
+@Controller("/ws/chat")
+class ChatController extends BaseWebSocketController {
+  @WebSocket("/")
+  handleConnection(ws: WS, req: Request) {
+    ws.on("message", (message) => {
+      ws.send(`Received: ${message}`);
+    });
+  }
+}
+
+// Register WebSocket routes
+const router = require("express-ws")(app).router;
+const chatController = new ChatController();
+chatController.registerWebSocketRoutes(router);
+```
+
+## API Reference
+
+### Decorators
+
+- `@Controller(baseRoute: string)` - Class decorator for defining a base route
+- `@Get(route: string)` - Method decorator for HTTP GET endpoints
+- `@Post(route: string)` - Method decorator for HTTP POST endpoints
+- `@Put(route: string)` - Method decorator for HTTP PUT endpoints
+- `@Patch(route: string)` - Method decorator for HTTP PATCH endpoints
+- `@Delete(route: string)` - Method decorator for HTTP DELETE endpoints
+- `@WebSocket(route: string)` - Method decorator for WebSocket endpoints
+- `@Middleware(middleware: RequestHandler)` - Method decorator for applying middleware
+
+### Classes
+
+- `BaseController` - Base class for REST controllers
+- `BaseWebSocketController` - Base class for WebSocket controllers
+
+## License
+
+This project is licensed under the [GNU Affero General Public License v3.0](https://github.com/makeplane/plane/blob/master/LICENSE.txt).

packages/decorators/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@plane/decorators",
+  "version": "0.1.0",
+  "description": "Controller and route decorators for Express.js applications",
+  "license": "AGPL-3.0",
+  "private": true,
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check:lint": "eslint . --max-warnings 2",
+    "check:types": "tsc --noEmit",
+    "check:format": "prettier --check \"**/*.{ts,tsx,md,json,css,scss}\"",
+    "fix:lint": "eslint . --fix",
+    "fix:format": "prettier --write \"**/*.{ts,tsx,md,json,css,scss}\"",
+    "clean": "rm -rf .turbo && rm -rf .next && rm -rf node_modules && rm -rf dist"
+  },
+  "devDependencies": {
+    "@plane/eslint-config": "workspace:*",
+    "@plane/typescript-config": "workspace:*",
+    "@types/express": "^4.17.21",
+    "@types/node": "catalog:",
+    "@types/ws": "^8.5.10",
+    "reflect-metadata": "^0.2.2",
+    "tsdown": "catalog:",
+    "typescript": "catalog:"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts"
+}

packages/decorators/src/controller.ts

@@ -0,0 +1,102 @@
+import type { RequestHandler, Router, Request } from "express";
+import type { WebSocket } from "ws";
+
+import "reflect-metadata";
+
+export type HttpMethod = "get" | "post" | "put" | "delete" | "patch" | "options" | "head" | "ws";
+
+type ControllerInstance = {
+  [key: string]: any;
+};
+
+export type ControllerConstructor = {
+  new (...args: any[]): ControllerInstance;
+  prototype: ControllerInstance;
+};
+
+export function registerController(
+  router: Router,
+  Controller: ControllerConstructor,
+  dependencies: unknown[] = []
+): void {
+  // Create the controller instance with dependencies
+  const instance = new Controller(...dependencies);
+
+  // Determine if it's a WebSocket controller or REST controller by checking
+  // if it has any methods with the "ws" method metadata
+  const isWebsocket = Object.getOwnPropertyNames(Controller.prototype).some((methodName) => {
+    if (methodName === "constructor") return false;
+    return Reflect.getMetadata("method", instance, methodName) === "ws";
+  });
+
+  if (isWebsocket) {
+    // Register as WebSocket controller
+    // Pass the existing instance with dependencies to avoid creating a new instance without them
+    registerWebSocketController(router, Controller, instance);
+  } else {
+    // Register as REST controller with the existing instance
+    registerRestController(router, Controller, instance);
+  }
+}
+
+function registerRestController(
+  router: Router,
+  Controller: ControllerConstructor,
+  existingInstance?: ControllerInstance
+): void {
+  const instance = existingInstance || new Controller();
+  const baseRoute = Reflect.getMetadata("baseRoute", Controller) as string;
+
+  Object.getOwnPropertyNames(Controller.prototype).forEach((methodName) => {
+    if (methodName === "constructor") return; // Skip the constructor
+
+    const method = Reflect.getMetadata("method", instance, methodName) as HttpMethod;
+    const route = Reflect.getMetadata("route", instance, methodName) as string;
+    const middlewares = (Reflect.getMetadata("middlewares", instance, methodName) as RequestHandler[]) || [];
+
+    if (method && route) {
+      const handler = instance[methodName] as unknown;
+
+      if (typeof handler === "function") {
+        if (method !== "ws") {
+          (router[method] as (path: string, ...handlers: RequestHandler[]) => void)(
+            `${baseRoute}${route}`,
+            ...middlewares,
+            handler.bind(instance)
+          );
+        }
+      }
+    }
+  });
+}
+
+function registerWebSocketController(
+  router: Router,
+  Controller: ControllerConstructor,
+  existingInstance?: ControllerInstance
+): void {
+  const instance = existingInstance || new Controller();
+  const baseRoute = Reflect.getMetadata("baseRoute", Controller) as string;
+
+  Object.getOwnPropertyNames(Controller.prototype).forEach((methodName) => {
+    if (methodName === "constructor") return; // Skip the constructor
+
+    const method = Reflect.getMetadata("method", instance, methodName) as string;
+    const route = Reflect.getMetadata("route", instance, methodName) as string;
+
+    if (method === "ws" && route) {
+      const handler = instance[methodName] as unknown;
+
+      if (typeof handler === "function" && "ws" in router && typeof router.ws === "function") {
+        router.ws(`${baseRoute}${route}`, (ws: WebSocket, req: Request) => {
+          try {
+            handler.call(instance, ws, req);
+          } catch (error) {
+            console.error(`WebSocket error in ${Controller.name}.${methodName}`, error);
+            ws.close(1011, error instanceof Error ? error.message : "Internal server error");
+          }
+        });
+      }
+    }
+  });
+}

packages/decorators/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./controller";
+export * from "./rest";
+export * from "./websocket";

packages/decorators/src/rest.ts

@@ -0,0 +1,51 @@
+import "reflect-metadata";
+import { RequestHandler } from "express";
+
+// Define valid HTTP methods
+type RestMethod = "get" | "post" | "put" | "patch" | "delete";
+
+/**
+ * Controller decorator
+ * @param baseRoute
+ * @returns
+ */
+export function Controller(baseRoute: string = ""): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return function (target: Function) {
+    Reflect.defineMetadata("baseRoute", baseRoute, target);
+  };
+}
+
+/**
+ * Factory function to create HTTP method decorators
+ * @param method HTTP method to handle
+ * @returns Method decorator
+ */
+function createHttpMethodDecorator(method: RestMethod): (route: string) => MethodDecorator {
+  return function (route: string): MethodDecorator {
+    return function (target: object, propertyKey: string | symbol) {
+      Reflect.defineMetadata("method", method, target, propertyKey);
+      Reflect.defineMetadata("route", route, target, propertyKey);
+    };
+  };
+}
+
+// Export HTTP method decorators using the factory
+export const Get = createHttpMethodDecorator("get");
+export const Post = createHttpMethodDecorator("post");
+export const Put = createHttpMethodDecorator("put");
+export const Patch = createHttpMethodDecorator("patch");
+export const Delete = createHttpMethodDecorator("delete");
+
+/**
+ * Middleware decorator
+ * @param middleware
+ * @returns
+ */
+export function Middleware(middleware: RequestHandler): MethodDecorator {
+  return function (target: object, propertyKey: string | symbol) {
+    const middlewares = Reflect.getMetadata("middlewares", target, propertyKey) || [];
+    middlewares.push(middleware);
+    Reflect.defineMetadata("middlewares", middlewares, target, propertyKey);
+  };
+}

packages/decorators/src/websocket.ts

@@ -0,0 +1,13 @@
+import "reflect-metadata";
+
+/**
+ * WebSocket method decorator
+ * @param route
+ * @returns
+ */
+export function WebSocket(route: string): MethodDecorator {
+  return function (target: object, propertyKey: string | symbol) {
+    Reflect.defineMetadata("method", "ws", target, propertyKey);
+    Reflect.defineMetadata("route", route, target, propertyKey);
+  };
+}

packages/decorators/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "@plane/typescript-config/node-library.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "lib": ["ES2020"],
+    "rootDir": ".",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["./src", "./*.ts"],
+  "exclude": ["dist", "build", "node_modules"]
+}

packages/decorators/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  outDir: "dist",
+  format: ["esm", "cjs"],
+  exports: true,
+  dts: true,
+  clean: true,
+  sourcemap: false,
+});