docs: READMEs and performance documentation updated

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.

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
 

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
+```