@skmtc/core 0.0.791 → 0.0.793

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 (113) hide show
  1. package/esm/dsl/GeneratedValueList.d.ts +158 -0
  2. package/esm/dsl/GeneratedValueList.d.ts.map +1 -1
  3. package/esm/dsl/GeneratedValueList.js +158 -0
  4. package/esm/dsl/Stringable.d.ts +76 -0
  5. package/esm/dsl/Stringable.d.ts.map +1 -1
  6. package/esm/dsl/Stringable.js +75 -0
  7. package/esm/helpers/collateExamples.d.ts +150 -0
  8. package/esm/helpers/collateExamples.d.ts.map +1 -1
  9. package/esm/helpers/collateExamples.js +145 -0
  10. package/esm/helpers/formatNumber.d.ts +95 -0
  11. package/esm/helpers/formatNumber.d.ts.map +1 -1
  12. package/esm/helpers/formatNumber.js +95 -0
  13. package/esm/helpers/generationStats.d.ts +287 -1
  14. package/esm/helpers/generationStats.d.ts.map +1 -1
  15. package/esm/helpers/generationStats.js +266 -0
  16. package/esm/helpers/isEmpty.d.ts +62 -0
  17. package/esm/helpers/isEmpty.d.ts.map +1 -1
  18. package/esm/helpers/isEmpty.js +62 -0
  19. package/esm/helpers/isImported.d.ts +80 -0
  20. package/esm/helpers/isImported.d.ts.map +1 -1
  21. package/esm/helpers/isImported.js +80 -0
  22. package/esm/helpers/naming.d.ts +65 -1
  23. package/esm/helpers/naming.d.ts.map +1 -1
  24. package/esm/helpers/naming.js +65 -1
  25. package/esm/helpers/parseModuleName.d.ts +175 -0
  26. package/esm/helpers/parseModuleName.d.ts.map +1 -1
  27. package/esm/helpers/parseModuleName.js +153 -0
  28. package/esm/helpers/toResolvedArtifactPath.d.ts +145 -0
  29. package/esm/helpers/toResolvedArtifactPath.d.ts.map +1 -1
  30. package/esm/helpers/toResolvedArtifactPath.js +140 -0
  31. package/esm/oas/example/Example.d.ts +81 -1
  32. package/esm/oas/example/Example.d.ts.map +1 -1
  33. package/esm/oas/example/Example.js +74 -1
  34. package/esm/oas/header/Header.d.ts +217 -1
  35. package/esm/oas/header/Header.d.ts.map +1 -1
  36. package/esm/oas/header/Header.js +207 -1
  37. package/esm/oas/info/Info.d.ts +72 -0
  38. package/esm/oas/info/Info.d.ts.map +1 -1
  39. package/esm/oas/info/Info.js +62 -0
  40. package/esm/oas/mediaType/MediaType.d.ts +85 -0
  41. package/esm/oas/mediaType/MediaType.d.ts.map +1 -1
  42. package/esm/oas/mediaType/MediaType.js +77 -0
  43. package/esm/oas/pathItem/PathItem.d.ts +92 -0
  44. package/esm/oas/pathItem/PathItem.d.ts.map +1 -1
  45. package/esm/oas/pathItem/PathItem.js +85 -0
  46. package/esm/oas/requestBody/RequestBody.d.ts +264 -0
  47. package/esm/oas/requestBody/RequestBody.d.ts.map +1 -1
  48. package/esm/oas/requestBody/RequestBody.js +257 -0
  49. package/esm/oas/schema/Schema.d.ts +117 -0
  50. package/esm/oas/schema/Schema.d.ts.map +1 -1
  51. package/esm/typescript/identifiers.d.ts +159 -0
  52. package/esm/typescript/identifiers.d.ts.map +1 -1
  53. package/esm/typescript/identifiers.js +159 -0
  54. package/esm/typescript/withDescription.d.ts +119 -0
  55. package/esm/typescript/withDescription.d.ts.map +1 -1
  56. package/esm/typescript/withDescription.js +119 -0
  57. package/package.json +1 -1
  58. package/script/dsl/GeneratedValueList.d.ts +158 -0
  59. package/script/dsl/GeneratedValueList.d.ts.map +1 -1
  60. package/script/dsl/GeneratedValueList.js +158 -0
  61. package/script/dsl/Stringable.d.ts +76 -0
  62. package/script/dsl/Stringable.d.ts.map +1 -1
  63. package/script/dsl/Stringable.js +75 -0
  64. package/script/helpers/collateExamples.d.ts +150 -0
  65. package/script/helpers/collateExamples.d.ts.map +1 -1
  66. package/script/helpers/collateExamples.js +145 -0
  67. package/script/helpers/formatNumber.d.ts +95 -0
  68. package/script/helpers/formatNumber.d.ts.map +1 -1
  69. package/script/helpers/formatNumber.js +95 -0
  70. package/script/helpers/generationStats.d.ts +287 -1
  71. package/script/helpers/generationStats.d.ts.map +1 -1
  72. package/script/helpers/generationStats.js +266 -0
  73. package/script/helpers/isEmpty.d.ts +62 -0
  74. package/script/helpers/isEmpty.d.ts.map +1 -1
  75. package/script/helpers/isEmpty.js +62 -0
  76. package/script/helpers/isImported.d.ts +80 -0
  77. package/script/helpers/isImported.d.ts.map +1 -1
  78. package/script/helpers/isImported.js +80 -0
  79. package/script/helpers/naming.d.ts +65 -1
  80. package/script/helpers/naming.d.ts.map +1 -1
  81. package/script/helpers/naming.js +65 -1
  82. package/script/helpers/parseModuleName.d.ts +175 -0
  83. package/script/helpers/parseModuleName.d.ts.map +1 -1
  84. package/script/helpers/parseModuleName.js +153 -0
  85. package/script/helpers/toResolvedArtifactPath.d.ts +145 -0
  86. package/script/helpers/toResolvedArtifactPath.d.ts.map +1 -1
  87. package/script/helpers/toResolvedArtifactPath.js +140 -0
  88. package/script/oas/example/Example.d.ts +81 -1
  89. package/script/oas/example/Example.d.ts.map +1 -1
  90. package/script/oas/example/Example.js +74 -1
  91. package/script/oas/header/Header.d.ts +217 -1
  92. package/script/oas/header/Header.d.ts.map +1 -1
  93. package/script/oas/header/Header.js +207 -1
  94. package/script/oas/info/Info.d.ts +72 -0
  95. package/script/oas/info/Info.d.ts.map +1 -1
  96. package/script/oas/info/Info.js +62 -0
  97. package/script/oas/mediaType/MediaType.d.ts +85 -0
  98. package/script/oas/mediaType/MediaType.d.ts.map +1 -1
  99. package/script/oas/mediaType/MediaType.js +77 -0
  100. package/script/oas/pathItem/PathItem.d.ts +92 -0
  101. package/script/oas/pathItem/PathItem.d.ts.map +1 -1
  102. package/script/oas/pathItem/PathItem.js +85 -0
  103. package/script/oas/requestBody/RequestBody.d.ts +264 -0
  104. package/script/oas/requestBody/RequestBody.d.ts.map +1 -1
  105. package/script/oas/requestBody/RequestBody.js +257 -0
  106. package/script/oas/schema/Schema.d.ts +117 -0
  107. package/script/oas/schema/Schema.d.ts.map +1 -1
  108. package/script/typescript/identifiers.d.ts +159 -0
  109. package/script/typescript/identifiers.d.ts.map +1 -1
  110. package/script/typescript/identifiers.js +159 -0
  111. package/script/typescript/withDescription.d.ts +119 -0
  112. package/script/typescript/withDescription.d.ts.map +1 -1
  113. package/script/typescript/withDescription.js +119 -0
