From 373560690ff4c58c47be74e87bfe145f0d6c6389 Mon Sep 17 00:00:00 2001 From: dutchenkoOleg Date: Sun, 7 Mar 2021 08:21:09 +0200 Subject: [PATCH 1/3] Enhance `jestFunctionSignatureTest` method. Adds `name` field for custom test naming --- src/function-signature-test.ts | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/function-signature-test.ts b/src/function-signature-test.ts index 59876ce..243ecdd 100644 --- a/src/function-signature-test.ts +++ b/src/function-signature-test.ts @@ -15,6 +15,7 @@ * expected: 9 * }, * { + * name: 'Custom test name' * parameters: [false, 4, 5], * expected: null * } @@ -24,12 +25,13 @@ export default function void>( method: T, cases: { - parameters: Parameters; - expected: ReturnType; + name?: string; + parameters: Parameters; + expected: ReturnType; }[] ): void { - cases.forEach(({ parameters, expected }, i) => { - test(`Test case #${i + 1}`, () => { + cases.forEach(({ name, parameters, expected }, i) => { + test(name || `Test case #${i + 1}`, () => { const result = method(...parameters); expect(result).toStrictEqual(expected); }); From 91c1f163aaf6ae9ef8e8de39bcc2340645708600 Mon Sep 17 00:00:00 2001 From: dutchenkoOleg Date: Sun, 7 Mar 2021 08:21:49 +0200 Subject: [PATCH 2/3] Enhance AutoDoc flow --- README.md | 49 ++-- package-lock.json | 436 +++++++++++++++++++++++++++-- package.json | 5 +- utils/autodoc-ts-tool.js | 145 ++++++++++ utils/autodoc-typedoc-normalize.js | 22 ++ 5 files changed, 615 insertions(+), 42 deletions(-) create mode 100644 utils/autodoc-ts-tool.js create mode 100644 utils/autodoc-typedoc-normalize.js diff --git a/README.md b/README.md index 5416a63..dfc9c44 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,6 @@ --- - ## Usage ### Install npm package @@ -45,35 +44,37 @@ Function signature test with set of custom cases _Parameters:_ -| Name | Data type | Argument | Default value | Description | -| ------ | --------- | -------- | ------------- | ----------- | -| method | `T` | | | -| cases | | | | +| Name | Data type | Argument | Default value | Description | +| ------ | ------------------------------------------------------------------------- | -------- | ------------- | ----------- | +| method | `T` | | | +| cases | `{ name?: string; parameters: Parameters; expected: ReturnType }[]` | | | _Returns:_ `void` _Examples:_ ```ts -// x.ts -export const x = (y: boolean, z: number, w: number): number | null => (y ? z + w : null); - -// x.spec.ts -import x from 'x.ts'; -import { jestFunctionSignatureTest } from '@wezom/toolkit-jest'; - -describe('Function signature should match specification', () => { - jestFunctionSignatureTest(x, [ - { - parameters: [true, 4, 5], - expected: 9 - }, - { - parameters: [false, 4, 5], - expected: null - } - ]); -}); + // x.ts + export const x = (y: boolean, z: number, w: number):number|null => y ? z + w : null; + + // x.spec.ts + import x from 'x.ts' + import { jestFunctionSignatureTest } from '@wezom/toolkit-jest' + + describe('Function signature should match specification', () => { + jestFunctionSignatureTest(x, [ + { + parameters: [true, 4, 5], + expected: 9 + }, + { + name: 'Custom test name' + parameters: [false, 4, 5], + expected: null + } + ]); + }); + ``` [comment]: <> (AUTODOC-TOOL-END) diff --git a/package-lock.json b/package-lock.json index b603e27..abf7ab9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,6 +22,7 @@ "rollup": "^2.39.0", "rollup-plugin-typescript2": "^0.29.0", "ts-jest": "^26.5.1", + "typedoc": "^0.20.30", "typescript": "^4.1.3" } }, @@ -709,7 +710,6 @@ "jest-resolve": "^26.6.2", "jest-util": "^26.6.2", "jest-worker": "^26.6.2", - "node-notifier": "^8.0.0", "slash": "^3.0.0", "source-map": "^0.6.0", "string-length": "^4.0.1", @@ -1514,6 +1514,15 @@ "integrity": "sha1-x57Zf380y48robyXkLzDZkdLS3k=", "dev": true }, + "node_modules/at-least-node": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz", + "integrity": "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==", + "dev": true, + "engines": { + "node": ">= 4.0.0" + } + }, "node_modules/atob": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/atob/-/atob-2.1.2.tgz", @@ -2021,6 +2030,15 @@ "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", "dev": true }, + "node_modules/colors": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.4.0.tgz", + "integrity": "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA==", + "dev": true, + "engines": { + "node": ">=0.1.90" + } + }, "node_modules/combined-stream": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", @@ -2511,8 +2529,7 @@ "esprima": "^4.0.1", "estraverse": "^4.2.0", "esutils": "^2.0.2", - "optionator": "^0.8.1", - "source-map": "~0.6.1" + "optionator": "^0.8.1" }, "bin": { "escodegen": "bin/escodegen.js", @@ -3648,6 +3665,27 @@ "dev": true, "optional": true }, + "node_modules/handlebars": { + "version": "4.7.7", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.7.tgz", + "integrity": "sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA==", + "dev": true, + "dependencies": { + "minimist": "^1.2.5", + "neo-async": "^2.6.0", + "source-map": "^0.6.1", + "wordwrap": "^1.0.0" + }, + "bin": { + "handlebars": "bin/handlebars" + }, + "engines": { + "node": ">=0.4.7" + }, + "optionalDependencies": { + "uglify-js": "^3.1.4" + } + }, "node_modules/har-schema": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/har-schema/-/har-schema-2.0.0.tgz", @@ -3923,6 +3961,15 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "dev": true }, + "node_modules/interpret": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", + "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==", + "dev": true, + "engines": { + "node": ">= 0.10" + } + }, "node_modules/ip-regex": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/ip-regex/-/ip-regex-2.1.0.tgz", @@ -4546,7 +4593,6 @@ "@types/node": "*", "anymatch": "^3.0.3", "fb-watchman": "^2.0.0", - "fsevents": "^2.1.2", "graceful-fs": "^4.2.4", "jest-regex-util": "^26.0.0", "jest-serializer": "^26.6.2", @@ -5093,9 +5139,6 @@ "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", "integrity": "sha1-h3Gq4HmbZAdrdmQPygWPnBDjPss=", "dev": true, - "dependencies": { - "graceful-fs": "^4.1.6" - }, "optionalDependencies": { "graceful-fs": "^4.1.6" } @@ -5198,9 +5241,9 @@ } }, "node_modules/lodash": { - "version": "4.17.20", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz", - "integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA==", + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", "dev": true }, "node_modules/lodash.sortby": { @@ -5221,6 +5264,12 @@ "node": ">=10" } }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "node_modules/make-dir": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz", @@ -5290,6 +5339,18 @@ "node": ">=0.10.0" } }, + "node_modules/marked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/marked/-/marked-2.0.1.tgz", + "integrity": "sha512-5+/fKgMv2hARmMW7DOpykr2iLhl0NgjyELk5yn92iE7z8Se1IS9n3UsFm86hFXIkvMBmVxki8+ckcpjBeyo/hw==", + "dev": true, + "bin": { + "marked": "bin/marked" + }, + "engines": { + "node": ">= 8.16.2" + } + }, "node_modules/meow": { "version": "6.1.1", "resolved": "https://registry.npmjs.org/meow/-/meow-6.1.1.tgz", @@ -5553,6 +5614,12 @@ "integrity": "sha1-Sr6/7tdUHywnrPspvbvRXI1bpPc=", "dev": true }, + "node_modules/neo-async": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz", + "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", + "dev": true + }, "node_modules/nice-try": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/nice-try/-/nice-try-1.0.5.tgz", @@ -5833,6 +5900,30 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/onigasm": { + "version": "2.2.5", + "resolved": "https://registry.npmjs.org/onigasm/-/onigasm-2.2.5.tgz", + "integrity": "sha512-F+th54mPc0l1lp1ZcFMyL/jTs2Tlq4SqIHKIXGZOR/VkHkF9A7Fr5rRr5+ZG/lWeRsyrClLYRq7s/yFQ/XhWCA==", + "dev": true, + "dependencies": { + "lru-cache": "^5.1.1" + } + }, + "node_modules/onigasm/node_modules/lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "dev": true, + "dependencies": { + "yallist": "^3.0.2" + } + }, + "node_modules/onigasm/node_modules/yallist": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", + "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", + "dev": true + }, "node_modules/optionator": { "version": "0.9.1", "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.1.tgz", @@ -6360,6 +6451,18 @@ "node": ">=4" } }, + "node_modules/rechoir": { + "version": "0.6.2", + "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", + "integrity": "sha1-hSBLVNuoLVdC4oyWdW70OvUOM4Q=", + "dev": true, + "dependencies": { + "resolve": "^1.1.6" + }, + "engines": { + "node": ">= 0.10" + } + }, "node_modules/redent": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz", @@ -6635,9 +6738,6 @@ "resolved": "https://registry.npmjs.org/rollup/-/rollup-2.39.0.tgz", "integrity": "sha512-+WR3bttcq7zE+BntH09UxaW3bQo3vItuYeLsyk4dL2tuwbeSKJuvwiawyhEnvRdRgrII0Uzk00FpctHO/zB1kw==", "dev": true, - "dependencies": { - "fsevents": "~2.3.1" - }, "bin": { "rollup": "dist/bin/rollup" }, @@ -7113,6 +7213,23 @@ "node": ">=8" } }, + "node_modules/shelljs": { + "version": "0.8.4", + "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.4.tgz", + "integrity": "sha512-7gk3UZ9kOfPLIAbslLzyWeGiEqx9e3rxwZM0KE6EL8GlGwjym9Mrlx5/p33bWTu9YG6vcS4MBxYZDHYr5lr8BQ==", + "dev": true, + "dependencies": { + "glob": "^7.0.0", + "interpret": "^1.0.0", + "rechoir": "^0.6.2" + }, + "bin": { + "shjs": "bin/shjs" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/shellwords": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/shellwords/-/shellwords-0.1.1.tgz", @@ -7120,6 +7237,16 @@ "dev": true, "optional": true }, + "node_modules/shiki": { + "version": "0.9.2", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.9.2.tgz", + "integrity": "sha512-BjUCxVbxMnvjs8jC4b+BQ808vwjJ9Q8NtLqPwXShZ307HdXiDFYP968ORSVfaTNNSWYDBYdMnVKJ0fYNsoZUBA==", + "dev": true, + "dependencies": { + "onigasm": "^2.2.5", + "vscode-textmate": "^5.2.0" + } + }, "node_modules/signal-exit": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.3.tgz", @@ -8067,6 +8194,79 @@ "is-typedarray": "^1.0.0" } }, + "node_modules/typedoc": { + "version": "0.20.30", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.20.30.tgz", + "integrity": "sha512-A4L6JDShPFwZDt9qp7FBsEpW7C6rA5fRv6ywgBuxGxZnT2wuF5afbWzmrwqHR3Xw38V1H2L4v/VJ0S/llBwV6Q==", + "dev": true, + "dependencies": { + "colors": "^1.4.0", + "fs-extra": "^9.1.0", + "handlebars": "^4.7.7", + "lodash": "^4.17.21", + "lunr": "^2.3.9", + "marked": "^2.0.1", + "minimatch": "^3.0.0", + "progress": "^2.0.3", + "shelljs": "^0.8.4", + "shiki": "^0.9.2", + "typedoc-default-themes": "^0.12.8" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 10.8.0" + }, + "peerDependencies": { + "typescript": "3.9.x || 4.0.x || 4.1.x || 4.2.x" + } + }, + "node_modules/typedoc-default-themes": { + "version": "0.12.8", + "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.12.8.tgz", + "integrity": "sha512-tyjyDTKy/JLnBSwvhoqd99VIjrP33SdOtwcMD32b+OqnrjZWe8HmZECbfBoacqoxjHd58gfeNw6wA7uvqWFa4w==", + "dev": true, + "engines": { + "node": ">= 8" + } + }, + "node_modules/typedoc/node_modules/fs-extra": { + "version": "9.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.1.0.tgz", + "integrity": "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==", + "dev": true, + "dependencies": { + "at-least-node": "^1.0.0", + "graceful-fs": "^4.2.0", + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/typedoc/node_modules/jsonfile": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", + "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", + "dev": true, + "dependencies": { + "universalify": "^2.0.0" + }, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/typedoc/node_modules/universalify": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz", + "integrity": "sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==", + "dev": true, + "engines": { + "node": ">= 10.0.0" + } + }, "node_modules/typescript": { "version": "4.1.5", "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.1.5.tgz", @@ -8080,6 +8280,19 @@ "node": ">=4.2.0" } }, + "node_modules/uglify-js": { + "version": "3.13.0", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.13.0.tgz", + "integrity": "sha512-TWYSWa9T2pPN4DIJYbU9oAjQx+5qdV5RUDxwARg8fmJZrD/V27Zj0JngW5xg1DFz42G0uDYl2XhzF6alSzD62w==", + "dev": true, + "optional": true, + "bin": { + "uglifyjs": "bin/uglifyjs" + }, + "engines": { + "node": ">=0.8.0" + } + }, "node_modules/union-value": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/union-value/-/union-value-1.0.1.tgz", @@ -8249,6 +8462,12 @@ "extsprintf": "^1.2.0" } }, + "node_modules/vscode-textmate": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-5.2.0.tgz", + "integrity": "sha512-Uw5ooOQxRASHgu6C7GVvUxisKXfSgW4oFlO+aa+PAkgmH89O3CXxEEzNRNtHSqtXFTl0nAC1uYj0GMSH27uwtQ==", + "dev": true + }, "node_modules/w3c-hr-time": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/w3c-hr-time/-/w3c-hr-time-1.0.2.tgz", @@ -8347,6 +8566,12 @@ "node": ">=0.10.0" } }, + "node_modules/wordwrap": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz", + "integrity": "sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus=", + "dev": true + }, "node_modules/wrap-ansi": { "version": "6.2.0", "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", @@ -9656,6 +9881,12 @@ "integrity": "sha1-x57Zf380y48robyXkLzDZkdLS3k=", "dev": true }, + "at-least-node": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz", + "integrity": "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==", + "dev": true + }, "atob": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/atob/-/atob-2.1.2.tgz", @@ -10062,6 +10293,12 @@ "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", "dev": true }, + "colors": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/colors/-/colors-1.4.0.tgz", + "integrity": "sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA==", + "dev": true + }, "combined-stream": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", @@ -11338,6 +11575,19 @@ "dev": true, "optional": true }, + "handlebars": { + "version": "4.7.7", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.7.tgz", + "integrity": "sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA==", + "dev": true, + "requires": { + "minimist": "^1.2.5", + "neo-async": "^2.6.0", + "source-map": "^0.6.1", + "uglify-js": "^3.1.4", + "wordwrap": "^1.0.0" + } + }, "har-schema": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/har-schema/-/har-schema-2.0.0.tgz", @@ -11545,6 +11795,12 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "dev": true }, + "interpret": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", + "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==", + "dev": true + }, "ip-regex": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/ip-regex/-/ip-regex-2.1.0.tgz", @@ -12516,9 +12772,9 @@ } }, "lodash": { - "version": "4.17.20", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz", - "integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA==", + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", "dev": true }, "lodash.sortby": { @@ -12536,6 +12792,12 @@ "yallist": "^4.0.0" } }, + "lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true + }, "make-dir": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz", @@ -12589,6 +12851,12 @@ "object-visit": "^1.0.0" } }, + "marked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/marked/-/marked-2.0.1.tgz", + "integrity": "sha512-5+/fKgMv2hARmMW7DOpykr2iLhl0NgjyELk5yn92iE7z8Se1IS9n3UsFm86hFXIkvMBmVxki8+ckcpjBeyo/hw==", + "dev": true + }, "meow": { "version": "6.1.1", "resolved": "https://registry.npmjs.org/meow/-/meow-6.1.1.tgz", @@ -12789,6 +13057,12 @@ "integrity": "sha1-Sr6/7tdUHywnrPspvbvRXI1bpPc=", "dev": true }, + "neo-async": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz", + "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==", + "dev": true + }, "nice-try": { "version": "1.0.5", "resolved": "https://registry.npmjs.org/nice-try/-/nice-try-1.0.5.tgz", @@ -13009,6 +13283,32 @@ "mimic-fn": "^2.1.0" } }, + "onigasm": { + "version": "2.2.5", + "resolved": "https://registry.npmjs.org/onigasm/-/onigasm-2.2.5.tgz", + "integrity": "sha512-F+th54mPc0l1lp1ZcFMyL/jTs2Tlq4SqIHKIXGZOR/VkHkF9A7Fr5rRr5+ZG/lWeRsyrClLYRq7s/yFQ/XhWCA==", + "dev": true, + "requires": { + "lru-cache": "^5.1.1" + }, + "dependencies": { + "lru-cache": { + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz", + "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==", + "dev": true, + "requires": { + "yallist": "^3.0.2" + } + }, + "yallist": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz", + "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", + "dev": true + } + } + }, "optionator": { "version": "0.9.1", "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.1.tgz", @@ -13390,6 +13690,15 @@ } } }, + "rechoir": { + "version": "0.6.2", + "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", + "integrity": "sha1-hSBLVNuoLVdC4oyWdW70OvUOM4Q=", + "dev": true, + "requires": { + "resolve": "^1.1.6" + } + }, "redent": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz", @@ -13962,6 +14271,17 @@ "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", "dev": true }, + "shelljs": { + "version": "0.8.4", + "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.4.tgz", + "integrity": "sha512-7gk3UZ9kOfPLIAbslLzyWeGiEqx9e3rxwZM0KE6EL8GlGwjym9Mrlx5/p33bWTu9YG6vcS4MBxYZDHYr5lr8BQ==", + "dev": true, + "requires": { + "glob": "^7.0.0", + "interpret": "^1.0.0", + "rechoir": "^0.6.2" + } + }, "shellwords": { "version": "0.1.1", "resolved": "https://registry.npmjs.org/shellwords/-/shellwords-0.1.1.tgz", @@ -13969,6 +14289,16 @@ "dev": true, "optional": true }, + "shiki": { + "version": "0.9.2", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.9.2.tgz", + "integrity": "sha512-BjUCxVbxMnvjs8jC4b+BQ808vwjJ9Q8NtLqPwXShZ307HdXiDFYP968ORSVfaTNNSWYDBYdMnVKJ0fYNsoZUBA==", + "dev": true, + "requires": { + "onigasm": "^2.2.5", + "vscode-textmate": "^5.2.0" + } + }, "signal-exit": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.3.tgz", @@ -14728,12 +15058,74 @@ "is-typedarray": "^1.0.0" } }, + "typedoc": { + "version": "0.20.30", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.20.30.tgz", + "integrity": "sha512-A4L6JDShPFwZDt9qp7FBsEpW7C6rA5fRv6ywgBuxGxZnT2wuF5afbWzmrwqHR3Xw38V1H2L4v/VJ0S/llBwV6Q==", + "dev": true, + "requires": { + "colors": "^1.4.0", + "fs-extra": "^9.1.0", + "handlebars": "^4.7.7", + "lodash": "^4.17.21", + "lunr": "^2.3.9", + "marked": "^2.0.1", + "minimatch": "^3.0.0", + "progress": "^2.0.3", + "shelljs": "^0.8.4", + "shiki": "^0.9.2", + "typedoc-default-themes": "^0.12.8" + }, + "dependencies": { + "fs-extra": { + "version": "9.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.1.0.tgz", + "integrity": "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==", + "dev": true, + "requires": { + "at-least-node": "^1.0.0", + "graceful-fs": "^4.2.0", + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" + } + }, + "jsonfile": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", + "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.6", + "universalify": "^2.0.0" + } + }, + "universalify": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz", + "integrity": "sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==", + "dev": true + } + } + }, + "typedoc-default-themes": { + "version": "0.12.8", + "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.12.8.tgz", + "integrity": "sha512-tyjyDTKy/JLnBSwvhoqd99VIjrP33SdOtwcMD32b+OqnrjZWe8HmZECbfBoacqoxjHd58gfeNw6wA7uvqWFa4w==", + "dev": true + }, "typescript": { "version": "4.1.5", "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.1.5.tgz", "integrity": "sha512-6OSu9PTIzmn9TCDiovULTnET6BgXtDYL4Gg4szY+cGsc3JP1dQL8qvE8kShTRx1NIw4Q9IBHlwODjkjWEtMUyA==", "dev": true }, + "uglify-js": { + "version": "3.13.0", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.13.0.tgz", + "integrity": "sha512-TWYSWa9T2pPN4DIJYbU9oAjQx+5qdV5RUDxwARg8fmJZrD/V27Zj0JngW5xg1DFz42G0uDYl2XhzF6alSzD62w==", + "dev": true, + "optional": true + }, "union-value": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/union-value/-/union-value-1.0.1.tgz", @@ -14874,6 +15266,12 @@ "extsprintf": "^1.2.0" } }, + "vscode-textmate": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-5.2.0.tgz", + "integrity": "sha512-Uw5ooOQxRASHgu6C7GVvUxisKXfSgW4oFlO+aa+PAkgmH89O3CXxEEzNRNtHSqtXFTl0nAC1uYj0GMSH27uwtQ==", + "dev": true + }, "w3c-hr-time": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/w3c-hr-time/-/w3c-hr-time-1.0.2.tgz", @@ -14954,6 +15352,12 @@ "integrity": "sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ==", "dev": true }, + "wordwrap": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz", + "integrity": "sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus=", + "dev": true + }, "wrap-ansi": { "version": "6.2.0", "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz", diff --git a/package.json b/package.json index 4924c9b..20d0559 100644 --- a/package.json +++ b/package.json @@ -12,8 +12,8 @@ "test": "npm run prettier && npm run eslint && npm run jest", "test:autofix": "npm run prettier:autofix && npm run eslint:autofix && npm run jest:coverage", "----------------------------------------------- AUTODOC": "SECTION", - "autodoc:typedoc": "typedoc src --json .cache/typedoc.json && node ../../utils/autodoc-typedoc-normalize.js", - "autodoc:inject": "node ../../utils/autodoc-ts-tool.js && prettier ./README.md --write", + "autodoc:typedoc": "typedoc src --json .cache/typedoc.json && node ./utils/autodoc-typedoc-normalize.js", + "autodoc:inject": "node ./utils/autodoc-ts-tool.js && prettier ./README.md --write", "----------------------------------------------- TEST": "SECTION", "prettier": "prettier \"./src/**/*.ts\" --check", "prettier:autofix": "npm run prettier -- --write", @@ -59,6 +59,7 @@ "rollup": "^2.39.0", "rollup-plugin-typescript2": "^0.29.0", "ts-jest": "^26.5.1", + "typedoc": "^0.20.30", "typescript": "^4.1.3" } } diff --git a/utils/autodoc-ts-tool.js b/utils/autodoc-ts-tool.js new file mode 100644 index 0000000..0df2e3d --- /dev/null +++ b/utils/autodoc-ts-tool.js @@ -0,0 +1,145 @@ +const fs = require('fs'); +const fromCWD = require('from-cwd'); +const typedoc = require('typedoc'); + +const toolsFilePath = fromCWD('README.md'); +const toolsTypeDocPath = fromCWD('.cache/typedoc.normalized.json'); +const toolsFileContent = fs.readFileSync(toolsFilePath).toString(); +const toolsTypeDoc = JSON.parse(fs.readFileSync(toolsTypeDocPath).toString()); + +const _code = (value, isRest) => + value === undefined ? '' : `\`${isRest ? '...' : ''}${value}\``; +const _trimCode = (value) => value.replace(/^`|`$/g, ''); +const _trimAllCode = (value) => value.replace(/`/g, ''); +const _parseTrimJoin = (arr, joiner) => arr.map(_parseType).map(_trimCode).join(joiner); +const _parseType = (docType, { isRest } = {}) => { + switch (docType.type) { + case 'intrinsic': + return _code(docType.name, isRest); + case 'reference': + if (Array.isArray(docType.typeArguments)) { + const tArgs = _parseTrimJoin(docType.typeArguments, ' / '); + if (tArgs.length) { + return _code(`${docType.name}<${tArgs}>`, isRest); + } + } + return _code(docType.name, isRest); + case 'array': + const _type = _parseType(docType.elementType, { isRest }); + return _type ? _code(_trimCode(_type) + '[]') : _type; + case 'reflection': + return _code(_trimAllCode(_parseReflection(docType.declaration, true))); + case 'intersection': + return _code(_parseTrimJoin(docType.types, ' & '), isRest); + case 'union': + return _code(_parseTrimJoin(docType.types, ' │ '), isRest); + case 'literal': + return _code(docType.value, isRest); + default: + return ''; + } +}; + +const _parseReflection = (declaration, oneLine) => { + if (!declaration) { + return ''; + } + if ( + declaration.kindString === 'Type literal' && + Array.isArray(declaration.children) + ) { + const d = declaration.children + .sort((a = {}, b = {}) => { + const { line: lineA = 0, character: charA = 0 } = (a.sources || [])[0]; + const { line: lineB = 0, character: charB = 0 } = (b.sources || [])[0]; + return lineA === lineB ? charA - charB : lineA - lineB; + }) + .map((child) => { + const name = + child.flags && child.flags.isOptional ? child.name + '?' : child.name; + const value = _parseType(child.type); + return `${name}: ${value}`; + }, {}); + if (d.length > 0) { + if (d.length === 1) { + return `{ ${d[0]} }`; + } else { + const joiner = oneLine ? ' ' : '\n '; + const end = oneLine ? ' ' : '\n'; + return '{' + joiner + d.join(`;${joiner}`) + end + '}'; + } + } + } + return ''; +}; + +const regExp = /(\[comment]: <> \(AUTODOC-TOOL-START::(.+)\))((?!\[comment]: <> \(AUTODOC-TOOL-END\)).|\n)*(\[comment]: <> \(AUTODOC-TOOL-END\))/gm; +const newToolsFileContent = toolsFileContent.replace(regExp, (str, g1, g2, g3, g4) => { + const blocks = ['']; + const doc = toolsTypeDoc[g2]; + if (!!doc) { + doc.signatures.map((signature) => { + const { + comment: { shortText = '', tags = [] } = {}, + parameters = [], + type: rType = {} + } = signature; + + const parametersTable = []; + if (parameters.length > 0) { + parametersTable.push('_Parameters:_\n'); + parametersTable.push( + '| Name | Data type | Argument | Default value | Description ' + ); + parametersTable.push( + '| ---- | --------- | -------- | ------------- | ----------- ' + ); + parametersTable.push( + ...parameters + .map((parameter) => { + const { flags = {}, comment = {}, type = {} } = parameter; + const dataType = _parseType(type, { + isRest: flags.isRest + }); + return ( + '| ' + + [ + parameter.name, + dataType, + flags.isOptional || parameter.defaultValue + ? '_optional_' + : '', + _code(parameter.defaultValue), + comment.text || '' + ].join(' | ') + ); + }) + .filter(Boolean) + ); + } + + let returnType = _parseType(rType); + if (returnType) { + returnType = '_Returns:_ ' + returnType; + } + + blocks.push( + shortText, + parametersTable.join('\n'), + returnType, + ...tags + .map(({ tag, text }) => { + if (tag === 'example') { + return `_Examples:_\n\n\`\`\`ts${text}\n\`\`\``; + } + }) + .filter(Boolean) + ); + }); + } + return [g1, ...blocks, g4].join('\n\n'); +}); + +if (newToolsFileContent !== toolsFileContent) { + fs.writeFileSync(toolsFilePath, newToolsFileContent); +} diff --git a/utils/autodoc-typedoc-normalize.js b/utils/autodoc-typedoc-normalize.js new file mode 100644 index 0000000..ac57b6e --- /dev/null +++ b/utils/autodoc-typedoc-normalize.js @@ -0,0 +1,22 @@ +const fs = require('fs'); +const fromCWD = require('from-cwd'); + +const toolsTypeDocPath = fromCWD('.cache/typedoc.json'); +const toolsTypeDocNormalizedPath = fromCWD('.cache/typedoc.normalized.json'); +const toolsTypeDoc = JSON.parse( + fs.readFileSync(toolsTypeDocPath).toString() +).children.reduce((acc, module) => { + if (module.name === 'index') { + return acc; + } else { + module.children.forEach((child) => { + acc[`${module.name}#${child.name}`] = child; + }); + } + return acc; +}, {}); + +fs.writeFileSync( + toolsTypeDocNormalizedPath, + JSON.stringify(toolsTypeDoc, undefined, '\t') +); From 18c42422b89197c2fc4039a5d6f51f122ee645d4 Mon Sep 17 00:00:00 2001 From: dutchenkoOleg Date: Sun, 7 Mar 2021 08:22:45 +0200 Subject: [PATCH 3/3] 3.1.0 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index abf7ab9..5c7f59f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@wezom/toolkit-jest", - "version": "3.0.0", + "version": "3.1.0", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@wezom/toolkit-jest", - "version": "3.0.0", + "version": "3.1.0", "license": "BSD-3-Clause", "devDependencies": { "@wezom/eslint-config": "^2.1.0-beta.0", diff --git a/package.json b/package.json index 20d0559..4337285 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@wezom/toolkit-jest", - "version": "3.0.0", + "version": "3.1.0", "description": "Useful tools for working with Jest", "main": "dist/index.js", "files": [