@synchjs/ewb 1.0.0

package/README.md

@@ -0,0 +1,292 @@
+# @synchjs/ewb
+
+A robust, decorator-based web server framework built on top of **Express** and optimized for **Bun**. It provides a structured way to build scalable APIs with built-in support for **OpenAPI (Swagger)**, **Validation**, **Authentication**, and **Frontend Asset Serving** (with Tailwind CSS support).
+
+## Features
+
+- 🏗 **Decorator-based Routing**: Define controllers and routes using concise decorators (`@Controller`, `@Get`, `@Post`).
+- 🔒 **Built-in Authentication**: Easy-to-use Bearer Token authentication (`@BearerAuth`).
+- 📜 **Auto-generated Swagger Docs**: Your API documentation is generated automatically from your code.
+- ✅ **Request Validation**: Schema-based validation using AJV.
+- 🎨 **Frontend Serving**: Serve HTML/CSS/JS assets from memory, with built-in **Tailwind CSS** processing via Bun plugins.
+- 🧩 **Dependency Injection**: Support for IoC containers.
+- 🚀 **Bun Optimized**: Leverages Bun's build capabilities for static assets.
+- 🖥 **TUI-style Logs**: Clean and informative startup messages.
+
+## Installation
+
+```bash
+bun add @synchjs/ewb
+```
+
+## Quick Start
+
+### 1. Create a Controller
+
+Create a file `controllers/HomeController.ts`:
+
+```typescript
+import { Controller, Get } from "ewb";
+import type { Request, Response } from "express";
+
+@Controller("/")
+export class HomeController {
+  @Get("/", {
+    summary: "Welcome endpoint",
+    description: "Returns a welcome message.",
+  })
+  public index(req: Request, res: Response) {
+    return { message: "Hello from @synchjs/ewb!" };
+  }
+}
+```
+
+### 2. Start the Server
+
+Create `index.ts`:
+
+```typescript
+import { Server } from "ewb";
+
+const server = new Server({
+  id: "main",
+  port: 3000,
+  controllersDir: "controllers", // Directory where your controllers are located
+  enableSwagger: true, // Enable Swagger UI at /api-docs
+});
+
+server.init();
+```
+
+Run with Bun:
+
+```bash
+bun run index.ts
+```
+
+### 3. Customize Swagger Path
+
+You can change where Swagger UI is served:
+
+```typescript
+const server = new Server({
+  id: "main",
+  port: 3000,
+  enableSwagger: true,
+  swaggerPath: "/docs", // Now available at http://localhost:3000/docs
+});
+```
+
+## Detailed Usage
+
+### Controllers & Routing
+
+Use `@Controller` to define a base path and HTTP method decorators for routes.
+
+```typescript
+import { Controller, Get, Post, Put, Delete } from "ewb";
+import type { Request, Response } from "express";
+
+@Controller("/users", { tags: ["Users"] })
+export class UserController {
+  @Get("/:id")
+  public getUser(req: Request, res: Response) {
+    const { id } = req.params;
+    return { id, name: "User " + id };
+  }
+
+  @Post("/", {
+    summary: "Create User",
+    responses: {
+      201: { description: "User created" },
+    },
+  })
+  public createUser(req: Request, res: Response) {
+    // Logic to create user
+    return { id: 1, ...req.body };
+  }
+}
+```
+
+### Authentication
+
+Secure your endpoints using `@BearerAuth`. It integrates with JWT verification automatically.
+
+- **Class Level:** Protects all routes in the controller.
+- **Method Level:** Protects specific routes.
+- **@Public():** Excludes a route from class-level auth.
+
+```typescript
+import { Controller, Get, BearerAuth, Public } from "ewb";
+
+@Controller("/secure")
+@BearerAuth("my_secret_key") // Optional: Custom secret, defaults to process.env.JWT_SECRET
+export class SecureController {
+  @Get("/dashboard")
+  public dashboard(req: Request, res: Response) {
+    // Access user data attached by middleware (req.user)
+    const user = (req as any).user;
+    return { message: "Secret data", user };
+  }
+
+  @Get("/status")
+  @Public() // Accessible without token
+  public status(req: Request, res: Response) {
+    return { status: "OK" };
+  }
+}
+```
+
+#### Advanced Security (@Security, @OAuth, @ApiKey)
+
+For other authentication methods like OAuth2 or API Keys, use generic decorators:
+
+```typescript
+import { Controller, Get, OAuth, ApiKey } from "ewb";
+
+@Controller("/api")
+export class ApiController {
+  @Get("/profile")
+  @OAuth(["read:profile"]) // Marks route as requiring OAuth2 with specific scope
+  public getProfile() {
+    return { name: "John Doe" };
+  }
+
+  @Get("/data")
+  @ApiKey("X-API-KEY") // Custom security scheme name
+  public getData() {
+    return { sensitive: "data" };
+  }
+}
+```
+
+**Configure Handlers and Schemes:**
+
+```typescript
+const server = new Server({
+  // ...,
+  securitySchemes: {
+    oauth2: {
+      type: "oauth2",
+      flows: {
+        /* ... standard OpenAPI flow definition ... */
+      },
+    },
+  },
+  securityHandlers: {
+    oauth2: (req, res, next) => {
+      // Your OAuth validation logic here
+      next();
+    },
+  },
+});
+```
+
+### Request Validation
+
+Define a JSON schema in the `@Post` (or other method) decorator to automatically validate the request body using AJV.
+
+```typescript
+@Post("/register", {
+  summary: "Register new user",
+  requestBody: {
+    content: {
+      "application/json": {
+        schema: {
+          type: "object",
+          properties: {
+            username: { type: "string" },
+            email: { type: "string", format: "email" },
+            age: { type: "integer", minimum: 18 }
+          },
+          required: ["username", "email"]
+        }
+      }
+    }
+  }
+})
+public register(req: Request, res: Response) {
+  // If execution reaches here, req.body is valid
+  return { success: true };
+}
+```
+
+### Serving Frontend Assets (with Tailwind CSS)
+
+You can serve compiled HTML and automatically process Tailwind CSS using the `@Serve` and `@Tailwindcss` decorators.
+
+1.  **Project Structure**:
+
+    ```
+    /views
+      src/
+        index.html
+        index.css (imports tailwind, or handled via plugin)
+        frontend.tsx
+    ```
+
+2.  **Controller Setup**:
+
+```typescript
+import { Controller, Get, Serve, Tailwindcss } from "ewb";
+
+@Controller("/")
+@Tailwindcss({
+  enable: true,
+  plugins: [
+    /* Bun plugins or custom PostCSS wrappers */
+  ],
+})
+export class FrontendController {
+  @Get("/")
+  @Serve("views/src/index.html") // Path to your HTML entry point
+  public app(req: Request, res: Response) {
+    // The decorator handles the response.
+  }
+}
+```
+
+### Middleware
+
+Apply custom Express middleware to controllers or routes using `@Middleware`.
+
+```typescript
+import { Controller, Get, Middleware } from "ewb";
+
+const logAccess = (req: Request, res: Response, next: NextFunction) => {
+  console.log("Accessed!");
+  next();
+};
+
+@Controller("/audit")
+@Middleware(logAccess)
+export class AuditController {
+  @Get("/")
+  public index(req: Request, res: Response) {
+    return { message: "Audited" };
+  }
+}
+```
+
+## Server Configuration
+
+The `Server` class accepts the following options:
+
+| Option             | Type               | Description                                                      |
+| ------------------ | ------------------ | ---------------------------------------------------------------- |
+| `id`               | `string`           | Unique identifier for the server instance.                       |
+| `port`             | `number`           | Port to listen on.                                               |
+| `controllersDir`   | `string`           | Directory containing controller files.                           |
+| `enableSwagger`    | `boolean`          | Enable OpenAPI documentation.                                    |
+| `swaggerPath`      | `string`           | Custom path for Swagger UI (default: `/api-docs`).               |
+| `logging`          | `boolean`          | Enable/disable TUI startup messages (default: true).             |
+| `corsOptions`      | `CorsOptions`      | Configuration for CORS.                                          |
+| `helmetOptions`    | `HelmetOptions`    | Configuration for Helmet security headers.                       |
+| `rateLimitOptions` | `RateLimitOptions` | Configuration for rate limiting.                                 |
+| `securitySchemes`  | `object`           | custom OpenAPI security schemes definitions.                     |
+| `securityHandlers` | `object`           | Middleware handlers for security schemes.                        |
+| `container`        | `object`           | IoC container for dependency injection (must have `get` method). |
+
+## License
+
+MIT

