Skip to content

Latest commit

 

History

History
292 lines (206 loc) · 9.41 KB

README.md

File metadata and controls

292 lines (206 loc) · 9.41 KB
Raw
'ts-blank-space' as a logo. the 'ts' is in TypeScript blue and the 'blank-space' is in JavaScript orange

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

npm Badge

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
  • It is small
    • Around 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

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, and when removing a leading type annotation could introduce an ASI hazard.

Example one - type-only statement

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

becomes:

statementWithNoSemiColon
;
("not calling above statement");

Example two - computed class fields/methods

class C {
    field = 1/* no ; */
    public ["computed field not accessing above"] = 2
}

becomes:

class C {
    field = 1/* no ; */
    ;      ["computed field not accessing above"] = 2
}

Arrow function type annotations that introduce a new line

If the type annotations around an arrow function's parameters introduce a new line then only replacing them with blank space can be incorrect. Therefore, in addition to removing the type annotation, the ( or ) surrounding the function parameters may also be moved.

Example one - multi-line return type:

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

becomes:

let f = (a        , b

) => [a, b];

Example two - async with multi-line type arguments:

let f = async <
    T
>(v: T) => {};

becomes:

let f = async (

  v   ) => {};

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 generate .jsx output. 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.

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

...

const tsxSource = ts.createSourceFile("input.tsx", tsxInput, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TSX);
const jsxOutput = blankSourceFile(tsxSource, onError);

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 {};";

3rd party ecosystem plugins

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.