nestjs-api-describe 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriele Partiti
+
+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,170 @@
+# nestjs-api-describe
+
+[![CI](https://github.com/gabrielepartiti/nestjs-api-describe/actions/workflows/ci.yml/badge.svg)](https://github.com/gabrielepartiti/nestjs-api-describe/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/nestjs-api-describe)](https://www.npmjs.com/package/nestjs-api-describe)
+
+Composite decorators for standardizing OpenAPI documentation and input validation in NestJS APIs.
+
+## Installation
+
+```bash
+pnpm add nestjs-api-describe
+```
+
+### Peer dependencies
+
+```bash
+pnpm add @nestjs/common @nestjs/swagger class-validator class-transformer reflect-metadata
+```
+
+## Quick Start
+
+### ControllerDescribe
+
+A composite method decorator that combines HTTP method, Swagger documentation, auth metadata, and error responses in a single declaration.
+
+```typescript
+import { Controller } from '@nestjs/common';
+import { ControllerDescribe } from 'nestjs-api-describe';
+
+@Controller('users')
+export class UsersController {
+  @ControllerDescribe({
+    method: 'GET',
+    path: ':id',
+    summary: 'Get user by ID',
+    description: 'Returns a single user by their unique identifier',
+    responseType: UserResponseDto,
+    errors: [404],
+  })
+  findOne(@Param('id') id: string) {
+    return this.usersService.findOne(id);
+  }
+
+  @ControllerDescribe({
+    method: 'POST',
+    summary: 'Register a new user',
+    responseType: UserResponseDto,
+    isPublic: true,
+    errors: [409],
+  })
+  register(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+}
+```
+
+#### Options
+
+| Option         | Type             | Required | Default | Description                              |
+| -------------- | ---------------- | -------- | ------- | ---------------------------------------- |
+| `method`       | `HttpMethod`     | yes      |         | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`  |
+| `path`         | `string`         | no       | `''`    | Route path                               |
+| `summary`      | `string`         | yes      |         | Swagger operation summary                |
+| `description`  | `string`         | no       |         | Swagger operation description            |
+| `responseType` | `Type<unknown>`  | yes      |         | Response DTO class for Swagger           |
+| `isPublic`     | `boolean`        | no       | `false` | If true, skips auth decorators           |
+| `errors`       | `number[]`       | no       | `[]`    | Additional HTTP error status codes       |
+
+Non-public routes automatically include `401` and `403` error responses and `@ApiBearerAuth()`.
+
+### DtoDescribe
+
+A composite property decorator that combines Swagger `@ApiProperty`, class-validator validators, and class-transformer transforms.
+
+```typescript
+import { DtoDescribe } from 'nestjs-api-describe';
+
+export class CreateUserDto {
+  @DtoDescribe({
+    description: 'User email address',
+    type: 'email',
+    example: 'user@example.com',
+  })
+  email!: string;
+
+  @DtoDescribe({
+    description: 'Display name',
+    type: 'string',
+    minLength: 2,
+    maxLength: 50,
+  })
+  name!: string;
+
+  @DtoDescribe({
+    description: 'User age',
+    type: 'int',
+    min: 0,
+    max: 150,
+  })
+  age!: number;
+
+  @DtoDescribe({
+    description: 'User preferences',
+    type: 'object',
+    required: false,
+  })
+  preferences?: Record<string, unknown>;
+}
+```
+
+#### Options
+
+| Option       | Type             | Required | Default | Description                        |
+| ------------ | ---------------- | -------- | ------- | ---------------------------------- |
+| `description`| `string`         | yes      |         | Swagger property description       |
+| `type`       | `DtoType`        | yes      |         | Field type (see supported types)   |
+| `example`    | `unknown`        | no       |         | Swagger example value              |
+| `required`   | `boolean`        | no       | `true`  | Adds `IsNotEmpty` or `IsOptional`  |
+| `enum`       | `object`         | no       |         | Enum object (for `type: 'enum'`)   |
+| `isArray`    | `boolean`        | no       |         | Marks as array in Swagger          |
+| `nested`     | `Type<unknown>`  | no       |         | Nested DTO class                   |
+| `minLength`  | `number`         | no       |         | Min string length                  |
+| `maxLength`  | `number`         | no       |         | Max string length                  |
+| `min`        | `number`         | no       |         | Min numeric value                  |
+| `max`        | `number`         | no       |         | Max numeric value                  |
+| `pattern`    | `RegExp`         | no       |         | Regex pattern validation           |
+
+#### Supported types
+
+| Type         | Validators applied                        |
+| ------------ | ----------------------------------------- |
+| `string`     | `IsString`, `Length`, `Transform(trim)`   |
+| `number`     | `IsNumber`, `Min`, `Max`                  |
+| `int`        | `IsInt`, `Min`, `Max`                     |
+| `boolean`    | `IsBoolean`                               |
+| `uuid`       | `IsUUID`                                  |
+| `email`      | `IsEmail`, `Transform(lowercase + trim)`  |
+| `date`       | `IsDate`, `Type(() => Date)`              |
+| `dateString` | `IsDateString`                            |
+| `url`        | `IsUrl`                                   |
+| `enum`       | `IsEnum`                                  |
+| `nested`     | `ValidateNested`, `Type(() => nested)`    |
+| `array`      | `IsArray`, `ValidateNested` (if nested)   |
+| `object`     | `IsObject`                                |
+
+### ApiDescribeModule
+
+Optional NestJS dynamic module for global configuration.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ApiDescribeModule } from 'nestjs-api-describe';
+
+@Module({
+  imports: [
+    ApiDescribeModule.forRoot({
+      defaultErrors: [400, 500],
+      customErrorDescriptions: {
+        400: 'Validation failed',
+        500: 'Something went wrong',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,43 @@
+import { Type, DynamicModule } from '@nestjs/common';
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+type DtoType = 'string' | 'number' | 'int' | 'boolean' | 'uuid' | 'email' | 'date' | 'dateString' | 'url' | 'enum' | 'nested' | 'array' | 'object';
+interface ControllerDescribeOptions {
+    method: HttpMethod;
+    path?: string;
+    summary: string;
+    description?: string;
+    responseType: Type<unknown>;
+    isPublic?: boolean;
+    errors?: number[];
+}
+interface DtoDescribeOptions {
+    description: string;
+    example?: unknown;
+    required?: boolean;
+    type: DtoType;
+    enum?: object;
+    isArray?: boolean;
+    nested?: Type<unknown>;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+}
+interface ApiDescribeModuleOptions {
+    defaultErrors?: number[];
+    customErrorDescriptions?: Record<number, string>;
+}
+declare const IS_PUBLIC_KEY = "isPublic";
+declare const API_DESCRIBE_OPTIONS = "API_DESCRIBE_OPTIONS";
+
+declare function ControllerDescribe(options: ControllerDescribeOptions): MethodDecorator;
+
+declare function DtoDescribe(options: DtoDescribeOptions): PropertyDecorator;
+
+declare class ApiDescribeModule {
+    static forRoot(options?: ApiDescribeModuleOptions): DynamicModule;
+}
+
+export { API_DESCRIBE_OPTIONS, ApiDescribeModule, type ApiDescribeModuleOptions, ControllerDescribe, type ControllerDescribeOptions, DtoDescribe, type DtoDescribeOptions, type DtoType, type HttpMethod, IS_PUBLIC_KEY };

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { Type, DynamicModule } from '@nestjs/common';
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+type DtoType = 'string' | 'number' | 'int' | 'boolean' | 'uuid' | 'email' | 'date' | 'dateString' | 'url' | 'enum' | 'nested' | 'array' | 'object';
+interface ControllerDescribeOptions {
+    method: HttpMethod;
+    path?: string;
+    summary: string;
+    description?: string;
+    responseType: Type<unknown>;
+    isPublic?: boolean;
+    errors?: number[];
+}
+interface DtoDescribeOptions {
+    description: string;
+    example?: unknown;
+    required?: boolean;
+    type: DtoType;
+    enum?: object;
+    isArray?: boolean;
+    nested?: Type<unknown>;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    pattern?: RegExp;
+}
+interface ApiDescribeModuleOptions {
+    defaultErrors?: number[];
+    customErrorDescriptions?: Record<number, string>;
+}
+declare const IS_PUBLIC_KEY = "isPublic";
+declare const API_DESCRIBE_OPTIONS = "API_DESCRIBE_OPTIONS";
+
+declare function ControllerDescribe(options: ControllerDescribeOptions): MethodDecorator;
+
+declare function DtoDescribe(options: DtoDescribeOptions): PropertyDecorator;
+
+declare class ApiDescribeModule {
+    static forRoot(options?: ApiDescribeModuleOptions): DynamicModule;
+}
+
+export { API_DESCRIBE_OPTIONS, ApiDescribeModule, type ApiDescribeModuleOptions, ControllerDescribe, type ControllerDescribeOptions, DtoDescribe, type DtoDescribeOptions, type DtoType, type HttpMethod, IS_PUBLIC_KEY };

package/dist/index.js

@@ -0,0 +1,237 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  API_DESCRIBE_OPTIONS: () => API_DESCRIBE_OPTIONS,
+  ApiDescribeModule: () => ApiDescribeModule,
+  ControllerDescribe: () => ControllerDescribe,
+  DtoDescribe: () => DtoDescribe,
+  IS_PUBLIC_KEY: () => IS_PUBLIC_KEY
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var IS_PUBLIC_KEY = "isPublic";
+var API_DESCRIBE_OPTIONS = "API_DESCRIBE_OPTIONS";
+
+// src/controller-describe.decorator.ts
+var import_common = require("@nestjs/common");
+var import_swagger = require("@nestjs/swagger");
+var METHOD_DECORATORS = {
+  GET: import_common.Get,
+  POST: import_common.Post,
+  PUT: import_common.Put,
+  PATCH: import_common.Patch,
+  DELETE: import_common.Delete
+};
+var ERROR_DESCRIPTIONS = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  409: "Conflict",
+  422: "Unprocessable Entity",
+  500: "Internal Server Error"
+};
+function getErrorDescription(code) {
+  return ERROR_DESCRIPTIONS[code] ?? `Error ${String(code)}`;
+}
+function getErrorDecorators(errors) {
+  return errors.map(
+    (code) => (0, import_swagger.ApiResponse)({
+      status: code,
+      description: getErrorDescription(code)
+    })
+  );
+}
+function getSuccessStatus(method) {
+  return method === "POST" ? 201 : 200;
+}
+function addPublicDecorators(decorators, isPublic, allErrors) {
+  if (isPublic) {
+    allErrors.delete(401);
+    allErrors.delete(403);
+    decorators.push((0, import_common.SetMetadata)(IS_PUBLIC_KEY, true));
+  } else {
+    decorators.push((0, import_swagger.ApiBearerAuth)());
+  }
+}
+function buildDecorators(options) {
+  const {
+    method,
+    path = "",
+    summary,
+    description,
+    responseType,
+    isPublic = false,
+    errors = []
+  } = options;
+  const decorators = [];
+  decorators.push(METHOD_DECORATORS[method](path));
+  const operationOptions = description !== void 0 ? { summary, description } : { summary };
+  decorators.push((0, import_swagger.ApiOperation)(operationOptions));
+  decorators.push((0, import_swagger.ApiResponse)({ status: getSuccessStatus(method), type: responseType }));
+  const allErrors = /* @__PURE__ */ new Set([401, 403, ...errors]);
+  addPublicDecorators(decorators, isPublic, allErrors);
+  decorators.push(...getErrorDecorators([...allErrors]));
+  return decorators;
+}
+function ControllerDescribe(options) {
+  return (0, import_common.applyDecorators)(...buildDecorators(options));
+}
+
+// src/dto-describe.decorator.ts
+var import_common2 = require("@nestjs/common");
+var import_swagger2 = require("@nestjs/swagger");
+var import_class_transformer = require("class-transformer");
+var import_class_validator = require("class-validator");
+function buildApiPropertyOptions(options) {
+  const apiOptions = {
+    description: options.description,
+    required: options.required ?? true
+  };
+  if (options.example !== void 0) {
+    apiOptions.example = options.example;
+  }
+  if (options.isArray === true) {
+    apiOptions.isArray = true;
+  }
+  if (options.type === "enum" && options.enum !== void 0) {
+    apiOptions.enum = options.enum;
+  }
+  if (options.nested !== void 0) {
+    apiOptions.type = options.nested;
+  }
+  return apiOptions;
+}
+function getStringDecorators(options) {
+  const decorators = [(0, import_class_validator.IsString)()];
+  if (options.minLength !== void 0 || options.maxLength !== void 0) {
+    decorators.push((0, import_class_validator.Length)(options.minLength ?? 0, options.maxLength));
+  }
+  decorators.push(
+    (0, import_class_transformer.Transform)(
+      ({ value }) => typeof value === "string" ? value.trim() : value
+    )
+  );
+  return decorators;
+}
+function getNumberDecorators(options) {
+  const decorators = [(0, import_class_validator.IsNumber)()];
+  if (options.min !== void 0) {
+    decorators.push((0, import_class_validator.Min)(options.min));
+  }
+  if (options.max !== void 0) {
+    decorators.push((0, import_class_validator.Max)(options.max));
+  }
+  return decorators;
+}
+function getIntDecorators(options) {
+  const decorators = [(0, import_class_validator.IsInt)()];
+  if (options.min !== void 0) {
+    decorators.push((0, import_class_validator.Min)(options.min));
+  }
+  if (options.max !== void 0) {
+    decorators.push((0, import_class_validator.Max)(options.max));
+  }
+  return decorators;
+}
+function getEmailDecorators() {
+  return [
+    (0, import_class_validator.IsEmail)(),
+    (0, import_class_transformer.Transform)(
+      ({ value }) => typeof value === "string" ? value.toLowerCase().trim() : value
+    )
+  ];
+}
+function getNestedDecorators(nested) {
+  return [(0, import_class_validator.ValidateNested)(), (0, import_class_transformer.Type)(() => nested)];
+}
+function getArrayDecorators(nested) {
+  const decorators = [(0, import_class_validator.IsArray)()];
+  if (nested !== void 0) {
+    decorators.push((0, import_class_validator.ValidateNested)({ each: true }), (0, import_class_transformer.Type)(() => nested));
+  }
+  return decorators;
+}
+var TYPE_DECORATOR_MAP = {
+  string: getStringDecorators,
+  number: getNumberDecorators,
+  int: getIntDecorators,
+  boolean: () => [(0, import_class_validator.IsBoolean)()],
+  uuid: () => [(0, import_class_validator.IsUUID)()],
+  email: getEmailDecorators,
+  date: () => [(0, import_class_validator.IsDate)(), (0, import_class_transformer.Type)(() => Date)],
+  dateString: () => [(0, import_class_validator.IsDateString)()],
+  url: () => [(0, import_class_validator.IsUrl)()],
+  enum: (opts) => opts.enum !== void 0 ? [(0, import_class_validator.IsEnum)(opts.enum)] : [],
+  nested: (opts) => opts.nested !== void 0 ? getNestedDecorators(opts.nested) : [],
+  array: (opts) => getArrayDecorators(opts.nested),
+  object: () => [(0, import_class_validator.IsObject)()]
+};
+function getTypeDecorators(options) {
+  const decoratorFn = TYPE_DECORATOR_MAP[options.type];
+  return decoratorFn(options);
+}
+function DtoDescribe(options) {
+  const decorators = [];
+  decorators.push((0, import_swagger2.ApiProperty)(buildApiPropertyOptions(options)));
+  const isRequired = options.required ?? true;
+  decorators.push(isRequired ? (0, import_class_validator.IsNotEmpty)() : (0, import_class_validator.IsOptional)());
+  decorators.push(...getTypeDecorators(options));
+  if (options.pattern !== void 0) {
+    decorators.push((0, import_class_validator.Matches)(options.pattern));
+  }
+  return (0, import_common2.applyDecorators)(...decorators);
+}
+
+// src/api-describe.module.ts
+var import_common3 = require("@nestjs/common");
+var ApiDescribeModule = class {
+  static forRoot(options) {
+    return {
+      module: ApiDescribeModule,
+      global: true,
+      providers: [{ provide: API_DESCRIBE_OPTIONS, useValue: options ?? {} }],
+      exports: [API_DESCRIBE_OPTIONS]
+    };
+  }
+};
+ApiDescribeModule = __decorateClass([
+  (0, import_common3.Module)({})
+], ApiDescribeModule);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  API_DESCRIBE_OPTIONS,
+  ApiDescribeModule,
+  ControllerDescribe,
+  DtoDescribe,
+  IS_PUBLIC_KEY
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/types.ts","../src/controller-describe.decorator.ts","../src/dto-describe.decorator.ts","../src/api-describe.module.ts"],"sourcesContent":["export type {\n  HttpMethod,\n  DtoType,\n  ControllerDescribeOptions,\n  DtoDescribeOptions,\n  ApiDescribeModuleOptions,\n} from './types';\nexport { IS_PUBLIC_KEY, API_DESCRIBE_OPTIONS } from './types';\nexport { ControllerDescribe } from './controller-describe.decorator';\nexport { DtoDescribe } from './dto-describe.decorator';\nexport { ApiDescribeModule } from './api-describe.module';\n","import type { Type } from '@nestjs/common';\n\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n\nexport type DtoType =\n  | 'string'\n  | 'number'\n  | 'int'\n  | 'boolean'\n  | 'uuid'\n  | 'email'\n  | 'date'\n  | 'dateString'\n  | 'url'\n  | 'enum'\n  | 'nested'\n  | 'array'\n  | 'object';\n\nexport interface ControllerDescribeOptions {\n  method: HttpMethod;\n  path?: string;\n  summary: string;\n  description?: string;\n  responseType: Type<unknown>;\n  isPublic?: boolean;\n  errors?: number[];\n}\n\nexport interface DtoDescribeOptions {\n  description: string;\n  example?: unknown;\n  required?: boolean;\n  type: DtoType;\n  enum?: object;\n  isArray?: boolean;\n  nested?: Type<unknown>;\n  minLength?: number;\n  maxLength?: number;\n  min?: number;\n  max?: number;\n  pattern?: RegExp;\n}\n\nexport interface ApiDescribeModuleOptions {\n  defaultErrors?: number[];\n  customErrorDescriptions?: Record<number, string>;\n}\n\nexport const IS_PUBLIC_KEY = 'isPublic';\nexport const API_DESCRIBE_OPTIONS = 'API_DESCRIBE_OPTIONS';\n","import { applyDecorators, Delete, Get, Patch, Post, Put, SetMetadata } from '@nestjs/common';\nimport { ApiBearerAuth, ApiOperation, ApiResponse } from '@nestjs/swagger';\nimport type { ControllerDescribeOptions, HttpMethod } from './types';\nimport { IS_PUBLIC_KEY } from './types';\n\nconst METHOD_DECORATORS: Record<HttpMethod, (path?: string) => MethodDecorator> = {\n  GET: Get,\n  POST: Post,\n  PUT: Put,\n  PATCH: Patch,\n  DELETE: Delete,\n};\n\nconst ERROR_DESCRIPTIONS: Record<number, string> = {\n  400: 'Bad Request',\n  401: 'Unauthorized',\n  403: 'Forbidden',\n  404: 'Not Found',\n  409: 'Conflict',\n  422: 'Unprocessable Entity',\n  500: 'Internal Server Error',\n};\n\nfunction getErrorDescription(code: number): string {\n  return ERROR_DESCRIPTIONS[code] ?? `Error ${String(code)}`;\n}\n\nfunction getErrorDecorators(errors: number[]): MethodDecorator[] {\n  return errors.map((code) =>\n    ApiResponse({\n      status: code,\n      description: getErrorDescription(code),\n    }),\n  );\n}\n\nfunction getSuccessStatus(method: HttpMethod): number {\n  return method === 'POST' ? 201 : 200;\n}\n\nfunction addPublicDecorators(\n  decorators: (MethodDecorator | ClassDecorator)[],\n  isPublic: boolean,\n  allErrors: Set<number>,\n): void {\n  if (isPublic) {\n    allErrors.delete(401);\n    allErrors.delete(403);\n    decorators.push(SetMetadata(IS_PUBLIC_KEY, true));\n  } else {\n    decorators.push(ApiBearerAuth());\n  }\n}\n\nfunction buildDecorators(options: ControllerDescribeOptions): (MethodDecorator | ClassDecorator)[] {\n  const {\n    method,\n    path = '',\n    summary,\n    description,\n    responseType,\n    isPublic = false,\n    errors = [],\n  } = options;\n\n  const decorators: (MethodDecorator | ClassDecorator)[] = [];\n  decorators.push(METHOD_DECORATORS[method](path));\n\n  const operationOptions = description !== undefined ? { summary, description } : { summary };\n  decorators.push(ApiOperation(operationOptions));\n  decorators.push(ApiResponse({ status: getSuccessStatus(method), type: responseType }));\n\n  const allErrors = new Set([401, 403, ...errors]);\n  addPublicDecorators(decorators, isPublic, allErrors);\n  decorators.push(...getErrorDecorators([...allErrors]));\n\n  return decorators;\n}\n\nexport function ControllerDescribe(options: ControllerDescribeOptions): MethodDecorator {\n  return applyDecorators(...buildDecorators(options));\n}\n","import type { Type } from '@nestjs/common';\nimport { applyDecorators } from '@nestjs/common';\nimport type { ApiPropertyOptions } from '@nestjs/swagger';\nimport { ApiProperty } from '@nestjs/swagger';\nimport { Transform, Type as ClassType } from 'class-transformer';\nimport {\n  IsArray,\n  IsBoolean,\n  IsDate,\n  IsDateString,\n  IsEmail,\n  IsEnum,\n  IsInt,\n  IsNotEmpty,\n  IsNumber,\n  IsObject,\n  IsOptional,\n  IsString,\n  IsUrl,\n  IsUUID,\n  Length,\n  Matches,\n  Max,\n  Min,\n  ValidateNested,\n} from 'class-validator';\nimport type { DtoDescribeOptions, DtoType } from './types';\n\nfunction buildApiPropertyOptions(options: DtoDescribeOptions): ApiPropertyOptions {\n  const apiOptions: ApiPropertyOptions = {\n    description: options.description,\n    required: options.required ?? true,\n  };\n\n  if (options.example !== undefined) {\n    apiOptions.example = options.example;\n  }\n\n  if (options.isArray === true) {\n    apiOptions.isArray = true;\n  }\n\n  if (options.type === 'enum' && options.enum !== undefined) {\n    apiOptions.enum = options.enum;\n  }\n\n  if (options.nested !== undefined) {\n    apiOptions.type = options.nested;\n  }\n\n  return apiOptions;\n}\n\nfunction getStringDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsString()];\n\n  if (options.minLength !== undefined || options.maxLength !== undefined) {\n    decorators.push(Length(options.minLength ?? 0, options.maxLength));\n  }\n\n  decorators.push(\n    Transform(({ value }: { value: unknown }) =>\n      typeof value === 'string' ? value.trim() : value,\n    ),\n  );\n\n  return decorators;\n}\n\nfunction getNumberDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsNumber()];\n\n  if (options.min !== undefined) {\n    decorators.push(Min(options.min));\n  }\n\n  if (options.max !== undefined) {\n    decorators.push(Max(options.max));\n  }\n\n  return decorators;\n}\n\nfunction getIntDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsInt()];\n\n  if (options.min !== undefined) {\n    decorators.push(Min(options.min));\n  }\n\n  if (options.max !== undefined) {\n    decorators.push(Max(options.max));\n  }\n\n  return decorators;\n}\n\nfunction getEmailDecorators(): PropertyDecorator[] {\n  return [\n    IsEmail(),\n    Transform(({ value }: { value: unknown }) =>\n      typeof value === 'string' ? value.toLowerCase().trim() : value,\n    ),\n  ];\n}\n\nfunction getNestedDecorators(nested: Type<unknown>): PropertyDecorator[] {\n  return [ValidateNested(), ClassType(() => nested)];\n}\n\nfunction getArrayDecorators(nested?: Type<unknown>): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsArray()];\n\n  if (nested !== undefined) {\n    decorators.push(ValidateNested({ each: true }), ClassType(() => nested));\n  }\n\n  return decorators;\n}\n\nconst TYPE_DECORATOR_MAP: Record<DtoType, (options: DtoDescribeOptions) => PropertyDecorator[]> = {\n  string: getStringDecorators,\n  number: getNumberDecorators,\n  int: getIntDecorators,\n  boolean: () => [IsBoolean()],\n  uuid: () => [IsUUID()],\n  email: getEmailDecorators,\n  date: () => [IsDate(), ClassType(() => Date)],\n  dateString: () => [IsDateString()],\n  url: () => [IsUrl()],\n  enum: (opts) => (opts.enum !== undefined ? [IsEnum(opts.enum)] : []),\n  nested: (opts) => (opts.nested !== undefined ? getNestedDecorators(opts.nested) : []),\n  array: (opts) => getArrayDecorators(opts.nested),\n  object: () => [IsObject()],\n};\n\nfunction getTypeDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decoratorFn = TYPE_DECORATOR_MAP[options.type];\n  return decoratorFn(options);\n}\n\nexport function DtoDescribe(options: DtoDescribeOptions): PropertyDecorator {\n  const decorators: PropertyDecorator[] = [];\n\n  decorators.push(ApiProperty(buildApiPropertyOptions(options)));\n\n  const isRequired = options.required ?? true;\n  decorators.push(isRequired ? IsNotEmpty() : IsOptional());\n  decorators.push(...getTypeDecorators(options));\n\n  if (options.pattern !== undefined) {\n    decorators.push(Matches(options.pattern));\n  }\n\n  return applyDecorators(...decorators);\n}\n","import { DynamicModule, Module } from '@nestjs/common';\nimport type { ApiDescribeModuleOptions } from './types';\nimport { API_DESCRIBE_OPTIONS } from './types';\n\n@Module({})\nexport class ApiDescribeModule {\n  static forRoot(options?: ApiDescribeModuleOptions): DynamicModule {\n    return {\n      module: ApiDescribeModule,\n      global: true,\n      providers: [{ provide: API_DESCRIBE_OPTIONS, useValue: options ?? {} }],\n      exports: [API_DESCRIBE_OPTIONS],\n    };\n  }\n}\n"],"mappings":"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","names":["import_common","import_swagger","ClassType","import_common"]}

package/dist/index.mjs

@@ -0,0 +1,229 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/types.ts
+var IS_PUBLIC_KEY = "isPublic";
+var API_DESCRIBE_OPTIONS = "API_DESCRIBE_OPTIONS";
+
+// src/controller-describe.decorator.ts
+import { applyDecorators, Delete, Get, Patch, Post, Put, SetMetadata } from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiResponse } from "@nestjs/swagger";
+var METHOD_DECORATORS = {
+  GET: Get,
+  POST: Post,
+  PUT: Put,
+  PATCH: Patch,
+  DELETE: Delete
+};
+var ERROR_DESCRIPTIONS = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  409: "Conflict",
+  422: "Unprocessable Entity",
+  500: "Internal Server Error"
+};
+function getErrorDescription(code) {
+  return ERROR_DESCRIPTIONS[code] ?? `Error ${String(code)}`;
+}
+function getErrorDecorators(errors) {
+  return errors.map(
+    (code) => ApiResponse({
+      status: code,
+      description: getErrorDescription(code)
+    })
+  );
+}
+function getSuccessStatus(method) {
+  return method === "POST" ? 201 : 200;
+}
+function addPublicDecorators(decorators, isPublic, allErrors) {
+  if (isPublic) {
+    allErrors.delete(401);
+    allErrors.delete(403);
+    decorators.push(SetMetadata(IS_PUBLIC_KEY, true));
+  } else {
+    decorators.push(ApiBearerAuth());
+  }
+}
+function buildDecorators(options) {
+  const {
+    method,
+    path = "",
+    summary,
+    description,
+    responseType,
+    isPublic = false,
+    errors = []
+  } = options;
+  const decorators = [];
+  decorators.push(METHOD_DECORATORS[method](path));
+  const operationOptions = description !== void 0 ? { summary, description } : { summary };
+  decorators.push(ApiOperation(operationOptions));
+  decorators.push(ApiResponse({ status: getSuccessStatus(method), type: responseType }));
+  const allErrors = /* @__PURE__ */ new Set([401, 403, ...errors]);
+  addPublicDecorators(decorators, isPublic, allErrors);
+  decorators.push(...getErrorDecorators([...allErrors]));
+  return decorators;
+}
+function ControllerDescribe(options) {
+  return applyDecorators(...buildDecorators(options));
+}
+
+// src/dto-describe.decorator.ts
+import { applyDecorators as applyDecorators2 } from "@nestjs/common";
+import { ApiProperty } from "@nestjs/swagger";
+import { Transform, Type as ClassType } from "class-transformer";
+import {
+  IsArray,
+  IsBoolean,
+  IsDate,
+  IsDateString,
+  IsEmail,
+  IsEnum,
+  IsInt,
+  IsNotEmpty,
+  IsNumber,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUrl,
+  IsUUID,
+  Length,
+  Matches,
+  Max,
+  Min,
+  ValidateNested
+} from "class-validator";
+function buildApiPropertyOptions(options) {
+  const apiOptions = {
+    description: options.description,
+    required: options.required ?? true
+  };
+  if (options.example !== void 0) {
+    apiOptions.example = options.example;
+  }
+  if (options.isArray === true) {
+    apiOptions.isArray = true;
+  }
+  if (options.type === "enum" && options.enum !== void 0) {
+    apiOptions.enum = options.enum;
+  }
+  if (options.nested !== void 0) {
+    apiOptions.type = options.nested;
+  }
+  return apiOptions;
+}
+function getStringDecorators(options) {
+  const decorators = [IsString()];
+  if (options.minLength !== void 0 || options.maxLength !== void 0) {
+    decorators.push(Length(options.minLength ?? 0, options.maxLength));
+  }
+  decorators.push(
+    Transform(
+      ({ value }) => typeof value === "string" ? value.trim() : value
+    )
+  );
+  return decorators;
+}
+function getNumberDecorators(options) {
+  const decorators = [IsNumber()];
+  if (options.min !== void 0) {
+    decorators.push(Min(options.min));
+  }
+  if (options.max !== void 0) {
+    decorators.push(Max(options.max));
+  }
+  return decorators;
+}
+function getIntDecorators(options) {
+  const decorators = [IsInt()];
+  if (options.min !== void 0) {
+    decorators.push(Min(options.min));
+  }
+  if (options.max !== void 0) {
+    decorators.push(Max(options.max));
+  }
+  return decorators;
+}
+function getEmailDecorators() {
+  return [
+    IsEmail(),
+    Transform(
+      ({ value }) => typeof value === "string" ? value.toLowerCase().trim() : value
+    )
+  ];
+}
+function getNestedDecorators(nested) {
+  return [ValidateNested(), ClassType(() => nested)];
+}
+function getArrayDecorators(nested) {
+  const decorators = [IsArray()];
+  if (nested !== void 0) {
+    decorators.push(ValidateNested({ each: true }), ClassType(() => nested));
+  }
+  return decorators;
+}
+var TYPE_DECORATOR_MAP = {
+  string: getStringDecorators,
+  number: getNumberDecorators,
+  int: getIntDecorators,
+  boolean: () => [IsBoolean()],
+  uuid: () => [IsUUID()],
+  email: getEmailDecorators,
+  date: () => [IsDate(), ClassType(() => Date)],
+  dateString: () => [IsDateString()],
+  url: () => [IsUrl()],
+  enum: (opts) => opts.enum !== void 0 ? [IsEnum(opts.enum)] : [],
+  nested: (opts) => opts.nested !== void 0 ? getNestedDecorators(opts.nested) : [],
+  array: (opts) => getArrayDecorators(opts.nested),
+  object: () => [IsObject()]
+};
+function getTypeDecorators(options) {
+  const decoratorFn = TYPE_DECORATOR_MAP[options.type];
+  return decoratorFn(options);
+}
+function DtoDescribe(options) {
+  const decorators = [];
+  decorators.push(ApiProperty(buildApiPropertyOptions(options)));
+  const isRequired = options.required ?? true;
+  decorators.push(isRequired ? IsNotEmpty() : IsOptional());
+  decorators.push(...getTypeDecorators(options));
+  if (options.pattern !== void 0) {
+    decorators.push(Matches(options.pattern));
+  }
+  return applyDecorators2(...decorators);
+}
+
+// src/api-describe.module.ts
+import { Module } from "@nestjs/common";
+var ApiDescribeModule = class {
+  static forRoot(options) {
+    return {
+      module: ApiDescribeModule,
+      global: true,
+      providers: [{ provide: API_DESCRIBE_OPTIONS, useValue: options ?? {} }],
+      exports: [API_DESCRIBE_OPTIONS]
+    };
+  }
+};
+ApiDescribeModule = __decorateClass([
+  Module({})
+], ApiDescribeModule);
+export {
+  API_DESCRIBE_OPTIONS,
+  ApiDescribeModule,
+  ControllerDescribe,
+  DtoDescribe,
+  IS_PUBLIC_KEY
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/controller-describe.decorator.ts","../src/dto-describe.decorator.ts","../src/api-describe.module.ts"],"sourcesContent":["import type { Type } from '@nestjs/common';\n\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n\nexport type DtoType =\n  | 'string'\n  | 'number'\n  | 'int'\n  | 'boolean'\n  | 'uuid'\n  | 'email'\n  | 'date'\n  | 'dateString'\n  | 'url'\n  | 'enum'\n  | 'nested'\n  | 'array'\n  | 'object';\n\nexport interface ControllerDescribeOptions {\n  method: HttpMethod;\n  path?: string;\n  summary: string;\n  description?: string;\n  responseType: Type<unknown>;\n  isPublic?: boolean;\n  errors?: number[];\n}\n\nexport interface DtoDescribeOptions {\n  description: string;\n  example?: unknown;\n  required?: boolean;\n  type: DtoType;\n  enum?: object;\n  isArray?: boolean;\n  nested?: Type<unknown>;\n  minLength?: number;\n  maxLength?: number;\n  min?: number;\n  max?: number;\n  pattern?: RegExp;\n}\n\nexport interface ApiDescribeModuleOptions {\n  defaultErrors?: number[];\n  customErrorDescriptions?: Record<number, string>;\n}\n\nexport const IS_PUBLIC_KEY = 'isPublic';\nexport const API_DESCRIBE_OPTIONS = 'API_DESCRIBE_OPTIONS';\n","import { applyDecorators, Delete, Get, Patch, Post, Put, SetMetadata } from '@nestjs/common';\nimport { ApiBearerAuth, ApiOperation, ApiResponse } from '@nestjs/swagger';\nimport type { ControllerDescribeOptions, HttpMethod } from './types';\nimport { IS_PUBLIC_KEY } from './types';\n\nconst METHOD_DECORATORS: Record<HttpMethod, (path?: string) => MethodDecorator> = {\n  GET: Get,\n  POST: Post,\n  PUT: Put,\n  PATCH: Patch,\n  DELETE: Delete,\n};\n\nconst ERROR_DESCRIPTIONS: Record<number, string> = {\n  400: 'Bad Request',\n  401: 'Unauthorized',\n  403: 'Forbidden',\n  404: 'Not Found',\n  409: 'Conflict',\n  422: 'Unprocessable Entity',\n  500: 'Internal Server Error',\n};\n\nfunction getErrorDescription(code: number): string {\n  return ERROR_DESCRIPTIONS[code] ?? `Error ${String(code)}`;\n}\n\nfunction getErrorDecorators(errors: number[]): MethodDecorator[] {\n  return errors.map((code) =>\n    ApiResponse({\n      status: code,\n      description: getErrorDescription(code),\n    }),\n  );\n}\n\nfunction getSuccessStatus(method: HttpMethod): number {\n  return method === 'POST' ? 201 : 200;\n}\n\nfunction addPublicDecorators(\n  decorators: (MethodDecorator | ClassDecorator)[],\n  isPublic: boolean,\n  allErrors: Set<number>,\n): void {\n  if (isPublic) {\n    allErrors.delete(401);\n    allErrors.delete(403);\n    decorators.push(SetMetadata(IS_PUBLIC_KEY, true));\n  } else {\n    decorators.push(ApiBearerAuth());\n  }\n}\n\nfunction buildDecorators(options: ControllerDescribeOptions): (MethodDecorator | ClassDecorator)[] {\n  const {\n    method,\n    path = '',\n    summary,\n    description,\n    responseType,\n    isPublic = false,\n    errors = [],\n  } = options;\n\n  const decorators: (MethodDecorator | ClassDecorator)[] = [];\n  decorators.push(METHOD_DECORATORS[method](path));\n\n  const operationOptions = description !== undefined ? { summary, description } : { summary };\n  decorators.push(ApiOperation(operationOptions));\n  decorators.push(ApiResponse({ status: getSuccessStatus(method), type: responseType }));\n\n  const allErrors = new Set([401, 403, ...errors]);\n  addPublicDecorators(decorators, isPublic, allErrors);\n  decorators.push(...getErrorDecorators([...allErrors]));\n\n  return decorators;\n}\n\nexport function ControllerDescribe(options: ControllerDescribeOptions): MethodDecorator {\n  return applyDecorators(...buildDecorators(options));\n}\n","import type { Type } from '@nestjs/common';\nimport { applyDecorators } from '@nestjs/common';\nimport type { ApiPropertyOptions } from '@nestjs/swagger';\nimport { ApiProperty } from '@nestjs/swagger';\nimport { Transform, Type as ClassType } from 'class-transformer';\nimport {\n  IsArray,\n  IsBoolean,\n  IsDate,\n  IsDateString,\n  IsEmail,\n  IsEnum,\n  IsInt,\n  IsNotEmpty,\n  IsNumber,\n  IsObject,\n  IsOptional,\n  IsString,\n  IsUrl,\n  IsUUID,\n  Length,\n  Matches,\n  Max,\n  Min,\n  ValidateNested,\n} from 'class-validator';\nimport type { DtoDescribeOptions, DtoType } from './types';\n\nfunction buildApiPropertyOptions(options: DtoDescribeOptions): ApiPropertyOptions {\n  const apiOptions: ApiPropertyOptions = {\n    description: options.description,\n    required: options.required ?? true,\n  };\n\n  if (options.example !== undefined) {\n    apiOptions.example = options.example;\n  }\n\n  if (options.isArray === true) {\n    apiOptions.isArray = true;\n  }\n\n  if (options.type === 'enum' && options.enum !== undefined) {\n    apiOptions.enum = options.enum;\n  }\n\n  if (options.nested !== undefined) {\n    apiOptions.type = options.nested;\n  }\n\n  return apiOptions;\n}\n\nfunction getStringDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsString()];\n\n  if (options.minLength !== undefined || options.maxLength !== undefined) {\n    decorators.push(Length(options.minLength ?? 0, options.maxLength));\n  }\n\n  decorators.push(\n    Transform(({ value }: { value: unknown }) =>\n      typeof value === 'string' ? value.trim() : value,\n    ),\n  );\n\n  return decorators;\n}\n\nfunction getNumberDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsNumber()];\n\n  if (options.min !== undefined) {\n    decorators.push(Min(options.min));\n  }\n\n  if (options.max !== undefined) {\n    decorators.push(Max(options.max));\n  }\n\n  return decorators;\n}\n\nfunction getIntDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsInt()];\n\n  if (options.min !== undefined) {\n    decorators.push(Min(options.min));\n  }\n\n  if (options.max !== undefined) {\n    decorators.push(Max(options.max));\n  }\n\n  return decorators;\n}\n\nfunction getEmailDecorators(): PropertyDecorator[] {\n  return [\n    IsEmail(),\n    Transform(({ value }: { value: unknown }) =>\n      typeof value === 'string' ? value.toLowerCase().trim() : value,\n    ),\n  ];\n}\n\nfunction getNestedDecorators(nested: Type<unknown>): PropertyDecorator[] {\n  return [ValidateNested(), ClassType(() => nested)];\n}\n\nfunction getArrayDecorators(nested?: Type<unknown>): PropertyDecorator[] {\n  const decorators: PropertyDecorator[] = [IsArray()];\n\n  if (nested !== undefined) {\n    decorators.push(ValidateNested({ each: true }), ClassType(() => nested));\n  }\n\n  return decorators;\n}\n\nconst TYPE_DECORATOR_MAP: Record<DtoType, (options: DtoDescribeOptions) => PropertyDecorator[]> = {\n  string: getStringDecorators,\n  number: getNumberDecorators,\n  int: getIntDecorators,\n  boolean: () => [IsBoolean()],\n  uuid: () => [IsUUID()],\n  email: getEmailDecorators,\n  date: () => [IsDate(), ClassType(() => Date)],\n  dateString: () => [IsDateString()],\n  url: () => [IsUrl()],\n  enum: (opts) => (opts.enum !== undefined ? [IsEnum(opts.enum)] : []),\n  nested: (opts) => (opts.nested !== undefined ? getNestedDecorators(opts.nested) : []),\n  array: (opts) => getArrayDecorators(opts.nested),\n  object: () => [IsObject()],\n};\n\nfunction getTypeDecorators(options: DtoDescribeOptions): PropertyDecorator[] {\n  const decoratorFn = TYPE_DECORATOR_MAP[options.type];\n  return decoratorFn(options);\n}\n\nexport function DtoDescribe(options: DtoDescribeOptions): PropertyDecorator {\n  const decorators: PropertyDecorator[] = [];\n\n  decorators.push(ApiProperty(buildApiPropertyOptions(options)));\n\n  const isRequired = options.required ?? true;\n  decorators.push(isRequired ? IsNotEmpty() : IsOptional());\n  decorators.push(...getTypeDecorators(options));\n\n  if (options.pattern !== undefined) {\n    decorators.push(Matches(options.pattern));\n  }\n\n  return applyDecorators(...decorators);\n}\n","import { DynamicModule, Module } from '@nestjs/common';\nimport type { ApiDescribeModuleOptions } from './types';\nimport { API_DESCRIBE_OPTIONS } from './types';\n\n@Module({})\nexport class ApiDescribeModule {\n  static forRoot(options?: ApiDescribeModuleOptions): DynamicModule {\n    return {\n      module: ApiDescribeModule,\n      global: true,\n      providers: [{ provide: API_DESCRIBE_OPTIONS, useValue: options ?? {} }],\n      exports: [API_DESCRIBE_OPTIONS],\n    };\n  }\n}\n"],"mappings":"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","names":["applyDecorators"]}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "nestjs-api-describe",
+  "version": "1.0.0",
+  "description": "Composite decorators for standardizing OpenAPI documentation and input validation in NestJS APIs",
+  "author": "Gabriele Partiti",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nestjs",
+    "decorator",
+    "openapi",
+    "swagger",
+    "validation",
+    "class-validator",
+    "dto"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gabry-ts/nestjs-api-describe"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint 'src/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts'",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "prepare": "husky"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10",
+    "@nestjs/swagger": ">=7",
+    "class-transformer": ">=0.5",
+    "class-validator": ">=0.14",
+    "reflect-metadata": ">=0.1"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/swagger": "^7.0.0",
+    "@nestjs/testing": "^10.0.0",
+    "@types/jest": "^29.5.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.0",
+    "eslint": "^8.57.0",
+    "husky": "^9.0.0",
+    "jest": "^29.7.0",
+    "lint-staged": "^15.0.0",
+    "prettier": "^3.0.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0",
+    "ts-jest": "^29.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}