@mini2/core 2.0.1-beta.0 → 2.0.1-beta.4

package/Readme.MD

@@ -6,10 +6,14 @@
 
 - 🚀 **Decorator-Based Routing**: Easy route definition with decorators like `@get`, `@post`
 - 📝 **Automatic Swagger Documentation**: API documentation generated automatically
+- 🧪 **Example-Driven OpenAPI**: Generate request/response schemas and examples from `RouteOptions.examples`
+- 🧰 **Postman-Friendly Metadata**: Attach `@preRequestScript` / `@testScript` to operations via OpenAPI vendor extensions
 - 🔧 **Dependency Injection**: Powerful DI container based on InversifyJS
 - 🛡️ **Security Middlewares**: Authentication, authorization, and validation
+- 🔒 **Swagger Basic Auth**: Optionally protect Swagger UI and JSON spec endpoints with Basic Authentication
 - 📦 **Full TypeScript Support**: Type-safe API development
 - 🎯 **Response Builder**: Consistent API responses
+- 🧭 **Autoload Controllers/Injectables**: Optional filesystem-based autoload to discover modules automatically
 - ⚡ **Quick Setup**: Minimal configuration required
 
 ## 📦 Installation
@@ -264,6 +268,43 @@ async downloadFile(@req() req: Request, @res() res: Response) {
 }
 ```
 
+#### **@body() / @query() / @params() / @headers()**
+
+Inject validated/normalized request data into method parameters. When validation is enabled via `@validate(...)`, these decorators prefer the validated instance (class-transformer + class-validator) and fall back to raw Express data.
+
+```typescript
+@put('/:id')
+@validate({
+  params: IdParamsDto,
+  query: SearchQueryDto,
+  body: UpdateDto,
+  headers: MyHeadersDto,
+})
+async update(
+  @params() params: IdParamsDto,
+  @query() query: SearchQueryDto,
+  @body() body: UpdateDto,
+  @headers() headers: MyHeadersDto,
+) {
+  return new ResponseBuilder().ok({ params, query, body, headers });
+}
+```
+
+#### **@next()**
+
+Injects Express `next` into your handler (useful for `next(err)` patterns when you want to delegate error handling).
+
+```typescript
+@get('/health')
+health(@next() next: NextFunction) {
+  try {
+    // ...
+  } catch (e) {
+    next(e);
+  }
+}
+```
+
 ### 🛡️ Security Decorators
 
 #### **@authenticated()**
@@ -314,6 +355,16 @@ async getReports(@req() req: Request) {
 - Uses OR logic: user needs ANY of the specified permissions
 - Throws `ForbiddenException` if insufficient permissions
 
+#### **Default Header-Based Auth (for local/test setups)**
+
+The built-in `authenticatedMiddleware` and `authorizedMiddleware` support a simple header-based flow that is convenient for local development and tests:
+
+- `x-authenticated`: `"true" | "1" | "yes" | "y"` (required for authenticated routes)
+- `x-user-id`: user identifier (optional)
+- `x-user-permissions`: comma-separated permissions (optional, e.g. `"admin,reader"`)
+
+If authentication fails, an `UnauthorizedException` is thrown; if authorization fails, a `ForbiddenException` is thrown.
+
 ### ✅ Validation Decorators
 
 #### **@validate(options: ValidationOptions)**
@@ -340,6 +391,7 @@ async createUser(@req() req: Request) {
 - `body`: DTO class for request body validation
 - `params`: DTO class for URL parameters validation
 - `query`: DTO class for query parameters validation
+- `headers`: DTO class for header validation
 
 **Example DTO Classes:**
 
@@ -604,6 +656,16 @@ async createUser(@req() req: Request) {
 - `body` - Request body validation
 - `params` - URL parameters validation
 - `query` - Query parameters validation
+- `headers` - Request header validation
+
+**Advanced options (via `@validate`)**
+
+Each validation entry can be configured with:
+
+- `transformOptions`: class-transformer options
+- `validatorOptions`: class-validator options
+- `logging`: debug logs for source/transformed payloads
+- `customHttpError`: override the default 400 response with a custom `HttpException`
 
 #### **authenticatedMiddleware**
 
@@ -855,6 +917,58 @@ const swaggerOptions = {
 };
 ```
 
