Thursday, 11 October 2018

Introduction to TypeScript

This article describes how to create a Node.js application written in TypeScript. Full code can be found in this GitHub repository.

Let's first initialize our Node project:

>npm init -y


Installation


TypeScript has a command-line compiler which transforms TypeScript code into JavaScript. It comes in a form of a Node package named typescript. Let's install it as a development dependency:

>npm install typescript --save-dev
npm notice created a lockfile as package-lock.json. You should commit this file.
+ typescript@3.1.1
added 1 package from 1 contributor and audited 1 package in 1.318s
found 0 vulnerabilities

package.json now contains:

{
    ...
    "devDependencies": {
        "typescript": "^3.1.1"
    }
}

TypeScript Compiler


Let's see what are the command line arguments and options of tsc:

>npx tsc
Version 3.1.1
Syntax:   tsc [options] [file...]

Examples: tsc hello.ts
          tsc --outFile file.js file.ts
          tsc @args.txt
          tsc --build tsconfig.json

Options:
 -h, --help                                         Print this message.
 -w, --watch                                        Watch input files.
 --all                                              Show all compiler options.
 -v, --version                                      Print the compiler's version.
 --init                                             Initializes a TypeScript project and creates a tsconfig.json file.
 -p FILE OR DIRECTORY, --project FILE OR DIRECTORY  Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
 -b, --build                                        Build one or more projects and their dependencies, if out of date
 --pretty                                           Stylize errors and messages using color and context (experimental).
 -t VERSION, --target VERSION                       Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'.
 -m KIND, --module KIND                             Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'.
 --lib                                              Specify library files to be included in the compilation.
                                                      'es5' 'es6' 'es2015' 'es7' 'es2016' 'es2017' 'es2018' 'esnext' 'dom' 'dom.iterable' 'webworker' 'webworker.importscripts' 'scripthost' 'es2015.core' 'es2015.collection' 'es2015.generator' 'es2015.iterable' 'es2015.promise' 'es2015.proxy' 'es2015.reflect' 'es2015.symbol' 'es2015.symbol.wellknown' 'es2016.array.include' 'es2017.object' 'es2017.sharedmemory' 'es2017.string' 'es2017.intl' 'es2017.typedarrays' 'es2018.intl' 'es2018.promise' 'es2018.regexp' 'esnext.array' 'esnext.symbol' 'esnext.asynciterable' 'esnext.intl'
 --allowJs                                          Allow javascript files to be compiled.
 --jsx KIND                                         Specify JSX code generation: 'preserve', 'react-native', or 'react'.
 -d, --declaration                                  Generates corresponding '.d.ts' file.
 --declarationMap                                   Generates a sourcemap for each corresponding '.d.ts' file.
 --sourceMap                                        Generates corresponding '.map' file.
 --outFile FILE                                     Concatenate and emit output to single file.
 --outDir DIRECTORY                                 Redirect output structure to the directory.
 --removeComments                                   Do not emit comments to output.
 --noEmit                                           Do not emit outputs.
 --strict                                           Enable all strict type-checking options.
 --noImplicitAny                                    Raise error on expressions and declarations with an implied 'any' type.
 --strictNullChecks                                 Enable strict null checks.
 --strictFunctionTypes                              Enable strict checking of function types.
 --strictPropertyInitialization                     Enable strict checking of property initialization in classes.
 --noImplicitThis                                   Raise error on 'this' expressions with an implied 'any' type.
 --alwaysStrict                                     Parse in strict mode and emit "use strict" for each source file.
 --noUnusedLocals                                   Report errors on unused locals.
 --noUnusedParameters                               Report errors on unused parameters.
 --noImplicitReturns                                Report error when not all code paths in function return a value.
 --noFallthroughCasesInSwitch                       Report errors for fallthrough cases in switch statement.
 --types                                            Type declaration files to be included in compilation.
 --esModuleInterop                                  Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'.
 @<file>                                            Insert command line options and files from a file.

Compiling


Let's add to the project some TypeScript file.

..\demo-typescript\src\index.ts:

function greeter(person : string) {
    return "Hello, " + person;
}

let user = "Bojan";
let greeting = greeter(user);
console.log(greeting);

Let's follow an example from tsc --help in order to get TS code compiled into JavaScript:

..\demo-typescript>npx tsc --outFile build/index.js src/index.ts

After this command is executed build/index.js file is created and it looks like this:

function greeter(person) {
    return "Hello, " + person;
}
var user = "Bojan";
var greeting = greeter(user);
console.log(greeting);

We can run it with Node.js:

\demo-typescript>node build/index.js
Hello, Bojan

It is not possible to specify compiling files from entire directory via command line arguments - all files have to be explicitly listed. This and also listing all arguments in the command line is not practical. Solution for this is specifying all options in the configuration file and instructing tsc to read everything from it.

Configuration


TypeScript transpiler uses a config file tsconfig.json. To create , use:

..\demo-typescript>npx tsc --init
message TS6071: Successfully created a tsconfig.json file.


Default content of tsconfig.json is:

