@digitaldefiance/node-express-suite 3.11.32 → 3.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/README.md +874 -8
  2. package/package.json +5 -5
  3. package/src/controllers/openapi.d.ts +67 -0
  4. package/src/controllers/openapi.d.ts.map +1 -0
  5. package/src/controllers/openapi.js +89 -0
  6. package/src/controllers/openapi.js.map +1 -0
  7. package/src/decorators/auth.d.ts +128 -0
  8. package/src/decorators/auth.d.ts.map +1 -0
  9. package/src/decorators/auth.js +230 -0
  10. package/src/decorators/auth.js.map +1 -0
  11. package/src/decorators/base-controller.d.ts +144 -6
  12. package/src/decorators/base-controller.d.ts.map +1 -1
  13. package/src/decorators/base-controller.js +487 -31
  14. package/src/decorators/base-controller.js.map +1 -1
  15. package/src/decorators/controller.d.ts +63 -7
  16. package/src/decorators/controller.d.ts.map +1 -1
  17. package/src/decorators/controller.js +70 -39
  18. package/src/decorators/controller.js.map +1 -1
  19. package/src/decorators/handler-args.d.ts +68 -0
  20. package/src/decorators/handler-args.d.ts.map +1 -0
  21. package/src/decorators/handler-args.js +83 -0
  22. package/src/decorators/handler-args.js.map +1 -0
  23. package/src/decorators/http-methods.d.ts +143 -0
  24. package/src/decorators/http-methods.d.ts.map +1 -0
  25. package/src/decorators/http-methods.js +265 -0
  26. package/src/decorators/http-methods.js.map +1 -0
  27. package/src/decorators/index.d.ts +22 -0
  28. package/src/decorators/index.d.ts.map +1 -1
  29. package/src/decorators/index.js +56 -0
  30. package/src/decorators/index.js.map +1 -1
  31. package/src/decorators/lifecycle.d.ts +248 -0
  32. package/src/decorators/lifecycle.d.ts.map +1 -0
  33. package/src/decorators/lifecycle.js +301 -0
  34. package/src/decorators/lifecycle.js.map +1 -0
  35. package/src/decorators/metadata-collector.d.ts +175 -0
  36. package/src/decorators/metadata-collector.d.ts.map +1 -0
  37. package/src/decorators/metadata-collector.js +272 -0
  38. package/src/decorators/metadata-collector.js.map +1 -0
  39. package/src/decorators/metadata-keys.d.ts +121 -0
  40. package/src/decorators/metadata-keys.d.ts.map +1 -0
  41. package/src/decorators/metadata-keys.js +116 -0
  42. package/src/decorators/metadata-keys.js.map +1 -0
  43. package/src/decorators/middleware.d.ts +181 -0
  44. package/src/decorators/middleware.d.ts.map +1 -0
  45. package/src/decorators/middleware.js +400 -0
  46. package/src/decorators/middleware.js.map +1 -0
  47. package/src/decorators/openapi-params.d.ts +192 -0
  48. package/src/decorators/openapi-params.d.ts.map +1 -0
  49. package/src/decorators/openapi-params.js +332 -0
  50. package/src/decorators/openapi-params.js.map +1 -0
  51. package/src/decorators/openapi.d.ts +201 -0
  52. package/src/decorators/openapi.d.ts.map +1 -0
  53. package/src/decorators/openapi.js +334 -0
  54. package/src/decorators/openapi.js.map +1 -0
  55. package/src/decorators/params.d.ts +217 -0
  56. package/src/decorators/params.d.ts.map +1 -0
  57. package/src/decorators/params.js +323 -0
  58. package/src/decorators/params.js.map +1 -0
  59. package/src/decorators/response.d.ts +200 -0
  60. package/src/decorators/response.d.ts.map +1 -0
  61. package/src/decorators/response.js +315 -0
  62. package/src/decorators/response.js.map +1 -0
  63. package/src/decorators/schema.d.ts +99 -0
  64. package/src/decorators/schema.d.ts.map +1 -0
  65. package/src/decorators/schema.js +329 -0
  66. package/src/decorators/schema.js.map +1 -0
  67. package/src/decorators/transaction.d.ts +69 -0
  68. package/src/decorators/transaction.d.ts.map +1 -0
  69. package/src/decorators/transaction.js +80 -0
  70. package/src/decorators/transaction.js.map +1 -0
  71. package/src/decorators/validation.d.ts +188 -0
  72. package/src/decorators/validation.d.ts.map +1 -0
  73. package/src/decorators/validation.js +269 -0
  74. package/src/decorators/validation.js.map +1 -0
  75. package/src/decorators/zod-validation.d.ts +164 -4
  76. package/src/decorators/zod-validation.d.ts.map +1 -1
  77. package/src/decorators/zod-validation.js +692 -13
  78. package/src/decorators/zod-validation.js.map +1 -1
  79. package/src/index.d.ts +1 -0
  80. package/src/index.d.ts.map +1 -1
  81. package/src/index.js +1 -0
  82. package/src/index.js.map +1 -1
  83. package/src/interfaces/openApi/decoratorOptions.d.ts +760 -0
  84. package/src/interfaces/openApi/decoratorOptions.d.ts.map +1 -0
  85. package/src/interfaces/openApi/decoratorOptions.js +734 -0
  86. package/src/interfaces/openApi/decoratorOptions.js.map +1 -0
  87. package/src/interfaces/openApi/index.d.ts +1 -0
  88. package/src/interfaces/openApi/index.d.ts.map +1 -1
  89. package/src/interfaces/openApi/index.js +23 -0
  90. package/src/interfaces/openApi/index.js.map +1 -1
  91. package/src/interfaces/openApi/parameter.d.ts +2 -0
  92. package/src/interfaces/openApi/parameter.d.ts.map +1 -1
  93. package/src/interfaces/openApi/parameter.js +3 -1
  94. package/src/interfaces/openApi/parameter.js.map +1 -1
  95. package/src/interfaces/openApi/parameterSchema.d.ts +2 -0
  96. package/src/interfaces/openApi/parameterSchema.d.ts.map +1 -1
  97. package/src/interfaces/openApi/parameterSchema.js +3 -0
  98. package/src/interfaces/openApi/parameterSchema.js.map +1 -1
  99. package/src/openapi/builder.d.ts +249 -0
  100. package/src/openapi/builder.d.ts.map +1 -0
  101. package/src/openapi/builder.js +352 -0
  102. package/src/openapi/builder.js.map +1 -0
  103. package/src/openapi/controller.d.ts +153 -0
  104. package/src/openapi/controller.d.ts.map +1 -0
  105. package/src/openapi/controller.js +331 -0
  106. package/src/openapi/controller.js.map +1 -0
  107. package/src/openapi/index.d.ts +12 -0
  108. package/src/openapi/index.d.ts.map +1 -0
  109. package/src/openapi/index.js +20 -0
  110. package/src/openapi/index.js.map +1 -0
  111. package/src/openapi/markdown-generator.d.ts +52 -0
  112. package/src/openapi/markdown-generator.d.ts.map +1 -0
  113. package/src/openapi/markdown-generator.js +569 -0
  114. package/src/openapi/markdown-generator.js.map +1 -0
  115. package/src/openapi/middleware/index.d.ts +9 -0
  116. package/src/openapi/middleware/index.d.ts.map +1 -0
  117. package/src/openapi/middleware/index.js +15 -0
  118. package/src/openapi/middleware/index.js.map +1 -0
  119. package/src/openapi/middleware/redoc.d.ts +314 -0
  120. package/src/openapi/middleware/redoc.d.ts.map +1 -0
  121. package/src/openapi/middleware/redoc.js +181 -0
  122. package/src/openapi/middleware/redoc.js.map +1 -0
  123. package/src/openapi/middleware/swagger-ui.d.ts +123 -0
  124. package/src/openapi/middleware/swagger-ui.d.ts.map +1 -0
  125. package/src/openapi/middleware/swagger-ui.js +227 -0
  126. package/src/openapi/middleware/swagger-ui.js.map +1 -0
  127. package/src/openapi/schemas.d.ts +170 -0
  128. package/src/openapi/schemas.d.ts.map +1 -0
  129. package/src/openapi/schemas.js +340 -0
  130. package/src/openapi/schemas.js.map +1 -0
  131. package/src/registry/controller-registry.d.ts +78 -0
  132. package/src/registry/controller-registry.d.ts.map +1 -0
  133. package/src/registry/controller-registry.js +86 -0
  134. package/src/registry/controller-registry.js.map +1 -0
  135. package/src/registry/index.d.ts +2 -0
  136. package/src/registry/index.d.ts.map +1 -1
  137. package/src/registry/index.js +3 -1
  138. package/src/registry/index.js.map +1 -1
  139. package/src/routers/api.d.ts +2 -1
  140. package/src/routers/api.d.ts.map +1 -1
  141. package/src/routers/api.js +7 -1
  142. package/src/routers/api.js.map +1 -1
  143. package/src/types.d.ts +1 -0
  144. package/src/types.d.ts.map +1 -1
  145. package/src/types.js +1 -0
  146. package/src/types.js.map +1 -1