package/dist/Components/ServeMemoryStore.d.ts

@@ -0,0 +1,14 @@
+import type { TailwindOptions } from "../Decorations/Tailwind";
+export declare class ServeMemoryStore {
+    private static _instance;
+    private _assets;
+    private _htmlCache;
+    private constructor();
+    static get instance(): ServeMemoryStore;
+    getAsset(path: string): {
+        type: string;
+        content: Uint8Array;
+    };
+    buildAndCache(htmlPath: string, options?: TailwindOptions): Promise<string>;
+}
+//# sourceMappingURL=ServeMemoryStore.d.ts.map

package/dist/Components/ServeMemoryStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServeMemoryStore.d.ts","sourceRoot":"","sources":["../../src/Components/ServeMemoryStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAmB;IAC3C,OAAO,CAAC,OAAO,CACH;IACZ,OAAO,CAAC,UAAU,CAAkC;IAEpD,OAAO;IAEP,WAAkB,QAAQ,IAAI,gBAAgB,CAK7C;IAEM,QAAQ,CAAC,IAAI,EAAE,MAAM;cAbS,MAAM;iBAAW,UAAU;;IAmBnD,aAAa,CACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAgD,GACxD,OAAO,CAAC,MAAM,CAAC;CAsEnB"}

package/dist/Components/ServeMemoryStore.js

