migrate.to.v1.md

Migrating from 0.x.x to 1.x.x

There are several significant changes from 0.x.x to 1.x.x:

• Breaking: Protocol-Common is now published as an ESModule library.
• Breaking: Minimum node version supported is node 16.
• Breaking: The underlying logging mechanism (Winston) has been swapped out for Pino logger.
• Breaking: Protocol-Common now provides shallow-imports and does not support deep imports.
• Breaking: New ProtocolHttpService implementation.

Protocol-Common is now published as an ESModule library.

This has a few downstream effects for clients of Protocol-Common. Most importantly:

1. Make sure your package.json specifies "type": "module"
2. Make sure all imports of local components use the .js extension. This does not apply to components imported from external sources (e.g. modules imported from npm).

To make sure that this behavior is enforced in future updates to the codebase, we recommend adding the following rule to your .eslintrc.json configuration file:

"import/extensions": [
    "error",
    {
        "js": "ignorePackages",
        "json": "ignorePackages"
    }
]

Jest + ESM

Because our package is now exported as an ESModule, there may be some new and weird error messages you see if you use Jest for running unit tests in your own TypeScript application. Fear not! Here's how you can support ESM imports with TypeScript in Jest.

1. If you have not already, install the ts-jest package as a dev dependency.

npm install --save-dev ts-jest

2. Add the following to your Jest configuration:

"globals": {
    "ts-jest": {
        "useESM": true
    }
},
"extensionsToTreatAsEsm": [
    ".ts"
]

3. Be sure to add the --experimental-vm-modules flag to your Node environment prior to running Jest. You can read more about ESM support in Jest here.

"scripts": {
    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
}

Minimum node version supported is node 16.

Using --experimental-json-module flag

We are using some experimental flags in node 16. When running services, include --experimental-json-modules flag in the start command.

EG:

npm run build && node -r dotenv/config --experimental-json-modules dist/app.js

JSON resources

In particular, this is true if you are importing any .json files in your application. If you are doing so, you need to add an assertion to your import line. This will likely cause a typescript error, so you'll also need to use a @ts-ignore flag. E.g.

// @ts-ignore: assertions are currently required when importing json
import data from '../config/env.json' assert { type: 'json'};

See the documentation here for more information: https://nodejs.org/docs/latest-v16.x/api/esm.html#json-modules

Getting an eslint error now?

Add this rule to your .eslintrc.json file:

"@typescript-eslint/ban-ts-comment": [
    "error",
    {
        "ts-ignore": "allow-with-description"
    }
]

The underlying logging mechanism has been swapped out for Pino logger.

To use the new Logger you need to do 3 things:

1. Add ProtocolLoggerModule to your module imports in app.module.ts (or wherever your top-level module is)
2. At application start-up time, after loading your top-level module, use ProtocolLogger as your app logger:

app.useLogger(app.get(ProtocolLogger));

3. Anywhere you want to use the logger, import the default Nest Logger and use that:

import { Logger } from '@nestjs/common';

Logger.info() -> Logger.log()

Note that if you were using the previous Logger provided by this library, you might be using a .info() function. Unfortunately, that function does not exist on the default Nest Logger. Instead, use .log()

Protocol-Common now provides shallow-imports and does not support deep imports.

When importing from protocol-common, import everything from the top level (except for validations, which has a different top-level import).

E.g.

import { HttpConstants } from 'protocol-common/http-context/http.constants'; // DON'T DO THIS!
import { HttpConstants } from 'protocol-common'; // THIS IS GOOD!

import { ProtocolValidationPipe } from 'protocol-common/validation/protocol.validation.pipe'; // DON'T DO THIS!
import { ProtocolValidationPipe } from 'protocol-common/validation'; // THIS IS GOOD!

New ProtocolHttpService implementation.

1. Delete any dependency on @nestjs/axios from your package.json
2. Anywhere you were importing HttpModule from @nestjs/axios or @nestjs/common, now import ProtocolHttpModule from protocol-common.
3. Instead of manually creating a ProtocolHttpService, you can now just add it to the constructor and rely on NestJS's dependency injection system.