From 523f217e8af73545c54056e2488b507d1a79f0e4 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Fri, 8 Apr 2022 12:41:11 +0200 Subject: [PATCH 1/5] chore: sort expected outputs --- test/scripts/apidoc/signature.expected.json | 108 ++++++++++---------- test/scripts/apidoc/signature.spec.ts | 2 +- 2 files changed, 55 insertions(+), 55 deletions(-) diff --git a/test/scripts/apidoc/signature.expected.json b/test/scripts/apidoc/signature.expected.json index f6e398fe95d..b50a3874b04 100644 --- a/test/scripts/apidoc/signature.expected.json +++ b/test/scripts/apidoc/signature.expected.json @@ -1,14 +1,4 @@ { - "noParamMethod": { - "name": "noParamMethod", - "title": "No Param Method", - "description": "

Test with no parameters.

\n", - "parameters": [], - "returns": "number", - "examples": "
faker.noParamMethod(): number\n
\n
", - "deprecated": false, - "seeAlsos": [] - }, "defaultBooleanParamMethod": { "name": "defaultBooleanParamMethod", "title": "Default Boolean Param Method", @@ -89,6 +79,32 @@ "deprecated": false, "seeAlsos": [] }, + "noParamMethod": { + "name": "noParamMethod", + "title": "No Param Method", + "description": "

Test with no parameters.

\n", + "parameters": [], + "returns": "number", + "examples": "
faker.noParamMethod(): number\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, + "optionalStringParamMethod": { + "name": "optionalStringParamMethod", + "title": "Optional String Param Method", + "description": "

Test with an optional parameter.

\n", + "parameters": [ + { + "name": "b?", + "type": "string", + "description": "

The string parameter.

\n" + } + ], + "returns": "number", + "examples": "
faker.optionalStringParamMethod(b?: string): number\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, "optionsInlineParamMethodWithDefaults": { "name": "optionsInlineParamMethodWithDefaults", "title": "Options Inline Param Method With Defaults", @@ -161,50 +177,6 @@ "deprecated": false, "seeAlsos": [] }, - "optionsTypeParamMethodWithDefaults": { - "name": "optionsTypeParamMethodWithDefaults", - "title": "Options Type Param Method With Defaults", - "description": "

Test with a function parameters with defaults.

\n", - "parameters": [ - { - "name": "a", - "type": "ParameterOptionsTypeA", - "default": "{ value: 1 }", - "description": "

Parameter with signature default.

\n" - }, - { - "name": "b", - "type": "ParameterOptionsTypeB", - "default": "{ value: 1 }", - "description": "

Parameter with jsdocs default.

\n" - }, - { - "name": "c", - "type": "ParameterOptionsTypeC", - "description": "

Parameter with inner jsdocs default.

\n" - } - ], - "returns": "number", - "examples": "
faker.optionsTypeParamMethodWithDefaults(a: ParameterOptionsTypeA = { value: 1 }, b: ParameterOptionsTypeB = { value: 1 }, c: ParameterOptionsTypeC): number\n
\n
", - "deprecated": false, - "seeAlsos": [] - }, - "optionalStringParamMethod": { - "name": "optionalStringParamMethod", - "title": "Optional String Param Method", - "description": "

Test with an optional parameter.

\n", - "parameters": [ - { - "name": "b?", - "type": "string", - "description": "

The string parameter.

\n" - } - ], - "returns": "number", - "examples": "
faker.optionalStringParamMethod(b?: string): number\n
\n
", - "deprecated": false, - "seeAlsos": [] - }, "optionsParamMethod": { "name": "optionsParamMethod", "title": "Options Param Method", @@ -241,6 +213,34 @@ "deprecated": false, "seeAlsos": [] }, + "optionsTypeParamMethodWithDefaults": { + "name": "optionsTypeParamMethodWithDefaults", + "title": "Options Type Param Method With Defaults", + "description": "

Test with a function parameters with defaults.

\n", + "parameters": [ + { + "name": "a", + "type": "ParameterOptionsTypeA", + "default": "{ value: 1 }", + "description": "

Parameter with signature default.

\n" + }, + { + "name": "b", + "type": "ParameterOptionsTypeB", + "default": "{ value: 1 }", + "description": "

Parameter with jsdocs default.

\n" + }, + { + "name": "c", + "type": "ParameterOptionsTypeC", + "description": "

Parameter with inner jsdocs default.

\n" + } + ], + "returns": "number", + "examples": "
faker.optionsTypeParamMethodWithDefaults(a: ParameterOptionsTypeA = { value: 1 }, b: ParameterOptionsTypeB = { value: 1 }, c: ParameterOptionsTypeC): number\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, "requiredNumberParamMethod": { "name": "requiredNumberParamMethod", "title": "Required Number Param Method", diff --git a/test/scripts/apidoc/signature.spec.ts b/test/scripts/apidoc/signature.spec.ts index d550dfd215c..0d9008ec64d 100644 --- a/test/scripts/apidoc/signature.spec.ts +++ b/test/scripts/apidoc/signature.spec.ts @@ -41,7 +41,7 @@ describe('signature', () => { expect(Object.keys(methods).sort()).toEqual(Object.keys(expected).sort()); }); - it.each(Object.keys(expected))('%s', (name) => { + it.each(Object.keys(expected).sort())('%s', (name) => { const method = methods[name]; const actual = analyzeSignature(method.signatures[0], null, method.name); actuals[name] = actual; From 170bd26a124492e575795e53990c70ee60aa5a7f Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Fri, 8 Apr 2022 12:42:18 +0200 Subject: [PATCH 2/5] docs: add test case for literal union --- test/scripts/apidoc/signature.example.ts | 11 +++++++++++ test/scripts/apidoc/signature.expected.json | 16 ++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts index 16dae935b22..2219b072659 100644 --- a/test/scripts/apidoc/signature.example.ts +++ b/test/scripts/apidoc/signature.example.ts @@ -1,3 +1,5 @@ +import type { LiteralUnion } from '../../../src/faker'; + /** * Parameter options type with default from signature. */ @@ -113,6 +115,15 @@ export class SignatureTest { return fn('a'); } + /** + * Test with LiteralUnion. + * + * @param value `'a'` or `'b'`. + */ + literalUnionParamMethod(value: LiteralUnion<'a' | 'b'>): string { + return value; + } + /** * Test with a function parameters. * diff --git a/test/scripts/apidoc/signature.expected.json b/test/scripts/apidoc/signature.expected.json index b50a3874b04..811b194c0f7 100644 --- a/test/scripts/apidoc/signature.expected.json +++ b/test/scripts/apidoc/signature.expected.json @@ -32,6 +32,22 @@ "deprecated": false, "seeAlsos": [] }, + "literalUnionParamMethod": { + "name": "literalUnionParamMethod", + "title": "Literal Union Param Method", + "description": "

Test with LiteralUnion.

\n", + "parameters": [ + { + "name": "value", + "type": "LiteralUnion<\"a\" | \"b\", string>", + "description": "

'a' or 'b'.

\n" + } + ], + "returns": "string", + "examples": "
faker.literalUnionParamMethod(value: LiteralUnion<\"a\" | \"b\", string>): string\n
\n
", + "deprecated": false, + "seeAlsos": [] + }, "methodWithDeprecated": { "name": "methodWithDeprecated", "title": "Method With Deprecated", From 7a7f2bfa96ef33763e51870dadaa5732f742b109 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Fri, 8 Apr 2022 12:44:57 +0200 Subject: [PATCH 3/5] chore: fix imports --- scripts/apidoc/moduleMethods.ts | 2 +- scripts/apidoc/signature.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts index 7b090d13e9c..3d81c2db104 100644 --- a/scripts/apidoc/moduleMethods.ts +++ b/scripts/apidoc/moduleMethods.ts @@ -1,6 +1,6 @@ import * as TypeDoc from 'typedoc'; import type { Method } from '../../docs/.vitepress/components/api-docs/method'; -import faker from '../../src'; +import { faker } from '../../src'; import { writeApiDocsData, writeApiDocsModulePage } from './apiDocsWriter'; import { analyzeSignature, toBlock } from './signature'; import type { PageIndex } from './utils'; diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 31674c834a0..52494c2e14a 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -14,7 +14,7 @@ import type { Method, MethodParameter, } from '../../docs/.vitepress/components/api-docs/method'; -import faker from '../../src'; +import { faker } from '../../src'; import { pathOutputDir } from './utils'; // TODO ST-DDT 2022-02-20: Actually import this/fix module import errors // import vitepressConfig from '../../docs/.vitepress/config'; From 721d63ce7a55497918c6ad75748942bdf3739e98 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Fri, 8 Apr 2022 14:08:52 +0200 Subject: [PATCH 4/5] chore: add debug script to simplify isolated api-docs debugging --- test/scripts/apidoc/signature.debug.ts | 16 ++++++++++++++++ test/scripts/apidoc/signature.spec.ts | 22 ++++------------------ test/scripts/apidoc/utils.ts | 26 ++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 18 deletions(-) create mode 100644 test/scripts/apidoc/signature.debug.ts create mode 100644 test/scripts/apidoc/utils.ts diff --git a/test/scripts/apidoc/signature.debug.ts b/test/scripts/apidoc/signature.debug.ts new file mode 100644 index 00000000000..542224ad95e --- /dev/null +++ b/test/scripts/apidoc/signature.debug.ts @@ -0,0 +1,16 @@ +/** + * This file exists, because vitest doesn't allow me to debug code outside of src and test. + * And it's easier to test these features independently from the main project. + */ +import { analyzeSignature } from '../../../scripts/apidoc/signature'; +import { loadExampleMethods } from './utils'; + +/* Run with `pnpm esno test/scripts/apidoc/signature.debug.ts` */ + +const methods = loadExampleMethods(); + +Object.entries(methods).forEach(([name, method]) => { + console.log('Analyzing: ', name); + const result = analyzeSignature(method.signatures[0], null, method.name); + console.log('Result: ', result); +}); diff --git a/test/scripts/apidoc/signature.spec.ts b/test/scripts/apidoc/signature.spec.ts index 0d9008ec64d..427ed923987 100644 --- a/test/scripts/apidoc/signature.spec.ts +++ b/test/scripts/apidoc/signature.spec.ts @@ -1,12 +1,12 @@ import { writeFileSync } from 'fs'; import { resolve } from 'path'; -import * as TypeDoc from 'typedoc'; import { afterAll, describe, expect, it } from 'vitest'; import type { Method } from '../../../docs/.vitepress/components/api-docs/method'; import { analyzeSignature } from '../../../scripts/apidoc/signature'; -import { newTypeDocApp, patchProject } from '../../../scripts/apidoc/utils'; import { SignatureTest } from './signature.example'; import expected_ from './signature.expected.json'; +import { loadExampleMethods } from './utils'; + const expected: Record = expected_; function prettyJson(object): string { @@ -14,24 +14,9 @@ function prettyJson(object): string { } describe('signature', () => { - const app = newTypeDocApp(); - - app.bootstrap({ - entryPoints: ['test/scripts/apidoc/signature.example.ts'], - tsconfig: 'test/scripts/apidoc/tsconfig.json', - }); - - const project = app.convert(); - - patchProject(project); - - const methods: Record = project - .getChildrenByKind(TypeDoc.ReflectionKind.Class)[0] - .getChildrenByKind(TypeDoc.ReflectionKind.Method) - .reduce((a, v) => ({ ...a, [v.name]: v }), {}); - describe('analyzeSignature()', () => { const actuals = {}; + const methods = loadExampleMethods(); it('dummy dependency to rerun the test if the example changes', () => { expect(new SignatureTest()).toBeTruthy(); @@ -43,6 +28,7 @@ describe('signature', () => { it.each(Object.keys(expected).sort())('%s', (name) => { const method = methods[name]; + expect(method, `Method ${name} to be defined`).toBeDefined(); const actual = analyzeSignature(method.signatures[0], null, method.name); actuals[name] = actual; diff --git a/test/scripts/apidoc/utils.ts b/test/scripts/apidoc/utils.ts new file mode 100644 index 00000000000..d4d11e8c2e8 --- /dev/null +++ b/test/scripts/apidoc/utils.ts @@ -0,0 +1,26 @@ +import type { DeclarationReflection } from 'typedoc'; +import { ReflectionKind } from 'typedoc'; +import { newTypeDocApp, patchProject } from '../../../scripts/apidoc/utils'; + +/** + * Loads the example methods using TypeDoc. + */ +export function loadExampleMethods(): Record { + const app = newTypeDocApp(); + + app.bootstrap({ + entryPoints: ['test/scripts/apidoc/signature.example.ts'], + tsconfig: 'test/scripts/apidoc/tsconfig.json', + }); + + const project = app.convert(); + + patchProject(project); + + const methods: Record = project + .getChildrenByKind(ReflectionKind.Class)[0] + .getChildrenByKind(ReflectionKind.Method) + .reduce((a, v) => ({ ...a, [v.name]: v }), {}); + + return methods; +} From dc2c1a23d4566e8e7c0299a029a50664fa8b5538 Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Fri, 8 Apr 2022 14:10:22 +0200 Subject: [PATCH 5/5] docs: nice literal unions --- scripts/apidoc/signature.ts | 5 +++++ test/scripts/apidoc/signature.expected.json | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 52494c2e14a..dafd2c6d112 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -228,6 +228,11 @@ function typeToText(type_: Type, short = false): string { case 'reference': if (!type.typeArguments || !type.typeArguments.length) { return type.name; + } else if (type.name === 'LiteralUnion') { + return [ + typeToText(type.typeArguments[0]), + typeToText(type.typeArguments[1]), + ].join(' | '); } else { return `${type.name}<${type.typeArguments .map((t) => typeToText(t, short)) diff --git a/test/scripts/apidoc/signature.expected.json b/test/scripts/apidoc/signature.expected.json index 811b194c0f7..5e4f913afdd 100644 --- a/test/scripts/apidoc/signature.expected.json +++ b/test/scripts/apidoc/signature.expected.json @@ -39,12 +39,12 @@ "parameters": [ { "name": "value", - "type": "LiteralUnion<\"a\" | \"b\", string>", + "type": "\"a\" | \"b\" | string", "description": "

'a' or 'b'.

\n" } ], "returns": "string", - "examples": "
faker.literalUnionParamMethod(value: LiteralUnion<\"a\" | \"b\", string>): string\n
\n
", + "examples": "
faker.literalUnionParamMethod(value: \"a\" | \"b\" | string): string\n
\n
", "deprecated": false, "seeAlsos": [] },