From 363efad2f121bb399a2b7150419199aab57ead21 Mon Sep 17 00:00:00 2001 From: Ashley Claymore Date: Tue, 20 Aug 2024 19:22:54 +0100 Subject: [PATCH] docs: READMEs and performance documentation updated --- README.md | 41 +++++++++++++++++++---------- docs/development.md | 15 +---------- perf/README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 28 deletions(-) create mode 100644 perf/README.md diff --git a/README.md b/README.md index 4d6c056..6bccbcc 100644 --- a/README.md +++ b/README.md @@ -30,12 +30,29 @@ class C extends Array { } ``` +## Rationale + +The benefits of this library are: + +- It is fast + - Only 50% slower than a native transformer in a micro-benchmark (see `./perf` folder) + - No new JavaScript code is generated, instead it re-uses slices of the existing source string + - This is particularly true if other parts of your program are already generating the TypeScript SourceFile object for other reasons because it can [be reused](#bring-your-own-ast), and producing the AST is the most time consuming part. +- 100% JavaScript runtime +- It is small + - ~700 lines of code and one dependency (`typescript`) + - By doing so little the code should be relatively easy to maintain +- Uses the official TypeScript parser +- No need for additional SourceMap processing. See ["where are my SourceMaps?"](#where-are-my-sourcemaps) + +:information_source: Not all TypeScript syntax is supported (see [unsupported syntax](#unsupported)). There is also no down leveling, the JavaScript is preserved as is. + ## Contents +- [Installing](#installing) - [API](#api) - [Node.js Loader](#nodejs-loader) - [Source Maps](#where-are-my-sourcemaps) -- [Rationale](#rationale) - [Implementation details](#does-it-really-just-blank-out-all-the-type-annotations) - [Unsupported syntax](#unsupported) - [tsconfig.json](#recommend-tsconfigjson-compiler-settings) @@ -46,6 +63,12 @@ class C extends Array { - [Code of Conduct](#code-of-conduct) - [Security Vulnerability Reporting](#security-vulnerability-reporting) +## Installing + +```sh +npm install ts-blank-space +``` + ## API ### String to String @@ -83,27 +106,17 @@ console.log(blankSourceFile(ast)); # Install (one time): $ npm install --save-dev ts-blank-space -# Example usage: +# Example usage (Node.js v18.18): $ node --import ts-blank-space/register ./path/to/your/file.ts ``` +In addition to loading `*.ts` files, an import resolver is also registered which will catches failed `*.js` imports and re-attempts the import replacing the extension with `.ts`. This allows import paths to choose either `.ts` or `.js` depending on which other factors the project may need to take into account such as bundling and package distribution. + ## Where are my SourceMaps? Because all the JavaScript in the output is located at the same line, column, and byte-offset as the original there is no mapping information that is lost during the transform. -## Rationale - -The benefits of this library are: - -- It is fast (for a pure JavaScript transform). See the `./perf` folder - - No new JavaScript needs to be emitted from an AST, it re-uses slices of the existing source string - - This is particularly true if other parts of your program are already generating the TypeScript SourceFile object for other reasons because it can [be reused](#bring-your-own-ast), and producing the AST is the most time consuming part. -- It is small (~700 LOC) - - By doing so little the code should be relatively easy to maintain - - The hard part, of parsing the source, is delegated to the official TypeScript parser. -- No need for additional SourceMap processing. See ["where are my SourceMaps?"](#where-are-my-sourcemaps) - ## Does it really just blank out all the type annotations? There are two cases, described here, where it does more than replace the TypeScript syntax with blank space. diff --git a/docs/development.md b/docs/development.md index e07cf91..936527d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -49,20 +49,7 @@ npm run test-ecosystem ### Performance tests -Setup: - -```sh -cd perf -npm ci -./setup.sh -``` - -Running: - -```sh -cd perf -./bench.sh -``` +See [`../perf/README`](../perf/README.md). ## Website diff --git a/perf/README.md b/perf/README.md new file mode 100644 index 0000000..7383e1b --- /dev/null +++ b/perf/README.md @@ -0,0 +1,64 @@ +# `ts-blank-space` performance tests + +Transforming just over 500,000 lines of TypeScript (one 50k file, ten times). + +## Setup + +```sh +npm i +./setup.sh +``` + +You will also need to install https://github.com/sharkdp/hyperfine + +## Running + +```sh +./bench.sh +``` + +## Results + +- Node.js v20.11.1 +- Apple M2 Pro 32GB + +```sh +Summary + node ./swc-native-async.js ./fixtures/checker.txt 10 ran + 1.52 ± 0.05 times faster than node ./ts-blank-space.js ./fixtures/checker.txt 10 + 1.71 ± 0.03 times faster than node ./swc-wasm-strip.js ./fixtures/checker.txt 10 + 1.85 ± 0.05 times faster than node ./sucrase.js ./fixtures/checker.txt 10 + 3.19 ± 0.05 times faster than node ./swc-native-sync.js ./fixtures/checker.txt 10 + 4.98 ± 0.08 times faster than node ./swc-wasm.js ./fixtures/checker.txt 10 + 7.58 ± 0.16 times faster than node ./typescript.js ./fixtures/checker.txt 10 +``` + +```sh +Benchmark: node ./swc-native-async.js ./fixtures/checker.txt 10 + Time (mean ± σ): 853.7 ms ± 11.8 ms [User: 2891.6 ms, System: 144.4 ms] + Range (min … max): 836.9 ms … 865.9 ms 10 runs + +Benchmark: node ./ts-blank-space.js ./fixtures/checker.txt 10 + Time (mean ± σ): 1.295 s ± 0.035 s [User: 2.150 s, System: 0.146 s] + Range (min … max): 1.255 s … 1.363 s 10 runs + +Benchmark: node ./swc-wasm-strip.js ./fixtures/checker.txt 10 + Time (mean ± σ): 1.462 s ± 0.013 s [User: 1.670 s, System: 0.050 s] + Range (min … max): 1.444 s … 1.481 s 10 runs + +Benchmark: node ./sucrase.js ./fixtures/checker.txt 10 + Time (mean ± σ): 1.583 s ± 0.041 s [User: 2.261 s, System: 0.250 s] + Range (min … max): 1.535 s … 1.637 s 10 runs + +Benchmark: node ./swc-native-sync.js ./fixtures/checker.txt 10 + Time (mean ± σ): 2.727 s ± 0.020 s [User: 2.856 s, System: 0.133 s] + Range (min … max): 2.698 s … 2.755 s 10 runs + +Benchmark: node ./swc-wasm.js ./fixtures/checker.txt 10 + Time (mean ± σ): 4.252 s ± 0.027 s [User: 5.605 s, System: 0.136 s] + Range (min … max): 4.223 s … 4.313 s 10 runs + +Benchmark: node ./typescript.js ./fixtures/checker.txt 10 + Time (mean ± σ): 6.470 s ± 0.109 s [User: 9.967 s, System: 0.370 s] + Range (min … max): 6.336 s … 6.710 s 10 runs +```