• Ogle
  • Magister
  • Syntheogen
  • nthClock
  • JavaScript
  • TypeScript
  • C++
  • C#
  • React
  • WPF
  • Git
  • Split Notation
  • Physics (PDF)
  • DSP (PDF)
  • Math (PDF)
  • Mathematica
  • Play Time
  • Music
  • Politics
  • More from Ian Mortimer’s Time Traveler’s Guide to Medieval England:

    “...blind horses are usually worth only about half their usual price. In case you are wondering why there are so many blind horses, it is because they have been stolen, and blinding a horse is one way to prevent it from finding its way back home or recognizing its true master.”

    Yesterday, today, or tomorrow, this is what happens when animals are treated as property.

    TypeScript Notes

    Programming language notes — TypeScript 5

    TypeScript Notes

    These are my TypeScript notes, covering version 5. They are not complete, but I am working on them now. If you find a mistake, please let me know.

    The example code uses a new notation I am developing. More on that soon.

    This page includes a two-column print style. For best results, print in landscape, apply narrow margins, change the Scale setting in your browser’s print options to 70%, and enable background graphics. Firefox and Chrome each have their own set of printing bugs, but one of them usually works.

    Contents

    tsc

    The typescript package includes a transpiler tsc, which translates TypeScript into JavaScript. Tools like Babel can also transpile it.

    tsc supports numerous command line options, but these are typically added to tsconfig.json files, rather than being passed on the command line. TypeScript filenames or globs can also be passed as tsc arguments. tsconfig.json is ignored when source files are specified this way.

    Sources

    tsc CLI Options

    Help and setup options

    -h
    --help
    Lists commonly-used compiler options.
    --all
    Lists all compiler options.
    --init
    Creates a tsconfig.json file in the current folder.

    General build options

    -p path
    --project path
    Builds using the specified configuration file, or with the tsconfig.json file in the specified folder.
    --showConfig
    Displays the content of the tsconfig.json that would be used during a build, without actually building.
    --noEmitOnError
    Prevents output file generation if build errors are reported.
    --diagnostics
    --extendedDiagnostics
    Displays compilation performance data, including total build time.

    Library and module input options

    --lib versionList
    tsc provides declaration files that describe standard JavaScript functions and containers, plus the DOM API. By default, it uses the --target setting to decide which version of these libraries to include. This option can be used to select a different version, or to include some libraries while excluding others. Library versions can also be selected by configuring the package manager.
    --noLib
    Stops tsc from automatically including library declaration files, even if --lib is set. The developer must provide their own declarations for types like Object, Function, String, et cetera.
    --moduleDetection
    Determines how tsc decides whether a source file is a module.
    --moduleResolution
    Determines how tsc finds the files referenced by module imports, so that their types can be identified. This is called module resolution. Though classic is the default setting for some --module selections, it will be deprecated in TypeScript 6. Node projects should use node16 or nodenext, which are the defaults for the corresponding --module selections. Other configurations are more complex; these are addressed the TypeScript documentation.
    --rootDirs pathList
    Defines one or more folders that are implicitly merged (along with their subfolders) with the source folder hierarchy when resolving import paths. The modules in the various hierarchies can then be specified as if they were part of a single directory structure. This should not be confused with --rootDir, which affects the folder hierarchy created within the --outDir folder.
    --traceResolution
    Displays build output that explains why each module was included and how it was resolved.
    --allowArbitraryExtensions
    The module name inside an import is called a module specifier. This flag disables the build error that normally occurs when a specifier includes an unexpected file extension.
    --moduleSuffixes suffixList
    Provides a list of suffixes to be appended automatically to module specifiers when resolving these to files.
    --resolveJsonModule

    Allows JSON files to be imported as JavaScript objects:

    import Data from "./data.json";
    
    --noUncheckedSideEffectImports
    Side effect imports are imports that bring nothing into scope. By default, tsc ignores these if the specified module is not found. This flag produces a build error instead.
    --isolatedDeclarations
    By default, TypeScript allows variable types and function signatures to be inferred from their definitions. Those definitions can themselves rely on inferred types (possibly from other modules) which causes declaration generation to take longer than it might. When this flag is set, exported variables and functions produce compile errors if their declarations would require non-trivial type inference.

    Sources

    Supporting lib from node_modules The module output format The module compiler option Modules - Choosing Compiler Options

    Source input options

    --allowJs
    Allows plain JavaScript files to be used within the project. When disabled, importing a JavaScript file produces a compiler error.
    --checkJs
    Enables error checking for plain JavaScript files processed with --allowJs.
    --listFiles
    --explainFiles
    --listFilesOnly
    Lists all files that were read during the build, including external files referenced by internal project files. --explainFiles also gives the reason for each file's inclusion. --listFilesOnly lists them without actually building.

    Declaration output options

    --declaration
    Produces type definition files in addition to normal build output. These files use the d.ts file extension. Like C/C++ headers, they describe the public interfaces of compiled modules.
    --emitDeclarationOnly
    Causes d.ts files to be generated without other build output.
    --declarationDir path
    Specifies a separate output folder for d.ts files.
    --declarationMap
    Produces source maps that link d.ts files to the ts files that generated them.
    --stripInternal
    Causes any export that includes an @internal directive in its JSDOC comment to be excluded from the declaration output.

    Module output options

    --module value

    Determines the module type to be used in js file output. The default is es6 (also specified with es2015), or CommonJS if --target is es5. es2020 produces ES6 modules, while adding support for dynamic imports and import.meta metadata. es2022 adds top-level await. esnext and nodenext target current versions of JavaScript and Node, and will incorporate new features as those are standardized.

    Node projects should use node16 or nodenext, not commonjs or any of the ECMAScript options. Node now supports both CommonJS and ECMAScript modules, so, like Node, tsc uses a source file's extension or the package.json in its folder or an ancestor folder to identify its module type. cts and mts files are considered to be CommonJS or ECMAScript modules, respectively. ts files are considered to be ECMAScript modules if the type property in its package.json is set to module. This decision affects the file's transpilation, plus its output file extension.

    --verbatimModuleSyntax
    TypeScript allows types and interfaces to be imported from modules; imports that only target these elements are called type-only imports. Because types have no use in JavaScript, these imports may be omitted from js file output, which prevents side effects from being performed. This flag ensures that all modules are imported in the js output, except those explicitly defined as type-only with import type.

    Source output options

    --target value
    Specifies the JavaScript version to be used when generating js files. The default is es5. esnext uses the highest version supported by this version of TypeScript.
    --outDir path
    Determines the folder into which output files and folders will be placed. This includes compiled js files, declarations, source maps, and others. The source folder hierarchy will be reproduced as well. When this option not used, output files are placed in the source folders alongside the ts files that generated them.
    --rootDir path
    When combined with --outDir, this option specifies the root folder relative to which source file paths are compared when reproducing the source folder hierarchy inside the --outDir folder. This should not be confused with --rootDirs, which defines extra paths for module resolution.
    --outFile pathName
    Causes all non-module files to be concatenated into the specified output file. --module must be set to None, System, or AMD.
    --listEmittedFiles
    Lists all output files that were generated by the compiler.
    --emitBOM
    Adds UTF-8 byte-order marks to all output files.
    --newLine
    Determines whether output files end lines with lf or crlf. The default is lf.
    --removeComments
    Comments in source files are normally included in js file output. This flag removes them.
    --jsx value
    --jsxFactory value
    --jsxFragmentFactory value
    --jsxImportSource value
    These settings determine whether and how JSX is transpiled in the js file output. They can be changed in specific files by adding @jsxRuntime, @jsx, @jsxFrag, @jsxImportSource directives to comments inside them.

    Source map output options

    --sourceMap
    Produces js.map and jsx.map source map files that associate js files with the ts files that generated them. The flag adds comments to the compiled js files; those comments reference the map files, which then reference the ts files. This allows debuggers to show the original TypeScript while running the compiled JavaScript.
    --inlineSourceMap
    Produces source map data, but instead of storing it in source map files, this flag adds it to the js file comments that would reference those files, if --sourceMap were used instead.
    --inlineSources
    Adds ts file content directly to the source map files, if --sourceMap is used, or to the source map comments, if --inlineSourceMap is used.

    Error checking options

    --strict

    Collectively enables these flags, which can be individually disabled after:

    • alwaysStrict
    • strictNullChecks
    • strictBindCallApply
    • strictFunctionTypes
    • strictPropertyInitialization
    • noImplicitAny
    • noImplicitThis
    • useUnknownInCatchVariable
    --alwaysStrict
    Enables strict mode for all files, and adds "use strict" to all js output.
    --strictNullChecks
    Associates unique types with undefined and null, which are added to the union of types that qualify a variable or other element, if undefined or null are possible values. This produces a build error if the element is read without checking for undefined or null.
    --strictPropertyInitialization
    Produces a build error if a class field is defined without being initialized in the body or assigned in the constructor. This does not apply if undefined is part of the field's type.
    --strictFunctionTypes
    Produces a build error if any non-method function is assigned to a type with less stringent parameter types.
    --strictBindCallApply
    Produces a build error if call, bind, or apply is invoked with arguments that fail to match the parent function.
    --strictBuiltinIteratorReturn
    Causes iterators to produce values that are qualified with a concrete type plus undefined, rather than any.
    --noImplicitAny
    TypeScript sometimes assumes a type of any if a type has not been specified, and cannot be inferred. This flag produces a build error instead.
    --noImplicitOverride
    Produces a build error if a subclass overrides a parent method without the override keyword.
    --noImplicitReturns
    Produces a build error if any function execution path lacks an explicit return, unless the function's return type is undefined.
    --noImplicitThis
    Produces a build error if properties are read from this in a context in which the type of this is not known.
    --noFallthroughCasesInSwitch
    Produces a build error if any case statement lacks a break, return, or throw.
    --noUnusedLocals
    --noUnusedParameters
    Produces a build error if any local variable or function parameter is defined but not used.
    --allowUnreachableCode
    --allowUnusedLabels
    By default, tsc produces warnings when it finds unreachable code or unused labels. Setting this option to true suppresses those warnings instead. Setting it to false produces build errors.
    --exactOptionalPropertyTypes
    Properties in types and interfaces can be suffixed with question marks to show that their presence is optional. Originally, these types and interfaces were satisfied when the optional properties were missing from the object, or when they were explicitly set to undefined. When this flag is set, undefined properties no longer satisfy these constraints.
    --downlevelIteration
    Causes code points containing multiple code units to be handled correctly when ECMAScript 6 iteration functionality is transpiled to older versions.
    --useUnknownInCatchVariables
    The exception parameter in a catch statement can be explicitly typed as any or unknown. By default, if it is not explicitly typed, it is considered to be any. This option causes it to be considered unknown instead.

    Sources

    Strict Builtin Iterator Checks

    Build mode options

    Incremental builds can be performed by dividing a large project into smaller subsidiary projects. Each subsidiary has its own tsconfig.json file, which must include --composite. A single parent project references the others with project references, defined in the references property within its tsconfig.json. The parent can then be built with --build or -b, which enable build mode. This mode builds the subsidiary projects if they are out of date, then loads their declaration files, and then builds the parent.

    Build mode options include:

    -b [pathList]
    --build [pathList]

    Builds the projects referenced by pathList, with each element being the path to a tsconfig.json file or to a folder that contains one. If no pathList is provided, the current folder is assumed.

    Before each pathList project is built, its project references are checked, and those projects are built, if they are out of date. This flag implicitly sets --noEmitOnError for all projects.

    --composite

    Allows this project to be included as a project reference when another project uses build mode. In particular, this flag enforces requirements that allow tsc to determine whether this project is up to date, or whether it needs to be rebuilt. It also implicitly enables --declaration. All source files in this project must be listed in files or include within tsconfig.json.

    When specified on the command line, this option can only be disabled, by passing false or null as an argument. It can be enabled only within tsconfig.json.

    --force
    Builds all files in the project, even those that have not changed. This may be necessary when d.ts files or other build output is committed to source control, if the source control app does not preserve timestamps. Must be combined with --build.
    --verbose
    Builds the project with verbose log output. Must be combined with --build.
    --clean
    Cleans the project. Must be combined with --build.

    Sources

    Project References

    tsconfig.json

    When source files are not passed as command line arguments, tsc searches upward from the current folder for a tsconfig.json file. If no file is found, tsc displays the help, or produces an error, if --build was specified.

    Sources

    TSConfig Reference

    General sources

    The TypeScript Handbook
    Microsoft