CCF/js/ccf-app/DEVELOPMENT.md

Development notes

NOTE: Before contributing to this package, please read this document in full.

Getting started

npm install

Code

Relative imports: Every relative import of another TypeScript module must end with .js (yes, not .ts). The extension is the target extension and all TypeScript-related tooling understands this. Omitting extensions will lead to omitted extensions in the transpiled .js files which may cause import issues depending on the module loader used in the consuming environment.

Tests

npm test

Tests make use of the src/polyfill.ts module and run in Node.js, not in CCF. This allows to iterate quickly and allows to test most functions.

End-to-end tests running inside CCF are located in /tests/npm-app and are run as part of CCF's regular CI.

Debugging

Tests executed via npm test run in Node.js and can be debugged easily. The simplest workflow is using the JavaScript Debug Terminal in VS Code. Set a break point and run npm test inside the JavaScript Debug Terminal. The debugger will attach and stop automatically.

Debugging problems that only happen in CCF is harder.

If the problem occurs in native functions/properties exposed from C++ (see src/global.ts) then VS Code's C++ debugger can be used when running a CCF end-to-end test in virtual mode (not SGX).

Debugging of JavaScript code running in CCF is currently not possible. However, all uncaught exceptions and output from console.log() are dumped to the node's log files.

Docs

npm run docs
# or in watch mode with web server:
npm run docs:serve

typedoc's default theme is extended in doc/theme to add a backlink to CCF's main docs and add a version selector.

When this package's docs are built within CCF's multi-version Sphinx-based documentation then additional environment variables are set to enable the version selector.

A dummy CCF version configuration can be simulated as follows to show the version selector without running Sphinx:

export SMV_CURRENT_VERSION=ccf-0.19.1
export SMV_METADATA_PATH=$(pwd)/doc/theme/helpers/versions.sample.json
npm run docs:serve

Packaging

tsconfig.json is configured such that the transpiled JavaScript files are output in the root folder. This allows to consume modules without subfolder like import .. from '@microsoft/ccf-app/crypto.js. A side-effect of this is that the root folder becomes messy during development.

A look into the future:

• Node.js gained support for export maps which give library authors control over how other packages can import modules, essentially allowing to redirect imports to different folders and/or names, including omitting file extensions.
• TypeScript still lacks support for export maps. Once TypeScript gains support, this package should make use of it and generate files in lib/ instead of the root, while also simplifying imports by removing .js.
• Another benefit of export maps is that test code can self-reference the package. This avoids long relative paths and serves as additional copy-pastable sample code.

Releases

Releases of this package are automated in CI together with CCF releases. Even if nothing in this package changes, a new release is published.

The version number in package.json is fixed to 0.0.0 and is automatically set during release using npm version.