{
  "compilerOptions": {
    /* Basic Options */
    "target": "es5",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */
    "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
    // "lib": [],                             /* Specify library files to be included in the compilation. */
    // "allowJs": true,                       /* Allow javascript files to be compiled. */
    // "checkJs": true,                       /* Report errors in .js files. */
    // "jsx": "preserve",                     /* Specify JSX code generation: 'preserve', 'react-native', or 'react'. */
    // "declaration": true,                   /* Generates corresponding '.d.ts' file. */
    // "declarationMap": true,                /* Generates a sourcemap for each corresponding '.d.ts' file. */
    // "sourceMap": true,                     /* Generates corresponding '.map' file. */
    // "outFile": "./",                       /* Concatenate and emit output to single file. */
    // "outDir": "./",                        /* Redirect output structure to the directory. */
    // "rootDir": "./",                       /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */
    // "composite": true,                     /* Enable project compilation */
    // "removeComments": true,                /* Do not emit comments to output. */
    // "noEmit": true,                        /* Do not emit outputs. */
    // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
    // "downlevelIteration": true,            /* Provide full support for iterables in 'for-of', spread, and destructuring when targeting 'ES5' or 'ES3'. */
    // "isolatedModules": true,               /* Transpile each file as a separate module (similar to 'ts.transpileModule'). */

    /* Strict Type-Checking Options */
    "strict": true,                           /* Enable all strict type-checking options. */
    // "noImplicitAny": true,                 /* Raise error on expressions and declarations with an implied 'any' type. */
    // "strictNullChecks": true,              /* Enable strict null checks. */
    // "strictFunctionTypes": true,           /* Enable strict checking of function types. */
    // "strictPropertyInitialization": true,  /* Enable strict checking of property initialization in classes. */
    // "noImplicitThis": true,                /* Raise error on 'this' expressions with an implied 'any' type. */
    // "alwaysStrict": true,                  /* Parse in strict mode and emit "use strict" for each source file. */

    /* Additional Checks */
    // "noUnusedLocals": true,                /* Report errors on unused locals. */
    // "noUnusedParameters": true,            /* Report errors on unused parameters. */
    // "noImplicitReturns": true,             /* Report error when not all code paths in function return a value. */
    // "noFallthroughCasesInSwitch": true,    /* Report errors for fallthrough cases in switch statement. */

    /* Module Resolution Options */
    // "moduleResolution": "node",            /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */
    // "baseUrl": "./",                       /* Base directory to resolve non-absolute module names. */
    // "paths": {},                           /* A series of entries which re-map imports to lookup locations relative to the 'baseUrl'. */
    // "rootDirs": [],                        /* List of root folders whose combined content represents the structure of the project at runtime. */
    // "typeRoots": [],                       /* List of folders to include type definitions from. */
    // "types": [],                           /* Type declaration files to be included in compilation. */
    // "allowSyntheticDefaultImports": true,  /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */
    "esModuleInterop": true                   /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
    // "preserveSymlinks": true,              /* Do not resolve the real path of symlinks. */

    /* Source Map Options */
    // "sourceRoot": "",                      /* Specify the location where debugger should locate TypeScript files instead of source locations. */
    // "mapRoot": "",                         /* Specify the location where debugger should locate map files instead of generated locations. */
    // "inlineSourceMap": true,               /* Emit a single file with source maps instead of having a separate file. */
    // "inlineSources": true,                 /* Emit the source alongside the sourcemaps within a single file; requires '--inlineSourceMap' or '--sourceMap' to be set. */

    /* Experimental Options */
    // "experimentalDecorators": true,        /* Enables experimental support for ES7 decorators. */
    // "emitDecoratorMetadata": true,         /* Enables experimental support for emitting type metadata for decorators. */
  }
}


If we execute

>npx tsc

...tsc will compile all .ts files in the project and place matching .js files next to .ts files.

To specify output directory (named e.g. "bundle") into which we want output structure to be placed in, we can set in config file:

"outDir": "./bundle/",

npx tsc will now output all .js files (preserving their original directory tree) in the bundle directory.


Let's now add build and start scripts to package.json so we don't have to use npx and run tools manually but follow the common approach - use npm as the task runner:

..\demo-typescript\package.json:

  "scripts": {
    ...
    "build-ts" : "tsc",
    "start" : "node bundle/index.js"
  },

Let's verify it:

..\demo-typescript>npm run build-ts

> demo-typescript@1.0.0 build-ts ..\demo-typescript
> tsc


..\demo-typescript>npm run start

> demo-typescript@1.0.0 start ..\demo-typescript
> node bundle/index.js

Hello, Bojan


Syntax

Variables

const x: number = 0;

Functions


Function Arguments


function foo(s: string){}
function foo(n: number){}

Modules


import { MyInterface, MyClass, MyFunction, MyEnum,  MyType } from '../myDomain/myModule';


References:

http://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html
https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
Style guide: https://github.com/basarat/typescript-book/blob/master/docs/styleguide/styleguide.md
https://www.quora.com/topic/TypeScript
Typescript. The bad, the worse, and the ugly.
JavaScript - TypeScript: Making .NET Developers Comfortable with JavaScript (2013)
Configuring TypeScript compiler
How to run typescript compiler as a package.json script without grunt or gulp?
How to set up a TypeScript project

Post a Comment