strong-tie/inbound-calls

1# process-warning2 3[![CI](https://github.com/fastify/process-warning/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/fastify/process-warning/actions/workflows/ci.yml)4[![NPM version](https://img.shields.io/npm/v/process-warning.svg?style=flat)](https://www.npmjs.com/package/process-warning)5[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)6 7A small utility for generating consistent warning objects across your codebase.8It also exposes a utility for emitting those warnings, guaranteeing that they are issued only once (unless configured otherwise).9 10_This module is used by the [Fastify](https://fastify.dev) framework and it was called `fastify-warning` prior to version 1.0.0._11 12### Install13 14```15npm i process-warning16```17 18### Usage19 20The module exports two builder functions for creating warnings.21 22```js23const {24  createWarning,25  createDeprecation26} = require('process-warning')27 28const warning = createWarning({29  name: 'ExampleWarning',30  code: 'EXP_WRN_001',31  message: 'Hello %s',32  unlimited: true33})34warning('world')35```36 37#### Methods38 39##### `createWarning({ name, code, message[, unlimited] })`40 41- `name` (`string`, required) - The error name, you can access it later with42`error.name`. For consistency, we recommend prefixing module error names43with `{YourModule}Warning`44- `code` (`string`, required) - The warning code, you can access it later with45`error.code`. For consistency, we recommend prefixing plugin error codes with46`{ThreeLetterModuleName}_`, e.g. `FST_`. NOTE: codes should be all uppercase.47- `message` (`string`, required) - The warning message. You can also use48interpolated strings for formatting the message.49- `options` (`object`, optional) - Optional options with the following50properties:51  + `unlimited` (`boolean`, optional) - Should the warning be emitted more than52  once? Defaults to `false`.53 54 55##### `createDeprecation({code, message[, options]})`56 57This is a wrapper for `createWarning`. It is equivalent to invoking58`createWarning` with the `name` parameter set to "DeprecationWarning".59 60Deprecation warnings have extended support for the Node.js CLI options:61`--throw-deprecation`, `--no-deprecation`, and `--trace-deprecation`.62 63##### `warning([, a [, b [, c]]])`64 65The returned `warning` function can used for emitting warnings.66A warning is guaranteed to be emitted at least once.67 68- `[, a [, b [, c]]]` (`any`, optional) - Parameters for string interpolation.69 70```js71const { createWarning } = require('process-warning')72const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'message' })73FST_ERROR_CODE()74```75 76How to use an interpolated string:77```js78const { createWarning } = require('process-warning')79const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'Hello %s'})80FST_ERROR_CODE('world')81```82 83The `warning` object has methods and properties for managing the warning's state. Useful for testing.84```js85const { createWarning } = require('process-warning')86const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'Hello %s'})87console.log(FST_ERROR_CODE.emitted) // false88FST_ERROR_CODE('world')89console.log(FST_ERROR_CODE.emitted) // true90 91const FST_ERROR_CODE_2 = createWarning('MyAppWarning', 'FST_ERROR_CODE_2', 'Hello %s')92FST_ERROR_CODE_2.emitted = true93FST_ERROR_CODE_2('world') // will not be emitted because it is not unlimited94```95 96How to use an unlimited warning:97```js98const { createWarning } = require('process-warning')99const FST_ERROR_CODE = createWarning({ name: 'MyAppWarning', code: 'FST_ERROR_CODE', message: 'Hello %s', unlimited: true })100FST_ERROR_CODE('world') // will be emitted101FST_ERROR_CODE('world') // will be emitted again102```103 104#### Suppressing warnings105 106It is possible to suppress warnings by utilizing one of node's built-in warning suppression mechanisms.107 108Warnings can be suppressed:109 110- by setting the `NODE_NO_WARNINGS` environment variable to `1`111- by passing the `--no-warnings` flag to the node process112- by setting '--no-warnings' in the `NODE_OPTIONS` environment variable113 114For more information see [node's documentation](https://nodejs.org/api/cli.html).115 116## License117 118Licensed under [MIT](./LICENSE).119