@@ -0,0 +1,77 @@
+import tailwindPlugin from "bun-plugin-tailwind";
+export class ServeMemoryStore {
+    static _instance;
+    _assets = new Map();
+    _htmlCache = new Map();
+    constructor() { }
+    static get instance() {
+        if (!ServeMemoryStore._instance) {
+            ServeMemoryStore._instance = new ServeMemoryStore();
+        }
+        return ServeMemoryStore._instance;
+    }
+    getAsset(path) {
+        // Remove leading slash for matching if stored without it, or normalize.
+        // We will store with leading slash.
+        return this._assets.get(path);
+    }
+    async buildAndCache(htmlPath, options = { enable: false, plugins: [] }) {
+        const cacheKey = htmlPath +
+            (options.enable ? ":tw" : "") +
+            (options.plugins ? ":" + options.plugins.length : "");
+        if (this._htmlCache.has(cacheKey)) {
+            return this._htmlCache.get(cacheKey);
+        }
+        try {
+            const plugins = [...(options.plugins || [])];
+            if (options.enable) {
+                plugins.push(tailwindPlugin);
+            }
+            const build = await Bun.build({
+                entrypoints: [htmlPath],
+                target: "browser",
+                minify: true,
+                naming: "[name]-[hash].[ext]", // Ensure unique names
+                publicPath: "/", // Assets served from root
+                plugins: plugins,
+            });
+            if (!build.success) {
+                console.error("Build failed:", build.logs);
+                throw new Error("Build failed");
+            }
+            let htmlContent = "";
+            for (const output of build.outputs) {
+                const content = await output.arrayBuffer();
+                let text = await output.text(); // For HTML/CSS
+                // output.path is the absolute path if we were writing, or the name.
+                // With naming option, output.path usually contains the generated name.
+                // For artifacts, we need to map the requested URL to this content.
+                // output.kind gives us hint.
+                // Parse the relative path (URL) from the output.
+                // Since we didn't specify outdir, Bun might give us just the name or path relative to cwd.
+                // However, with `publicPath: "/"`, the HTML imports will look like `/foo-hash.js`.
+                // We need to store keys as `/foo-hash.js`.
+                // Let's rely on the fact that `output.path` usually returns what would be written to disk.
+                // We need the filename part.
+                const filename = output.path.split(/[/\\]/).pop();
+                const webPath = "/" + filename;
+                if (output.type === "text/html" || filename?.endsWith(".html")) {
+                    htmlContent = text;
+                }
+                else {
+                    let finalContent = new Uint8Array(content);
+                    this._assets.set(webPath, {
+                        type: output.type,
+                        content: finalContent,
+                    });
+                }
+            }
+            this._htmlCache.set(cacheKey, htmlContent);
+            return htmlContent;
+        }
+        catch (error) {
+            console.error("Serve build error:", error);
+            throw error;
+        }
+    }
+}

