{"_id":"@dabh/diagnostics","_rev":"4160399","name":"@dabh/diagnostics","description":"Tools for debugging your node.js modules and event loop","dist-tags":{"latest":"2.0.8"},"maintainers":[{"name":"dabh","email":"dabh@stanford.edu"}],"time":{"modified":"2026-03-01T20:38:37.000Z","created":"2020-06-22T17:42:35.156Z","2.0.8":"2025-09-30T23:24:37.665Z","2.0.7":"2025-09-30T15:31:19.931Z","2.0.6":"2025-09-30T06:00:23.857Z","2.0.5":"2025-09-30T04:18:20.014Z","2.0.3":"2022-02-12T23:41:41.239Z","2.0.2":"2020-06-22T17:42:35.156Z"},"users":{},"author":{"name":"Arnout Kazemier"},"repository":{"type":"git","url":"git://github.com/DABH/diagnostics.git"},"versions":{"2.0.8":{"name":"@dabh/diagnostics","version":"2.0.8","description":"Tools for debugging your node.js modules and event loop","main":"./node","browser":"./browser","scripts":{"test:basic":"mocha --require test/mock.js test/*.test.js","test:node":"mocha --require test/mock test/node.js","test:browser":"mocha --require test/mock test/browser.js","test:runner":"npm run test:basic && npm run test:node && npm run test:browser","webpack:node:prod":"webpack --mode=production node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:node:dev":"webpack --mode=development node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:prod":"webpack --mode=production browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:dev":"webpack --mode=development browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","test":"nyc --reporter=text --reporter=lcov npm run test:runner"},"repository":{"type":"git","url":"git://github.com/DABH/diagnostics.git"},"keywords":["debug","debugger","debugging","diagnostic","diagnostics","event","loop","metrics","stats"],"author":{"name":"Arnout Kazemier"},"license":"MIT","bugs":{"url":"https://github.com/DABH/diagnostics/issues"},"homepage":"https://github.com/DABH/diagnostics","devDependencies":{"assume":"2.3.x","asyncstorageapi":"^1.0.2","mocha":"^11.7.2","nyc":"^17.1.0","objstorage":"^1.0.0","pre-commit":"github:metcalfc/pre-commit#b36c649fd5348d7604a86b7b2f3429c780d1478f","require-poisoning":"^2.0.0","webpack":"5.x","webpack-bundle-size-analyzer":"^3.0.0","webpack-cli":"6.x"},"dependencies":{"@so-ric/colorspace":"^1.1.6","enabled":"2.0.x","kuler":"^2.0.0"},"contributors":[{"name":"Martijn Swaagman","url":"https://github.com/swaagie"},{"name":"Jarrett Cruger","url":"https://github.com/jcrugzz"},{"name":"Sevastos","url":"https://github.com/sevastos"}],"directories":{"test":"test"},"_id":"@dabh/diagnostics@2.0.8","gitHead":"c5dd09ef5c8972c72ee549f60f1c258d734420d3","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"shasum":"ead97e72ca312cf0e6dd7af0d300b58993a31a5e","size":10113,"noattachment":false,"key":"/@dabh/diagnostics/-/@dabh/diagnostics-2.0.8.tgz","tarball":"http://registry.cnpm.dingdandao.com/@dabh/diagnostics/download/@dabh/diagnostics-2.0.8.tgz"},"_npmUser":{"name":"dabh","email":"dabh@alumni.stanford.edu"},"maintainers":[{"name":"dabh","email":"dabh@stanford.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/diagnostics_2.0.8_1759274677486_0.5201058502686327"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2025-09-30T23:24:37.665Z","publish_time":1759274677665,"_source_registry_name":"default","_cnpm_publish_time":1759274677665},"2.0.7":{"name":"@dabh/diagnostics","version":"2.0.7","description":"Tools for debugging your node.js modules and event loop","main":"./node","browser":"./browser","scripts":{"test:basic":"mocha --require test/mock.js test/*.test.js","test:node":"mocha --require test/mock test/node.js","test:browser":"mocha --require test/mock test/browser.js","test:runner":"npm run test:basic && npm run test:node && npm run test:browser","webpack:node:prod":"webpack --mode=production node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:node:dev":"webpack --mode=development node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:prod":"webpack --mode=production browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:dev":"webpack --mode=development browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","test":"nyc --reporter=text --reporter=lcov npm run test:runner"},"repository":{"type":"git","url":"git://github.com/DABH/diagnostics.git"},"keywords":["debug","debugger","debugging","diagnostic","diagnostics","event","loop","metrics","stats"],"author":{"name":"Arnout Kazemier"},"license":"MIT","bugs":{"url":"https://github.com/DABH/diagnostics/issues"},"homepage":"https://github.com/DABH/diagnostics","devDependencies":{"assume":"2.3.x","asyncstorageapi":"^1.0.2","mocha":"^11.7.2","nyc":"^17.1.0","objstorage":"^1.0.0","pre-commit":"github:metcalfc/pre-commit#b36c649fd5348d7604a86b7b2f3429c780d1478f","require-poisoning":"^2.0.0","webpack":"5.x","webpack-bundle-size-analyzer":"^3.0.0","webpack-cli":"6.x"},"dependencies":{"@so-ric/colorspace":"^1.1.6","enabled":"2.0.x","fix-esm":"^1.0.1","kuler":"^2.0.0"},"contributors":[{"name":"Martijn Swaagman","url":"https://github.com/swaagie"},{"name":"Jarrett Cruger","url":"https://github.com/jcrugzz"},{"name":"Sevastos","url":"https://github.com/sevastos"}],"directories":{"test":"test"},"_id":"@dabh/diagnostics@2.0.7","gitHead":"2d79b579d13f80b40dd2d259eeda238c54fa3d44","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"shasum":"4c55b804199a09f3330a1dd325df4d456009701d","size":10120,"noattachment":false,"key":"/@dabh/diagnostics/-/@dabh/diagnostics-2.0.7.tgz","tarball":"http://registry.cnpm.dingdandao.com/@dabh/diagnostics/download/@dabh/diagnostics-2.0.7.tgz"},"_npmUser":{"name":"dabh","email":"dabh@alumni.stanford.edu"},"maintainers":[{"name":"dabh","email":"dabh@stanford.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/diagnostics_2.0.7_1759246279734_0.09245745724244303"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2025-09-30T15:31:19.931Z","publish_time":1759246279931,"_source_registry_name":"default","_cnpm_publish_time":1759246279931},"2.0.6":{"name":"@dabh/diagnostics","version":"2.0.6","description":"Tools for debugging your node.js modules and event loop","main":"./node","browser":"./browser","scripts":{"test:basic":"mocha --require test/mock.js test/*.test.js","test:node":"mocha --require test/mock test/node.js","test:browser":"mocha --require test/mock test/browser.js","test:runner":"npm run test:basic && npm run test:node && npm run test:browser","webpack:node:prod":"webpack --mode=production node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:node:dev":"webpack --mode=development node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:prod":"webpack --mode=production browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:dev":"webpack --mode=development browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","test":"nyc --reporter=text --reporter=lcov npm run test:runner"},"repository":{"type":"git","url":"git://github.com/DABH/diagnostics.git"},"keywords":["debug","debugger","debugging","diagnostic","diagnostics","event","loop","metrics","stats"],"author":{"name":"Arnout Kazemier"},"license":"MIT","bugs":{"url":"https://github.com/DABH/diagnostics/issues"},"homepage":"https://github.com/DABH/diagnostics","devDependencies":{"assume":"2.3.x","asyncstorageapi":"^1.0.2","mocha":"^11.7.2","nyc":"^17.1.0","objstorage":"^1.0.0","pre-commit":"github:metcalfc/pre-commit#b36c649fd5348d7604a86b7b2f3429c780d1478f","require-poisoning":"^2.0.0","webpack":"5.x","webpack-bundle-size-analyzer":"^3.0.0","webpack-cli":"6.x"},"dependencies":{"@so-ric/colorspace":"^1.1.4","enabled":"2.0.x","fix-esm":"^1.0.1","kuler":"^2.0.0"},"contributors":[{"name":"Martijn Swaagman","url":"https://github.com/swaagie"},{"name":"Jarrett Cruger","url":"https://github.com/jcrugzz"},{"name":"Sevastos","url":"https://github.com/sevastos"}],"directories":{"test":"test"},"_id":"@dabh/diagnostics@2.0.6","gitHead":"37f7001db8c38e3a62b58c16df0438d9093ada4d","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"shasum":"15d800c0a90881dc7face0b06c98781e760e4cd3","size":10154,"noattachment":false,"key":"/@dabh/diagnostics/-/@dabh/diagnostics-2.0.6.tgz","tarball":"http://registry.cnpm.dingdandao.com/@dabh/diagnostics/download/@dabh/diagnostics-2.0.6.tgz"},"_npmUser":{"name":"dabh","email":"dabh@alumni.stanford.edu"},"maintainers":[{"name":"dabh","email":"dabh@stanford.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/diagnostics_2.0.6_1759212023687_0.42033477088100235"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2025-09-30T06:00:23.857Z","publish_time":1759212023857,"_source_registry_name":"default","_cnpm_publish_time":1759212023857},"2.0.5":{"name":"@dabh/diagnostics","version":"2.0.5","description":"Tools for debugging your node.js modules and event loop","main":"./node","browser":"./browser","scripts":{"test:basic":"mocha --require test/mock.js test/*.test.js","test:node":"mocha --require test/mock test/node.js","test:browser":"mocha --require test/mock test/browser.js","test:runner":"npm run test:basic && npm run test:node && npm run test:browser","webpack:node:prod":"webpack --mode=production node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:node:dev":"webpack --mode=development node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:prod":"webpack --mode=production browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:dev":"webpack --mode=development browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","test":"nyc --reporter=text --reporter=lcov npm run test:runner"},"repository":{"type":"git","url":"git://github.com/DABH/diagnostics.git"},"keywords":["debug","debugger","debugging","diagnostic","diagnostics","event","loop","metrics","stats"],"author":{"name":"Arnout Kazemier"},"license":"MIT","bugs":{"url":"https://github.com/DABH/diagnostics/issues"},"homepage":"https://github.com/DABH/diagnostics","devDependencies":{"assume":"2.3.x","asyncstorageapi":"^1.0.2","mocha":"9.2.x","nyc":"^15.1.0","objstorage":"^1.0.0","pre-commit":"1.2.x","require-poisoning":"^2.0.0","webpack":"4.x","webpack-bundle-size-analyzer":"^3.0.0","webpack-cli":"3.x"},"dependencies":{"@so-ric/colorspace":"^1.1.4","enabled":"2.0.x","kuler":"^2.0.0"},"contributors":[{"name":"Martijn Swaagman","url":"https://github.com/swaagie"},{"name":"Jarrett Cruger","url":"https://github.com/jcrugzz"},{"name":"Sevastos","url":"https://github.com/sevastos"}],"directories":{"test":"test"},"_id":"@dabh/diagnostics@2.0.5","gitHead":"1307a6d821f99cbd8163b04eabe159e6b02954ae","_nodeVersion":"24.2.0","_npmVersion":"11.3.0","dist":{"shasum":"3611e4d1563be71d69c3e38f364088a786a64835","size":10067,"noattachment":false,"key":"/@dabh/diagnostics/-/@dabh/diagnostics-2.0.5.tgz","tarball":"http://registry.cnpm.dingdandao.com/@dabh/diagnostics/download/@dabh/diagnostics-2.0.5.tgz"},"_npmUser":{"name":"dabh","email":"dabh@alumni.stanford.edu"},"maintainers":[{"name":"dabh","email":"dabh@stanford.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/diagnostics_2.0.5_1759205899844_0.6303587162883553"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2025-09-30T04:18:20.014Z","publish_time":1759205900014,"_source_registry_name":"default","_cnpm_publish_time":1759205900014},"2.0.3":{"name":"@dabh/diagnostics","version":"2.0.3","description":"Tools for debugging your node.js modules and event loop","main":"./node","browser":"./browser","scripts":{"test:basic":"mocha --require test/mock.js test/*.test.js","test:node":"mocha --require test/mock test/node.js","test:browser":"mocha --require test/mock test/browser.js","test:runner":"npm run test:basic && npm run test:node && npm run test:browser","webpack:node:prod":"webpack --mode=production node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:node:dev":"webpack --mode=development node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:prod":"webpack --mode=production browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:dev":"webpack --mode=development browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","test":"nyc --reporter=text --reporter=lcov npm run test:runner"},"repository":{"type":"git","url":"git://github.com/3rd-Eden/diagnostics.git"},"keywords":["debug","debugger","debugging","diagnostic","diagnostics","event","loop","metrics","stats"],"author":{"name":"Arnout Kazemier"},"license":"MIT","bugs":{"url":"https://github.com/3rd-Eden/diagnostics/issues"},"homepage":"https://github.com/3rd-Eden/diagnostics","devDependencies":{"assume":"2.3.x","asyncstorageapi":"^1.0.2","mocha":"9.2.x","nyc":"^15.1.0","objstorage":"^1.0.0","pre-commit":"1.2.x","require-poisoning":"^2.0.0","webpack":"4.x","webpack-bundle-size-analyzer":"^3.0.0","webpack-cli":"3.x"},"dependencies":{"colorspace":"1.1.x","enabled":"2.0.x","kuler":"^2.0.0"},"contributors":[{"name":"Martijn Swaagman","url":"https://github.com/swaagie"},{"name":"Jarrett Cruger","url":"https://github.com/jcrugzz"},{"name":"Sevastos","url":"https://github.com/sevastos"}],"directories":{"test":"test"},"gitHead":"442e28023b53da963e79f4a1dff26df8e8541c47","_id":"@dabh/diagnostics@2.0.3","_nodeVersion":"14.16.1","_npmVersion":"8.4.1","dist":{"shasum":"7f7e97ee9a725dffc7808d93668cc984e1dc477a","size":10024,"noattachment":false,"key":"/@dabh/diagnostics/-/@dabh/diagnostics-2.0.3.tgz","tarball":"http://registry.cnpm.dingdandao.com/@dabh/diagnostics/download/@dabh/diagnostics-2.0.3.tgz"},"_npmUser":{"name":"dabh","email":"dabh@alumni.stanford.edu"},"maintainers":[{"name":"dabh","email":"dabh@stanford.edu"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/diagnostics_2.0.3_1644709301065_0.3580397577851959"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-02-12T23:41:48.056Z","publish_time":1644709301239,"_cnpm_publish_time":1644709301239},"2.0.2":{"name":"@dabh/diagnostics","version":"2.0.2","description":"Tools for debugging your node.js modules and event loop","main":"./node","browser":"./browser","scripts":{"test:basic":"mocha --require test/mock.js test/*.test.js","test:node":"mocha --require test/mock test/node.js","test:browser":"mocha --require test/mock test/browser.js","test:runner":"npm run test:basic && npm run test:node && npm run test:browser","webpack:node:prod":"webpack --mode=production node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:node:dev":"webpack --mode=development node/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:prod":"webpack --mode=production browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","webpack:browser:dev":"webpack --mode=development browser/index.js -o /dev/null --json | webpack-bundle-size-analyzer","test":"nyc --reporter=text --reporter=lcov npm run test:runner"},"repository":{"type":"git","url":"git://github.com/3rd-Eden/diagnostics.git"},"keywords":["debug","debugger","debugging","diagnostic","diagnostics","event","loop","metrics","stats"],"author":{"name":"Arnout Kazemier"},"license":"MIT","bugs":{"url":"https://github.com/3rd-Eden/diagnostics/issues"},"homepage":"https://github.com/3rd-Eden/diagnostics","devDependencies":{"assume":"2.1.x","asyncstorageapi":"^1.0.2","mocha":"5.2.x","nyc":"^14.1.1","objstorage":"^1.0.0","pre-commit":"1.2.x","require-poisoning":"^2.0.0","webpack":"^4.29.5","webpack-bundle-size-analyzer":"^3.0.0","webpack-cli":"^3.2.3"},"dependencies":{"colorspace":"1.1.x","enabled":"2.0.x","kuler":"^2.0.0"},"contributors":[{"name":"Martijn Swaagman","url":"https://github.com/swaagie"},{"name":"Jarrett Cruger","url":"https://github.com/jcrugzz"},{"name":"Sevastos","url":"https://github.com/sevastos"}],"directories":{"test":"test"},"gitHead":"5d8f82956c32bf73a8802e806c585758fad627ba","_id":"@dabh/diagnostics@2.0.2","_nodeVersion":"12.18.0","_npmVersion":"6.14.5","dist":{"shasum":"290d08f7b381b8f94607dc8f471a12c675f9db31","size":295914,"noattachment":false,"key":"/@dabh/diagnostics/-/@dabh/diagnostics-2.0.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/@dabh/diagnostics/download/@dabh/diagnostics-2.0.2.tgz"},"maintainers":[{"name":"dabh","email":"dabh@stanford.edu"}],"_npmUser":{"name":"dabh","email":"dabh@alumni.stanford.edu"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/diagnostics_2.0.2_1592847754925_0.6493991704926261"},"_hasShrinkwrap":false,"publish_time":1592847755156,"_cnpm_publish_time":1592847755156}},"readme":"# `diagnostics`\n\nDiagnostics in the evolution of debug pattern that is used in the Node.js core,  \nthis extremely small but powerful technique can best be compared as feature\nflags for loggers. The created debug logger is disabled by default but can be\nenabled without changing a line of code, using flags.\n\n- Allows debugging in multiple JavaScript environments such as Node.js, browsers\n  and React-Native.\n- Separated development and production builds to minimize impact on your\n  application when bundled.\n- Allows for customization of logger, messages, and much more.\n\n![Output Example](example.png)\n\n## Installation\n\nThe module is released in the public npm registry and can be installed by\nrunning:\n\n```\nnpm install --save @dabh/diagnostics\n```\n\n## Usage\n\n- [Introduction](#introduction)\n- [Advanced usage](#advanced-usage)\n  - [Production and development builds](#production-and-development-builds)\n    - [WebPack](#webpack)\n    - [Node.js](#nodejs)\n- [API](#api)\n  - [.enabled](#enabled)\n  - [.namespace](#namespace)\n  - [.dev/prod](#devprod)\n  - [set](#set)\n  - [modify](#modify)\n  - [use](#use)\n- [Modifiers](#modifiers)\n  - [namespace](#namespace-1)\n- [Adapters](#adapters)\n  - [process.env](#process-env)\n  - [hash](#hash)\n  - [localStorage](#localstorage)\n  - [AsyncStorage](#asyncstorage)\n- [Loggers](#loggers)\n\n### Introduction\n\nTo create a new logger simply `require` the `@dabh/diagnostics` module and call\nthe returned function. It accepts 2 arguments:\n\n1. `namespace` **Required** This is the namespace of your logger so we know if we need to\n   enable your logger when a debug flag is used. Generally you use the name of\n   your library or application as first root namespace. For example if you're\n   building a parser in a library (example) you would set namespace\n   `example:parser`.\n2. `options` An object with additional configuration for the logger.\n   following keys are recognized:\n   - `force` Force the logger to be enabled.\n   - `colors` Colors are enabled by default for the logs, but you can set this\n     option to `false` to disable it.\n\n```js\nconst debug = require('@dabh/diagnostics')('foo:bar:baz');\nconst debug = require('@dabh/diagnostics')('foo:bar:baz', { options });\n\ndebug('this is a log message %s', 'that will only show up when enabled');\ndebug('that is pretty neat', { log: 'more', data: 1337 });\n```\n\nUnlike `console.log` statements that add and remove during your development\nlifecycle you create meaningful log statements that will give you insight in\nthe library or application that you're developing.\n\nThe created debugger uses different \"adapters\" to extract the debug flag\nout of the JavaScript environment. To learn more about enabling the debug flag\nin your specific environment click on one of the enabled adapters below.\n\n- **browser**: [localStorage](#localstorage), [hash](#hash)\n- **node.js**: [environment variables](#processenv)\n- **react-native**: [AsyncStorage](#asyncstorage)\n\nPlease note that the returned logger is fully configured out of the box, you\ndo not need to set any of the adapters/modifiers your self, they are there\nfor when you want more advanced control over the process. But if you want to\nlearn more about that, read the next section.\n\n### Advanced usage\n\nThere are 2 specific usage patterns for `diagnostic`, library developers who\nimplement it as part of their modules and applications developers who either\nuse it in their application or are searching for ways to consume the messages.\n\nWith the simple log interface as discussed in the [introduction](#introduction)\nsection we make it easy for developers to add it as part of their libraries\nand applications, and with powerful [API](#api) we allow infinite customization\nby allowing custom adapters, loggers and modifiers to ensure that this library\nmaintains relevant. These methods not only allow introduction of new loggers,\nbut allow you think outside the box. For example you can maintain a history\nof past log messages, and output those when an uncaught exception happens in\nyour application so you have additional context\n\n```js\nconst diagnostics = require('@dabh/diagnostics');\n\nlet index = 0;\nconst limit = 200;\nconst history = new Array(limit);\n\n//\n// Force all `diagnostic` loggers to be enabled.\n//\ndiagnostics.force = process.env.NODE_ENV === 'prod';\ndiagnostics.set(function customLogger(meta, message) {\n  history[index]= { meta, message, now: Date.now() };\n  if (index++ === limit) index = 0;\n\n  //\n  // We're running a development build, so output.\n  //\n  if (meta.dev) console.log.apply(console, message);\n});\n\nprocess.on('uncaughtException', async function (err) {\n  await saveErrorToDisk(err, history);\n  process.exit(1);\n});\n```\n\nThe small snippet above will maintain a 200 limited FIFO (First In First Out)\nqueue of all debug messages that can be referenced when your application crashes\n\n#### Production and development builds\n\nWhen you `require` the `@dabh/diagnostics` module you will be given a logger that is\noptimized for `development` so it can provide the best developer experience\npossible.\n\nThe development logger enables all the [adapters](#adapters) for your\nJavaScript environment, adds a logger that outputs the messages to `console.log`\nand registers our message modifiers so log messages will be prefixed with the\nsupplied namespace so you know where the log messages originates from.\n\nThe development logger does not have any adapter, modifier and logger enabled\nby default. This ensures that your log messages never accidentally show up in\nproduction. However this does not mean that it's not possible to get debug\nmessages in production. You can `force` the debugger to be enabled, and\nsupply a [custom logger](#loggers).\n\n```js\nconst diagnostics = require('@dabh/diagnostics');\nconst debug = debug('foo:bar', { force: true });\n\n//\n// Or enable _every_ diagnostic instance:\n//\ndiagnostics.force = true;\n```\n\n##### WebPack\n\nWebPack has the concept of [mode](https://webpack.js.org/concepts/mode/#usage)'s\nwhich creates different\n\n```js\nmodule.exports = {\n  mode: 'development' // 'production'\n}\n```\n\nWhen you are building your app using the WebPack CLI you can use the `--mode`\nflag:\n\n```\nwebpack --mode=production app.js -o /dist/bundle.js\n```\n\n##### Node.js\n\nWhen you are running your app using `Node.js` you should the `NODE_ENV`\nenvironment variable to `production` to ensure that you libraries that you\nimport are optimized for production.\n\n```\nNODE_ENV=production node app.js\n```\n\n### API\n\nThe returned logger exposes some addition properties that can be used used in\nyour application or library:\n\n#### .enabled\n\nThe returned logger will have a `.enabled` property assigned to it. This boolean\ncan be used to check if the logger was enabled:\n\n```js\nconst debug = require('@dabh/diagnostics')('foo:bar');\n\nif (debug.enabled) {\n  //\n  // Do something special\n  //\n}\n```\n\nThis property is exposed as:\n\n- Property on the logger.\n- Property on the meta/options object.\n\n#### .namespace\n\nThis is the namespace that you originally provided to the function.\n\n```js\nconst debug = require('@dabh/diagnostics')('foo:bar');\n\nconsole.log(debug.namespace); // foo:bar\n```\n\nThis property is exposed as:\n\n- Property on the logger.\n- Property on the meta/options object.\n\n#### .dev/prod\n\nThere are different builds available of `diagnostics`, when you create a\nproduction build of your application using `NODE_ENV=production` you will be\ngiven an optimized, smaller build of `diagnostics` to reduce your bundle size.\nThe `dev` and `prod` booleans on the returned logger indicate if you have a\nproduction or development version of the logger.\n\n```js\nconst debug = require('@dabh/diagnostics')('foo:bar');\n\nif (debug.prod) {\n  // do stuff\n}\n```\n\nThis property is exposed as:\n\n- Property on the logger.\n- Property on the meta/options object.\n\n#### set\n\nSets a new logger as default for  **all** `diagnostic` instances. The passed\nargument should be a function that write the log messages to where ever you\nwant. It receives 2 arguments:\n\n1. `meta` An object with all the options that was provided to the original\n   logger that wants to write the log message as well as properties of the\n   debugger such as `prod`, `dev`, `namespace`, `enabled`. See [API](#api) for\n   all exposed properties.\n2. `args` An array of the log messages that needs to be written.\n\n```js\nconst debug = require('@dabh/diagnostics')('foo:more:namespaces');\n\ndebug.use(function logger(meta, args) {\n  console.log(meta);\n  console.debug(...args);\n});\n```\n\nThis method is exposed as:\n\n- Method on the logger.\n- Method on the meta/options object.\n- Method on `diagnostics` module.\n\n#### modify\n\nThe modify method allows you add a new message modifier to **all** `diagnostic`\ninstances. The passed argument should be a function that returns the passed\nmessage after modification. The function receives 2 arguments:\n\n1. `message`, Array, the log message.\n2. `options`, Object, the options that were passed into the logger when it was\n   initially created.\n\n```js\nconst debug = require('@dabh/diagnostics')('example:modifiers');\n\ndebug.modify(function (message, options) {\n  return messages;\n});\n```\n\nThis method is exposed as:\n\n- Method on the logger.\n- Method on the meta/options object.\n- Method on `diagnostics` module.\n\nSee [modifiers](#modifiers) for more information.\n\n#### use\n\nAdds a new `adapter` to **all** `diagnostic` instances. The passed argument\nshould be a function returns a boolean that indicates if the passed in\n`namespace` is allowed to write log messages.\n\n```js\nconst diagnostics = require('@dabh/diagnostics');\nconst debug = diagnostics('foo:bar');\n\ndebug.use(function (namespace) {\n  return namespace === 'foo:bar';\n});\n```\n\nThis method is exposed as:\n\n- Method on the logger.\n- Method on the meta/options object.\n- Method on `diagnostics` module.\n\nSee [adapters](#adapters) for more information.\n\n### Modifiers\n\nTo be as flexible as possible when it comes to transforming messages we've\ncome up with the concept of `modifiers` which can enhance the debug messages.\nThis allows you to introduce functionality or details that you find important\nfor debug messages, and doesn't require us to add additional bloat to the\n`diagnostic` core.\n\nFor example, you want the messages to be prefixed with the date-time of when\nthe log message occured:\n\n```js\nconst diagnostics = require('@dabh/diagnostics');\n\ndiagnostics.modify(function datetime(args, options) {\n  args.unshift(new Date());\n  return args;\n});\n```\n\nNow all messages will be prefixed with date that is outputted by `new Date()`.\nThe following modifiers are shipped with `diagnostics` and are enabled in\n**development** mode only:\n\n- [namespace](#namespace)\n\n#### namespace\n\nThis modifier is enabled for all debug instances and prefixes the messages\nwith the name of namespace under which it is logged. The namespace is colored\nusing the `colorspace` module which groups similar namespaces under the same\ncolorspace. You can have multiple namespaces for the debuggers where each\nnamespace should be separated by a `:`\n\n```\nfoo\nfoo:bar\nfoo:bar:baz\n```\n\nFor console based output the `namespace-ansi` is used.\n\n### Adapters\n\nAdapters allows `diagnostics` to pull the `DEBUG` and `DIAGNOSTICS` environment\nvariables from different sources. Not every JavaScript environment has a\n`process.env` that we can leverage. Adapters allows us to have different\nadapters for different environments. It means you can write your own custom\nadapter if needed as well.\n\nThe `adapter` function should be passed a function as argument, this function\nwill receive the `namespace` of a logger as argument and it should return a\nboolean that indicates if that logger should be enabled or not.\n\n```js\nconst debug = require('@dabh/diagnostics')('example:namespace');\n\ndebug.adapter(require('@dabh/diagnostics/adapters/localstorage'));\n```\n\nThe modifiers are only enabled for `development`. The following adapters are\navailable are available:\n\n#### process.env\n\nThis adapter is enabled for `node.js`.\n\nUses the `DEBUG` or `DIAGNOSTICS` (both are recognized) environment variables to\npass in debug flag:\n\n**UNIX/Linux/Mac**\n```\nDEBUG=foo* node index.js\n```\n\nUsing environment variables on Windows is a bit different, and also depends on\ntoolchain you are using:\n\n**Windows**\n```\nset DEBUG=foo* & node index.js\n```\n\n**Powershell**\n```\n$env:DEBUG='foo*';node index.js\n```\n\n#### hash\n\nThis adapter is enabled for `browsers`.\n\nThis adapter uses the `window.location.hash` of as source for the environment\nvariables. It assumes that hash is formatted using the same syntax as query\nstrings:\n\n```js\nhttp://example.com/foo/bar#debug=foo*\n```\n\nIt triggers on both the `debug=` and `diagnostics=` names.\n\n#### localStorage\n\nThis adapter is enabled for `browsers`.\n\nThis adapter uses the `localStorage` of the browser to store the debug flags.\nYou can set the debug flag your self in your application code, but you can\nalso open browser WebInspector and enable it through the console.\n\n```js\nlocalStorage.setItem('debug', 'foo*');\n```\n\nIt triggers on both the `debug` and `diagnostics` storage items. (Please note\nthat these keys should be entered in lowercase)\n\n#### AsyncStorage\n\nThis adapter is enabled for `react-native`.\n\nThis adapter uses the `AsyncStorage` API that is exposed by the `react-native`\nlibrary to store and read the `debug` or `diagnostics` storage items.\n\n```js\nimport { AsyncStorage } from 'react-native';\n\nAsyncStorage.setItem('debug', 'foo*');\n```\n\nUnlike other adapters, this is the only adapter that is `async` so that means\nthat we're not able to instantly determine if a created logger should be\nenabled or disabled. So when a logger is created in `react-native` we initially\nassume it's disabled, any message that send during period will be queued\ninternally.\n\nOnce we've received the data from the `AsyncStorage` API we will determine\nif the logger should be enabled, flush the queued messages if needed and set\nall `enabled` properties accordingly on the returned logger.\n\n### Loggers\n\nBy default it will log all messages to `console.log` in when the logger is\nenabled using the debug flag that is set using one of the adapters.\n\n## License\n\n[MIT](LICENSE)\n","_attachments":{},"homepage":"https://github.com/DABH/diagnostics","bugs":{"url":"https://github.com/DABH/diagnostics/issues"},"license":"MIT"}