plus-typescript

plus-typescript

This is a fork of TypeScript, including a 30 line hack to allow type annotations using comments in the code.

If you enclose all ts-specific code inside comments, a .js file is typed AND still executable by node/browser without the need of a transpilation step.

Then, you can directly edit sources on Chrome Developer Tools with hot-reload and instant feedback. Chrome Developer Tools also allows you to map a local folder so you can save your changes using Chrome Developer Tools as a fast-and-dirty IDE.

We wanted all of this without losing the amazing productivity TypeScript brings in, so this hack was born to allow us to type-checked .js files as if they where .ts files, with all TS-specific code & annotations included in special comments.

Examples

example.ts: TypeScript: type-checked, needs transpiling step

export function 
  ShowHelp(title:string, options:Record<string,OptDecl>):void{
    // show help about declared options
    console.log("-".repeat(60))
    console.log("Options:")
...
}

example.js, plus-typescript, type-checked, can be run by node/browser

export function 
  ShowHelp(title/*:string*/, options/*:Record<string,OptDecl>*/) /*:void*/ {
    // show help about declared options
    console.log("-".repeat(60))
    console.log("Options:")
...
}

How it works

The 30-line hack inside TypeScript infrastructure services makes the following sequences invisible to tsc:

• /*: and */ when used on the same line, so you can write title/*:string*/ and tsc will see: title:string

• /*+ and +*/ slash-asterisk-plus and plus-asterisk-slash, are invisble to tsc

• also: .js files are processed as if they were .ts files

Slash-asterisk-plus examples

You need to enclose type declarations with slash-asterisk-plus

//util/CommandLineArgs.js
/*+
export type OptionDeclaration =
    {
        shortName: string
        valueType?: string
        helpText?: string
        value?: string|number|boolean
    }
+*/

//main.js
/*+import type { OptionDeclaration } from "./util/CommandLineArgs"+*/

function view(command/*:string*/, fnJSONparams/*+?:any+*/)/*:string*/ {...

Here the annotation ?:any is processed by typescript but ignored by node and the browser

Usage

npm install --save-dev plus-typescript
npm remove typescript

set the following as build script:

//package.json
  "scripts": {
    "build": "node build.js",
  }

• Keep all files in /src with a .js extension
• add "plus-typescript" instead of "typescript" in your package.json's "devDependencies:{"
• move all ts type-annotations inside comments /*: or /*+
• use the .js files directly with node or in the browser

See the example project for a complete package.json example

Example project

plus-ts-test is a project example using plus-typescript and node v14 to make a CLI tool, you can see the project here: github.com/luciotato/plus-ts-test

Status

This is beta. Mantainers and contributors are welcomed.

Contibuting

The modifications are in the plus branch, and that's the brach that's published in npm as plus-typescript.

The master branch will be kept up-to-date with the official TypeScript repository.

We're keeping similar version numbers as TypeScript

Besides the hack, plus-typescript is completely API-compatible with TypeScript.

TypeScript

TypeScript is a language for application-scale JavaScript. TypeScript adds optional types to JavaScript that support tools for large-scale JavaScript applications for any browser, for any host, on any OS. TypeScript compiles to readable, standards-based JavaScript. Try it out at the playground, and stay up to date via our blog and Twitter account.

Find others who are using TypeScript at our community page.

Installing

For the latest stable version:

npm install -g typescript

For our nightly builds:

npm install -g typescript@next

Contribute

There are many ways to contribute to TypeScript.

• Submit bugs and help us verify fixes as they are checked in.
• Review the source code changes.
• Engage with other TypeScript users and developers on StackOverflow.
• Help each other in the TypeScript Community Discord.
• Join the #typescript discussion on Twitter.
• Contribute bug fixes.
• Read the archived language specification (docx, pdf, md).

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.

Documentation

• TypeScript in 5 minutes
• Programming handbook
• Homepage

Building

In order to build the TypeScript compiler, ensure that you have Git and Node.js installed.

Clone a copy of the repo:

git clone https://github.com/microsoft/TypeScript.git

Change to the TypeScript directory:

cd TypeScript

Install Gulp tools and dev dependencies:

npm install -g gulp
npm ci

Use one of the following to build and test:

gulp local             # Build the compiler into built/local.
gulp clean             # Delete the built compiler.
gulp LKG               # Replace the last known good with the built one.
                       # Bootstrapping step to be executed when the built compiler reaches a stable state.
gulp tests             # Build the test infrastructure using the built compiler.
gulp runtests          # Run tests using the built compiler and test infrastructure.
                       # Some low-value tests are skipped when not on a CI machine - you can use the
                       # --skipPercent=0 command to override this behavior and run all tests locally.
                       # You can override the specific suite runner used or specify a test for this command.
                       # Use --tests=<testPath> for a specific test and/or --runner=<runnerName> for a specific suite.
                       # Valid runners include conformance, compiler, fourslash, project, user, and docker
                       # The user and docker runners are extended test suite runners - the user runner
                       # works on disk in the tests/cases/user directory, while the docker runner works in containers.
                       # You'll need to have the docker executable in your system path for the docker runner to work.
gulp runtests-parallel # Like runtests, but split across multiple threads. Uses a number of threads equal to the system
                       # core count by default. Use --workers=<number> to adjust this.
gulp baseline-accept   # This replaces the baseline test results with the results obtained from gulp runtests.
gulp lint              # Runs eslint on the TypeScript source.
gulp help              # List the above commands.

Usage

node built/local/tsc.js hello.ts

Roadmap

For details on our planned features and future direction please refer to our roadmap.