package/dist/Components/Server.d.ts

@@ -0,0 +1,48 @@
+import { type Request, type Response, type NextFunction } from "express";
+import { type HelmetOptions } from "helmet";
+import cors from "cors";
+import { type Options as RateLimitOptions } from "express-rate-limit";
+export declare class Server {
+    private readonly _app;
+    private readonly _port;
+    private readonly _controllersDir;
+    readonly _id: string;
+    private readonly _enableSwagger;
+    private readonly _swaggerPath;
+    private readonly _enableLogging;
+    private readonly _securitySchemes?;
+    private readonly _ajv;
+    private readonly _securityHandlers;
+    private readonly _container?;
+    private _serverInstance?;
+    private _controllerCount;
+    private _routeCount;
+    private _tailwindEnabled;
+    constructor(options: ServerOptions);
+    private log;
+    init(): Promise<void>;
+    private printStartupMessage;
+    close(): void;
+    private loadControllers;
+    private createJwtMiddleware;
+    private createAuthMiddleware;
+    private createValidationMiddleware;
+    private setupSwagger;
+}
+export interface ServerOptions {
+    port: number;
+    enableSwagger?: boolean;
+    swaggerPath?: string;
+    logging?: boolean;
+    id: string;
+    controllersDir?: string;
+    corsOptions?: cors.CorsOptions;
+    helmetOptions?: HelmetOptions;
+    rateLimitOptions?: Partial<RateLimitOptions>;
+    securityHandlers?: Record<string, (req: Request, res: Response, next: NextFunction) => void>;
+    securitySchemes?: Record<string, any>;
+    container?: {
+        get: (target: any) => any;
+    };
+}
+//# sourceMappingURL=Server.d.ts.map

package/dist/Components/Server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Server.d.ts","sourceRoot":"","sources":["../../src/Components/Server.ts"],"names":[],"mappings":"AAAA,OAAgB,EAEd,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AAKjB,OAAe,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAkB,EAChB,KAAK,OAAO,IAAI,gBAAgB,EACjC,MAAM,oBAAoB,CAAC;AAuB5B,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAM;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAM;IAC3B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAGhC;IACF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAgC;IAC5D,OAAO,CAAC,eAAe,CAAC,CAAa;IAErC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,gBAAgB,CAAS;gBAErB,OAAO,EAAE,aAAa;IAkClC,OAAO,CAAC,GAAG;IAME,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqClC,OAAO,CAAC,mBAAmB;IAmCpB,KAAK,IAAI,IAAI;YASN,eAAe;IAoP7B,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,oBAAoB;IAyD5B,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,YAAY;CAmErB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC;IAC/B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CACvB,MAAM,EACN,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAC1D,CAAC;IACF,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE;QAAE,GAAG,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAA;KAAE,CAAC;CAC3C"}