Skip to main content

license GitHub issues GitHub pulls TS-Standard - TypeScript Standard Style Guide

How to build the xPack Logger

This page is designed for developers of the xPack Logger project and provides documentation on how to build and test the package.

Prerequisites​

The xPack Logger is a portable Node.js project, and development can be performed on macOS, GNU/Linux and even Windows (although some npm scripts require bash).

The prerequisites are:

  • node >= 18.0.0
  • npm

To ensure compatibility with older node, preferably revert to an older one:

nvm use --lts 18
code

Get project sources​

The project is hosted on GitHub:

The project uses two branches:

  • master, with the latest stable version (default)
  • development, with the current development version

To clone the stable branch (master), run the following commands in a terminal (on Windows use the Git Bash console):

mkdir ~/Work/npm-modules && cd ~/Work/npm-modules
git clone https://github.com/xpack/logger-ts.git logger-ts.git

For development purposes, clone the development branch:

mkdir ~/Work/npm-modules && cd ~/Work/npm-modules
git clone \
  --branch development \
  https://github.com/xpack/logger-ts.git logger-ts.git

Or, if the repo was already cloned:

git -C ~/Work/npm-modules/logger-ts.git pull

Satisfy dependencies​

npm --prefix ~/Work/npm-modules/logger-ts.git install

To facilitate the use of this module in other packages, add a link from the central npm storage to this local development folder:

npm --prefix ~/Work/npm-modules/logger-ts.git link

And in the projects referring it:

npm link @xpack/logger

Start the compile background task​

The TypeScript compiler can automatically recompile modified files. For this, start it in watch mode.

npm --prefix ~/Work/npm-modules/logger-ts.git run compile-watch

Language standard compliance​

The current version is compiled with TypeScript 4.9.5:

The compiler is configured to produce es2020 & commonjs files, which means ECMAScript6 with legacy CommonJS modules, that can be imported by any other project either via require() or import.

For more details on how to configure tsconfig.json, please see:

Standard style​

As style, the project uses ts-standard, the TypeScript variant of Standard Style, automatically checked at each commit via CI.

// eslint-disable-next-line @typescript-eslint/no-xxx-yyy

The known rules are documented in the typescript-eslint project.

Generally, to fit two editor windows side by side in a screen, all files should limit the line length to 80.

/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */

Known and accepted exceptions:

  • none

To manually fix compliance with the style guide (where possible):

% npm run fix

> @xpack/logger@undefined fix
> ts-standard --fix src && standard --fix test
...

Documentation metadata​

The documentation metadata uses the TypeDoc tags, without explicit types, since they are provided by TypeScript.

note

Microsoft is currently developing a new project (TSDoc) which tries to standardise TypeScript documentation metadata.

This standard is generaly compatible with TypeDoc; at the time of this writing, among the visible differences is the lack of the @category or @group tags.

Tests​

The tests use the node-tap framework (A Test-Anything-Protocol library for Node.js, written by Isaac Schlueter).

Tests can be written in TypeScript, assuming ts-node is also installed (https://node-tap.org/docs/using-with/#using-tap-with-typescript)

As for any npm package, the standard way to run the project tests is via npm run test:

npm --prefix ~/Work/npm-modules/logger-ts.git install
npm --prefix ~/Work/npm-modules/logger-ts.git run test

A typical test result looks like:

% npm run test-100-c8

> @xpack/logger@{customField('version')} pretest-100-c8 ...
> npm run lint

> @xpack/logger@{customField('version')} lint ...
> ts-standard src && standard esm

> @xpack/logger@{customField('version')} test-100-c8 ...
> npm run test-tap-coverage-100-c8 -s

...

To run a specific test with more verbose output, use npm run tap:

% npm run tap tests/tap/010-xxx.ts

...

Coverage tests​

Coverage tests are a good indication on how much of the source files is exercised by the tests. Ideally all source files should be covered 100%, for all 4 criteria (statements, branches, functions, lines).

Thus, passing coverage tests was enforced for all tests, as seen before.

Coverage exceptions​

Exclusions are marked with /* istanbul ignore next */ for istanbul and /* c8 ignore start */ /* c8 ignore stop */ for c8.

  • none

Continuous Integration (CI)​

The module is tested with 100% coverage and CI tested on every push via GitHub Actions, on Ubuntu, Windows and macOS, using node 18 and 20.

Tricks & tips​

To trace TypeScript module resolution:

    "compile": "tsc --traceResolution  -p ./",