A small, fast, pure JavaScript type-stripper that uses the official TypeScript parser.

---

TypeScript goes in:

class C<T> extends Array<T> implements I {
//     ^^^              ^^^^^^^^^^^^^^^^
    private field!: string;
//  ^^^^^^^      ^^^^^^^^^

    method<T>(this: T, a?: string): void {
//        ^^^ ^^^^^^^^  ^^^^^^^^^ ^^^^^^
    }
}

JavaScript + space comes out:

class C    extends Array                 {
//     ^^^              ^^^^^^^^^^^^^^^^
            field         ;
//  ^^^^^^^      ^^^^^^^^^

    method   (         a         )       {
//        ^^^ ^^^^^^^^  ^^^^^^^^^ ^^^^^^
    }
}

Try it out in the playground.

Rationale

The benefits of this library are:

• It is fast
  • See ./perf folder for a micro-benchmark
    • Only 4 times slower than a native multi-threaded transformer
    • Fastest compared to non-native (JavaScript or Wasm)
  • No new JavaScript code is generated; instead, it re-uses slices of the existing source string
  • This is particularly true if your program is already generating the TypeScript SourceFile object, because it can be reused -- and producing the AST is the most time consuming part.
• 100% JavaScript runtime
  • No Wasm
  • No native-addons
  • No child process
• It is small
  • Less than 700 lines of code and one dependency (TypeScript)
  • By doing so little, the code should be relatively easy to maintain
• Delegates the parsing to the official TypeScript parser
• No need for additional SourceMap processing; see "where are my SourceMaps?"

ℹ️ Not all TypeScript syntax is supported (see unsupported syntax). There is also no down-leveling; the JavaScript is preserved as is.

Contents

• Installing
• API
• Node.js Loader
• SourceMaps
• Implementation details
• Unsupported Syntax
• tsconfig.json
• TSX/JSX
• ESM Output
• Contributions
• License
• Code of Conduct
• Security Vulnerability Reporting

Installing

npm install ts-blank-space

API

String to String

export default function tsBlankSpace(ts: string, onError?: (node) => void): string;

import tsBlankSpace from "ts-blank-space";

console.log(tsBlankSpace(`let x: string;`));
// "let x        ;"

Bring your own AST

export function blankSourceFile(ts: typescript.SourceFile, onError?: (node) => void): string;

import ts from "typescript";
import { blankSourceFile } from "ts-blank-space";

const ast = ts.createSourceFile(...);
console.log(blankSourceFile(ast));

Node.js Loader

ts-blank-space exposes the required Node.js module loader hooks to use ts-blank-space to pre-process *.ts that are imported before they are evaluated.

# Install (one time):
$ npm install --save-dev ts-blank-space

# Example usage (Node.js >= v18.20):
$ node --import ts-blank-space/register ./path/to/your/file.ts

In addition to loading *.ts files, an import resolver is also registered which 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.

ℹ️ The loader assumes that all .ts files are ESM.

Where are my SourceMaps?

Because all the JavaScript in the output is located at the same line, column, and byte-offset as the original source, no mapping information is lost during the transform.

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.

ASI (automatic semicolon insertion)

To guard against ASI issues in the output, ts-blank-space will add ; to the end of type-only statements.

Example input:

statementWithNoSemiColon
type Erased = true
("not calling above statement")

becomes:

statementWithNoSemiColon
;
("not calling above statement");

Arrow function return types that introduce a new line

If the annotation marking the return type of an arrow function introduces a new line before the =>, then only replacing it with blank space would be incorrect.

Therefore, in addition to removing the type annotation, the ) is moved down to the end of the type annotation.

Example input:

let f = (a: string, b: string): Array<
   string
> => [a, b];

becomes:

let f = (a        , b

) => [a, b];

Unsupported Syntax

Some parts of TypeScript are not supported because they can't be erased in place due to having runtime semantics. See unsupported_syntax.md.

When unsupported syntax is encountered, ts-blank-space will call the optional onError callback and continue. Examples can be seen in errors.test.ts.

Recommended tsconfig.json compiler settings

{
    // Because JS syntax is emitted as-is
    "target": "esnext",
    // Because class fields are preserved as written which corresponds
    // to 'define' semantics in the ECMAScript specification
    "useDefineForClassFields": true,
    // Because imports and exports are preserved as written, only removing the
    // parts which are explicitly annotated with the `type` keyword
    "verbatimModuleSyntax": true,
}

TSX/JSX

.tsx input will be .jsx output because the JSX parts are not transformed, but instead preserved in the output.

By default, ts-blank-space will parse the file assuming .ts. If the original file contains JSX syntax, then the parsing should be done manually. There is a TSX example in valid.test.ts.

Ensuring ESM output

TypeScript may add an export {}; if all imports and exports were removed (because they were import/export type).

Because ts-blank-space only removes code, this is not performed. To force the output to always have an ESM syntactic marker, you can manually append "export {};";

Contributions

We ❤️ contributions.

Have you had a good experience with this project? Why not share some love and contribute code, or just let us know about any issues you had with it?

We welcome issue reports here; be sure to choose the proper issue template for your issue, so that we can be sure you're providing the necessary information.

Before sending a Pull Request, please make sure you read our Contribution Guidelines.

License

Please read the LICENSE file.

Code of Conduct

This project has adopted a Code of Conduct. If you have any concerns about the Code, or behavior which you have experienced in the project, please contact us at [email protected].

Security Vulnerability Reporting

Please refer to the project Security Policy.