Typescript workflow

Our Typescript workflow

Repository structure

Each SDK package has its own folder that follows the same convention:

• devdoc contains our requirement documents that list what we expect from each class/API. It's more of a technical specification detailing expectations and tests than API documentation. Each requirement is identified by a tag and the corresponding tag can be found both in code and docs, in order to quickly locate an implementation detail.
• src contains the Typescript code
• test contains the Javascript test code. For now, we're keeping our javascript tests because it's what most of our customers use but we will consider moving the tests to Typescript too in the future.
• lib contains the generated Javascript code, the generated Typescript declaration files and during development the generated .map files. This folder shall not be checked in.

NPM packages

NPM packages ship basically the content of the lib folder as well as entrypoints and metadata files. Meaning only the Javascript code and .d.ts files find their way to the package.

Linking packages together

Because the full implementation of a feature can span across multiple packages, it is necessary to be able to "link" packages together, meaning relying on edited files on the local hard drive instead of files downloaded from NPM packages in the node_modules folder.

To make it easier to link packages together, we've created the dev_setup.(sh|cmd) scripts in the /build folder. These will create the proper links between all packages, install all dependencies, and transpile the typescript code into javascript so that you're ready to write code and debug as soon as it's done.

Building and Linting

As of writing this, we haven't adopted gulp/grunt and therefore rely on npm scripts described in package.json files. All packages come with the same scripts:

• lint will run the code linter, tslint in our case. We do not lint the generated javascript code. All packages share the same tslint.json file located at the root of the repository.
• build will run the Typescript compiler, without any command line options, relying exclusively on a tsconfig.json file for each package.
• alltests will run all tests including integration tests with the default mocha reporter
• alltests-min will run all tests including integration tests with the minimal mocha reporter, printing ony one character per test.
• unittests will run only unit tests with the default mocha reporter
• unittests-min will run only unit tests with the minimal mocha reporter, printing ony one character per test.
• ci will run the linter, compiler and all tests, with minimal mocha reports, then will check code coverage numbers.

Working on a new feature or a bugfix: an example.

1. Create a local copy of the repository and cd into it

$ git clone https://github.com/azure/azure-iot-sdk-node
$ cd azure-iot-sdk-node

2. Create links between all packages

$ .\build\dev_setup.cmd

or

$ ./build/dev_setup.sh

3. Change some code in the typescript files
4. Build/Lint your code changes

$ npm -s run build
$ npm -s run lint

5. Assuming you've now fixed all errors, run the tests

$ npm -s run ci

If all tests pass, code review/pull request and checking your stuff in are in order.

Debugging typescript code

This is all detailed here