+#### **🧪 Example-Driven OpenAPI (Schemas + Examples)**
+
+You can provide concrete request/response examples per route. If `examples` are present, Swagger generation prefers them to:
+
+- Build request body schemas and attach `example`
+- Generate path/query/header parameters (with examples when available)
+- Generate **all response status codes** with `example` and `examples.default` for compatibility
+
+Example (simplified):
+
+```typescript
+@post('/create', 'Create', {
+  examples: [{
+    request: {
+      body: { title: 'Test Item', order: 1 },
+      params: { id: '123' },
+      query: { page: 1 },
+      headers: { 'x-echo': 'hello' },
+    },
+    response: {
+      201: { description: 'Created', data: { ok: true } },
+      400: { description: 'Validation error', data: { error: 'Validation failed' } },
+    },
+  }],
+})
+create() { /* ... */ }
+```
+
+#### **🧰 Postman Scripts via OpenAPI Vendor Extensions**
+
+Attach Postman-compatible scripts to a route:
+
+- `@preRequestScript(script: string)` → `x-postman-prerequest`
+- `@testScript(script: string)` → `x-postman-test`
+
+Swagger/OpenAPI will include them as vendor extensions on the operation, and also as a combined `x-postman-events` list (when present). This is useful for tooling that can import OpenAPI and preserve Postman behaviors.
+
+#### **🔒 Protect Swagger with Basic Auth**
+
+To protect Swagger UI and the raw OpenAPI JSON spec, set `swaggerBasicAuth` in `IConfig`:
+
+```typescript
+await app.init({
+  host: 'localhost',
+  port: 3000,
+  applicationName: 'Protected API',
+  swaggerBasicAuth: { username: 'admin', password: 'secret123' },
+});
+```
+
+This will protect both `docsPath` and `jsonPath` endpoints (defaults: `/api-docs` and `/api-docs.json`).
+
 #### **🔐 Security Documentation**
 
 Security decorators automatically add authentication requirements:
@@ -898,6 +1012,36 @@ async createUser(@req() req: Request) {
 - OpenAPI JSON can be used with external documentation tools
 - All validation errors are automatically documented with examples
 
+### 🧭 Autoload (Filesystem Discovery)
+
+The framework can automatically discover and load controllers/injectables from a directory (useful for local dev, tests, and modular apps).
+
+```typescript
+await app.init(
+  { host: 'localhost', port: 3000, applicationName: 'My API' },
+  {
+    autoload: true,
+    workingDirectory: __dirname,
+    extensions: ['.ts', '.mts', '.cts'],
+    patterns: ['**/*.(ts|js)'],
+    logging: true,
+  }
+);
+```
+
+Notes:
+
+- Files starting with `//mini-dont-auto-load` are skipped.
+- In production you typically point `workingDirectory` to your compiled output (e.g. `dist`).
+
+### 🧪 Local Test Server + Postman Collection
+
+This repo includes a runnable demo server and an example Postman collection to quickly validate Swagger generation, examples, and Postman script extensions:
+
+- `local-test-server/index.ts`: starts the server with autoload enabled
+- `local-test-server/local-test-controller.ts`: demonstrates `examples`, `@preRequestScript`, and `@testScript`
+- `local-test-server/Local Test Server.postman_collection.json`: ready-to-import collection
+
 ### 📝 TypeScript Support
 
 Full TypeScript support with type-safe API development:
@@ -1016,6 +1160,39 @@ export class UserController {
 }
 ```
 
+### 🔎 DI Auto Discovery (`autoBind` + `bindDiscovered`)
+
+For modular apps, you can register bindings via decorators and then bind them in one shot.
+
+```typescript
+import { autoBind, bindDiscovered, MINI_TYPES } from '@mini2/core';
+
+@autoBind(MINI_TYPES.IController, { scope: 'Transient', priority: 10 })
+@controller('/api/users')
+export class UserController extends Controller {}
+
+// After loading modules (or using autoload), bind everything discovered:
+bindDiscovered();
+```
+
+Notes:
+
+- Supported scopes: `Singleton`, `Transient`, `Request`
+- `priority` controls binding order (lower first)
+
+### 🧩 Custom Route Metadata (`@custom`)
+
+If you want to attach arbitrary metadata to a route (e.g., for tooling), use `@custom(key, value)` which stores data in `RouteOptions.extraData`.
+
+```typescript
+@get('/reports')
+@custom('x-internal-owner', 'analytics')
+@custom('x-stability', 'beta')
+async reports() {
+  return new ResponseBuilder().ok({ ok: true });
+}
+```
+
 ## 📋 Complete Export List
 
 ```typescript

package/dist/api-docs/postman.d.ts

@@ -0,0 +1,123 @@
+import 'reflect-metadata';
+import { Express } from 'express';
+import { ISwaggerBasicAuth } from '../interfaces/config.interface';
+type PostmanScript = {
+    type: 'text/javascript';
+    exec: string[];
+};
+type PostmanEvent = {
+    listen: 'prerequest' | 'test';
+    script: PostmanScript;
+};
+type PostmanHeader = {
+    key: string;
+    value: string;
+};
+type PostmanQuery = {
+    key: string;
+    value: string;
+};
+type PostmanVariable = {
+    key: string;
+    value: string;
+};
+type PostmanUrl = {
+    raw: string;
+    host: string[];
+    path: string[];
+    query?: PostmanQuery[];
+    variable?: PostmanVariable[];
+};
+type PostmanRequest = {
+    method: string;
+    header: PostmanHeader[];
+    url: PostmanUrl;
+    description?: string;
+    body?: {
+        mode: 'raw';
+        raw: string;
+        options: {
+            raw: {
+                language: 'json';
+                examples?: unknown[];
+            };
+        };
+    };
+};
+type PostmanResponse = {
+    name: string;
+    originalRequest: PostmanRequest;
+    status: string;
+    code: number;
+    _postman_previewlanguage: 'json' | 'text';
+    header: PostmanHeader[];
+    cookie: unknown[];
+    body: string;
+};
+type PostmanRequestItem = {
+    name: string;
+    event?: PostmanEvent[];
+    request: PostmanRequest;
+    response: PostmanResponse[];
+};
+type PostmanFolderItem = {
+    name: string;
+    item: PostmanRequestItem[];
+};
+type PostmanCollection = {
+    info: {
+        _postman_id: string;
+        name: string;
+        description: string;
+        schema: string;
+    };
+    item: PostmanFolderItem[];
+    variable: Array<{
+        key: string;
+        value: string;
+    }>;
+};
+export interface IPostmanIntegrationOptions {
+    title?: string;
+    description?: string;
+    version?: string;
+    servers?: Array<{
+        url: string;
+        description: string;
+    }>;
+    jsonPath?: string;
+    basicAuth?: ISwaggerBasicAuth;
+    baseUrlVariableName?: string;
+}
+export declare class PostmanIntegration {
+    private postmanCollection;
+    private options;
+    constructor(options?: IPostmanIntegrationOptions);
+    generatePostmanCollection(controllers: any[]): void;
+    setupPostman(app: Express): void;
+    getPostmanCollection(): PostmanCollection | null;
+    private buildRequestItem;
+    private buildRequest;
+    private extractBodyExamples;
+    private buildResponses;
+    private createDefaultResponse;
+    private buildEvents;
+    private toPostmanScript;
+    private buildQuery;
+    private buildPathVariables;
+    private extractPathVariables;
+    private extractPostmanPath;
+    private defaultStatusForMethod;
+    private stringifyScalar;
+    private isRecord;
+    private generateSummary;
+    private generateDescription;
+    private extractControllerFolderName;
+    private extractResourceName;
+    private getDefaultBaseUrl;
+    private buildCollectionDescription;
+    private generateCollectionId;
+    private basicAuthMiddleware;
+}
+export default PostmanIntegration;
+//# sourceMappingURL=postman.d.ts.map

package/dist/api-docs/postman.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postman.d.ts","sourceRoot":"","sources":["../../api-docs/postman.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAmC,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAQnE,KAAK,aAAa,GAAG;IACpB,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;CACf,CAAC;AAEF,KAAK,YAAY,GAAG;IACnB,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC;IAC9B,MAAM,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,KAAK,aAAa,GAAG;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,YAAY,GAAG;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,eAAe,GAAG;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,UAAU,GAAG;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B,CAAC;AAEF,KAAK,cAAc,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,GAAG,EAAE,UAAU,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE;QACN,IAAI,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE;YACR,GAAG,EAAE;gBACJ,QAAQ,EAAE,MAAM,CAAC;gBACjB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;aACrB,CAAC;SACF,CAAC;KACF,CAAC;CACF,CAAC;AAEF,KAAK,eAAe,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,cAAc,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC5B,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,EAAE,CAAC;CAC3B,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACxB,IAAI,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;IACF,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD,CAAC;AAEF,MAAM,WAAW,0BAA0B;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,OAAO,CAA6B;gBAEhC,OAAO,GAAE,0BAA+B;IAc7C,yBAAyB,CAAC,WAAW,EAAE,GAAG,EAAE;IAyD5C,YAAY,CAAC,GAAG,EAAE,OAAO;IAkBzB,oBAAoB;IAI3B,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,YAAY;IAuEpB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,cAAc;IAoEtB,OAAO,CAAC,qBAAqB;IAkB7B,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,sBAAsB;IAK9B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,mBAAmB;IAkB3B,OAAO,CAAC,2BAA2B;IAKnC,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,0BAA0B;IAUlC,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,mBAAmB;CAsB3B;AAED,eAAe,kBAAkB,CAAC"}