rpccloud-js v0.0.6

RPC Cloud JS

Basic Setup

Module and Dependencies

I start by initialing this as an npm project.

$ npm init

Then, I install typescript, jest, ts-jest and @types/jest as dependencies:

$ npm i typescript jest ts-jest @types/jest --save-dev

At the time of this writing, that means typescript@2.7.1, jest@22.1.4 and ts-jest@22.0.2.

TypeScript

Next, we initialize this as a TypeScript project using:

$ npx tsc --init .

I want my TypeScript generated code to be stored in ./lib and I want declarations generated. So, I configure outDir in tsconfig.json to be ./lib.

Files

My .gitignore is then configured to be:

/node_modules
/lib
/coverage

...while my .npmignore is just:

/node_modules
/coverage

For the same reason, I remove the default value for files in tsconfig.json and replace it with:

    "exclude": ["node_modules", "dist"]

Configurating Jest

At this point, I'd like to run that test. But first I need to create a jest.config.js file for all my jest settings. This has to take into account the fact that I'm using ts-jest and the fact that my tests are stored in __tests__. So the resulting file looks like this:

module.exports = {
    transform: {
        "^.+\\.tsx?$": "ts-jest",
    },
    testRegex: "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
    moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
};

Scripts

I then add the following scripts to package.json:

  "scripts": {
    "compile": "tsc",
    "test": "jest --env=node --colors --coverage test"
  },

Code Coverage

Configuration

To enable code coverage, I update my jest.config.js file to:

module.exports = {
    transform: {
        "^.+\\.tsx?$": "ts-jest",
    },
    testRegex: "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
    moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
    collectCoverage: true,
};

I'll also want to update my .gitignore and .npmignore files to avoid version controlling or publishing the coverage directory generated by jest.

Compilation

Recall that we added a compile script to our package.json. We can compile the code with yarn compile. Doing so, we see that the lib directory is populated with two subdirectories, src and __tests__.

However, if we look in those directories, we will find that they only include the generated Javascript code. They do not include type definitions. In order to generate type definitions (.d.ts files) so that other TypeScript users can benefit from all the type information we've added to our code, we have to set the declaration field in our tsconfig.json file to be true.

Also note that in order for others to use this package as an NPM module, you need to set the main field in package.json to lib/src/index.js. Furthermore, in order for others to be able to access the types in this module, we also need to set the typings field in package.json to lib/src/index.d.ts. In other words,

    "main": "lib/src/index.js",
    "typings": "lib/src/index.d.ts",

If properly configured, we can then launch a node session and import our new package:

$ node
> var me = require(".")
undefined
> me
{ evaluate: [Function: evaluate],
  assertNever: [Function: assertNever] }
>

Now be sure to update your jest.config.js to include the following setting or jest will start matching the code in the lib/__tests__ directory:

    testPathIgnorePatterns: ["/lib/", "/node_modules/"],

Debugging

Finally, we come to debugging. I'm using Visual Studio Code, so I'll demonstrate how to get debugging working there. Some of this information may very well translate to other IDEs.

In VSCode, we can go to the debugging sidebar. Initially, next to the "play" button will be the words "No Configuration". Clicking on that brings up a pull-down menu with an option "Add Confiuration...".

As much as I love TypeScript, debugging is really its Achilles Heel. It isn't that you cannot debug, it is that it is just difficult to get working. If you select "Add Configuration..." and then "Node.js", you'll see several preconfigurations including one for mocha. But there isn't one for jest. So you'll have to create your own .vscode/launch.json file. Fortunately, the jest page suggestions you create a .vscode/launch.json file that looks like this:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Jest Tests",
            "type": "node",
            "request": "launch",
            "runtimeArgs": ["--inspect-brk", "${workspaceRoot}/node_modules/.bin/jest", "--runInBand"],
            "console": "integratedTerminal",
            "internalConsoleOptions": "neverOpen"
        }
    ]
}

I was pleasantly surprised to find that I could not only run my tests and get code coverage as usual, but also set breakpoints in both the tests (i.e., in __tests__/base.spec.ts) as well as in the code (e.g., src/core/functions.ts) and the debugger will find them.

Note that I tested all this on Node 8.x. I've seen issues with debugging using Node 6.x so if you are having trouble there, you might consider upgrading (or let, if you manage to fix it, submit a PR for this README explaining the fix).