Skip to content

Commit bdd5ddb

Browse files
kristianjfKristian Francisco
kristianjf
and
Kristian Francisco
authored
feat(openapi-typescript): add transformProperty hook for property signature modification (#2449)
* feat(openapi-typescript): add transformProperty hook for property signature modification Adds a new transformProperty hook that allows users to modify individual property signatures within Schema Objects. This enables adding JSDoc validation annotations and other property-level modifications that can't be achieved with existing transform/postTransform hooks. Features: - New transformProperty option in OpenAPITSOptions - Hook integration in schema-object transformer - Comprehensive documentation with JSDoc validation examples - Test coverage for JSDoc annotations and edge cases Resolves #2448 * chore: add changeset for transformProperty hook feature * fix: apply linting fixes for transformProperty feature - Format transformProperty type definition for better readability - Apply biome formatting to feature-related test code - Keep changes focused only on transformProperty feature files --------- Co-authored-by: Kristian Francisco <[email protected]>
1 parent 0f22be2 commit bdd5ddb

File tree

7 files changed

+341
-10
lines changed

7 files changed

+341
-10
lines changed

‎.changeset/bright-spies-rescue.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"openapi-typescript": minor
3+
---
4+
5+
Add transformProperty hook for property signature modification

‎docs/node.md‎

Lines changed: 144 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -83,13 +83,14 @@ const ast = await openapiTS(mySchema, { redocly });
8383

8484
The Node API supports all the [CLI flags](/cli#flags) in `camelCase` format, plus the following additional options:
8585

86-
| Name | Type | Default | Description |
87-
| :-------------- | :-------------: | :-------------: | :------------------------------------------------------------------------------------------- |
88-
| `transform` | `Function` | | Override the default Schema Object ➝ TypeScript transformer in certain scenarios |
89-
| `postTransform` | `Function` | | Same as `transform` but runs _after_ the TypeScript transformation |
90-
| `silent` | `boolean` | `false` | Silence warning messages (fatal errors will still show) |
91-
| `cwd` | `string \| URL` | `process.cwd()` | (optional) Provide the current working directory to help resolve remote `$ref`s (if needed). |
92-
| `inject` | `string` | | Inject arbitrary TypeScript types into the start of the file |
86+
| Name | Type | Default | Description |
87+
| :----------------- | :-------------: | :-------------: | :------------------------------------------------------------------------------------------- |
88+
| `transform` | `Function` | | Override the default Schema Object ➝ TypeScript transformer in certain scenarios |
89+
| `postTransform` | `Function` | | Same as `transform` but runs _after_ the TypeScript transformation |
90+
| `transformProperty`| `Function` | | Transform individual property signatures for Schema Object properties |
91+
| `silent` | `boolean` | `false` | Silence warning messages (fatal errors will still show) |
92+
| `cwd` | `string \| URL` | `process.cwd()` | (optional) Provide the current working directory to help resolve remote `$ref`s (if needed). |
93+
| `inject` | `string` | | Inject arbitrary TypeScript types into the start of the file |
9394

9495
### transform / postTransform
9596

@@ -254,4 +255,139 @@ file?: Blob | null; // [!code ++]
254255

255256
Any [Schema Object](https://spec.openapis.org/oas/latest.html#schema-object) present in your schema will be run through this formatter (even remote ones!). Also be sure to check the `metadata` parameter for additional context that may be helpful.
256257

257-
There are many other uses for this besides checking `format`. Because this must return a **string** you can produce any arbitrary TypeScript code you’d like (even your own custom types).
258+
There are many other uses for this besides checking `format`. Because this must return a **string** you can produce any arbitrary TypeScript code you'd like (even your own custom types).
259+
260+
### transformProperty
261+
262+
Use the `transformProperty()` option to modify individual property signatures within Schema Objects. This is particularly useful for adding JSDoc comments, validation annotations, or modifying property-level attributes that can't be achieved with `transform` or `postTransform`.
263+
264+
- `transformProperty()` runs **after** type conversion but **before** JSDoc comments are added
265+
- It receives the property signature, the original schema object, and transformation options
266+
- It should return a modified `PropertySignature` or `undefined` to leave the property unchanged
267+
268+
#### Example: JSDoc validation annotations
269+
270+
A common use case is adding validation annotations based on OpenAPI schema constraints:
271+
272+
::: code-group
273+
274+
```yaml [my-openapi-3-schema.yaml]
275+
components:
276+
schemas:
277+
User:
278+
type: object
279+
properties:
280+
name:
281+
type: string
282+
minLength: 1
283+
pattern: "^[a-zA-Z0-9]+$"
284+
email:
285+
type: string
286+
format: email
287+
age:
288+
type: integer
289+
minimum: 0
290+
maximum: 120
291+
required: [name, email]
292+
```
293+
294+
:::
295+
296+
::: code-group
297+
298+
```ts [src/my-project.ts]
299+
import fs from "node:fs";
300+
import ts from "typescript";
301+
import openapiTS, { astToString } from "openapi-typescript";
302+
303+
const ast = await openapiTS(mySchema, {
304+
transformProperty(property, schemaObject, options) {
305+
const validationTags: string[] = [];
306+
307+
// Add validation JSDoc tags based on schema constraints
308+
if (schemaObject.minLength !== undefined) {
309+
validationTags.push(`@minLength ${schemaObject.minLength}`);
310+
}
311+
if (schemaObject.maxLength !== undefined) {
312+
validationTags.push(`@maxLength ${schemaObject.maxLength}`);
313+
}
314+
if (schemaObject.minimum !== undefined) {
315+
validationTags.push(`@minimum ${schemaObject.minimum}`);
316+
}
317+
if (schemaObject.maximum !== undefined) {
318+
validationTags.push(`@maximum ${schemaObject.maximum}`);
319+
}
320+
if (schemaObject.pattern !== undefined) {
321+
validationTags.push(`@pattern ${schemaObject.pattern}`);
322+
}
323+
if (schemaObject.format !== undefined) {
324+
validationTags.push(`@format ${schemaObject.format}`);
325+
}
326+
327+
// If we have validation tags, add them as JSDoc comments
328+
if (validationTags.length > 0) {
329+
// Create a new property signature
330+
const newProperty = ts.factory.updatePropertySignature(
331+
property,
332+
property.modifiers,
333+
property.name,
334+
property.questionToken,
335+
property.type,
336+
);
337+
338+
// Add JSDoc comment
339+
const jsDocText = `*\n * ${validationTags.join('\n * ')}\n `;
340+
341+
ts.addSyntheticLeadingComment(
342+
newProperty,
343+
ts.SyntaxKind.MultiLineCommentTrivia,
344+
jsDocText,
345+
true,
346+
);
347+
348+
return newProperty;
349+
}
350+
351+
return property;
352+
},
353+
});
354+
355+
const contents = astToString(ast);
356+
fs.writeFileSync("./my-schema.ts", contents);
357+
```
358+
359+
:::
360+
361+
This transforms the schema into TypeScript with validation annotations:
362+
363+
::: code-group
364+
365+
```ts [my-schema.d.ts]
366+
export interface components {
367+
schemas: {
368+
User: {
369+
/**
370+
* @minLength 1
371+
* @pattern ^[a-zA-Z0-9]+$
372+
*/
373+
name: string;
374+
/**
375+
* @format email
376+
*/
377+
email: string;
378+
/**
379+
* @minimum 0
380+
* @maximum 120
381+
*/
382+
age?: number;
383+
};
384+
};
385+
}
386+
```
387+
388+
:::
389+
390+
The `transformProperty` function provides access to:
391+
- `property`: The TypeScript PropertySignature AST node
392+
- `schemaObject`: The original OpenAPI Schema Object for this property
393+
- `options`: Transformation context including path information and other utilities

‎packages/openapi-typescript/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ export default async function openapiTS(
8989
silent: options.silent ?? false,
9090
inject: options.inject ?? undefined,
9191
transform: typeof options.transform === "function" ? options.transform : undefined,
92+
transformProperty: typeof options.transformProperty === "function" ? options.transformProperty : undefined,
9293
makePathsEnum: options.makePathsEnum ?? false,
9394
generatePathParams: options.generatePathParams ?? false,
9495
resolve($ref) {

‎packages/openapi-typescript/src/transform/schema-object.ts‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -502,14 +502,26 @@ function transformSchemaObjectCore(schemaObject: SchemaObject, options: Transfor
502502
}
503503
}
504504

505-
const property = ts.factory.createPropertySignature(
505+
let property = ts.factory.createPropertySignature(
506506
/* modifiers */ tsModifiers({
507507
readonly: options.ctx.immutable || readOnly,
508508
}),
509509
/* name */ tsPropertyIndex(k),
510510
/* questionToken */ optional,
511511
/* type */ type,
512512
);
513+
514+
// Apply transformProperty hook if available
515+
if (typeof options.ctx.transformProperty === "function") {
516+
const result = options.ctx.transformProperty(property, v as SchemaObject, {
517+
...options,
518+
path: createRef([options.path, k]),
519+
});
520+
if (result) {
521+
property = result;
522+
}
523+
}
524+
513525
addJSDocComment(v, property);
514526
coreObjectType.push(property);
515527
}
@@ -519,7 +531,7 @@ function transformSchemaObjectCore(schemaObject: SchemaObject, options: Transfor
519531
if (schemaObject.$defs && typeof schemaObject.$defs === "object" && Object.keys(schemaObject.$defs).length) {
520532
const defKeys: ts.TypeElement[] = [];
521533
for (const [k, v] of Object.entries(schemaObject.$defs)) {
522-
const property = ts.factory.createPropertySignature(
534+
let property = ts.factory.createPropertySignature(
523535
/* modifiers */ tsModifiers({
524536
readonly: options.ctx.immutable || ("readonly" in v && !!v.readOnly),
525537
}),
@@ -530,6 +542,18 @@ function transformSchemaObjectCore(schemaObject: SchemaObject, options: Transfor
530542
path: createRef([options.path, "$defs", k]),
531543
}),
532544
);
545+
546+
// Apply transformProperty hook if available
547+
if (typeof options.ctx.transformProperty === "function") {
548+
const result = options.ctx.transformProperty(property, v as SchemaObject, {
549+
...options,
550+
path: createRef([options.path, "$defs", k]),
551+
});
552+
if (result) {
553+
property = result;
554+
}
555+
}
556+
533557
addJSDocComment(v, property);
534558
defKeys.push(property);
535559
}

‎packages/openapi-typescript/src/types.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -640,6 +640,12 @@ export interface OpenAPITSOptions {
640640
transform?: (schemaObject: SchemaObject, options: TransformNodeOptions) => ts.TypeNode | TransformObject | undefined;
641641
/** Modify TypeScript types built from Schema Objects */
642642
postTransform?: (type: ts.TypeNode, options: TransformNodeOptions) => ts.TypeNode | undefined;
643+
/** Modify property signatures for Schema Object properties */
644+
transformProperty?: (
645+
property: ts.PropertySignature,
646+
schemaObject: SchemaObject,
647+
options: TransformNodeOptions,
648+
) => ts.PropertySignature | undefined;
643649
/** Add readonly properties and readonly arrays? (default: false) */
644650
immutable?: boolean;
645651
/** (optional) Should logging be suppressed? (necessary for STDOUT) */
@@ -702,6 +708,7 @@ export interface GlobalContext {
702708
redoc: RedoclyConfig;
703709
silent: boolean;
704710
transform: OpenAPITSOptions["transform"];
711+
transformProperty: OpenAPITSOptions["transformProperty"];
705712
/** retrieve a node by $ref */
706713
resolve<T>($ref: string): T | undefined;
707714
inject?: string;

0 commit comments

Comments
 (0)