@@ -0,0 +1,201 @@
1
+ /**
2
+ * @fileoverview OpenAPI operation decorators for Express Suite.
3
+ * Provides @ApiOperation, @ApiTags, @ApiSummary, @ApiDescription, @Deprecated,
4
+ * @ApiOperationId, and @ApiExample decorators for documenting API operations.
5
+ * Supports both class-level and method-level application.
6
+ * @module decorators/openapi
7
+ */
8
+ import 'reflect-metadata';
9
+ import { ApiExampleDecoratorOptions, ApiOperationDecoratorOptions } from '../interfaces/openApi/decoratorOptions';
10
+ /**
11
+ * Internal interface for OpenAPI metadata stored on methods.
12
+ */
13
+ export interface OpenAPIMethodMetadata {
14
+ summary?: string;
15
+ description?: string;
16
+ tags?: string[];
17
+ operationId?: string;
18
+ deprecated?: boolean;
19
+ examples?: ApiExampleDecoratorOptions[];
20
+ }
21
+ /**
22
+ * Internal interface for OpenAPI metadata stored on classes.
23
+ */
24
+ export interface OpenAPIClassMetadata {
25
+ tags?: string[];
26
+ description?: string;
27
+ deprecated?: boolean;
28
+ }
29
+ /**
30
+ * Decorator that sets full OpenAPI operation metadata on a method.
31
+ * Can also be applied at class level to set default values for all methods.
32
+ *
33
+ * @param options - OpenAPI operation options
34
+ * @returns Class or method decorator
35
+ *
36
+ * @example
37
+ * ```typescript
38
+ * class UserController {
39
+ * @ApiOperation({
40
+ * summary: 'Get user by ID',
41
+ * description: 'Retrieves a user by their unique identifier',
42
+ * tags: ['Users'],
43
+ * operationId: 'getUserById',
44
+ * deprecated: false
45
+ * })
46
+ * @Get('/:id')
47
+ * getUser() {}
48
+ * }
49
+ * ```
50
+ */
51
+ export declare function ApiOperation(options: ApiOperationDecoratorOptions): ClassDecorator & MethodDecorator;
52
+ /**
53
+ * Decorator that adds tags to an operation or all operations in a controller.
54
+ * Tags are used to group operations in OpenAPI documentation.
55
+ * When applied at method level, tags are added to (not replace) class-level tags.
56
+ *
57
+ * @param tags - One or more tags to add
58
+ * @returns Class or method decorator
59
+ *
60
+ * @example
61
+ * ```typescript
62
+ * @ApiTags('Users', 'Admin')
63
+ * @ApiController('/api/users')
64
+ * class UserController {
65
+ * @Get('/')
66
+ * listUsers() {} // Has tags: ['Users', 'Admin']
67
+ *
68
+ * @ApiTags('Public')
69
+ * @Get('/public')
70
+ * publicUsers() {} // Has tags: ['Users', 'Admin', 'Public']
71
+ * }
72
+ * ```
73
+ */
74
+ export declare function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator;
75
+ /**
76
+ * Decorator that sets the summary for an operation.
77
+ * The summary is a short description of the operation.
78
+ *
79
+ * @param summary - Short summary text
80
+ * @returns Method decorator
81
+ *
82
+ * @example
83
+ * ```typescript
84
+ * class UserController {
85
+ * @ApiSummary('Get user by ID')
86
+ * @Get('/:id')
87
+ * getUser() {}
88
+ * }
89
+ * ```
90
+ */
91
+ export declare function ApiSummary(summary: string): MethodDecorator;
92
+ /**
93
+ * Decorator that sets the description for an operation.
94
+ * The description provides detailed information about the operation.
95
+ *
96
+ * @param description - Detailed description text
97
+ * @returns Method decorator
98
+ *
99
+ * @example
100
+ * ```typescript
101
+ * class UserController {
102
+ * @ApiDescription('Retrieves a user by their unique identifier. Returns 404 if not found.')
103
+ * @Get('/:id')
104
+ * getUser() {}
105
+ * }
106
+ * ```
107
+ */
108
+ export declare function ApiDescription(description: string): MethodDecorator;
109
+ /**
110
+ * Decorator that marks an operation or all operations in a controller as deprecated.
111
+ * Deprecated operations are still functional but should not be used in new code.
112
+ *
113
+ * @returns Class or method decorator
114
+ *
115
+ * @example
116
+ * ```typescript
117
+ * class UserController {
118
+ * @Deprecated()
119
+ * @Get('/old-endpoint')
120
+ * oldEndpoint() {}
121
+ * }
122
+ *
123
+ * // Or deprecate entire controller
124
+ * @Deprecated()
125
+ * @ApiController('/api/v1/users')
126
+ * class LegacyUserController {}
127
+ * ```
128
+ */
129
+ export declare function Deprecated(): ClassDecorator & MethodDecorator;
130
+ /**
131
+ * Decorator that sets a unique operation ID for an operation.
132
+ * Operation IDs are used to uniquely identify operations in OpenAPI.
133
+ *
134
+ * @param operationId - Unique identifier for the operation
135
+ * @returns Method decorator
136
+ *
137
+ * @example
138
+ * ```typescript
139
+ * class UserController {
140
+ * @ApiOperationId('getUserById')
141
+ * @Get('/:id')
142
+ * getUser() {}
143
+ * }
144
+ * ```
145
+ */
146
+ export declare function ApiOperationId(operationId: string): MethodDecorator;
147
+ /**
148
+ * Decorator that adds an example to an operation.
149
+ * Examples can be for request bodies or responses.
150
+ * Multiple examples can be added by stacking decorators.
151
+ *
152
+ * @param options - Example options including value, name, and type
153
+ * @returns Method decorator
154
+ *
155
+ * @example
156
+ * ```typescript
157
+ * class UserController {
158
+ * @ApiExample({
159
+ * name: 'validUser',
160
+ * summary: 'A valid user object',
161
+ * value: { id: '123', name: 'John Doe', email: 'john@example.com' },
162
+ * type: 'response',
163
+ * statusCode: 200
164
+ * })
165
+ * @ApiExample({
166
+ * name: 'createUserRequest',
167
+ * summary: 'Create user request body',
168
+ * value: { name: 'Jane Doe', email: 'jane@example.com' },
169
+ * type: 'request'
170
+ * })
171
+ * @Post('/')
172
+ * createUser() {}
173
+ * }
174
+ * ```
175
+ */
176
+ export declare function ApiExample(options: ApiExampleDecoratorOptions): MethodDecorator;
177
+ /**
178
+ * Gets the effective OpenAPI metadata for a method, merging class-level and method-level settings.
179
+ * Method-level settings override class-level settings, except for tags which are merged.
180
+ *
181
+ * @param target - The class constructor
182
+ * @param propertyKey - The method name
183
+ * @returns The merged OpenAPI metadata
184
+ */
185
+ export declare function getEffectiveOpenAPIMetadata(target: object, propertyKey: string | symbol): OpenAPIMethodMetadata;
186
+ /**
187
+ * Gets the class-level OpenAPI metadata.
188
+ *
189
+ * @param target - The class constructor
190
+ * @returns The class-level OpenAPI metadata
191
+ */
192
+ export declare function getClassOpenAPIMetadata(target: object): OpenAPIClassMetadata | undefined;
193
+ /**
194
+ * Gets the method-level OpenAPI metadata without merging with class-level.
195
+ *
196
+ * @param target - The class constructor
197
+ * @param propertyKey - The method name
198
+ * @returns The method-level OpenAPI metadata
199
+ */
200
+ export declare function getMethodOpenAPIMetadata(target: object, propertyKey: string | symbol): OpenAPIMethodMetadata | undefined;
201
+ //# sourceMappingURL=openapi.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/decorators/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC7B,MAAM,wCAAwC,CAAC;AAShD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,0BAA0B,EAAE,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAqCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,4BAA4B,GACpC,cAAc,GAAG,eAAe,CAkClC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,eAAe,CA+B3E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAU3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAUnE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,IAAI,cAAc,GAAG,eAAe,CAa7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,0BAA0B,GAClC,eAAe,CAkBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,qBAAqB,CAuCvB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,GACb,oBAAoB,GAAG,SAAS,CAElC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,qBAAqB,GAAG,SAAS,CAMnC"}
@@ -0,0 +1,334 @@
1
+ "use strict";
2
+ /**
3
+ * @fileoverview OpenAPI operation decorators for Express Suite.
4
+ * Provides @ApiOperation, @ApiTags, @ApiSummary, @ApiDescription, @Deprecated,
5
+ * @ApiOperationId, and @ApiExample decorators for documenting API operations.
6
+ * Supports both class-level and method-level application.
7
+ * @module decorators/openapi
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ exports.ApiOperation = ApiOperation;
11
+ exports.ApiTags = ApiTags;
12
+ exports.ApiSummary = ApiSummary;
13
+ exports.ApiDescription = ApiDescription;
14
+ exports.Deprecated = Deprecated;
15
+ exports.ApiOperationId = ApiOperationId;
16
+ exports.ApiExample = ApiExample;
17
+ exports.getEffectiveOpenAPIMetadata = getEffectiveOpenAPIMetadata;
18
+ exports.getClassOpenAPIMetadata = getClassOpenAPIMetadata;
19
+ exports.getMethodOpenAPIMetadata = getMethodOpenAPIMetadata;
20
+ require("reflect-metadata");
21
+ const metadata_keys_1 = require("./metadata-keys");
22
+ const metadata_collector_1 = require("./metadata-collector");
23
+ /**
24
+ * Creates a decorator that can be applied to both classes and methods.
25
+ * @param applyMetadata - Function to apply the metadata
26
+ * @returns A decorator function
27
+ */
28
+ function createOpenAPIDecorator(applyMetadata) {
29
+ function decorator(target, propertyKey, descriptor) {
30
+ if (propertyKey !== undefined && descriptor !== undefined) {
31
+ // Method decorator
32
+ applyMetadata(target.constructor, propertyKey);
33
+ return descriptor;
34
+ }
35
+ else {
36
+ // Class decorator
37
+ applyMetadata(target);
38
+ return target;
39
+ }
40
+ }
41
+ return decorator;
42
+ }
43
+ /**
44
+ * Decorator that sets full OpenAPI operation metadata on a method.
45
+ * Can also be applied at class level to set default values for all methods.
46
+ *
47
+ * @param options - OpenAPI operation options
48
+ * @returns Class or method decorator
49
+ *
50
+ * @example
51
+ * ```typescript
52
+ * class UserController {
53
+ * @ApiOperation({
54
+ * summary: 'Get user by ID',
55
+ * description: 'Retrieves a user by their unique identifier',
56
+ * tags: ['Users'],
57
+ * operationId: 'getUserById',
58
+ * deprecated: false
59
+ * })
60
+ * @Get('/:id')
61
+ * getUser() {}
62
+ * }
63
+ * ```
64
+ */
65
+ function ApiOperation(options) {
66
+ return createOpenAPIDecorator((target, propertyKey) => {
67
+ if (propertyKey !== undefined) {
68
+ // Method-level: merge into OPENAPI_METADATA
69
+ const metadata = {
70
+ summary: options.summary,
71
+ description: options.description,
72
+ tags: options.tags,
73
+ operationId: options.operationId,
74
+ deprecated: options.deprecated,
75
+ };
76
+ // Remove undefined values
77
+ Object.keys(metadata).forEach((key) => {
78
+ if (metadata[key] === undefined) {
79
+ delete metadata[key];
80
+ }
81
+ });
82
+ (0, metadata_collector_1.deepMergeMetadata)(metadata_keys_1.OPENAPI_METADATA, metadata, target, propertyKey);
83
+ }
84
+ else {
85
+ // Class-level: merge into OPENAPI_CONTROLLER_METADATA
86
+ const metadata = {
87
+ tags: options.tags,
88
+ description: options.description,
89
+ deprecated: options.deprecated,
90
+ };
91
+ // Remove undefined values
92
+ Object.keys(metadata).forEach((key) => {
93
+ if (metadata[key] === undefined) {
94
+ delete metadata[key];
95
+ }
96
+ });
97
+ (0, metadata_collector_1.deepMergeMetadata)(metadata_keys_1.OPENAPI_CONTROLLER_METADATA, metadata, target);
98
+ }
99
+ });
100
+ }
101
+ /**
102
+ * Decorator that adds tags to an operation or all operations in a controller.
103
+ * Tags are used to group operations in OpenAPI documentation.
104
+ * When applied at method level, tags are added to (not replace) class-level tags.
105
+ *
106
+ * @param tags - One or more tags to add
107
+ * @returns Class or method decorator
108
+ *
109
+ * @example
110
+ * ```typescript
111
+ * @ApiTags('Users', 'Admin')
112
+ * @ApiController('/api/users')
113
+ * class UserController {
114
+ * @Get('/')
115
+ * listUsers() {} // Has tags: ['Users', 'Admin']
116
+ *
117
+ * @ApiTags('Public')
118
+ * @Get('/public')
119
+ * publicUsers() {} // Has tags: ['Users', 'Admin', 'Public']
120
+ * }
121
+ * ```
122
+ */
123
+ function ApiTags(...tags) {
124
+ return createOpenAPIDecorator((target, propertyKey) => {
125
+ if (propertyKey !== undefined) {
126
+ // Method-level: add to existing tags
127
+ const existing = (0, metadata_collector_1.getMetadataOrDefault)(metadata_keys_1.OPENAPI_METADATA, target, propertyKey, {});
128
+ const existingTags = existing.tags ?? [];
129
+ const mergedTags = [...existingTags, ...tags];
130
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_METADATA, { tags: mergedTags }, target, propertyKey);
131
+ }
132
+ else {
133
+ // Class-level: set tags
134
+ const existing = (0, metadata_collector_1.getMetadataOrDefault)(metadata_keys_1.OPENAPI_CONTROLLER_METADATA, target, undefined, {});
135
+ const existingTags = existing.tags ?? [];
136
+ const mergedTags = [...existingTags, ...tags];
137
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_CONTROLLER_METADATA, { tags: mergedTags }, target);
138
+ }
139
+ });
140
+ }
141
+ /**
142
+ * Decorator that sets the summary for an operation.
143
+ * The summary is a short description of the operation.
144
+ *
145
+ * @param summary - Short summary text
146
+ * @returns Method decorator
147
+ *
148
+ * @example
149
+ * ```typescript
150
+ * class UserController {
151
+ * @ApiSummary('Get user by ID')
152
+ * @Get('/:id')
153
+ * getUser() {}
154
+ * }
155
+ * ```
156
+ */
157
+ function ApiSummary(summary) {
158
+ return (target, propertyKey, descriptor) => {
159
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_METADATA, { summary }, target.constructor, propertyKey);
160
+ return descriptor;
161
+ };
162
+ }
163
+ /**
164
+ * Decorator that sets the description for an operation.
165
+ * The description provides detailed information about the operation.
166
+ *
167
+ * @param description - Detailed description text
168
+ * @returns Method decorator
169
+ *
170
+ * @example
171
+ * ```typescript
172
+ * class UserController {
173
+ * @ApiDescription('Retrieves a user by their unique identifier. Returns 404 if not found.')
174
+ * @Get('/:id')
175
+ * getUser() {}
176
+ * }
177
+ * ```
178
+ */
179
+ function ApiDescription(description) {
180
+ return (target, propertyKey, descriptor) => {
181
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_METADATA, { description }, target.constructor, propertyKey);
182
+ return descriptor;
183
+ };
184
+ }
185
+ /**
186
+ * Decorator that marks an operation or all operations in a controller as deprecated.
187
+ * Deprecated operations are still functional but should not be used in new code.
188
+ *
189
+ * @returns Class or method decorator
190
+ *
191
+ * @example
192
+ * ```typescript
193
+ * class UserController {
194
+ * @Deprecated()
195
+ * @Get('/old-endpoint')
196
+ * oldEndpoint() {}
197
+ * }
198
+ *
199
+ * // Or deprecate entire controller
200
+ * @Deprecated()
201
+ * @ApiController('/api/v1/users')
202
+ * class LegacyUserController {}
203
+ * ```
204
+ */
205
+ function Deprecated() {
206
+ return createOpenAPIDecorator((target, propertyKey) => {
207
+ if (propertyKey !== undefined) {
208
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_METADATA, { deprecated: true }, target, propertyKey);
209
+ }
210
+ else {
211
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_CONTROLLER_METADATA, { deprecated: true }, target);
212
+ }
213
+ });
214
+ }
215
+ /**
216
+ * Decorator that sets a unique operation ID for an operation.
217
+ * Operation IDs are used to uniquely identify operations in OpenAPI.
218
+ *
219
+ * @param operationId - Unique identifier for the operation
220
+ * @returns Method decorator
221
+ *
222
+ * @example
223
+ * ```typescript
224
+ * class UserController {
225
+ * @ApiOperationId('getUserById')
226
+ * @Get('/:id')
227
+ * getUser() {}
228
+ * }
229
+ * ```
230
+ */
231
+ function ApiOperationId(operationId) {
232
+ return (target, propertyKey, descriptor) => {
233
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_METADATA, { operationId }, target.constructor, propertyKey);
234
+ return descriptor;
235
+ };
236
+ }
237
+ /**
238
+ * Decorator that adds an example to an operation.
239
+ * Examples can be for request bodies or responses.
240
+ * Multiple examples can be added by stacking decorators.
241
+ *
242
+ * @param options - Example options including value, name, and type
243
+ * @returns Method decorator
244
+ *
245
+ * @example
246
+ * ```typescript
247
+ * class UserController {
248
+ * @ApiExample({
249
+ * name: 'validUser',
250
+ * summary: 'A valid user object',
251
+ * value: { id: '123', name: 'John Doe', email: 'john@example.com' },
252
+ * type: 'response',
253
+ * statusCode: 200
254
+ * })
255
+ * @ApiExample({
256
+ * name: 'createUserRequest',
257
+ * summary: 'Create user request body',
258
+ * value: { name: 'Jane Doe', email: 'jane@example.com' },
259
+ * type: 'request'
260
+ * })
261
+ * @Post('/')
262
+ * createUser() {}
263
+ * }
264
+ * ```
265
+ */
266
+ function ApiExample(options) {
267
+ return (target, propertyKey, descriptor) => {
268
+ const existing = (0, metadata_collector_1.getMetadataOrDefault)(metadata_keys_1.OPENAPI_METADATA, target.constructor, propertyKey, {});
269
+ const existingExamples = existing.examples ?? [];
270
+ existingExamples.push(options);
271
+ (0, metadata_collector_1.mergeMetadata)(metadata_keys_1.OPENAPI_METADATA, { examples: existingExamples }, target.constructor, propertyKey);
272
+ return descriptor;
273
+ };
274
+ }
275
+ /**
276
+ * Gets the effective OpenAPI metadata for a method, merging class-level and method-level settings.
277
+ * Method-level settings override class-level settings, except for tags which are merged.
278
+ *
279
+ * @param target - The class constructor
280
+ * @param propertyKey - The method name
281
+ * @returns The merged OpenAPI metadata
282
+ */
283
+ function getEffectiveOpenAPIMetadata(target, propertyKey) {
284
+ // Get class-level OpenAPI metadata
285
+ const classMetadata = (0, metadata_collector_1.getMetadata)(metadata_keys_1.OPENAPI_CONTROLLER_METADATA, target) ??
286
+ {};
287
+ // Get method-level OpenAPI metadata
288
+ const methodMetadata = (0, metadata_collector_1.getMetadata)(metadata_keys_1.OPENAPI_METADATA, target, propertyKey) ??
289
+ {};
290
+ // Merge tags (class tags + method tags)
291
+ const classTags = classMetadata.tags ?? [];
292
+ const methodTags = methodMetadata.tags ?? [];
293
+ const mergedTags = [...classTags, ...methodTags];
294
+ // Method-level overrides class-level for other fields
295
+ const merged = {
296
+ description: methodMetadata.description ?? classMetadata.description,
297
+ deprecated: methodMetadata.deprecated ?? classMetadata.deprecated,
298
+ summary: methodMetadata.summary,
299
+ operationId: methodMetadata.operationId,
300
+ examples: methodMetadata.examples,
301
+ };
302
+ // Only add tags if there are any
303
+ if (mergedTags.length > 0) {
304
+ // Remove duplicates while preserving order
305
+ merged.tags = [...new Set(mergedTags)];
306
+ }
307
+ // Remove undefined values
308
+ Object.keys(merged).forEach((key) => {
309
+ if (merged[key] === undefined) {
310
+ delete merged[key];
311
+ }
312
+ });
313
+ return merged;
314
+ }
315
+ /**
316
+ * Gets the class-level OpenAPI metadata.
317
+ *
318
+ * @param target - The class constructor
319
+ * @returns The class-level OpenAPI metadata
320
+ */
321
+ function getClassOpenAPIMetadata(target) {
322
+ return (0, metadata_collector_1.getMetadata)(metadata_keys_1.OPENAPI_CONTROLLER_METADATA, target);
323
+ }
324
+ /**
325
+ * Gets the method-level OpenAPI metadata without merging with class-level.
326
+ *
327
+ * @param target - The class constructor
328
+ * @param propertyKey - The method name
329
+ * @returns The method-level OpenAPI metadata
330
+ */
331
+ function getMethodOpenAPIMetadata(target, propertyKey) {
332
+ return (0, metadata_collector_1.getMetadata)(metadata_keys_1.OPENAPI_METADATA, target, propertyKey);
333
+ }
334
+ //# sourceMappingURL=openapi.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/decorators/openapi.ts"],"names":[],"mappings":"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"}