constantia 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sperid Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# Constantia
+
+A decorator-based, type-safe web framework for building self-documenting REST APIs with automatic OpenAPI generation. Built on top of [Deepkit](https://deepkit.io/) runtime types for zero-overhead validation.
+
+```typescript
+@Controller('/users')
+class UserController {
+    @Get()
+    async list(): Promise<{ id: string; name: string }[]> {
+        return [{ id: '1', name: 'Alice' }];
+    }
+
+    @Get('/:id')
+    async getById(
+        @Param('id') id: string,
+    ): Promise<{ id: string; name: string }> {
+        if (id === '0') throw new BadRequestError('Invalid user ID');
+        return { id, name: 'Alice' };
+    }
+
+    @Post()
+    async create(
+        @Body() body: { name: string; email: string },
+    ): Promise<{ id: string }> {
+        return { id: '42' };
+    }
+}
+```
+
+Define your types in TypeScript, get validation + OpenAPI for free. No schemas, no codegen, no boilerplate.
+
+## Install
+
+```bash
+pnpm add constantia
+pnpm add -D @deepkit/type-compiler@1.0.1-alpha.155
+```
+
+Add to your `package.json`:
+
+```json
+{
+    "scripts": {
+        "postinstall": "node_modules/.bin/deepkit-type-install"
+    },
+    "pnpm": {
+        "onlyBuiltDependencies": ["@deepkit/type-compiler"]
+    }
+}
+```
+
+Add to your `tsconfig.json`:
+
+```json
+{
+    "compilerOptions": {
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true
+    },
+    "reflection": true
+}
+```
+
+> The `"reflection": true` key tells the Deepkit type compiler to emit type metadata at compile time.
+
+### Requirements
+
+-   **Node.js** >= 20
+-   **TypeScript** 5.x
+-   **pnpm** >= 8 (recommended)
+
+## Features
+
+-   **Decorator-based routing** — `@Controller`, `@Get`, `@Post`, `@Put`, `@Delete`, `@Patch`
+-   **Automatic type validation** — Parameters validated at runtime from TypeScript types (no schemas to write)
+-   **OpenAPI generation** — Full OpenAPI 3.0 spec auto-generated from your controllers
+-   **File uploads** — `@File`, `@Files` with size/count limits and temp file management
+-   **Streaming** — `@FileStream`, `@DataStream` for large files and real-time data
+-   **Middleware pipeline** — Koa-style `@Use` middleware with context injection via `@Inject`
+-   **Adapter pattern** — Framework-agnostic core; ships with Express adapter
+-   **Error handling** — Typed errors (`BadRequestError`, `NotFoundError`, etc.) that map to HTTP status codes
+-   **Configurable logger** — Plug in your own logger or use the built-in console logger
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import {
+    Controller,
+    Get,
+    Post,
+    Param,
+    Body,
+    Query,
+    ExpressAdapter,
+    registerControllersWrapper,
+    registerGlobalMiddlewaresWrapper,
+    registerOpenAPI,
+    BadRequestError,
+} from 'constantia';
+
+@Controller('/users')
+class UserController {
+    @Get()
+    async list(): Promise<{ id: string; name: string }[]> {
+        return [{ id: '1', name: 'Alice' }];
+    }
+
+    @Get('/:id')
+    async getById(
+        @Param('id') id: string,
+    ): Promise<{ id: string; name: string }> {
+        if (id === '0') throw new BadRequestError('Invalid user ID');
+        return { id, name: 'Alice' };
+    }
+
+    @Post()
+    async create(
+        @Body() body: { name: string; email: string },
+    ): Promise<{ id: string }> {
+        return { id: '42' };
+    }
+
+    @Get('/search')
+    async search(@Query('q') q: string): Promise<{ results: string[] }> {
+        return { results: [`Result for: ${q}`] };
+    }
+}
+
+const app = express();
+const adapter = new ExpressAdapter(app);
+
+registerGlobalMiddlewaresWrapper([])(adapter);
+registerControllersWrapper([UserController])(adapter);
+await registerOpenAPI(adapter, {
+    config: { title: 'My API', version: '1.0.0' },
+});
+
+app.listen(3000, () => console.log('Listening on :3000'));
+```
+
+Visit `http://localhost:3000/openapi.json` to see the generated spec.
+
+## Decorators
+
+### Class
+
+| Decorator              | Description                             |
+| ---------------------- | --------------------------------------- |
+| `@Controller('/path')` | Registers a class as a route controller |
+
+### Methods
+
+| Decorator           | Description                               |
+| ------------------- | ----------------------------------------- |
+| `@Get('/path')`     | `GET` route                               |
+| `@Post('/path')`    | `POST` route                              |
+| `@Put('/path')`     | `PUT` route                               |
+| `@Delete('/path')`  | `DELETE` route                            |
+| `@Patch('/path')`   | `PATCH` route                             |
+| `@DefaultHandler()` | Catch-all handler for the controller path |
+
+### Parameters
+
+| Decorator         | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| `@Param('name')`  | URL path parameter (`:name`)                    |
+| `@Query('name')`  | Query string parameter                          |
+| `@Body()`         | Request body (validated as object)              |
+| `@Header('name')` | Request header                                  |
+| `@Inject('key')`  | Inject a value from context (set by middleware) |
+| `@RawBody()`      | Raw request body as `Buffer`                    |
+
+### Files
+
+| Decorator                                        | Description                   |
+| ------------------------------------------------ | ----------------------------- |
+| `@File()`                                        | Single file upload            |
+| `@File('fieldName', { maxFileSize, maxFiles })`  | Named file with options       |
+| `@Files()`                                       | Multiple files (array)        |
+| `@Files('fieldName', { maxFileSize, maxFiles })` | Named multi-file with options |
+
+### Streaming
+
+| Decorator                                                        | Description                |
+| ---------------------------------------------------------------- | -------------------------- |
+| `@FileStream({ contentDisposition, contentType, downloadName })` | Stream a file response     |
+| `@DataStream({ contentType })`                                   | Stream data (e.g., ndjson) |
+
+Return types must match:
+
+```typescript
+// For @FileStream
+async download(): Promise<FileStreamResponse> { ... }
+
+// For @DataStream
+async events(): Promise<DataStreamResponse<MyEvent>> { ... }
+```
+
+### Middleware
+
+```typescript
+import { Use, Middleware, createMiddlewareFactory } from 'constantia';
+
+// Simple middleware
+const logRequest: Middleware = async (ctx, next) => {
+    console.log(`${ctx.request.method} ${ctx.request.url}`);
+    await next();
+};
+
+// Middleware factory (for parameterized middleware)
+const requireRole = createMiddlewareFactory((role: string) => {
+    return async (ctx, next) => {
+        const user = ctx.get<{ role: string }>('user');
+        if (user?.role !== role) throw new UnauthorizedError('Forbidden');
+        await next();
+    };
+});
+
+// Apply at class level (all routes)
+@Use(logRequest)
+@Controller('/admin')
+class AdminController {
+    // Apply at method level
+    @Use(requireRole('admin'))
+    @Get('/dashboard')
+    async dashboard(): Promise<{ status: string }> {
+        return { status: 'ok' };
+    }
+}
+```
+
+### Context Injection
+
+Middleware can inject values into the request context for controllers to consume:
+
+```typescript
+const authMiddleware: Middleware = async (ctx, next) => {
+    const token = ctx.request.headers['authorization'];
+    const user = await verifyToken(token);
+    ctx.set('user', user);
+    await next();
+};
+
+@Use(authMiddleware)
+@Controller('/profile')
+class ProfileController {
+    @Get()
+    async getProfile(@Inject('user') user: User): Promise<User> {
+        return user;
+    }
+}
+```
+
+## Errors
+
+Throw typed errors to return the corresponding HTTP status:
+
+```typescript
+import {
+    BadRequestError, // 400
+    UnauthorizedError, // 401
+    ForbiddenError, // 403
+    NotFoundError, // 404
+    InternalServerError, // 500
+    StatusCodeErrorError, // custom status
+} from 'constantia';
+
+throw new BadRequestError('Invalid input');
+throw new NotFoundError('User not found');
+throw new StatusCodeErrorError('Rate limited', 429);
+```
+
+## OpenAPI
+
+The spec is auto-generated from your decorators and TypeScript types. Expose it at runtime:
+
+```typescript
+await registerOpenAPI(adapter, {
+    config: {
+        title: 'My API',
+        version: '2.0.0',
+        description: 'My awesome API',
+    },
+});
+```
+
+Generate a static `openapi.json` at build time:
+
+```bash
+node dist/app.js --only-generate-spec ./openapi.json
+```
+
+Or generate alongside the running server:
+
+```bash
+node dist/app.js --generate-spec ./openapi.json
+```
+
+## Custom Logger
+
+By default Constantia logs to the console. Plug in your own:
+
+```typescript
+import { setLogger } from 'constantia';
+
+setLogger({
+    info: (msg) => myLogger.info(msg),
+    warn: (msg) => myLogger.warn(msg),
+    error: (msg, err) => myLogger.error(msg, err),
+    debug: (msg) => myLogger.debug(msg),
+});
+```
+
+## File Handling
+
+Uploaded files are stored as temp files. Important lifecycle methods:
+
+```typescript
+@Post('/upload')
+async upload(@File('document', { maxFileSize: 10 * 1024 * 1024 }) file: IFile) {
+    // file.name, file.size, file.mimetype, file.tempFilePath
+    const stream = file.getstream(); // ReadStream
+
+    // If you need to process after the response:
+    file.keepAlive(); // prevents auto-cleanup
+    // ... later ...
+    file.cleanup(); // manual cleanup when done
+}
+```
+
+## Project Structure (recommended)
+
+```
+src/
+├── controllers/
+│   ├── user.controller.ts
+│   ├── auth.controller.ts
+│   └── index.ts          # export all controllers
+├── middlewares/
+│   └── index.ts           # export global middlewares
+├── app.ts                 # boot express + constantia
+└── ...
+```
+
+```typescript
+// src/app.ts
+import express from 'express';
+import {
+    ExpressAdapter,
+    registerControllersWrapper,
+    registerGlobalMiddlewaresWrapper,
+    registerOpenAPI,
+} from 'constantia';
+import { controllers } from './controllers';
+import { globalMiddlewares } from './middlewares';
+
+const app = express();
+const adapter = new ExpressAdapter(app);
+
+registerGlobalMiddlewaresWrapper(globalMiddlewares)(adapter);
+registerControllersWrapper(controllers)(adapter);
+await registerOpenAPI(adapter);
+
+app.listen(3000);
+```
+
+## License
+
+MIT

package/dist/adapters/express.d.ts

@@ -0,0 +1,36 @@
+import type { Express } from 'express';
+import type { ControllerMetadata } from '../metadata.js';
+import { type IFrameworkAdapter } from './index.js';
+import { File } from '../types/files.js';
+import { Middleware } from '../types/middleware.js';
+declare global {
+    namespace Express {
+        interface Request {
+            rawBody?: Buffer;
+            uploadedFiles?: File[];
+        }
+    }
+}
+declare class ExpressAdapter implements IFrameworkAdapter {
+    private readonly app;
+    constructor(app: Express);
+    registerGlobalMiddlewares(middlewares: Middleware[]): void;
+    registerControllers([metadata, controllerClasses]: [
+        ControllerMetadata[],
+        Function[]
+    ]): void;
+    private registerController;
+    private registerRoute;
+    private buildNativeMiddlewares;
+    private runPipeline;
+    private makeCoreHandler;
+    private handleError;
+    private handleStreamResponse;
+    private extractParameters;
+    private parseNestedFormFields;
+    private setNestedValue;
+    private coerceValue;
+    private registerDefaultHandler;
+}
+export { ExpressAdapter };
+//# sourceMappingURL=express.d.ts.map

package/dist/adapters/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/adapters/express.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAqC,MAAM,SAAS,CAAC;AAI1E,OAAO,KAAK,EAGR,kBAAkB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,IAAI,EAAa,MAAM,gBAAgB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAYjD,OAAO,CAAC,MAAM,CAAC;IACX,UAAU,OAAO,CAAC;QACd,UAAU,OAAO;YACb,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;SAC1B;KACJ;CACJ;AAED,cAAM,cAAe,YAAW,iBAAiB;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,OAAO;IAEzC,yBAAyB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI;IAkB1D,mBAAmB,CAAC,CAAC,QAAQ,EAAE,iBAAiB,CAAC,EAAE;QAC/C,kBAAkB,EAAE;QACpB,QAAQ,EAAE;KACb,GAAG,IAAI;IAUR,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,aAAa;IAgDrB,OAAO,CAAC,sBAAsB;YAyDhB,WAAW;IAYzB,OAAO,CAAC,eAAe;IAsBvB,OAAO,CAAC,WAAW;YAkBL,oBAAoB;IA6FlC,OAAO,CAAC,iBAAiB;IA2NzB,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,sBAAsB;CA+DjC;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}