Skip to content

Commit 2ef2a68

Browse files
SamyPesseSamyPesse
committed
Document with TSDoc the properties of errors
1 parent 8727bd3 commit 2ef2a68

5 files changed

Lines changed: 212 additions & 66 deletions

File tree

‎src/comments.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
import { builders } from 'ast-types';
2+
3+
/**
4+
* Annotate a declaration with a JS Doc comment.
5+
*/
6+
export function annotateWithJSDocComment<T>(declaration: T, comment: string): T {
7+
return {
8+
...declaration,
9+
leadingComments: [builders.block('* ' + comment, true)],
10+
};
11+
}

‎src/compileValidateRequest.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@ import { OpenAPISpec } from './types';
55
import { compilePath } from './compilePath';
66
import { buildRequestError } from './error';
77
import { OpenAPIParsedPath, openapiPathToRegex } from './paths';
8+
import { annotateWithJSDocComment } from './comments';
89

9-
const COMMENT = `*
10+
const COMMENT = `
1011
Validate a request against the OpenAPI spec
1112
@param {{ method: string; path: string; body?: any; query: Record<string, string>; headers: Record<string, string>; }} request - Input request to validate
1213
@param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions
@@ -61,17 +62,16 @@ export function compileValidateRequest(compiler: Compiler, spec: OpenAPISpec) {
6162
nodes.push(builders.returnStatement(buildRequestError(404, 'no operation match path')));
6263

6364
return [
64-
{
65-
...builders.exportNamedDeclaration(
65+
annotateWithJSDocComment(
66+
builders.exportNamedDeclaration(
6667
builders.functionDeclaration.from({
6768
id: builders.identifier('validateRequest'),
6869
params: [request, context],
6970
body: builders.blockStatement(nodes),
7071
}),
7172
),
72-
// @ts-ignore
73-
leadingComments: [builders.block(COMMENT, true)],
74-
},
73+
COMMENT,
74+
),
7575
];
7676
}
7777

‎src/error.ts‎

Lines changed: 62 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,44 @@
11
import { namedTypes, builders } from 'ast-types';
2+
import { annotateWithJSDocComment } from './comments';
23

34
export const RequestErrorIdentifier = builders.identifier('RequestError');
45
export const RequestErrorClass = builders.classDeclaration.from({
56
id: RequestErrorIdentifier,
67
superClass: builders.identifier('Error'),
78
body: builders.classBody([
8-
builders.methodDefinition(
9-
'constructor',
10-
builders.identifier('constructor'),
11-
builders.functionExpression(
12-
null,
13-
[builders.identifier('code'), builders.identifier('message')],
14-
builders.blockStatement([
15-
builders.expressionStatement(
16-
builders.callExpression(builders.super(), [builders.identifier('message')]),
17-
),
18-
builders.expressionStatement(
19-
builders.assignmentExpression(
20-
'=',
21-
builders.memberExpression(
22-
builders.thisExpression(),
23-
builders.identifier('code'),
9+
annotateWithJSDocComment(
10+
builders.methodDefinition(
11+
'constructor',
12+
builders.identifier('constructor'),
13+
builders.functionExpression(
14+
null,
15+
[builders.identifier('code'), builders.identifier('message')],
16+
builders.blockStatement([
17+
builders.expressionStatement(
18+
builders.callExpression(builders.super(), [
19+
builders.identifier('message'),
20+
]),
21+
),
22+
annotateWithJSDocComment(
23+
builders.expressionStatement(
24+
builders.assignmentExpression(
25+
'=',
26+
builders.memberExpression(
27+
builders.thisExpression(),
28+
builders.identifier('code'),
29+
),
30+
builders.identifier('code'),
31+
),
2432
),
25-
builders.identifier('code'),
33+
'@type {number} HTTP code for the error',
2634
),
27-
),
28-
]),
35+
]),
36+
),
2937
),
38+
[
39+
'@param {number} code HTTP code for the error',
40+
'@param {string} message The error message',
41+
].join('\n'),
3042
),
3143
]),
3244
});
@@ -36,31 +48,40 @@ export const ValidationErrorClass = builders.classDeclaration.from({
3648
id: ValidationErrorIdentifier,
3749
superClass: RequestErrorIdentifier,
3850
body: builders.classBody([
39-
builders.methodDefinition(
40-
'constructor',
41-
builders.identifier('constructor'),
42-
builders.functionExpression(
43-
null,
44-
[builders.identifier('path'), builders.identifier('message')],
45-
builders.blockStatement([
46-
builders.expressionStatement(
47-
builders.callExpression(builders.super(), [
48-
builders.literal(409),
49-
builders.identifier('message'),
50-
]),
51-
),
52-
builders.expressionStatement(
53-
builders.assignmentExpression(
54-
'=',
55-
builders.memberExpression(
56-
builders.thisExpression(),
57-
builders.identifier('path'),
51+
annotateWithJSDocComment(
52+
builders.methodDefinition(
53+
'constructor',
54+
builders.identifier('constructor'),
55+
builders.functionExpression(
56+
null,
57+
[builders.identifier('path'), builders.identifier('message')],
58+
builders.blockStatement([
59+
builders.expressionStatement(
60+
builders.callExpression(builders.super(), [
61+
builders.literal(409),
62+
builders.identifier('message'),
63+
]),
64+
),
65+
annotateWithJSDocComment(
66+
builders.expressionStatement(
67+
builders.assignmentExpression(
68+
'=',
69+
builders.memberExpression(
70+
builders.thisExpression(),
71+
builders.identifier('path'),
72+
),
73+
builders.identifier('path'),
74+
),
5875
),
59-
builders.identifier('path'),
76+
'@type {string[]} The path that failed validation',
6077
),
61-
),
62-
]),
78+
]),
79+
),
6380
),
81+
[
82+
'@param {string[]} path The path that failed validation',
83+
'@param {string} message The error message',
84+
].join('\n'),
6485
),
6586
]),
6687
});

0 commit comments

Comments
 (0)