@shadow-library/fastify 1.5.0 → 1.6.0

package/README.md

@@ -952,6 +952,62 @@ class CreateProductDto {
 }
 ```
 
+## API Documentation Metadata
+
+The `@ApiOperation` decorator allows you to add OpenAPI/Swagger metadata to your route handlers. This metadata is integrated into the Fastify route schema and can be consumed by documentation generators like Swagger UI.
+
+```typescript
+@ApiOperation({
+  summary: string;              // Short description of the operation
+  description?: string;         // Detailed description
+  tags?: string[];              // Operation tags for grouping
+  deprecated?: boolean;         // Mark if endpoint is deprecated
+  externalDocs?: {              // Link to external documentation
+    url: string;
+    description?: string;
+  };
+  security?: Record<string, []>; // Security requirements
+})
+```
+
+### Example Usage
+
+```typescript
+import { HttpController, Get, Post, Body, ApiOperation } from '@shadow-library/fastify';
+
+@HttpController('/api/users')
+export class UserController {
+  @Get()
+  @ApiOperation({
+    summary: 'List all users',
+    description: 'Retrieve a paginated list of all users in the system',
+    tags: ['users'],
+  })
+  async getUsers() {
+    return [];
+  }
+
+  @Post()
+  @ApiOperation({
+    summary: 'Create a new user',
+    tags: ['users'],
+    security: { bearerAuth: [] },
+  })
+  async createUser(@Body() userData: CreateUserDto) {
+    return { id: 1, ...userData };
+  }
+
+  @Get('/:id')
+  @ApiOperation({
+    summary: 'Get user by ID',
+    deprecated: false,
+  })
+  async getUserById() {
+    return { id: 1, name: 'John' };
+  }
+}
+```
+
 ## Data Transformation
 
 The `@Transform` decorator enables automatic data transformation at two key points in the request-response lifecycle:
@@ -1036,13 +1092,14 @@ export class UserController {
 
 The following transformers are available out of the box:
 
-| Transformer       | Input Type | Output Type | Description                                |
-| ----------------- | ---------- | ----------- | ------------------------------------------ |
-| `email:normalize` | `string`   | `string`    | Trims whitespace and converts to lowercase |
-| `string:trim`     | `string`   | `string`    | Removes leading and trailing whitespace    |
-| `int:parse`       | `string`   | `number`    | Parses string to integer (base 10)         |
-| `float:parse`     | `string`   | `number`    | Parses string to floating-point number     |
-| `bigint:parse`    | `string`   | `bigint`    | Parses string to BigInt                    |
+| Transformer       | Input Type | Output Type | Description                                                                          |
+| ----------------- | ---------- | ----------- | ------------------------------------------------------------------------------------ |
+| `email:normalize` | `string`   | `string`    | Trims whitespace and converts to lowercase                                           |
+| `string:trim`     | `string`   | `string`    | Removes leading and trailing whitespace                                              |
+| `int:parse`       | `string`   | `number`    | Parses string to integer (base 10)                                                   |
+| `float:parse`     | `string`   | `number`    | Parses string to floating-point number                                               |
+| `bigint:parse`    | `string`   | `bigint`    | Parses string to BigInt                                                              |
+| `strip:null`      | `any`      | `any`       | Returns undefined when the field is null which will remove the field from the object |
 
 ### Request Transformation Examples
 

package/cjs/decorators/api-operation.decorator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+export interface ApiOperationMetadata {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    externalDocs?: {
+        url: string;
+        description?: string;
+    };
+    security?: Record<string, string[]>;
+    [key: string]: any;
+}
+/**
+ * Declaring the constants
+ */
+export declare function ApiOperation(options: ApiOperationMetadata): ClassDecorator & MethodDecorator;

package/cjs/decorators/api-operation.decorator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiOperation = ApiOperation;
+/**
+ * Importing npm packages
+ */
+const app_1 = require("@shadow-library/app");
+/**
+ * Declaring the constants
+ */
+function ApiOperation(options) {
+    return (0, app_1.Route)({ operation: options });
+}

package/cjs/decorators/index.d.ts

@@ -1,3 +1,4 @@
+export * from './api-operation.decorator.js';
 export * from './http-controller.decorator.js';
 export * from './http-input.decorator.js';
 export * from './http-output.decorator.js';

package/cjs/decorators/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./api-operation.decorator.js"), exports);
 __exportStar(require("./http-controller.decorator.js"), exports);
 __exportStar(require("./http-input.decorator.js"), exports);
 __exportStar(require("./http-output.decorator.js"), exports);

package/cjs/decorators/transform.decorator.d.ts

@@ -1,6 +1,7 @@
 /**
  * Importing npm packages
  */
+import { TransformerContext } from '@shadow-library/class-schema';
 /**
  * Importing user defined packages
  */
@@ -19,8 +20,10 @@ export interface InbuiltTransformers {
     'int:parse': (value: string) => number;
     'float:parse': (value: string) => number;
     'bigint:parse': (value: string) => bigint;
+    'strip:null': (value: any) => any;
 }
 export type TransformTypes = keyof CustomTransformers | keyof InbuiltTransformers;
+export type TransformerFn = (value: any, ctx: TransformerContext) => any;
 /**
  * Declaring the constants
  */

package/cjs/interfaces/server-metadata.interface.d.ts

@@ -8,7 +8,7 @@ import { FastifyInstance, RouteShorthandOptions } from 'fastify';
  * Importing user defined packages
  */
 import { HTTP_CONTROLLER_TYPE } from '../constants.js';
-import { HttpMethod, RouteInputSchemas } from '../decorators/index.js';
+import { ApiOperationMetadata, HttpMethod, RouteInputSchemas } from '../decorators/index.js';
 /**
  * Defining types
  */
@@ -20,6 +20,7 @@ declare module '@shadow-library/app' {
         schemas?: RouteInputSchemas & {
             response?: Record<number | string, JSONSchema | SchemaClass>;
         };
+        operation?: ApiOperationMetadata;
         rawBody?: boolean;
         silentValidation?: boolean;
         status?: number;

package/cjs/module/data-transformers.js

@@ -16,4 +16,5 @@ exports.INBUILT_TRANSFORMERS = {
     'int:parse': value => parseInt(value, 10),
     'float:parse': value => parseFloat(value),
     'bigint:parse': value => BigInt(value),
+    'strip:null': value => (value === null ? undefined : value),
 };

package/cjs/module/fastify-router.js

@@ -107,11 +107,11 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
         return '****';
     }
     generateDataTransformer(type) {
-        return (value, schema) => {
+        return (value, schema, ctx) => {
             const transformType = schema['x-fastify']?.transform?.[type];
             const transformer = this.transformers[transformType];
             (0, node_assert_1.default)(transformer, `transformer '${transformType}' not found`);
-            return transformer(value);
+            return transformer(value, ctx);
         };
     }
     getRequestLogger() {
@@ -157,6 +157,8 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
                         const versionPrefix = this.config.prefixVersioning ? `/v${version}` : '';
                         const path = this.joinPaths(this.config.routePrefix, versionPrefix, metadata.path, route.metadata.path);
                         const parsedController = { ...route, instance, metatype };
+                        if (metadata.operation || route.metadata.operation)
+                            route.metadata.operation = Object.assign({}, metadata.operation, route.metadata.operation);
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);
                     }
@@ -311,7 +313,7 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
                 }
             }
             const responseSchemas = { ...defaultResponseSchemas };
-            routeOptions.schema = { response: responseSchemas };
+            routeOptions.schema = { ...metadata.operation, response: responseSchemas };
             routeOptions.attachValidation = metadata.silentValidation ?? false;
             const { body: bodySchema, params: paramsSchema, query: querySchema, response: responseSchema } = metadata.schemas ?? {};
             const isMaskEnabled = this.config.maskSensitiveData ?? true;

package/esm/decorators/api-operation.decorator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Importing user defined packages
+ */
+/**
+ * Defining types
+ */
+export interface ApiOperationMetadata {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    externalDocs?: {
+        url: string;
+        description?: string;
+    };
+    security?: Record<string, string[]>;
+    [key: string]: any;
+}
+/**
+ * Declaring the constants
+ */
+export declare function ApiOperation(options: ApiOperationMetadata): ClassDecorator & MethodDecorator;

package/esm/decorators/api-operation.decorator.js

@@ -0,0 +1,10 @@
+/**
+ * Importing npm packages
+ */
+import { Route } from '@shadow-library/app';
+/**
+ * Declaring the constants
+ */
+export function ApiOperation(options) {
+    return Route({ operation: options });
+}

package/esm/decorators/index.d.ts

@@ -1,3 +1,4 @@
+export * from './api-operation.decorator.js';
 export * from './http-controller.decorator.js';
 export * from './http-input.decorator.js';
 export * from './http-output.decorator.js';

package/esm/decorators/index.js

@@ -1,3 +1,4 @@
+export * from './api-operation.decorator.js';
 export * from './http-controller.decorator.js';
 export * from './http-input.decorator.js';
 export * from './http-output.decorator.js';

package/esm/decorators/transform.decorator.d.ts

@@ -1,6 +1,7 @@
 /**
  * Importing npm packages
  */
+import { TransformerContext } from '@shadow-library/class-schema';
 /**
  * Importing user defined packages
  */
@@ -19,8 +20,10 @@ export interface InbuiltTransformers {
     'int:parse': (value: string) => number;
     'float:parse': (value: string) => number;
     'bigint:parse': (value: string) => bigint;
+    'strip:null': (value: any) => any;
 }
 export type TransformTypes = keyof CustomTransformers | keyof InbuiltTransformers;
+export type TransformerFn = (value: any, ctx: TransformerContext) => any;
 /**
  * Declaring the constants
  */

package/esm/interfaces/server-metadata.interface.d.ts

@@ -8,7 +8,7 @@ import { FastifyInstance, RouteShorthandOptions } from 'fastify';
  * Importing user defined packages
  */
 import { HTTP_CONTROLLER_TYPE } from '../constants.js';
-import { HttpMethod, RouteInputSchemas } from '../decorators/index.js';
+import { ApiOperationMetadata, HttpMethod, RouteInputSchemas } from '../decorators/index.js';
 /**
  * Defining types
  */
@@ -20,6 +20,7 @@ declare module '@shadow-library/app' {
         schemas?: RouteInputSchemas & {
             response?: Record<number | string, JSONSchema | SchemaClass>;
         };
+        operation?: ApiOperationMetadata;
         rawBody?: boolean;
         silentValidation?: boolean;
         status?: number;

package/esm/module/data-transformers.js

@@ -13,4 +13,5 @@ export const INBUILT_TRANSFORMERS = {
     'int:parse': value => parseInt(value, 10),
     'float:parse': value => parseFloat(value),
     'bigint:parse': value => BigInt(value),
+    'strip:null': value => (value === null ? undefined : value),
 };

package/esm/module/fastify-router.js

@@ -101,11 +101,11 @@ let FastifyRouter = class FastifyRouter extends Router {
         return '****';
     }
     generateDataTransformer(type) {
-        return (value, schema) => {
+        return (value, schema, ctx) => {
             const transformType = schema['x-fastify']?.transform?.[type];
             const transformer = this.transformers[transformType];
             assert(transformer, `transformer '${transformType}' not found`);
-            return transformer(value);
+            return transformer(value, ctx);
         };
     }
     getRequestLogger() {
@@ -151,6 +151,8 @@ let FastifyRouter = class FastifyRouter extends Router {
                         const versionPrefix = this.config.prefixVersioning ? `/v${version}` : '';
                         const path = this.joinPaths(this.config.routePrefix, versionPrefix, metadata.path, route.metadata.path);
                         const parsedController = { ...route, instance, metatype };
+                        if (metadata.operation || route.metadata.operation)
+                            route.metadata.operation = Object.assign({}, metadata.operation, route.metadata.operation);
                         parsedController.metadata.path = path;
                         parsedControllers.routes.push(parsedController);
                     }
@@ -305,7 +307,7 @@ let FastifyRouter = class FastifyRouter extends Router {
                 }
             }
             const responseSchemas = { ...defaultResponseSchemas };
-            routeOptions.schema = { response: responseSchemas };
+            routeOptions.schema = { ...metadata.operation, response: responseSchemas };
             routeOptions.attachValidation = metadata.silentValidation ?? false;
             const { body: bodySchema, params: paramsSchema, query: querySchema, response: responseSchema } = metadata.schemas ?? {};
             const isMaskEnabled = this.config.maskSensitiveData ?? true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shadow-library/fastify",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "sideEffects": false,
   "description": "A Fastify wrapper featuring decorator-based routing, middleware and error handling",
   "repository": {
@@ -28,7 +28,7 @@
   "peerDependencies": {
     "@fastify/view": "^10.0.0",
     "@shadow-library/app": "^1.0.11",
-    "@shadow-library/class-schema": "^0.0.12",
+    "@shadow-library/class-schema": "^0.1.3",
     "@shadow-library/common": "^1.0.22",
     "reflect-metadata": "^0.2.2"
   },