@@ -1,5 +1,145 @@
1
1
  import "../_dnt.polyfills.js";
2
2
  import { join } from '../deps/jsr.io/@std/path/1.1.2/join.js';
3
+ /**
4
+ * Resolves artifact destination paths relative to a base directory.
5
+ *
6
+ * This utility function combines a base path with a destination path to create
7
+ * the final resolved file path for generated artifacts. It handles special path
8
+ * prefixes (like '@/') and provides sensible defaults when no base path is specified.
9
+ *
10
+ * The function is used throughout the rendering pipeline to determine the final
11
+ * file system locations for generated code artifacts, ensuring consistent path
12
+ * resolution across different operating systems and deployment scenarios.
13
+ *
14
+ * @param args - Path resolution configuration
15
+ * @param args.basePath - Base directory path (defaults to './' if undefined)
16
+ * @param args.destinationPath - Destination path for the artifact
17
+ * @returns The resolved absolute or relative path for the artifact
18
+ *
19
+ * @example Basic path resolution
20
+ * ```typescript
21
+ * import { toResolvedArtifactPath } from '@skmtc/core';
22
+ *
23
+ * // With explicit base path
24
+ * const resolved1 = toResolvedArtifactPath({
25
+ * basePath: './src/generated',
26
+ * destinationPath: 'models/User.ts'
27
+ * });
28
+ * console.log(resolved1); // './src/generated/models/User.ts'
29
+ *
30
+ * // With undefined base path (uses default)
31
+ * const resolved2 = toResolvedArtifactPath({
32
+ * basePath: undefined,
33
+ * destinationPath: 'types.ts'
34
+ * });
35
+ * console.log(resolved2); // './types.ts'
36
+ * ```
37
+ *
38
+ * @example Special path prefix handling
39
+ * ```typescript
40
+ * // '@/' prefix gets stripped and resolved relative to base
41
+ * const resolved = toResolvedArtifactPath({
42
+ * basePath: './output',
43
+ * destinationPath: '@/api/models.ts'
44
+ * });
45
+ * console.log(resolved); // './output/api/models.ts'
46
+ *
47
+ * // Regular paths work normally
48
+ * const normal = toResolvedArtifactPath({
49
+ * basePath: './build',
50
+ * destinationPath: 'components/Button.tsx'
51
+ * });
52
+ * console.log(normal); // './build/components/Button.tsx'
53
+ * ```
54
+ *
55
+ * @example Cross-platform path resolution
56
+ * ```typescript
57
+ * // Works consistently across platforms
58
+ * const windowsPath = toResolvedArtifactPath({
59
+ * basePath: 'C:\\projects\\app\\dist',
60
+ * destinationPath: 'utils/helpers.js'
61
+ * });
62
+ *
63
+ * const unixPath = toResolvedArtifactPath({
64
+ * basePath: '/home/user/projects/app/dist',
65
+ * destinationPath: 'utils/helpers.js'
66
+ * });
67
+ * ```
68
+ *
69
+ * @example Usage in file generation
70
+ * ```typescript
71
+ * class ArtifactWriter {
72
+ * writeArtifact(
73
+ * content: string,
74
+ * destination: string,
75
+ * baseDir?: string
76
+ * ) {
77
+ * const resolvedPath = toResolvedArtifactPath({
78
+ * basePath: baseDir,
79
+ * destinationPath: destination
80
+ * });
81
+ *
82
+ * console.log(`Writing to: ${resolvedPath}`);
83
+ * return Deno.writeTextFile(resolvedPath, content);
84
+ * }
85
+ * }
86
+ *
87
+ * const writer = new ArtifactWriter();
88
+ * await writer.writeArtifact(
89
+ * 'export const greeting = "Hello";',
90
+ * '@/constants.ts',
91
+ * './src/generated'
92
+ * );
93
+ * // Writes to: ./src/generated/constants.ts
94
+ * ```
95
+ *
96
+ * @example Integration with rendering pipeline
97
+ * ```typescript
98
+ * class FileRenderer {
99
+ * renderFiles(
100
+ * files: Map<string, File>,
101
+ * outputDir: string
102
+ * ): Record<string, string> {
103
+ * const artifacts: Record<string, string> = {};
104
+ *
105
+ * for (const [destPath, file] of files) {
106
+ * const resolvedPath = toResolvedArtifactPath({
107
+ * basePath: outputDir,
108
+ * destinationPath: destPath
109
+ * });
110
+ *
111
+ * artifacts[resolvedPath] = file.toString();
112
+ * }
113
+ *
114
+ * return artifacts;
115
+ * }
116
+ * }
117
+ * ```
118
+ *
119
+ * @example Dynamic base path resolution
120
+ * ```typescript
121
+ * function resolveForEnvironment(
122
+ * destination: string,
123
+ * env: 'development' | 'production'
124
+ * ): string {
125
+ * const basePaths = {
126
+ * development: './dev-output',
127
+ * production: './dist'
128
+ * };
129
+ *
130
+ * return toResolvedArtifactPath({
131
+ * basePath: basePaths[env],
132
+ * destinationPath: destination
133
+ * });
134
+ * }
135
+ *
136
+ * const devPath = resolveForEnvironment('api.ts', 'development');
137
+ * const prodPath = resolveForEnvironment('api.ts', 'production');
138
+ *
139
+ * console.log(devPath); // './dev-output/api.ts'
140
+ * console.log(prodPath); // './dist/api.ts'
141
+ * ```
142
+ */
3
143
  export const toResolvedArtifactPath = ({ basePath, destinationPath }) => {
4
144
  return join(basePath ?? './', destinationPath.replace(/^@\//, ''));
5
145
  };
@@ -1,13 +1,93 @@
1
1
  import type { OasRef } from '../ref/Ref.js';
2
2
  import type { ToJsonSchemaOptions } from '../schema/Schema.js';
3
3
  import type { OpenAPIV3 } from 'openapi-types';
4
+ /**
5
+ * Constructor fields for {@link OasExample}.
6
+ */
4
7
  export type ExampleFields = {
8
+ /** Short summary of the example */
5
9
  summary: string | undefined;
10
+ /** Longer description of the example */
6
11
  description: string | undefined;
12
+ /** The example value */
7
13
  value: unknown;
14
+ /** Custom extension fields (x-* properties) */
8
15
  extensionFields?: Record<string, unknown>;
9
16
  };
10
- /** Provides example data represented by schema */
17
+ /**
18
+ * Represents an Example Object in the OpenAPI Specification.
19
+ *
20
+ * The `OasExample` class provides sample data for parameters, request bodies,
21
+ * responses, and other components in an OpenAPI document. Examples are crucial
22
+ * for API documentation, testing, and helping developers understand expected
23
+ * data formats and structures.
24
+ *
25
+ * This class supports rich example definitions with metadata, making API
26
+ * documentation more informative and interactive for developers.
27
+ *
28
+ * ## Key Features
29
+ *
30
+ * - **Sample Data**: Concrete examples of API inputs and outputs
31
+ * - **Documentation**: Summary and description for context
32
+ * - **Type Flexibility**: Supports any data type as example values
33
+ * - **Reference Support**: Can be referenced from multiple locations
34
+ * - **Markdown Support**: Rich text descriptions with CommonMark
35
+ *
36
+ * @example Simple string example
37
+ * ```typescript
38
+ * import { OasExample } from '@skmtc/core';
39
+ *
40
+ * const nameExample = new OasExample({
41
+ * summary: 'Typical user name',
42
+ * description: 'A common first and last name combination',
43
+ * value: 'John Doe'
44
+ * });
45
+ * ```
46
+ *
47
+ * @example JSON object example
48
+ * ```typescript
49
+ * const userExample = new OasExample({
50
+ * summary: 'Complete user profile',
51
+ * description: 'Example user with all profile fields populated',
52
+ * value: {
53
+ * id: 12345,
54
+ * name: 'Jane Smith',
55
+ * email: 'jane.smith@example.com',
56
+ * active: true,
57
+ * createdAt: '2023-01-15T10:30:00Z'
58
+ * }
59
+ * });
60
+ * ```
61
+ *
62
+ * @example Array example with multiple items
63
+ * ```typescript
64
+ * const productsExample = new OasExample({
65
+ * summary: 'Product list sample',
66
+ * description: 'Typical response for product catalog endpoint',
67
+ * value: [
68
+ * { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
69
+ * { id: 2, name: 'Book', price: 19.99, category: 'Education' },
70
+ * { id: 3, name: 'Coffee Mug', price: 12.50, category: 'Home' }
71
+ * ]
72
+ * });
73
+ * ```
74
+ *
75
+ * @example Error response example
76
+ * ```typescript
77
+ * const errorExample = new OasExample({
78
+ * summary: 'Validation error',
79
+ * description: 'Response when request validation fails',
80
+ * value: {
81
+ * error: 'Validation failed',
82
+ * code: 'INVALID_INPUT',
83
+ * details: [
84
+ * { field: 'email', message: 'Invalid email format' },
85
+ * { field: 'age', message: 'Must be between 18 and 120' }
86
+ * ]
87
+ * }
88
+ * });
89
+ * ```
90
+ */
11
91
  export declare class OasExample {
12
92
  #private;
13
93
  /** Static identifier property for OasExample */
@@ -1 +1 @@
1
- {"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,kDAAkD;AAClD,qBAAa,UAAU;;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;gBAIlB,MAAM,EAAE,aAAa;IAIjC,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,2EAA2E;IAC3E,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,6BAA6B;IAC7B,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAOrE"}
1
+ {"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,mCAAmC;IACnC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,wCAAwC;IACxC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,wBAAwB;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,qBAAa,UAAU;;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;gBAIlB,MAAM,EAAE,aAAa;IAIjC,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,2EAA2E;IAC3E,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,6BAA6B;IAC7B,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAOrE"}
@@ -10,7 +10,80 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
12
  var _OasExample_fields;
13
- /** Provides example data represented by schema */
13
+ /**
14
+ * Represents an Example Object in the OpenAPI Specification.
15
+ *
16
+ * The `OasExample` class provides sample data for parameters, request bodies,
17
+ * responses, and other components in an OpenAPI document. Examples are crucial
18
+ * for API documentation, testing, and helping developers understand expected
19
+ * data formats and structures.
20
+ *
21
+ * This class supports rich example definitions with metadata, making API
22
+ * documentation more informative and interactive for developers.
23
+ *
24
+ * ## Key Features
25
+ *
26
+ * - **Sample Data**: Concrete examples of API inputs and outputs
27
+ * - **Documentation**: Summary and description for context
28
+ * - **Type Flexibility**: Supports any data type as example values
29
+ * - **Reference Support**: Can be referenced from multiple locations
30
+ * - **Markdown Support**: Rich text descriptions with CommonMark
31
+ *
32
+ * @example Simple string example
33
+ * ```typescript
34
+ * import { OasExample } from '@skmtc/core';
35
+ *
36
+ * const nameExample = new OasExample({
37
+ * summary: 'Typical user name',
38
+ * description: 'A common first and last name combination',
39
+ * value: 'John Doe'
40
+ * });
41
+ * ```
42
+ *
43
+ * @example JSON object example
44
+ * ```typescript
45
+ * const userExample = new OasExample({
46
+ * summary: 'Complete user profile',
47
+ * description: 'Example user with all profile fields populated',
48
+ * value: {
49
+ * id: 12345,
50
+ * name: 'Jane Smith',
51
+ * email: 'jane.smith@example.com',
52
+ * active: true,
53
+ * createdAt: '2023-01-15T10:30:00Z'
54
+ * }
55
+ * });
56
+ * ```
57
+ *
58
+ * @example Array example with multiple items
59
+ * ```typescript
60
+ * const productsExample = new OasExample({
61
+ * summary: 'Product list sample',
62
+ * description: 'Typical response for product catalog endpoint',
63
+ * value: [
64
+ * { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
65
+ * { id: 2, name: 'Book', price: 19.99, category: 'Education' },
66
+ * { id: 3, name: 'Coffee Mug', price: 12.50, category: 'Home' }
67
+ * ]
68
+ * });
69
+ * ```
70
+ *
71
+ * @example Error response example
72
+ * ```typescript
73
+ * const errorExample = new OasExample({
74
+ * summary: 'Validation error',
75
+ * description: 'Response when request validation fails',
76
+ * value: {
77
+ * error: 'Validation failed',
78
+ * code: 'INVALID_INPUT',
79
+ * details: [
80
+ * { field: 'email', message: 'Invalid email format' },
81
+ * { field: 'age', message: 'Must be between 18 and 120' }
82
+ * ]
83
+ * }
84
+ * });
85
+ * ```
86
+ */
14
87
  export class OasExample {
15
88
  constructor(fields) {
16
89
  /** Static identifier property for OasExample */
@@ -4,16 +4,232 @@ import type { OasExample } from '../example/Example.js';
4
4
  import type { OasSchema } from '../schema/Schema.js';
5
5
  import type { ToJsonSchemaOptions } from '../schema/Schema.js';
6
6
  import type { OpenAPIV3 } from 'openapi-types';
7
+ /**
8
+ * Constructor fields for {@link OasHeader}.
9
+ */
7
10
  export type HeaderFields = {
11
+ /** A brief description of the header */
8
12
  description: string | undefined;
13
+ /** Whether the header is required */
9
14
  required: boolean | undefined;
15
+ /** Whether the header is deprecated */
10
16
  deprecated: boolean | undefined;
17
+ /** Schema defining the header's data type */
11
18
  schema: OasSchema | OasRef<'schema'> | undefined;
19
+ /** Example values for the header */
12
20
  examples: Record<string, OasExample | OasRef<'example'>> | undefined;
21
+ /** Content definitions for complex header values */
13
22
  content: Record<string, OasMediaType> | undefined;
23
+ /** Custom extension fields (x-* properties) */
14
24
  extensionFields?: Record<string, unknown>;
15
25
  };
16
- /** Describes a single header in the API */
26
+ /**
27
+ * Represents a Header Object in the OpenAPI Specification.
28
+ *
29
+ * The `OasHeader` class encapsulates the definition of a single HTTP header that
30
+ * can be sent with responses or expected in requests. Headers provide additional
31
+ * metadata about the HTTP message and can include authentication tokens, content
32
+ * information, pagination data, rate limiting details, and more.
33
+ *
34
+ * This class provides comprehensive support for header definitions with typed
35
+ * values, validation schemas, examples, and documentation.
36
+ *
37
+ * ## Key Features
38
+ *
39
+ * - **Schema Validation**: Typed header values through schema definitions
40
+ * - **Examples**: Multiple example values for documentation and testing
41
+ * - **Content Types**: Support for complex header values with media types
42
+ * - **Deprecation Support**: Mark headers as deprecated with proper warnings
43
+ * - **Required/Optional**: Control whether headers are mandatory
44
+ * - **Documentation**: Rich description support for API documentation
45
+ *
46
+ * @example Basic authentication header
47
+ * ```typescript
48
+ * import { OasHeader, OasString } from '@skmtc/core';
49
+ *
50
+ * const authHeader = new OasHeader({
51
+ * description: 'Bearer token for API authentication',
52
+ * required: true,
53
+ * schema: new OasString({
54
+ * pattern: '^Bearer [A-Za-z0-9+/=]+$',
55
+ * description: 'JWT bearer token'
56
+ * }),
57
+ * examples: {
58
+ * valid: new OasExample({
59
+ * summary: 'Valid bearer token',
60
+ * value: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
61
+ * })
62
+ * }
63
+ * });
64
+ * ```
65
+ *
66
+ * @example Pagination headers
67
+ * ```typescript
68
+ * const totalCountHeader = new OasHeader({
69
+ * description: 'Total number of items available',
70
+ * required: false,
71
+ * schema: new OasInteger({
72
+ * minimum: 0,
73
+ * description: 'Non-negative integer count'
74
+ * }),
75
+ * examples: {
76
+ * empty: new OasExample({ value: 0, description: 'No items' }),
77
+ * normal: new OasExample({ value: 150, description: 'Normal case' }),
78
+ * large: new OasExample({ value: 10000, description: 'Large dataset' })
79
+ * }
80
+ * });
81
+ *
82
+ * const linkHeader = new OasHeader({
83
+ * description: 'Pagination links (RFC 5988)',
84
+ * required: false,
85
+ * schema: new OasString({
86
+ * description: 'Comma-separated list of link relations'
87
+ * }),
88
+ * examples: {
89
+ * withNext: new OasExample({
90
+ * value: '</api/users?page=2>; rel="next", </api/users?page=10>; rel="last"'
91
+ * }),
92
+ * lastPage: new OasExample({
93
+ * value: '</api/users?page=9>; rel="prev", </api/users?page=1>; rel="first"'
94
+ * })
95
+ * }
96
+ * });
97
+ * ```
98
+ *
99
+ * @example Content type and encoding headers
100
+ * ```typescript
101
+ * const contentTypeHeader = new OasHeader({
102
+ * description: 'MIME type of the response content',
103
+ * required: true,
104
+ * schema: new OasString({
105
+ * enum: [
106
+ * 'application/json',
107
+ * 'application/xml',
108
+ * 'text/csv',
109
+ * 'application/pdf',
110
+ * 'application/octet-stream'
111
+ * ]
112
+ * }),
113
+ * examples: {
114
+ * json: new OasExample({ value: 'application/json' }),
115
+ * xml: new OasExample({ value: 'application/xml' }),
116
+ * csv: new OasExample({ value: 'text/csv' })
117
+ * }
118
+ * });
119
+ *
120
+ * const contentLengthHeader = new OasHeader({
121
+ * description: 'Size of the response body in bytes',
122
+ * required: false,
123
+ * schema: new OasInteger({
124
+ * minimum: 0,
125
+ * description: 'Content size in bytes'
126
+ * })
127
+ * });
128
+ * ```
129
+ *
130
+ * @example Rate limiting headers
131
+ * ```typescript
132
+ * const rateLimitHeader = new OasHeader({
133
+ * description: 'Number of requests remaining in the current window',
134
+ * required: false,
135
+ * schema: new OasInteger({
136
+ * minimum: 0,
137
+ * description: 'Remaining request count'
138
+ * }),
139
+ * examples: {
140
+ * available: new OasExample({ value: 95, description: '95 requests remaining' }),
141
+ * depleted: new OasExample({ value: 0, description: 'Rate limit reached' })
142
+ * }
143
+ * });
144
+ *
145
+ * const rateLimitResetHeader = new OasHeader({
146
+ * description: 'Unix timestamp when the rate limit window resets',
147
+ * required: false,
148
+ * schema: new OasInteger({
149
+ * minimum: 0,
150
+ * description: 'Unix timestamp in seconds'
151
+ * }),
152
+ * examples: {
153
+ * reset: new OasExample({
154
+ * value: 1634567890,
155
+ * description: 'Reset at 2021-10-18 12:31:30 UTC'
156
+ * })
157
+ * }
158
+ * });
159
+ * ```
160
+ *
161
+ * @example Custom application headers
162
+ * ```typescript
163
+ * const requestIdHeader = new OasHeader({
164
+ * description: 'Unique identifier for request tracing',
165
+ * required: false,
166
+ * schema: new OasString({
167
+ * format: 'uuid',
168
+ * description: 'UUID v4 request identifier'
169
+ * }),
170
+ * examples: {
171
+ * uuid: new OasExample({
172
+ * value: '123e4567-e89b-12d3-a456-426614174000',
173
+ * description: 'Request tracking ID'
174
+ * })
175
+ * }
176
+ * });
177
+ *
178
+ * const serverTimingHeader = new OasHeader({
179
+ * description: 'Server-side performance metrics',
180
+ * required: false,
181
+ * schema: new OasString({
182
+ * description: 'Server-Timing header format (RFC 8760)'
183
+ * }),
184
+ * examples: {
185
+ * timing: new OasExample({
186
+ * value: 'db;dur=53, app;dur=47.2',
187
+ * description: 'Database took 53ms, app logic 47.2ms'
188
+ * })
189
+ * }
190
+ * });
191
+ * ```
192
+ *
193
+ * @example Deprecated header
194
+ * ```typescript
195
+ * const deprecatedHeader = new OasHeader({
196
+ * description: 'Legacy API version header (deprecated)',
197
+ * required: false,
198
+ * deprecated: true,
199
+ * schema: new OasString({
200
+ * enum: ['v1', 'v2'],
201
+ * description: 'Use Accept or Content-Type header instead'
202
+ * }),
203
+ * examples: {
204
+ * legacy: new OasExample({
205
+ * value: 'v1',
206
+ * description: 'Legacy version (use Accept header instead)'
207
+ * })
208
+ * }
209
+ * });
210
+ * ```
211
+ *
212
+ * @example Using in response definitions
213
+ * ```typescript
214
+ * const successResponse = new OasResponse({
215
+ * description: 'Paginated user list',
216
+ * headers: {
217
+ * 'X-Total-Count': totalCountHeader,
218
+ * 'Link': linkHeader,
219
+ * 'X-Rate-Limit-Remaining': rateLimitHeader,
220
+ * 'X-Rate-Limit-Reset': rateLimitResetHeader,
221
+ * 'X-Request-ID': requestIdHeader
222
+ * },
223
+ * content: {
224
+ * 'application/json': new OasMediaType({
225
+ * schema: new OasArray({
226
+ * items: new OasRef({ $ref: '#/components/schemas/User' })
227
+ * })
228
+ * })
229
+ * }
230
+ * });
231
+ * ```
232
+ */
17
233
  export declare class OasHeader {
18
234
  #private;
19
235
  oasType: 'header';
@@ -1 +1 @@
1
- {"version":3,"file":"Header.d.ts","sourceRoot":"","sources":["../../../src/oas/header/Header.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IAC/B,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACpE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,2CAA2C;AAC3C,qBAAa,SAAS;;IACpB,OAAO,EAAE,QAAQ,CAAW;gBAGhB,MAAM,EAAE,YAAY;IAIhC,kCAAkC;IAClC,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,iEAAiE;IACjE,IAAI,QAAQ,IAAI,OAAO,GAAG,SAAS,CAElC;IAED,6FAA6F;IAC7F,IAAI,UAAU,IAAI,OAAO,GAAG,SAAS,CAEpC;IAED,4BAA4B;IAC5B,IAAI,MAAM,IAAI,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAErD;IAED,6BAA6B;IAC7B,IAAI,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAEzE;IAED,4BAA4B;IAC5B,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAEtD;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,qBAAqB;IACrB,OAAO,IAAI,SAAS;IAIpB,WAAW,IAAI,SAAS;IAIxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,GAAE,MAA2B,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC;IAc9E,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,YAAY;CASnE"}
1
+ {"version":3,"file":"Header.d.ts","sourceRoot":"","sources":["../../../src/oas/header/Header.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,wCAAwC;IACxC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,qCAAqC;IACrC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,uCAAuC;IACvC,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IAC/B,6CAA6C;IAC7C,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAChD,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACpE,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IACjD,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8MG;AACH,qBAAa,SAAS;;IACpB,OAAO,EAAE,QAAQ,CAAW;gBAGhB,MAAM,EAAE,YAAY;IAIhC,kCAAkC;IAClC,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,iEAAiE;IACjE,IAAI,QAAQ,IAAI,OAAO,GAAG,SAAS,CAElC;IAED,6FAA6F;IAC7F,IAAI,UAAU,IAAI,OAAO,GAAG,SAAS,CAEpC;IAED,4BAA4B;IAC5B,IAAI,MAAM,IAAI,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAErD;IAED,6BAA6B;IAC7B,IAAI,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAEzE;IAED,4BAA4B;IAC5B,IAAI,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAEtD;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,qBAAqB;IACrB,OAAO,IAAI,SAAS;IAIpB,WAAW,IAAI,SAAS;IAIxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,GAAE,MAA2B,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC;IAc9E,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,YAAY;CASnE"}