├── .README └── cli-output-demo.png ├── .eslintrc ├── .github ├── FUNDING.yml └── workflows │ ├── feature.yaml │ └── main.yaml ├── .gitignore ├── .husky ├── pre-commit └── pre-push ├── .nycrc ├── .releaserc ├── LICENSE ├── README.md ├── cspell.yaml ├── knip.json ├── package-lock.json ├── package.json ├── src ├── Roarr.ts ├── browser.ts ├── config.ts ├── constants.ts ├── factories │ ├── createLogger.ts │ ├── createMockLogger.ts │ ├── createNodeWriter.ts │ ├── createRoarrInitialGlobalState.ts │ └── createRoarrInitialGlobalStateBrowser.ts ├── getLogLevelName.ts ├── types.ts ├── typings.d.ts └── utilities │ ├── hasOwnProperty.ts │ ├── isBrowser.ts │ ├── isTruthy.ts │ └── stringify.ts ├── test ├── .eslintrc ├── benchmark.ts ├── helpers │ └── createIntegrationTest.ts └── roarr │ ├── createRoarrInitialGlobalState.ts │ ├── integrations │ ├── README.md │ ├── asyncLocalScope.ts │ ├── roarr.ts │ ├── roarrWriteNotTriggeredWhenRoarrLogIsDisabled.ts │ ├── roarrWriteOverridesMessageHandler.ts │ ├── roarrWriteUpdatesSequence.ts │ └── serializeMessage.ts │ └── utilities │ └── stringify.ts ├── tsconfig.build.json └── tsconfig.json /.README/cli-output-demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gajus/roarr/e170c9a1e3a249b4040146378f92e3d09e56deb4/.README/cli-output-demo.png -------------------------------------------------------------------------------- /.eslintrc: -------------------------------------------------------------------------------- 1 | { 2 | "ignorePatterns": ["dist", "package-lock.json"], 3 | "extends": "canonical/auto", 4 | "rules": { 5 | "@typescript-eslint/no-explicit-any": 0, 6 | "unicorn/prevent-abbreviations": 0, 7 | "id-length": 0 8 | }, 9 | "root": true 10 | } 11 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: gajus 2 | patreon: gajus 3 | -------------------------------------------------------------------------------- /.github/workflows/feature.yaml: -------------------------------------------------------------------------------- 1 | jobs: 2 | test: 3 | runs-on: ubuntu-latest 4 | environment: release 5 | name: Test 6 | steps: 7 | - name: setup repository 8 | uses: actions/checkout@v3 9 | with: 10 | fetch-depth: 0 11 | - name: setup node.js 12 | uses: actions/setup-node@v3 13 | with: 14 | node-version: "21" 15 | - run: npm ci 16 | - run: npm run lint 17 | - run: npm run test 18 | - run: npm run build 19 | timeout-minutes: 10 20 | name: Test and build 21 | on: 22 | pull_request: 23 | branches: 24 | - main 25 | types: 26 | - opened 27 | - synchronize 28 | - reopened 29 | - ready_for_review 30 | -------------------------------------------------------------------------------- /.github/workflows/main.yaml: -------------------------------------------------------------------------------- 1 | jobs: 2 | test: 3 | runs-on: ubuntu-latest 4 | environment: release 5 | name: Test 6 | steps: 7 | - name: setup repository 8 | uses: actions/checkout@v3 9 | with: 10 | fetch-depth: 0 11 | - name: setup node.js 12 | uses: actions/setup-node@v3 13 | with: 14 | node-version: "21" 15 | - run: npm ci 16 | - run: npm run lint 17 | - run: npm run test 18 | - run: npm run build 19 | - run: npx semantic-release 20 | env: 21 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 22 | NPM_TOKEN: ${{ secrets.NPM_TOKEN }} 23 | name: Test, build and release 24 | on: 25 | push: 26 | branches: 27 | - main 28 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | coverage 2 | dist 3 | node_modules 4 | *.log 5 | .* 6 | !.editorconfig 7 | !.eslintignore 8 | !.eslintrc 9 | !.github 10 | !.gitignore 11 | !.husky 12 | !.ncurc.js 13 | !.npmignore 14 | !.npmrc 15 | !.nycrc 16 | !.README 17 | !.releaserc 18 | -------------------------------------------------------------------------------- /.husky/pre-commit: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | . "$(dirname "$0")/_/husky.sh" 3 | 4 | npm run lint && npm run test && npm run build 5 | -------------------------------------------------------------------------------- /.husky/pre-push: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | . "$(dirname "$0")/_/husky.sh" 3 | -------------------------------------------------------------------------------- /.nycrc: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "@istanbuljs/nyc-config-typescript", 3 | "all": true 4 | } 5 | -------------------------------------------------------------------------------- /.releaserc: -------------------------------------------------------------------------------- 1 | { 2 | "branches": [ 3 | "main" 4 | ], 5 | "plugins": [ 6 | "@semantic-release/commit-analyzer", 7 | "@semantic-release/github", 8 | "@semantic-release/npm" 9 | ] 10 | } -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2023, Gajus Kuizinas (https://gajus.com/) 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions are met: 6 | * Redistributions of source code must retain the above copyright 7 | notice, this list of conditions and the following disclaimer. 8 | * Redistributions in binary form must reproduce the above copyright 9 | notice, this list of conditions and the following disclaimer in the 10 | documentation and/or other materials provided with the distribution. 11 | * Neither the name of the Gajus Kuizinas (https://gajus.com/) nor the 12 | names of its contributors may be used to endorse or promote products 13 | derived from this software without specific prior written permission. 14 | 15 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 16 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18 | DISCLAIMED. IN NO EVENT SHALL GAJUS KUIZINAS BE LIABLE FOR ANY 19 | DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 22 | ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 24 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Roarr 2 | 3 | [![NPM version](http://img.shields.io/npm/v/roarr.svg?style=flat-square)](https://www.npmjs.org/package/roarr) 4 | [![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical) 5 | [![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social&label=Follow)](https://twitter.com/kuizinas) 6 | 7 | JSON logger for Node.js and browser. 8 | 9 | ## Motivation 10 | 11 | For a long time I have been a big fan of using [`debug`](https://github.com/visionmedia/debug). `debug` is simple to use, works in Node.js and browser, does not require configuration and it is fast. However, problems arise when you need to parse logs. Anything but one-line text messages cannot be parsed in a safe way. 12 | 13 | To log structured data, I have been using [Winston](https://github.com/winstonjs/winston) and [Bunyan](https://github.com/trentm/node-bunyan). These packages are great for application-level logging. I have preferred Bunyan because of the [Bunyan CLI program](https://github.com/trentm/node-bunyan#cli-usage) used to pretty-print logs. However, these packages require program-level configuration – when constructing an instance of a logger, you need to define the transport and the log-level. This makes them unsuitable for use in code designed to be consumed by other applications. 14 | 15 | Then there is [pino](https://github.com/pinojs/pino). pino is fast JSON logger, it has CLI program equivalent to Bunyan, it decouples transports, and it has sane default configuration. Unfortunately, you still need to instantiate logger instance at the application-level. This makes it more suitable for application-level logging just like Winston and Bunyan. 16 | 17 | I needed a logger that: 18 | 19 | * Does not block the event cycle (=fast). 20 | * Does not require initialization. 21 | * Produces structured data. 22 | * [Decouples transports](#transports). 23 | * Has a [CLI program](#cli-program). 24 | * Works in Node.js and browser. 25 | * Configurable using environment variables. 26 | 27 | In other words, 28 | 29 | * a logger that I can use in an application code and in dependencies. 30 | * a logger that allows to correlate logs between the main application code and the dependency code. 31 | * a logger that works well with transports in external processes. 32 | 33 | Roarr is this logger. 34 | 35 | ## Usage 36 | 37 | ### Producing logs 38 | 39 | Roarr logger API for producing logs is the same in Node.js and browser. 40 | 41 | 1. Import `roarr` 42 | 2. Use any of the [API](#api) methods to log messages. 43 | 44 | Example: 45 | 46 | ```ts 47 | import { 48 | Roarr as log, 49 | } from 'roarr'; 50 | 51 | log('foo'); 52 | ``` 53 | 54 | ### Consuming logs 55 | 56 | Roarr logs are consumed differently in Node.js and browser. 57 | 58 | #### Node.js 59 | 60 | In Node.js, Roarr logging is disabled by default. To enable logging, you must start program with an environment variable `ROARR_LOG` set to `true`, e.g. 61 | 62 | ```bash 63 | ROARR_LOG=true node ./index.js 64 | ``` 65 | 66 | All logs will be written to stdout. 67 | 68 | #### Browser 69 | 70 | In a browser, you must implement `ROARR.write` method to read logs, e.g. 71 | 72 | ```ts 73 | import { 74 | ROARR, 75 | } from 'roarr'; 76 | 77 | ROARR.write = () => {}; 78 | ``` 79 | 80 | The API of the `ROARR.write` is: 81 | 82 | ```ts 83 | (message: string) => void; 84 | ``` 85 | 86 | Example implementation: 87 | 88 | ```ts 89 | import { 90 | ROARR, 91 | } from 'roarr'; 92 | 93 | ROARR.write = (message) => { 94 | console.log(JSON.parse(message)); 95 | }; 96 | ``` 97 | 98 | or if you are initializing `ROARR.write` _before_ `roarr` is loaded: 99 | 100 | ```ts 101 | // Ensure that `globalThis.ROARR` is configured. 102 | const ROARR = globalThis.ROARR = globalThis.ROARR || {}; 103 | 104 | ROARR.write = (message) => { 105 | console.log(JSON.parse(message)); 106 | }; 107 | ``` 108 | 109 | If your platform does not support [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis), use [`globalthis` polyfill](https://www.npmjs.com/package/globalthis). 110 | 111 | You may also use [`@roarr/browser-log-writer`](https://github.com/gajus/roarr-browser-log-writer) that implements and opinionated browser logger with [Liqe](https://github.com/gajus/liqe) query support for filtering logs. 112 | 113 | ### Filtering logs 114 | 115 | #### Node.js 116 | 117 | In Node.js, Roarr prints all or none logs (refer to the [`ROARR_LOG` environment variable](#environment-variables) documentation). 118 | 119 | Use [`@roarr/cli` program](https://github.com/gajus/roarr-cli#filtering-logs) to filter logs, e.g. 120 | 121 | ```bash 122 | ROARR_LOG=true node ./index.js | roarr --filter 'context.logLevel:>30' 123 | ``` 124 | 125 | #### Browser 126 | 127 | In a browser, Roarr calls `globalThis.ROARR.write` for every log message. Implement your own custom logic to filter logs, e.g. 128 | 129 | ```ts 130 | globalThis.ROARR.write = (message) => { 131 | const payload = JSON.parse(message); 132 | 133 | if (payload.context.logLevel > 30) { 134 | console.log(payload); 135 | } 136 | }; 137 | ``` 138 | 139 | ## Log message format 140 | 141 | |Property name|Contents| 142 | |---|---| 143 | |`context`|Arbitrary, user-provided structured data. See [context property names](#context-property-names).| 144 | |`message`|User-provided message formatted using [printf](https://en.wikipedia.org/wiki/Printf_format_string).| 145 | |`sequence`|Incremental sequence ID (see [`adopt`](#adopt) for description of the format and its meaning).| 146 | |`time`|Unix timestamp in milliseconds.| 147 | |`version`|Roarr log message format version.| 148 | 149 | Example: 150 | 151 | ```json 152 | { 153 | "context": { 154 | "application": "task-runner", 155 | "hostname": "curiosity.local", 156 | "instanceId": "01BVBK4ZJQ182ZWF6FK4EC8FEY", 157 | "taskId": 1 158 | }, 159 | "message": "starting task ID 1", 160 | "sequence": "0", 161 | "time": 1506776210000, 162 | "version": "1.0.0" 163 | } 164 | ``` 165 | 166 | ## API 167 | 168 | `roarr` package exports a function with the following API: 169 | 170 | ```ts 171 | export type Logger = 172 | ( 173 | context: MessageContext, 174 | message: string, 175 | c?: SprintfArgument, 176 | d?: SprintfArgument, 177 | e?: SprintfArgument, 178 | f?: SprintfArgument, 179 | g?: SprintfArgument, 180 | h?: SprintfArgument, 181 | i?: SprintfArgument, 182 | k?: SprintfArgument 183 | ) => void | 184 | ( 185 | message: string, 186 | b?: SprintfArgument, 187 | c?: SprintfArgument, 188 | d?: SprintfArgument, 189 | e?: SprintfArgument, 190 | f?: SprintfArgument, 191 | g?: SprintfArgument, 192 | h?: SprintfArgument, 193 | i?: SprintfArgument, 194 | k?: SprintfArgument 195 | ) => void; 196 | ``` 197 | 198 | To put it into words: 199 | 200 | * First parameter can be either a string (message) or an object. 201 | * If first parameter is an object (context), the second parameter must be a string (message). 202 | * Arguments after the message parameter are used to enable [printf message formatting](https://en.wikipedia.org/wiki/Printf_format_string). 203 | * Printf arguments must be of a primitive type (`string | number | boolean | null`). 204 | * There can be up to 9 printf arguments (or 8 if the first parameter is the context object). 205 | 206 | Refer to the [Usage documentation](#usage) for common usage examples. 207 | 208 | ### `adopt` 209 | 210 | ```ts 211 | (routine: () => Promise, context: MessageContext | TransformMessageFunction) => Promise, 212 | ``` 213 | 214 | `adopt` function uses Node.js [`async_context`](https://nodejs.org/api/async_context.html) to pass-down context properties. 215 | 216 | When using `adopt`, context properties will be added to all _all_ Roarr messages within the same asynchronous context, e.g. 217 | 218 | ```ts 219 | log.adopt( 220 | () => { 221 | log('foo 0'); 222 | 223 | log.adopt( 224 | () => { 225 | log('foo 1'); 226 | }, 227 | { 228 | baz: 'baz 1', 229 | }, 230 | ); 231 | }, 232 | { 233 | bar: 'bar 0', 234 | }, 235 | ); 236 | ``` 237 | 238 | ```json 239 | {"context":{"bar":"bar 0"},"message":"foo 0","sequence":"0","time":1506776210000,"version":"2.0.0"} 240 | {"context":{"bar":"bar 0","baz":"baz 1"},"message":"foo 1","sequence":"0.0","time":1506776210000,"version":"2.0.0"} 241 | ``` 242 | 243 | #### `sequence` value 244 | 245 | `sequence` represents async context hierarchy in [`ltree`](https://www.postgresql.org/docs/current/ltree.html) format, i.e. 246 | 247 | ```xml 248 | [.] 249 | ``` 250 | 251 | Members of sequence value represent log index relative to the async execution context. This information can be used to establish the origin of the log invocation in an asynchronous context, e.g. 252 | 253 | ```ts 254 | log.adopt(() => { 255 | log('foo 0'); 256 | log.adopt(() => { 257 | log('bar 0'); 258 | log.adopt(() => { 259 | log('baz 0'); 260 | setTimeout(() => { 261 | log('baz 1'); 262 | }, 10); 263 | }); 264 | log('bar 1'); 265 | }); 266 | }); 267 | ``` 268 | 269 | ```json 270 | {"context":{},"message":"foo 0","sequence":"0.0","time":1506776210000,"version":"2.0.0"} 271 | {"context":{},"message":"bar 0","sequence":"0.1.0","time":1506776210000,"version":"2.0.0"} 272 | {"context":{},"message":"baz 0","sequence":"0.1.1.0","time":1506776210000,"version":"2.0.0"} 273 | {"context":{},"message":"bar 1","sequence":"0.1.2","time":1506776210000,"version":"2.0.0"} 274 | {"context":{},"message":"baz 1","sequence":"0.1.1.1","time":1506776210010,"version":"2.0.0"} 275 | ``` 276 | 277 | Notice that even though logs `baz 0` and `baz 1` were produced at different times, you can tell that one was produced after another by looking at their sequence values `0.1.1.0` and `0.1.1.1`. 278 | 279 | #### Requirements 280 | 281 | * `adopt` method only works in Node.js. 282 | 283 | ### `child` 284 | 285 | The `child` function has two signatures: 286 | 287 | 1. Accepts an object. 288 | 2. Accepts a function. 289 | 290 | #### Object parameter 291 | 292 | ```ts 293 | (context: MessageContext): Logger, 294 | ``` 295 | 296 | Creates a child logger that appends child `context` to every subsequent message. 297 | 298 | Example: 299 | 300 | ```ts 301 | import { 302 | Roarr as log, 303 | } from 'roarr'; 304 | 305 | const barLog = log.child({ 306 | foo: 'bar' 307 | }); 308 | 309 | log.debug('foo 1'); 310 | 311 | barLog.debug('foo 2'); 312 | ``` 313 | 314 | ```json 315 | {"context":{"logLevel":20},"message":"foo 1","sequence":"0","time":1506776210000,"version":"2.0.0"} 316 | {"context":{"foo":"bar","logLevel":20},"message":"foo 2","sequence":"1","time":1506776210000,"version":"2.0.0"} 317 | ``` 318 | 319 | #### Function parameter 320 | 321 | ```ts 322 | (context: TransformMessageFunction>): Logger 323 | ``` 324 | 325 | Creates a child logger that translates every subsequent message. 326 | 327 | Example: 328 | 329 | ```ts 330 | import { 331 | Roarr as log, 332 | } from 'roarr'; 333 | 334 | const barLog = log.child<{error: Error}>((message) => { 335 | return { 336 | ...message, 337 | context: { 338 | ...message.context, 339 | ...message.context.error && { 340 | error: { 341 | message: message.context.error.message, 342 | }, 343 | }, 344 | }, 345 | }; 346 | }); 347 | 348 | log.debug('foo 1'); 349 | 350 | barLog.debug({ 351 | error: new Error('bar'), 352 | }, 'foo 2'); 353 | ``` 354 | 355 | ```json 356 | {"context":{"logLevel":20},"message":"foo 1","sequence":"0","time":1506776210000,"version":"2.0.0"} 357 | {"context":{"logLevel":20,"error":{"message":"bar"}},"message":"bar 2","sequence":"1","time":1506776210000,"version":"2.0.0"} 358 | ``` 359 | 360 | A typical use case for this pattern is serialization (e.g. of HTTP request, response or error object) and redaction of sensitive data from logs. 361 | 362 | ### `getContext` 363 | 364 | Returns the current context. 365 | 366 | Example: 367 | 368 | ```ts 369 | import { 370 | Roarr as log, 371 | } from 'roarr'; 372 | 373 | const childLogger = log.child({ 374 | foo: 'bar' 375 | }); 376 | 377 | childLogger.getContext(); 378 | 379 | // {foo: 'bar'} 380 | ``` 381 | 382 | ### `trace` 383 | ### `debug` 384 | ### `info` 385 | ### `warn` 386 | ### `error` 387 | ### `fatal` 388 | 389 | Convenience methods for logging a message with `logLevel` context property value set to a numeric value representing the [log level](#log-levels), e.g. 390 | 391 | ```ts 392 | import { 393 | Roarr as log, 394 | } from 'roarr'; 395 | 396 | log.trace('foo'); 397 | log.debug('foo'); 398 | log.info('foo'); 399 | log.warn('foo'); 400 | log.error('foo'); 401 | log.fatal('foo'); 402 | ``` 403 | 404 | Produces output: 405 | 406 | ```json 407 | {"context":{"logLevel":10},"message":"foo","sequence":"0","time":1506776210000,"version":"2.0.0"} 408 | {"context":{"logLevel":20},"message":"foo","sequence":"1","time":1506776210000,"version":"2.0.0"} 409 | {"context":{"logLevel":30},"message":"foo","sequence":"2","time":1506776210000,"version":"2.0.0"} 410 | {"context":{"logLevel":40},"message":"foo","sequence":"3","time":1506776210000,"version":"2.0.0"} 411 | {"context":{"logLevel":50},"message":"foo","sequence":"4","time":1506776210000,"version":"2.0.0"} 412 | {"context":{"logLevel":60},"message":"foo","sequence":"5","time":1506776210000,"version":"2.0.0"} 413 | ``` 414 | 415 | ### `traceOnce` 416 | ### `debugOnce` 417 | ### `infoOnce` 418 | ### `warnOnce` 419 | ### `errorOnce` 420 | ### `fatalOnce` 421 | 422 | Just like the regular logger methods, but logs the message only once. 423 | 424 | Note: Internally, Roarr keeps a record of the last 1,000 `Once` invocations. If this buffer overflows, then the message is going to be logged again until the next time the buffer overflows again. 425 | 426 | ## Utilities 427 | 428 | ### `getLogLevelName` 429 | 430 | Provides log level name (trace, debug, ...) for a numeric log level (10, 20, ...). 431 | 432 | If numeric log level is between two ranges, then resolves to the one with greater severity (e.g. 5 => trace). 433 | 434 | If numeric log level is greater than the maximum supported, then falls back to the greatest severity (fatal). 435 | 436 | ```ts 437 | import { 438 | getLogLevelName, 439 | } from 'roarr'; 440 | import type { 441 | LogLevelName, 442 | } from 'roarr'; 443 | 444 | getLogLevelName(numericLogLevel: number): LogLevelName; 445 | ``` 446 | 447 | ## Middlewares 448 | 449 | Roarr logger supports middlewares implemented as [`child`](#child) message translate functions, e.g. 450 | 451 | ```ts 452 | import { 453 | Roarr as log, 454 | } from 'roarr'; 455 | import createSerializeErrorMiddleware from '@roarr/middleware-serialize-error'; 456 | 457 | const childLog = log.child(createSerializeErrorMiddleware()); 458 | 459 | const error = new Error('foo'); 460 | 461 | log.debug({error}, 'bar'); 462 | childLog.debug({error}, 'bar'); 463 | ``` 464 | 465 | ```json 466 | {"context":{"logLevel":20,"error":{}},"message":"bar","sequence":"0","time":1506776210000,"version":"2.0.0"} 467 | {"context":{"logLevel":20,"error":{"name":"Error","message":"foo","stack":"[REDACTED]"}},"message":"bar","sequence":"1","time":1506776210000,"version":"2.0.0"} 468 | ``` 469 | 470 | Roarr middlewares enable translation of every bit of information that is used to construct a log message. 471 | 472 | The following are the official middlewares: 473 | 474 | * [`@roarr/middleware-serialize-error`](https://github.com/gajus/roarr-middleware-serialize-error) 475 | 476 | Raise an issue to add your middleware of your own creation. 477 | 478 | ## CLI program 479 | 480 | Roarr CLI program provides ability to filter and pretty-print Roarr logs. 481 | 482 | ![CLI output demo](./.README/cli-output-demo.png) 483 | 484 | CLI program has been moved to a separate package [`@roarr/cli`](https://github.com/gajus/roarr-cli). 485 | 486 | ```bash 487 | npm install @roarr/cli -g 488 | ``` 489 | 490 | Explore all CLI commands and options using `roarr --help` or refer to [`@roarr/cli`](https://github.com/gajus/roarr-cli) documentation. 491 | 492 | ## Transports 493 | 494 | A transport in most logging libraries is something that runs in-process to perform some operation with the finalized log line. For example, a transport might send the log line to a standard syslog server after processing the log line and reformatting it. 495 | 496 | Roarr does not support in-process transports. 497 | 498 | Roarr does not support in-process transports because Node processes are single threaded processes (ignoring some technical details). Given this restriction, Roarr purposefully offloads handling of the logs to external processes so that the threading capabilities of the OS can be used (or other CPUs). 499 | 500 | Depending on your configuration, consider one of the following log transports: 501 | 502 | * [Beats](https://www.elastic.co/products/beats) for aggregating at a process level (written in Go). 503 | * [logagent](https://github.com/sematext/logagent-js) for aggregating at a process level (written in JavaScript). 504 | * [Fluentd](https://www.fluentd.org/) for aggregating logs at a container orchestration level (e.g. Kubernetes) (written in Ruby). 505 | 506 | ## Node.js environment variables 507 | 508 | Use environment variables to control `roarr` behavior. 509 | 510 | |Name||Function|Default| 511 | |---|---|---|---| 512 | |`ROARR_LOG`|Boolean|Enables/ disables logging.|`false`| 513 | |`ROARR_STREAM`|`STDOUT`, `STDERR`|Name of the stream where the logs will be written.|`STDOUT`| 514 | 515 | When using `ROARR_STREAM=STDERR`, use [`3>&1 1>&2 2>&3 3>&-`](https://stackoverflow.com/a/2381643/368691) to pipe stderr output. 516 | 517 | ## Conventions 518 | 519 | ### Context property names 520 | 521 | Roarr does not have reserved context property names. However, I encourage use of the following conventions: 522 | 523 | |Context property name|Use case| 524 | |---|---| 525 | |`application`|Name of the application (do not use in code intended for distribution; see `package` property instead).| 526 | |`logLevel`|A numeric value indicating the [log level](#log-levels). See [API](#api) for the build-in loggers with a pre-set log-level.| 527 | |`namespace`|Namespace within a package, e.g. function name. Treat the same way that you would construct namespaces when using the [`debug`](https://github.com/visionmedia/debug) package.| 528 | |`package`|Name of the NPM package.| 529 | 530 | The `roarr pretty-print` [CLI program](#cli-program) is using the context property names suggested in the conventions to pretty-print the logs for the developer inspection purposes. 531 | 532 | #### Log levels 533 | 534 | The `roarr pretty-print` [CLI program](#cli-program) translates `logLevel` values to the following human-readable names: 535 | 536 | |`logLevel`|Human-readable name| 537 | |---|---| 538 | |10|TRACE| 539 | |20|DEBUG| 540 | |30|INFO| 541 | |40|WARN| 542 | |50|ERROR| 543 | |60|FATAL| 544 | 545 | ### Using Roarr in an application 546 | 547 | To avoid code duplication, you can use a singleton pattern to export a logger instance with predefined context properties (e.g. describing the application). 548 | 549 | I recommend to create a file `Logger.js` in the project directory. Inside this file create and export a child instance of Roarr with context parameters describing the project and the script instance, e.g. 550 | 551 | ```ts 552 | /** 553 | * @file Example contents of a Logger.js file. 554 | */ 555 | 556 | import { 557 | Roarr, 558 | } from 'roarr'; 559 | 560 | export const Logger = Roarr.child({ 561 | // .foo property is going to appear only in the logs that are created using 562 | // the current instance of a Roarr logger. 563 | foo: 'bar' 564 | }); 565 | ``` 566 | 567 | Roarr does not have reserved context property names. However, I encourage use of the [conventions](#conventions). 568 | 569 | ## Recipes 570 | 571 | ### Overriding message serializer 572 | 573 | Roarr is opinionated about how it serializes (converts objects to JSON string) log messages, e.g. in Node.js it uses a schema based serializer, which is very fast, but does not allow custom top-level properties. 574 | 575 | You can override this serializer by defining `ROARR.serializeMessage`: 576 | 577 | ```ts 578 | import type { 579 | MessageSerializer, 580 | } from 'roarr'; 581 | 582 | const ROARR = globalThis.ROARR = globalThis.ROARR || {}; 583 | 584 | const serializeMessage: MessageSerializer = (message) => { 585 | return JSON.stringify(message); 586 | }; 587 | 588 | ROARR.serializeMessage = serializeMessage; 589 | ``` 590 | 591 | ### Logging errors 592 | 593 | This is not specific to Roarr – this suggestion applies to any kind of logging. 594 | 595 | If you want to include an instance of [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) in the context, you must serialize the error. 596 | 597 | The least-error prone way to do this is to use an existing library, e.g. [`serialize-error`](https://www.npmjs.com/package/serialize-error). 598 | 599 | ```ts 600 | import { 601 | Roarr as log, 602 | } from 'roarr'; 603 | import serializeError from 'serialize-error'; 604 | 605 | // [..] 606 | 607 | send((error, result) => { 608 | if (error) { 609 | log.error({ 610 | error: serializeError(error) 611 | }, 'message not sent due to a remote error'); 612 | 613 | return; 614 | } 615 | 616 | // [..] 617 | }); 618 | ``` 619 | 620 | Without using serialization, your errors will be logged without the error name and stack trace. 621 | 622 | ## Anti-patterns 623 | 624 | ### Overriding `globalThis.ROARR.write` in Node.js 625 | 626 | Overriding `globalThis.ROARR.write` in Node.js works the same way as it does in [browser](#browser). However, overriding `ROARR.write` in Node.js is considered an anti-pattern because it defeats some of the major benefits outlined in [Motivation](https://github.com/gajus/roarr#motivation) section of the documentation. Namely, by overriding `ROARR.write` in Node.js you are adding blocking events to the event cycle and coupling application logic with log handling logic. 627 | 628 | If you have a use case that asks for overriding `ROARR.write` in Node.js, then [raise an issue](https://github.com/gajus/roarr/issues) to discuss your requirements. 629 | 630 | ## Integrations 631 | 632 | ### Using with Sentry 633 | 634 | https://github.com/gajus/roarr-sentry 635 | 636 | ### Using with Fastify 637 | 638 | https://github.com/gajus/roarr-fastify 639 | 640 | ### Using with Elasticsearch 641 | 642 | If you are using [Elasticsearch](https://www.elastic.co/products/elasticsearch), you will want to create an [index template](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-templates.html). 643 | 644 | The following serves as the ground work for the index template. It includes the main Roarr log message properties (context, message, time) and the context properties suggested in the [conventions](#conventions). 645 | 646 | ```json 647 | { 648 | "mappings": { 649 | "log_message": { 650 | "_source": { 651 | "enabled": true 652 | }, 653 | "dynamic": "strict", 654 | "properties": { 655 | "context": { 656 | "dynamic": true, 657 | "properties": { 658 | "application": { 659 | "type": "keyword" 660 | }, 661 | "hostname": { 662 | "type": "keyword" 663 | }, 664 | "instanceId": { 665 | "type": "keyword" 666 | }, 667 | "logLevel": { 668 | "type": "integer" 669 | }, 670 | "namespace": { 671 | "type": "text" 672 | }, 673 | "package": { 674 | "type": "text" 675 | } 676 | } 677 | }, 678 | "message": { 679 | "type": "text" 680 | }, 681 | "time": { 682 | "format": "epoch_millis", 683 | "type": "date" 684 | } 685 | } 686 | } 687 | }, 688 | "template": "logstash-*" 689 | } 690 | ``` 691 | 692 | ### Using with Scalyr 693 | 694 | If you are using [Scalyr](https://www.scalyr.com/), you will want to create a custom parser `RoarrLogger`: 695 | 696 | ```ts 697 | { 698 | patterns: { 699 | tsPattern: "\\w{3},\\s\\d{2}\\s\\w{3}\\s\\d{4}\\s[\\d:]+", 700 | tsPattern_8601: "\\d{4}-\\d{2}-\\d{2}T[\\d:.]+Z" 701 | } 702 | formats: [ 703 | {format: "${parse=json}$"}, 704 | {format: ".*\"time\":$timestamp=number$,.*"}, 705 | {format: "$timestamp=tsPattern$ GMT $detail$"}, 706 | {format: "$timestamp=tsPattern_8601$ $detail$"} 707 | ] 708 | } 709 | ``` 710 | 711 | and configure the individual programs to use `RoarrLogger`. In case of Kubernetes, this means adding a `log.config.scalyr.com/attributes.parser: RoarrLogger` annotation to the associated deployment, pod or container. 712 | 713 | ### Using with NestJS 714 | 715 | If you are using [NestJS](https://docs.nestjs.com/), you can use [`nestjs-logger-roarr`](https://www.npmjs.com/package/nestjs-logger-roarr) to perform logging inside your application. 716 | 717 | To enable one shared logger for the entire application: 718 | 719 | ```typescript 720 | import { RoarrLoggerService } from nestjs-logger-roarr'; 721 | import { AppModule } from "app.module"; 722 | 723 | const logger = RoarrLoggerService.sharedInstance(); 724 | const app = await NestFactory.create(AppModule, { logger }); 725 | ``` 726 | 727 | To enable mutiple injected loggers via the usual Module syntax: 728 | 729 | ```typescript 730 | import { Module } from '@nestjs/common'; 731 | import { ConfigModule } from '@nestjs/config; 732 | import { RoarrLoggerModule } from 'nestjs-logger-roarr'; 733 | 734 | @Module({ 735 | imports: [ 736 | RoarrLoggerModule.forRoot({ 737 | logLevel: 'warn', // this is the *minimum* log level that will be displayed 738 | }), 739 | ] 740 | }) 741 | 742 | export class AppModule {} 743 | ``` 744 | 745 | ## Documenting use of Roarr 746 | 747 | If your package is using Roarr, include instructions in `README.md` describing how to enable logging, e.g. 748 | 749 | ```md 750 | ## Logging 751 | 752 | This project uses [`roarr`](https://www.npmjs.com/package/roarr) logger to log the program's state. 753 | 754 | Export `ROARR_LOG=true` environment variable to enable log printing to `stdout`. 755 | 756 | Use [`roarr-cli`](https://github.com/gajus/roarr-cli) program to pretty-print the logs. 757 | ``` 758 | 759 | ## Context Truncation 760 | 761 | Roarr by default truncates context properties if the context object is wider or deeper than 10 properties. At the moment, this is a hard-coded value. Waiting for feedback on whether this is a reasonable default and if it needs to be configurable. 762 | 763 | When the context goes over this limit, you will start seeing `...` entries in your logs, e.g. 764 | 765 | ```json 766 | {"a":"a","b":"b","c":"c","d":"d","e":"e","f":"f","g":"g","h":"h","i":"i","j":"j","...":"1 item not stringified"} 767 | ``` 768 | 769 | The reason for this is to prevent accidental logging of massive objects that can cause context truncation and performance issues. 770 | 771 | ## Developing 772 | 773 | Every time a change is made to the logger, one must update `ROARR_VERSION` value in [`./src/config.ts`](./src/config.ts). 774 | 775 | Unfortunately, this process cannot be automated because the version number is not known before `semantic-version` is called. 776 | -------------------------------------------------------------------------------- /cspell.yaml: -------------------------------------------------------------------------------- 1 | ignoreRegExpList: 2 | - /.*[0-9].*/ 3 | language: en 4 | minWordLength: 5 5 | version: '0.2' 6 | words: 7 | - Gajus 8 | - Kuizinas 9 | - roarr 10 | - sprintf 11 | - tsimp -------------------------------------------------------------------------------- /knip.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://unpkg.com/knip@2/schema.json", 3 | "entry": [ 4 | "src/Roarr.ts", 5 | "src/browser.ts" 6 | ], 7 | "ignoreDependencies": [ 8 | "husky", 9 | "tsimp" 10 | ], 11 | "project": [ 12 | "src/**/*!", 13 | "test/**/*" 14 | ] 15 | } -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "author": { 3 | "email": "gajus@gajus.com", 4 | "name": "Gajus Kuizinas", 5 | "url": "http://gajus.com" 6 | }, 7 | "ava": { 8 | "extensions": { 9 | "ts": "module" 10 | }, 11 | "files": [ 12 | "test/roarr/**/*" 13 | ], 14 | "nodeArguments": [ 15 | "--import=tsimp" 16 | ] 17 | }, 18 | "browser": "./dist/browser.js", 19 | "dependencies": { 20 | "fast-printf": "^1.6.9", 21 | "safe-stable-stringify": "^2.4.3", 22 | "semver-compare": "^1.0.0" 23 | }, 24 | "description": "JSON logger for Node.js and browser.", 25 | "devDependencies": { 26 | "@istanbuljs/nyc-config-typescript": "^1.0.2", 27 | "@semantic-release/commit-analyzer": "^11.0.0", 28 | "@semantic-release/github": "^9.2.1", 29 | "@semantic-release/npm": "^11.0.0", 30 | "@types/node": "^20.8.9", 31 | "@types/semver-compare": "^1.0.2", 32 | "ava": "^6.1.2", 33 | "benchmark": "^2.1.4", 34 | "eslint": "^8.52.0", 35 | "eslint-config-canonical": "^42.3.0", 36 | "husky": "^8.0.3", 37 | "knip": "^2.38.4", 38 | "nyc": "^15.1.0", 39 | "semantic-release": "^22.0.5", 40 | "sinon": "^17.0.0", 41 | "tsimp": "^2.0.11", 42 | "tsx": "^4.7.1", 43 | "typescript": "^5.4.2" 44 | }, 45 | "engines": { 46 | "node": ">=18.0" 47 | }, 48 | "files": [ 49 | "src", 50 | "dist" 51 | ], 52 | "keywords": [ 53 | "log", 54 | "logger", 55 | "json" 56 | ], 57 | "license": "BSD-3-Clause", 58 | "main": "./dist/Roarr.js", 59 | "name": "roarr", 60 | "repository": { 61 | "type": "git", 62 | "url": "git@github.com:gajus/roarr.git" 63 | }, 64 | "scripts": { 65 | "benchmark": "ROARR_LOG=true tsx test/benchmark.ts", 66 | "build": "rm -fr ./dist && tsc --project tsconfig.build.json", 67 | "dev": "tsc --watch --project tsconfig.build.json", 68 | "lint": "eslint ./src ./test && tsc && knip", 69 | "test": "ava --serial --verbose" 70 | }, 71 | "types": "./dist/Roarr.d.ts", 72 | "version": "1.0.0" 73 | } 74 | -------------------------------------------------------------------------------- /src/Roarr.ts: -------------------------------------------------------------------------------- 1 | import { createLogger } from './factories/createLogger'; 2 | import { createRoarrInitialGlobalState } from './factories/createRoarrInitialGlobalState'; 3 | import { type MessageSerializer, type RoarrGlobalState } from './types'; 4 | import { stringify } from './utilities/stringify'; 5 | 6 | const ROARR = createRoarrInitialGlobalState( 7 | (globalThis.ROARR as RoarrGlobalState) || {}, 8 | ); 9 | 10 | globalThis.ROARR = ROARR; 11 | 12 | const serializeMessage: MessageSerializer = (message) => { 13 | return stringify(message); 14 | }; 15 | 16 | const Roarr = createLogger((message) => { 17 | if (ROARR.write) { 18 | // Stringify message as soon as it is received to prevent 19 | // properties of the context from being modified by reference. 20 | ROARR.write((ROARR.serializeMessage ?? serializeMessage)(message)); 21 | } 22 | }); 23 | 24 | export type { 25 | Logger, 26 | LogLevelName, 27 | LogWriter, 28 | Message, 29 | MessageContext, 30 | MessageEventHandler, 31 | MessageSerializer, 32 | RoarrGlobalState, 33 | TransformMessageFunction, 34 | } from './types'; 35 | 36 | export { ROARR, Roarr }; 37 | 38 | export { logLevels } from './constants'; 39 | export { getLogLevelName } from './getLogLevelName'; 40 | -------------------------------------------------------------------------------- /src/browser.ts: -------------------------------------------------------------------------------- 1 | import { createLogger } from './factories/createLogger'; 2 | import { createRoarrInitialGlobalStateBrowser } from './factories/createRoarrInitialGlobalStateBrowser'; 3 | import { type MessageSerializer, type RoarrGlobalState } from './types'; 4 | import { stringify } from './utilities/stringify'; 5 | 6 | const ROARR = createRoarrInitialGlobalStateBrowser( 7 | (globalThis.ROARR as RoarrGlobalState) || {}, 8 | ); 9 | 10 | globalThis.ROARR = ROARR; 11 | 12 | const serializeMessage: MessageSerializer = (message) => { 13 | return stringify(message); 14 | }; 15 | 16 | const Roarr = createLogger((message) => { 17 | if (ROARR.write) { 18 | // Stringify message as soon as it is received to prevent 19 | // properties of the context from being modified by reference. 20 | ROARR.write((ROARR.serializeMessage ?? serializeMessage)(message)); 21 | } 22 | }); 23 | 24 | export type { 25 | Logger, 26 | LogLevelName, 27 | Message, 28 | MessageContext, 29 | MessageEventHandler, 30 | MessageSerializer, 31 | RoarrGlobalState, 32 | TransformMessageFunction, 33 | } from './types'; 34 | 35 | export { ROARR, Roarr }; 36 | 37 | export { logLevels } from './constants'; 38 | export { getLogLevelName } from './getLogLevelName'; 39 | -------------------------------------------------------------------------------- /src/config.ts: -------------------------------------------------------------------------------- 1 | // This needs to be updated manually because there is no way 2 | // to know the package version at the build time. 3 | export const ROARR_VERSION = '5.0.0'; 4 | 5 | export const ROARR_LOG_FORMAT_VERSION = '2.0.0'; 6 | -------------------------------------------------------------------------------- /src/constants.ts: -------------------------------------------------------------------------------- 1 | export const logLevels = { 2 | debug: 20, 3 | error: 50, 4 | fatal: 60, 5 | info: 30, 6 | trace: 10, 7 | warn: 40, 8 | }; 9 | -------------------------------------------------------------------------------- /src/factories/createLogger.ts: -------------------------------------------------------------------------------- 1 | import { ROARR_LOG_FORMAT_VERSION } from '../config'; 2 | import { logLevels } from '../constants'; 3 | import { 4 | type AsyncLocalContext, 5 | type Logger, 6 | type MessageContext, 7 | type MessageEventHandler, 8 | type RoarrGlobalState, 9 | type TopLevelAsyncLocalContext, 10 | type TransformMessageFunction, 11 | } from '../types'; 12 | import { hasOwnProperty } from '../utilities/hasOwnProperty'; 13 | import { isBrowser } from '../utilities/isBrowser'; 14 | import { isTruthy } from '../utilities/isTruthy'; 15 | import { createMockLogger } from './createMockLogger'; 16 | import { printf } from 'fast-printf'; 17 | import safeStringify from 'safe-stable-stringify'; 18 | 19 | let loggedWarningAsyncLocalContext = false; 20 | 21 | const getGlobalRoarrContext = (): RoarrGlobalState => { 22 | return globalThis.ROARR; 23 | }; 24 | 25 | const createDefaultAsyncLocalContext = (): TopLevelAsyncLocalContext => { 26 | return { 27 | messageContext: {}, 28 | transforms: [], 29 | }; 30 | }; 31 | 32 | const getAsyncLocalContext = (): AsyncLocalContext => { 33 | const asyncLocalStorage = getGlobalRoarrContext().asyncLocalStorage; 34 | 35 | if (!asyncLocalStorage) { 36 | throw new Error('AsyncLocalContext is unavailable.'); 37 | } 38 | 39 | const asyncLocalContext = asyncLocalStorage.getStore(); 40 | 41 | if (asyncLocalContext) { 42 | return asyncLocalContext; 43 | } 44 | 45 | return createDefaultAsyncLocalContext(); 46 | }; 47 | 48 | const isAsyncLocalContextAvailable = (): boolean => { 49 | return Boolean(getGlobalRoarrContext().asyncLocalStorage); 50 | }; 51 | 52 | const getSequence = () => { 53 | if (isAsyncLocalContextAvailable()) { 54 | const asyncLocalContext = getAsyncLocalContext(); 55 | 56 | if ( 57 | hasOwnProperty(asyncLocalContext, 'sequenceRoot') && 58 | hasOwnProperty(asyncLocalContext, 'sequence') && 59 | typeof asyncLocalContext.sequence === 'number' 60 | ) { 61 | return ( 62 | String(asyncLocalContext.sequenceRoot) + 63 | '.' + 64 | String(asyncLocalContext.sequence++) 65 | ); 66 | } 67 | 68 | return String(getGlobalRoarrContext().sequence++); 69 | } 70 | 71 | return String(getGlobalRoarrContext().sequence++); 72 | }; 73 | 74 | const createChildLogger = (log: Logger, logLevel: number) => { 75 | return (a, b, c, d, e, f, g, h, index, index_) => { 76 | log.child({ 77 | logLevel, 78 | })(a, b, c, d, e, f, g, h, index, index_); 79 | }; 80 | }; 81 | 82 | const MAX_ONCE_ENTRIES = 1_000; 83 | 84 | const createOnceChildLogger = (log: Logger, logLevel: number) => { 85 | return (a, b, c, d, e, f, g, h, index, index_) => { 86 | const key = safeStringify({ 87 | a, 88 | b, 89 | c, 90 | d, 91 | e, 92 | f, 93 | g, 94 | h, 95 | i: index, 96 | j: index_, 97 | logLevel, 98 | }); 99 | 100 | if (!key) { 101 | throw new Error('Expected key to be a string'); 102 | } 103 | 104 | const onceLog = getGlobalRoarrContext().onceLog; 105 | 106 | if (onceLog.has(key)) { 107 | return; 108 | } 109 | 110 | onceLog.add(key); 111 | 112 | if (onceLog.size > MAX_ONCE_ENTRIES) { 113 | onceLog.clear(); 114 | } 115 | 116 | log.child({ 117 | logLevel, 118 | })(a, b, c, d, e, f, g, h, index, index_); 119 | }; 120 | }; 121 | 122 | export const createLogger = ( 123 | onMessage: MessageEventHandler, 124 | parentMessageContext: MessageContext = {}, 125 | transforms: ReadonlyArray> = [], 126 | ): Logger => { 127 | if (!isBrowser() && typeof process !== 'undefined') { 128 | // eslint-disable-next-line node/no-process-env 129 | const enabled = isTruthy(process.env.ROARR_LOG ?? ''); 130 | 131 | if (!enabled) { 132 | return createMockLogger(onMessage, parentMessageContext); 133 | } 134 | } 135 | 136 | const log = ( 137 | a: any, 138 | b: any, 139 | c: any, 140 | d: any, 141 | e: any, 142 | f: any, 143 | g: any, 144 | h: any, 145 | index: any, 146 | index_: any, 147 | ) => { 148 | const time = Date.now(); 149 | const sequence = getSequence(); 150 | 151 | let asyncLocalContext: AsyncLocalContext; 152 | 153 | if (isAsyncLocalContextAvailable()) { 154 | asyncLocalContext = getAsyncLocalContext(); 155 | } else { 156 | asyncLocalContext = createDefaultAsyncLocalContext(); 157 | } 158 | 159 | let context; 160 | let message; 161 | 162 | if (typeof a === 'string') { 163 | context = { 164 | ...asyncLocalContext.messageContext, 165 | ...parentMessageContext, 166 | }; 167 | } else { 168 | context = { 169 | ...asyncLocalContext.messageContext, 170 | ...parentMessageContext, 171 | ...a, 172 | }; 173 | } 174 | 175 | if (typeof a === 'string' && b === undefined) { 176 | message = a; 177 | } else if (typeof a === 'string') { 178 | if (!a.includes('%')) { 179 | throw new Error( 180 | 'When a string parameter is followed by other arguments, then it is assumed that you are attempting to format a message using printf syntax. You either forgot to add printf bindings or if you meant to add context to the log message, pass them in an object as the first parameter.', 181 | ); 182 | } 183 | 184 | message = printf(a, b, c, d, e, f, g, h, index, index_); 185 | } else { 186 | let fallbackMessage = b; 187 | 188 | if (typeof b !== 'string') { 189 | if (b === undefined) { 190 | fallbackMessage = ''; 191 | } else { 192 | throw new TypeError( 193 | 'Message must be a string. Received ' + typeof b + '.', 194 | ); 195 | } 196 | } 197 | 198 | message = printf(fallbackMessage, c, d, e, f, g, h, index, index_); 199 | } 200 | 201 | let packet = { 202 | context, 203 | message, 204 | sequence, 205 | time, 206 | version: ROARR_LOG_FORMAT_VERSION, 207 | }; 208 | 209 | for (const transform of [...asyncLocalContext.transforms, ...transforms]) { 210 | packet = transform(packet); 211 | 212 | if (typeof packet !== 'object' || packet === null) { 213 | throw new Error( 214 | 'Message transform function must return a message object.', 215 | ); 216 | } 217 | } 218 | 219 | onMessage(packet); 220 | }; 221 | 222 | /** 223 | * Creates a child logger with the provided context. 224 | * If context is an object, then its properties are prepended to all descending logs. 225 | * If context is a function, then that function is used to process all descending logs. 226 | */ 227 | log.child = (context) => { 228 | let asyncLocalContext: AsyncLocalContext; 229 | 230 | if (isAsyncLocalContextAvailable()) { 231 | asyncLocalContext = getAsyncLocalContext(); 232 | } else { 233 | asyncLocalContext = createDefaultAsyncLocalContext(); 234 | } 235 | 236 | if (typeof context === 'function') { 237 | return createLogger( 238 | onMessage, 239 | { 240 | ...asyncLocalContext.messageContext, 241 | ...parentMessageContext, 242 | ...context, 243 | }, 244 | [context, ...transforms], 245 | ); 246 | } 247 | 248 | return createLogger( 249 | onMessage, 250 | { 251 | ...asyncLocalContext.messageContext, 252 | ...parentMessageContext, 253 | ...context, 254 | }, 255 | transforms, 256 | ); 257 | }; 258 | 259 | log.getContext = () => { 260 | let asyncLocalContext: AsyncLocalContext; 261 | 262 | if (isAsyncLocalContextAvailable()) { 263 | asyncLocalContext = getAsyncLocalContext(); 264 | } else { 265 | asyncLocalContext = createDefaultAsyncLocalContext(); 266 | } 267 | 268 | return { 269 | ...asyncLocalContext.messageContext, 270 | ...parentMessageContext, 271 | }; 272 | }; 273 | 274 | log.adopt = async (routine, context) => { 275 | if (!isAsyncLocalContextAvailable()) { 276 | if (loggedWarningAsyncLocalContext === false) { 277 | loggedWarningAsyncLocalContext = true; 278 | 279 | onMessage({ 280 | context: { 281 | logLevel: logLevels.warn, 282 | package: 'roarr', 283 | }, 284 | message: 285 | 'async_hooks are unavailable; Roarr.adopt will not function as expected', 286 | sequence: getSequence(), 287 | time: Date.now(), 288 | version: ROARR_LOG_FORMAT_VERSION, 289 | }); 290 | } 291 | 292 | return routine(); 293 | } 294 | 295 | const asyncLocalContext = getAsyncLocalContext(); 296 | 297 | let sequenceRoot; 298 | 299 | if ( 300 | hasOwnProperty(asyncLocalContext, 'sequenceRoot') && 301 | hasOwnProperty(asyncLocalContext, 'sequence') && 302 | typeof asyncLocalContext.sequence === 'number' 303 | ) { 304 | sequenceRoot = 305 | asyncLocalContext.sequenceRoot + 306 | '.' + 307 | String(asyncLocalContext.sequence++); 308 | } else { 309 | sequenceRoot = String(getGlobalRoarrContext().sequence++); 310 | } 311 | 312 | let nextContext = { 313 | ...asyncLocalContext.messageContext, 314 | }; 315 | 316 | const nextTransforms = [...asyncLocalContext.transforms]; 317 | 318 | if (typeof context === 'function') { 319 | nextTransforms.push(context); 320 | } else { 321 | nextContext = { 322 | ...nextContext, 323 | ...context, 324 | }; 325 | } 326 | 327 | const asyncLocalStorage = getGlobalRoarrContext().asyncLocalStorage; 328 | 329 | if (!asyncLocalStorage) { 330 | throw new Error('Async local context unavailable.'); 331 | } 332 | 333 | return asyncLocalStorage.run( 334 | { 335 | messageContext: nextContext, 336 | sequence: 0, 337 | sequenceRoot, 338 | transforms: nextTransforms, 339 | }, 340 | () => { 341 | return routine(); 342 | }, 343 | ); 344 | }; 345 | 346 | log.debug = createChildLogger(log, logLevels.debug); 347 | log.debugOnce = createOnceChildLogger(log, logLevels.debug); 348 | log.error = createChildLogger(log, logLevels.error); 349 | log.errorOnce = createOnceChildLogger(log, logLevels.error); 350 | log.fatal = createChildLogger(log, logLevels.fatal); 351 | log.fatalOnce = createOnceChildLogger(log, logLevels.fatal); 352 | log.info = createChildLogger(log, logLevels.info); 353 | log.infoOnce = createOnceChildLogger(log, logLevels.info); 354 | log.trace = createChildLogger(log, logLevels.trace); 355 | log.traceOnce = createOnceChildLogger(log, logLevels.trace); 356 | log.warn = createChildLogger(log, logLevels.warn); 357 | log.warnOnce = createOnceChildLogger(log, logLevels.warn); 358 | 359 | return log; 360 | }; 361 | -------------------------------------------------------------------------------- /src/factories/createMockLogger.ts: -------------------------------------------------------------------------------- 1 | import { logLevels } from '../constants'; 2 | import { 3 | type Logger, 4 | type MessageContext, 5 | type MessageEventHandler, 6 | } from '../types'; 7 | 8 | const createChildLogger = (log: Logger, logLevel: number) => { 9 | return (a, b, c, d, e, f, g, h, index, index_) => { 10 | log.child({ 11 | logLevel, 12 | })(a, b, c, d, e, f, g, h, index, index_); 13 | }; 14 | }; 15 | 16 | export const createMockLogger = ( 17 | onMessage: MessageEventHandler, 18 | parentContext?: MessageContext, 19 | ): Logger => { 20 | // eslint-disable-next-line unicorn/consistent-function-scoping 21 | const log: Logger = () => { 22 | return undefined; 23 | }; 24 | 25 | log.adopt = async (routine) => { 26 | return routine(); 27 | }; 28 | 29 | log.child = () => { 30 | return createMockLogger(onMessage, parentContext); 31 | }; 32 | 33 | log.getContext = () => { 34 | return {}; 35 | }; 36 | 37 | log.debug = createChildLogger(log, logLevels.debug); 38 | log.debugOnce = createChildLogger(log, logLevels.debug); 39 | log.error = createChildLogger(log, logLevels.error); 40 | log.errorOnce = createChildLogger(log, logLevels.error); 41 | log.fatal = createChildLogger(log, logLevels.fatal); 42 | log.fatalOnce = createChildLogger(log, logLevels.fatal); 43 | log.info = createChildLogger(log, logLevels.info); 44 | log.infoOnce = createChildLogger(log, logLevels.info); 45 | log.trace = createChildLogger(log, logLevels.trace); 46 | log.traceOnce = createChildLogger(log, logLevels.trace); 47 | log.warn = createChildLogger(log, logLevels.warn); 48 | log.warnOnce = createChildLogger(log, logLevels.warn); 49 | 50 | return log; 51 | }; 52 | -------------------------------------------------------------------------------- /src/factories/createNodeWriter.ts: -------------------------------------------------------------------------------- 1 | import { type LogWriter } from '../types'; 2 | 3 | const createBlockingWriter = (stream: NodeJS.WritableStream): LogWriter => { 4 | return (message: string) => { 5 | stream.write(message + '\n'); 6 | }; 7 | }; 8 | 9 | export const createNodeWriter = (): LogWriter => { 10 | // eslint-disable-next-line node/no-process-env 11 | const targetStream = (process.env.ROARR_STREAM ?? 'STDOUT').toUpperCase(); 12 | 13 | const stream = 14 | targetStream.toUpperCase() === 'STDOUT' ? process.stdout : process.stderr; 15 | 16 | stream.on('error', (error) => { 17 | if (error.code === 'EPIPE') { 18 | return; 19 | } 20 | 21 | throw error; 22 | }); 23 | 24 | return createBlockingWriter(stream); 25 | }; 26 | -------------------------------------------------------------------------------- /src/factories/createRoarrInitialGlobalState.ts: -------------------------------------------------------------------------------- 1 | import { ROARR_VERSION } from '../config'; 2 | import { type RoarrGlobalState } from '../types'; 3 | import { createNodeWriter } from './createNodeWriter'; 4 | import compareSemver from 'semver-compare'; 5 | 6 | export const createRoarrInitialGlobalState = ( 7 | currentState: any, 8 | ): RoarrGlobalState => { 9 | const versions = (currentState.versions || []).concat(); 10 | 11 | if (versions.length > 1) { 12 | versions.sort(compareSemver); 13 | } 14 | 15 | const currentIsLatestVersion = 16 | !versions.length || 17 | compareSemver(ROARR_VERSION, versions[versions.length - 1]) === 1; 18 | 19 | if (!versions.includes(ROARR_VERSION)) { 20 | versions.push(ROARR_VERSION); 21 | } 22 | 23 | versions.sort(compareSemver); 24 | 25 | let newState = { 26 | onceLog: new Set(), 27 | sequence: 0, 28 | ...currentState, 29 | versions, 30 | }; 31 | 32 | if (currentIsLatestVersion || !newState.write) { 33 | try { 34 | // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires 35 | const AsyncLocalStorage = require('node:async_hooks').AsyncLocalStorage; 36 | 37 | const asyncLocalStorage = new AsyncLocalStorage(); 38 | 39 | newState = { 40 | ...newState, 41 | 42 | asyncLocalStorage, 43 | write: createNodeWriter(), 44 | }; 45 | // eslint-disable-next-line no-empty 46 | } catch {} 47 | } 48 | 49 | return newState; 50 | }; 51 | -------------------------------------------------------------------------------- /src/factories/createRoarrInitialGlobalStateBrowser.ts: -------------------------------------------------------------------------------- 1 | import { ROARR_VERSION } from '../config'; 2 | import { type RoarrGlobalState } from '../types'; 3 | import compareSemver from 'semver-compare'; 4 | 5 | export const createRoarrInitialGlobalStateBrowser = ( 6 | currentState: any, 7 | ): RoarrGlobalState => { 8 | const versions = (currentState.versions || []).concat(); 9 | 10 | if (versions.length > 1) { 11 | versions.sort(compareSemver); 12 | } 13 | 14 | if (!versions.includes(ROARR_VERSION)) { 15 | versions.push(ROARR_VERSION); 16 | } 17 | 18 | versions.sort(compareSemver); 19 | 20 | return { 21 | sequence: 0, 22 | ...currentState, 23 | versions, 24 | }; 25 | }; 26 | -------------------------------------------------------------------------------- /src/getLogLevelName.ts: -------------------------------------------------------------------------------- 1 | import { type LogLevelName } from './types'; 2 | 3 | export const getLogLevelName = (numericLogLevel: number): LogLevelName => { 4 | if (numericLogLevel <= 10) { 5 | return 'trace'; 6 | } 7 | 8 | if (numericLogLevel <= 20) { 9 | return 'debug'; 10 | } 11 | 12 | if (numericLogLevel <= 30) { 13 | return 'info'; 14 | } 15 | 16 | if (numericLogLevel <= 40) { 17 | return 'warn'; 18 | } 19 | 20 | if (numericLogLevel <= 50) { 21 | return 'error'; 22 | } 23 | 24 | return 'fatal'; 25 | }; 26 | -------------------------------------------------------------------------------- /src/types.ts: -------------------------------------------------------------------------------- 1 | import { type AsyncLocalStorage } from 'node:async_hooks'; 2 | 3 | type JsonValue = 4 | | JsonObject 5 | | JsonValue[] 6 | | boolean 7 | | number 8 | | string 9 | | readonly JsonValue[] 10 | | null 11 | | undefined; 12 | 13 | /** 14 | * @see https://stackoverflow.com/a/77390832/368691 15 | * @public 16 | */ 17 | export type JsonObject = { 18 | [k: string]: JsonValue; 19 | }; 20 | 21 | export type LogWriter = (message: string) => void; 22 | 23 | export type MessageContext = JsonObject & T; 24 | 25 | export type TopLevelAsyncLocalContext = { 26 | messageContext: MessageContext; 27 | transforms: ReadonlyArray>; 28 | }; 29 | 30 | type NestedAsyncLocalContext = TopLevelAsyncLocalContext & { 31 | sequence: number; 32 | sequenceRoot: string; 33 | }; 34 | 35 | export type AsyncLocalContext = 36 | | NestedAsyncLocalContext 37 | | TopLevelAsyncLocalContext; 38 | 39 | export type MessageSerializer = (message: Message) => string; 40 | 41 | export type RoarrGlobalState = { 42 | asyncLocalStorage?: AsyncLocalStorage; 43 | onceLog: Set; 44 | sequence: number; 45 | serializeMessage?: MessageSerializer; 46 | versions: readonly string[]; 47 | write: LogWriter; 48 | }; 49 | 50 | type SprintfArgument = boolean | number | string | null; 51 | 52 | export type Message = { 53 | readonly context: T; 54 | readonly message: string; 55 | readonly sequence: string; 56 | readonly time: number; 57 | readonly version: string; 58 | }; 59 | 60 | export type TransformMessageFunction = ( 61 | message: Message, 62 | ) => Message; 63 | 64 | type LogMethod = { 65 | ( 66 | context: Z, 67 | message: T, 68 | c?: T extends `${string}%${string}` ? SprintfArgument : never, 69 | d?: SprintfArgument, 70 | e?: SprintfArgument, 71 | f?: SprintfArgument, 72 | g?: SprintfArgument, 73 | h?: SprintfArgument, 74 | index?: SprintfArgument, 75 | index_?: SprintfArgument, 76 | ): void; 77 | ( 78 | message: T, 79 | b?: T extends `${string}%${string}` ? SprintfArgument : never, 80 | c?: SprintfArgument, 81 | d?: SprintfArgument, 82 | e?: SprintfArgument, 83 | f?: SprintfArgument, 84 | g?: SprintfArgument, 85 | h?: SprintfArgument, 86 | index?: SprintfArgument, 87 | index_?: SprintfArgument, 88 | ): void; 89 | }; 90 | 91 | type Child = { 92 | (context: TransformMessageFunction>): Logger; 93 | (context: MessageContext): Logger; 94 | }; 95 | 96 | export type Logger = LogMethod & { 97 | adopt: ( 98 | routine: () => T, 99 | context?: MessageContext | TransformMessageFunction, 100 | ) => Promise; 101 | child: Child; 102 | debug: LogMethod; 103 | debugOnce: LogMethod; 104 | error: LogMethod; 105 | errorOnce: LogMethod; 106 | fatal: LogMethod; 107 | fatalOnce: LogMethod; 108 | getContext: () => MessageContext; 109 | info: LogMethod; 110 | infoOnce: LogMethod; 111 | trace: LogMethod; 112 | traceOnce: LogMethod; 113 | warn: LogMethod; 114 | warnOnce: LogMethod; 115 | }; 116 | 117 | export type MessageEventHandler = (message: Message) => void; 118 | 119 | export type LogLevelName = 120 | | 'debug' 121 | | 'error' 122 | | 'fatal' 123 | | 'info' 124 | | 'trace' 125 | | 'warn'; 126 | -------------------------------------------------------------------------------- /src/typings.d.ts: -------------------------------------------------------------------------------- 1 | declare module '*.json' { 2 | export const version: string; 3 | } 4 | -------------------------------------------------------------------------------- /src/utilities/hasOwnProperty.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * A stricter type guard. 3 | * @see https://tsplay.dev/WK8zGw 4 | */ 5 | export const hasOwnProperty = ( 6 | object: X, 7 | property: Y, 8 | ): object is Record & X => { 9 | return Object.prototype.hasOwnProperty.call(object, property); 10 | }; 11 | -------------------------------------------------------------------------------- /src/utilities/isBrowser.ts: -------------------------------------------------------------------------------- 1 | export const isBrowser = () => typeof window !== 'undefined'; 2 | -------------------------------------------------------------------------------- /src/utilities/isTruthy.ts: -------------------------------------------------------------------------------- 1 | export const isTruthy = (value: string) => { 2 | return ['true', 't', 'yes', 'y', 'on', '1'].includes( 3 | value.trim().toLowerCase(), 4 | ); 5 | }; 6 | -------------------------------------------------------------------------------- /src/utilities/stringify.ts: -------------------------------------------------------------------------------- 1 | import { configure } from 'safe-stable-stringify'; 2 | 3 | const safeStringify = configure({ 4 | deterministic: false, 5 | // The reason for the following values is because it is fairly easy 6 | // to accidentally pass astronomically large objects to the logger. 7 | // For context, we were debugging a UI slowdown that was caused by 8 | // unknowingly trying to pass 5MB worth of data to the logger context. 9 | // 10 | // I am starting with hard limits for now to assess the impact of the changes, 11 | // but we may want to make these configurable in the future. 12 | maximumBreadth: 20, 13 | maximumDepth: 10, 14 | strict: false, 15 | }); 16 | 17 | export const stringify = (value: unknown): string => { 18 | try { 19 | return safeStringify(value) ?? ''; 20 | } catch (error) { 21 | // The only time I've seen this happen is when the value was excessively large. 22 | // eslint-disable-next-line no-console 23 | console.error('[roarr] could not serialize value', value); 24 | 25 | throw error; 26 | } 27 | }; 28 | -------------------------------------------------------------------------------- /test/.eslintrc: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "canonical/ava", 3 | "rules": { 4 | "filenames/match-regex": 0, 5 | "id-length": 0 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /test/benchmark.ts: -------------------------------------------------------------------------------- 1 | /* eslint-disable no-console */ 2 | 3 | import { Roarr } from '../src/Roarr'; 4 | import { Suite } from 'benchmark'; 5 | 6 | // eslint-disable-next-line node/no-process-env 7 | if (process.env.ROARR_LOG !== 'true') { 8 | throw new Error('Must run benchmark with ROARR_LOG=true.'); 9 | } 10 | 11 | (() => { 12 | const suite = new Suite('roarr', { 13 | onCycle: (event) => { 14 | console.log(String(event.target)); 15 | }, 16 | onError: (event) => { 17 | console.error(event.target.error); 18 | }, 19 | }); 20 | 21 | suite.add( 22 | 'simple message', 23 | () => { 24 | Roarr.info('foo'); 25 | }, 26 | { 27 | setup: () => { 28 | globalThis.ROARR.write = () => { 29 | return undefined; 30 | }; 31 | }, 32 | }, 33 | ); 34 | 35 | suite.add( 36 | 'message with printf', 37 | () => { 38 | Roarr.info('foo %s %s %s', 'bar', 'baz', 'qux'); 39 | }, 40 | { 41 | setup: () => { 42 | globalThis.ROARR.write = () => { 43 | return undefined; 44 | }; 45 | }, 46 | }, 47 | ); 48 | 49 | suite.add( 50 | 'message with context', 51 | () => { 52 | Roarr.info( 53 | { 54 | foo: 'bar', 55 | }, 56 | 'foo', 57 | ); 58 | }, 59 | { 60 | setup: () => { 61 | globalThis.ROARR.write = () => { 62 | return undefined; 63 | }; 64 | }, 65 | }, 66 | ); 67 | 68 | let largeContext; 69 | 70 | suite.add( 71 | 'message with large context', 72 | () => { 73 | Roarr.info(largeContext, 'foo'); 74 | }, 75 | { 76 | setup: () => { 77 | globalThis.ROARR.write = () => { 78 | return undefined; 79 | }; 80 | 81 | largeContext = {}; 82 | 83 | let size = 10_000; 84 | 85 | while (size--) { 86 | largeContext[Math.random()] = Math.random(); 87 | } 88 | }, 89 | }, 90 | ); 91 | 92 | let largeContextWithCircularReference; 93 | 94 | suite.add( 95 | 'message with large context', 96 | () => { 97 | Roarr.info(largeContextWithCircularReference, 'foo'); 98 | }, 99 | { 100 | setup: () => { 101 | globalThis.ROARR.write = () => { 102 | return undefined; 103 | }; 104 | 105 | largeContextWithCircularReference = {}; 106 | 107 | let size = 10_000; 108 | 109 | while (size--) { 110 | largeContextWithCircularReference[Math.random()] = Math.random(); 111 | } 112 | 113 | const foo: any = {}; 114 | 115 | foo.foo = foo; 116 | 117 | largeContextWithCircularReference.foo = foo; 118 | }, 119 | }, 120 | ); 121 | 122 | suite.run(); 123 | })(); 124 | -------------------------------------------------------------------------------- /test/helpers/createIntegrationTest.ts: -------------------------------------------------------------------------------- 1 | /* eslint-disable node/no-process-env */ 2 | /* eslint-disable ava/use-test */ 3 | 4 | import anyTest, { type TestFn } from 'ava'; 5 | import * as sinon from 'sinon'; 6 | 7 | export const createIntegrationTest = ({ 8 | writeLogs, 9 | }: { 10 | writeLogs: boolean; 11 | }) => { 12 | const test = anyTest as TestFn<{ 13 | ROARR: any; 14 | Roarr: any; 15 | write: sinon.SinonStubbedMember<(message: string) => void>; 16 | }>; 17 | 18 | test.beforeEach(async (t) => { 19 | process.env.ROARR_LOG = writeLogs ? '1' : '0'; 20 | 21 | // This import is affected by the `process.env.ROARR_LOG` value. 22 | const { Roarr, ROARR } = await import('../../src/Roarr'); 23 | 24 | sinon.restore(); 25 | 26 | const write = sinon.stub(ROARR, 'write'); 27 | 28 | // eslint-disable-next-line @typescript-eslint/no-empty-function 29 | write.callsFake(() => {}); 30 | 31 | t.context = { 32 | Roarr, 33 | ROARR, 34 | write, 35 | }; 36 | }); 37 | 38 | return test; 39 | }; 40 | -------------------------------------------------------------------------------- /test/roarr/createRoarrInitialGlobalState.ts: -------------------------------------------------------------------------------- 1 | import { ROARR_VERSION } from '../../src/config'; 2 | import { createRoarrInitialGlobalState } from '../../src/factories/createRoarrInitialGlobalState'; 3 | import test from 'ava'; 4 | 5 | test('creates new state', (t) => { 6 | const state = createRoarrInitialGlobalState({}); 7 | 8 | t.like(state, { 9 | sequence: 0, 10 | versions: [ROARR_VERSION], 11 | }); 12 | }); 13 | 14 | test('respects existing sequence', (t) => { 15 | const state = createRoarrInitialGlobalState({ 16 | sequence: 1, 17 | }); 18 | 19 | t.like(state, { 20 | sequence: 1, 21 | versions: [ROARR_VERSION], 22 | }); 23 | }); 24 | 25 | test('appends the latest version', (t) => { 26 | const state = createRoarrInitialGlobalState({ 27 | versions: ['0.0.1'], 28 | }); 29 | 30 | t.like(state, { 31 | sequence: 0, 32 | versions: ['0.0.1', ROARR_VERSION], 33 | }); 34 | }); 35 | 36 | test('sets "write" method if current is the first version', (t) => { 37 | const state = createRoarrInitialGlobalState({}); 38 | 39 | t.is(typeof state.write, 'function'); 40 | }); 41 | 42 | test('overrides "write" method if current is the latest version', (t) => { 43 | const state = createRoarrInitialGlobalState({ 44 | versions: ['0.0.1'], 45 | write: 'foo', 46 | }); 47 | 48 | t.is(typeof state.write, 'function'); 49 | }); 50 | 51 | test('does not override "write" method if current is not the latest version', (t) => { 52 | // eslint-disable-next-line @typescript-eslint/no-empty-function 53 | const write = () => {}; 54 | 55 | const state = createRoarrInitialGlobalState({ 56 | versions: ['100.0.0'], 57 | write, 58 | }); 59 | 60 | t.is(state.write, write); 61 | }); 62 | -------------------------------------------------------------------------------- /test/roarr/integrations/README.md: -------------------------------------------------------------------------------- 1 | # Integration Tests 2 | 3 | Tests in `./integrations` simulate `ROARR_LOG=0` (`noLog.ts`) and `ROARR_LOG=1` (`log.ts`) states. -------------------------------------------------------------------------------- /test/roarr/integrations/asyncLocalScope.ts: -------------------------------------------------------------------------------- 1 | /* eslint-disable max-nested-callbacks */ 2 | /* eslint-disable ava/use-test */ 3 | 4 | import { createLogger } from '../../../src/factories/createLogger'; 5 | import { createRoarrInitialGlobalState } from '../../../src/factories/createRoarrInitialGlobalState'; 6 | import { type Logger, type Message } from '../../../src/types'; 7 | import { createIntegrationTest } from '../../helpers/createIntegrationTest'; 8 | import { setTimeout } from 'node:timers/promises'; 9 | 10 | const test = createIntegrationTest({ 11 | writeLogs: true, 12 | }); 13 | 14 | const time = -1; 15 | const version = '2.0.0'; 16 | 17 | test.beforeEach(() => { 18 | globalThis.ROARR = null; 19 | 20 | globalThis.ROARR = createRoarrInitialGlobalState({}); 21 | }); 22 | 23 | const createLoggerWithHistory = (): Logger & { messages: Message[] } => { 24 | const messages: Message[] = []; 25 | 26 | const log = createLogger((message) => { 27 | messages.push({ 28 | ...message, 29 | time, 30 | }); 31 | }) as any; 32 | 33 | log.messages = messages; 34 | 35 | return log; 36 | }; 37 | 38 | test.serial('warns if async_hooks are unavailable', async (t) => { 39 | const firstLog = createLoggerWithHistory(); 40 | 41 | const log = firstLog.child({ 42 | // Ensure that we are not adding context to the internal warning. 43 | foo: 'bar', 44 | }); 45 | 46 | globalThis.ROARR.asyncLocalStorage = null; 47 | 48 | await log.adopt( 49 | // eslint-disable-next-line @typescript-eslint/no-empty-function 50 | () => {}, 51 | ); 52 | 53 | // Ensure that we log only once. 54 | await log.adopt( 55 | // eslint-disable-next-line @typescript-eslint/no-empty-function 56 | () => {}, 57 | ); 58 | 59 | t.deepEqual(firstLog.messages, [ 60 | { 61 | context: { 62 | logLevel: 40, 63 | package: 'roarr', 64 | }, 65 | message: 66 | 'async_hooks are unavailable; Roarr.adopt will not function as expected', 67 | sequence: '0', 68 | time, 69 | version, 70 | }, 71 | ]); 72 | }); 73 | 74 | test.serial('inherits context from async local scope', async (t) => { 75 | t.plan(1); 76 | 77 | const log = createLoggerWithHistory(); 78 | 79 | await log.adopt( 80 | () => { 81 | t.deepEqual(log.getContext(), { 82 | bar: 'bar', 83 | }); 84 | 85 | log('foo'); 86 | }, 87 | { 88 | bar: 'bar', 89 | }, 90 | ); 91 | }); 92 | 93 | test.serial('inherits context from parent async local scope', async (t) => { 94 | t.plan(2); 95 | 96 | const log = createLoggerWithHistory(); 97 | 98 | await log.adopt( 99 | async () => { 100 | t.deepEqual( 101 | log.getContext(), 102 | { 103 | bar: 'bar 0', 104 | }, 105 | 'first-level', 106 | ); 107 | 108 | log('foo 0'); 109 | 110 | await log.adopt( 111 | () => { 112 | t.deepEqual( 113 | log.getContext(), 114 | { 115 | bar: 'bar 0', 116 | baz: 'baz 1', 117 | }, 118 | 'second-level', 119 | ); 120 | 121 | log('foo 1'); 122 | }, 123 | { 124 | baz: 'baz 1', 125 | }, 126 | ); 127 | }, 128 | { 129 | bar: 'bar 0', 130 | }, 131 | ); 132 | }); 133 | 134 | test.serial( 135 | 'inherits message transformer from async local scope', 136 | async (t) => { 137 | const log = createLoggerWithHistory(); 138 | 139 | await log.adopt( 140 | () => { 141 | log('foo'); 142 | }, 143 | (message) => { 144 | return { 145 | ...message, 146 | context: { 147 | bar: 'bar', 148 | ...message.context, 149 | }, 150 | }; 151 | }, 152 | ); 153 | 154 | t.deepEqual(log.messages, [ 155 | { 156 | context: { 157 | bar: 'bar', 158 | }, 159 | message: 'foo', 160 | sequence: '0.0', 161 | time, 162 | version, 163 | }, 164 | ]); 165 | }, 166 | ); 167 | 168 | test.serial( 169 | 'inherits message transformer from parent async local scope', 170 | async (t) => { 171 | const log = createLoggerWithHistory(); 172 | 173 | await log.adopt( 174 | async () => { 175 | log('foo 0'); 176 | 177 | await log.adopt( 178 | () => { 179 | log('foo 1'); 180 | }, 181 | (message) => { 182 | return { 183 | ...message, 184 | context: { 185 | baz: 'baz', 186 | ...message.context, 187 | }, 188 | }; 189 | }, 190 | ); 191 | }, 192 | (message) => { 193 | return { 194 | ...message, 195 | context: { 196 | bar: 'bar', 197 | ...message.context, 198 | }, 199 | }; 200 | }, 201 | ); 202 | 203 | t.deepEqual(log.messages, [ 204 | { 205 | context: { 206 | bar: 'bar', 207 | }, 208 | message: 'foo 0', 209 | sequence: '0.0', 210 | time, 211 | version, 212 | }, 213 | { 214 | context: { 215 | bar: 'bar', 216 | baz: 'baz', 217 | }, 218 | message: 'foo 1', 219 | sequence: '0.1.0', 220 | time, 221 | version, 222 | }, 223 | ]); 224 | }, 225 | ); 226 | 227 | test.serial('top-level adopt increments global sequence', (t) => { 228 | const log = createLoggerWithHistory(); 229 | 230 | void log.adopt(() => { 231 | log('foo'); 232 | }); 233 | 234 | void log.adopt(() => { 235 | log('bar'); 236 | }); 237 | 238 | t.deepEqual(log.messages, [ 239 | { 240 | context: {}, 241 | message: 'foo', 242 | sequence: '0.0', 243 | time, 244 | version, 245 | }, 246 | { 247 | context: {}, 248 | message: 'bar', 249 | sequence: '1.0', 250 | time, 251 | version, 252 | }, 253 | ]); 254 | }); 255 | 256 | test.serial('top-level adopt increments global sequence (async)', async (t) => { 257 | const log = createLoggerWithHistory(); 258 | 259 | await log.adopt(async () => { 260 | log('foo'); 261 | }); 262 | 263 | await log.adopt(async () => { 264 | log('bar'); 265 | }); 266 | 267 | t.deepEqual(log.messages, [ 268 | { 269 | context: {}, 270 | message: 'foo', 271 | sequence: '0.0', 272 | time, 273 | version, 274 | }, 275 | { 276 | context: {}, 277 | message: 'bar', 278 | sequence: '1.0', 279 | time, 280 | version, 281 | }, 282 | ]); 283 | }); 284 | 285 | test.serial('logs within adopt increment local sequence', (t) => { 286 | const log = createLoggerWithHistory(); 287 | 288 | void log.adopt(() => { 289 | log('foo'); 290 | log('bar'); 291 | }); 292 | 293 | void log.adopt(() => { 294 | log('baz'); 295 | log('qux'); 296 | }); 297 | 298 | t.deepEqual(log.messages, [ 299 | { 300 | context: {}, 301 | message: 'foo', 302 | sequence: '0.0', 303 | time, 304 | version, 305 | }, 306 | { 307 | context: {}, 308 | message: 'bar', 309 | sequence: '0.1', 310 | time, 311 | version, 312 | }, 313 | { 314 | context: {}, 315 | message: 'baz', 316 | sequence: '1.0', 317 | time, 318 | version, 319 | }, 320 | { 321 | context: {}, 322 | message: 'qux', 323 | sequence: '1.1', 324 | time, 325 | version, 326 | }, 327 | ]); 328 | }); 329 | 330 | test.serial('logs within adopt increment local sequence (async)', async (t) => { 331 | const log = createLoggerWithHistory(); 332 | 333 | await log.adopt(async () => { 334 | log('foo'); 335 | log('bar'); 336 | }); 337 | 338 | await log.adopt(async () => { 339 | log('baz'); 340 | log('qux'); 341 | }); 342 | 343 | t.deepEqual(log.messages, [ 344 | { 345 | context: {}, 346 | message: 'foo', 347 | sequence: '0.0', 348 | time, 349 | version, 350 | }, 351 | { 352 | context: {}, 353 | message: 'bar', 354 | sequence: '0.1', 355 | time, 356 | version, 357 | }, 358 | { 359 | context: {}, 360 | message: 'baz', 361 | sequence: '1.0', 362 | time, 363 | version, 364 | }, 365 | { 366 | context: {}, 367 | message: 'qux', 368 | sequence: '1.1', 369 | time, 370 | version, 371 | }, 372 | ]); 373 | }); 374 | 375 | test.serial('nested adopt increment local sequence', (t) => { 376 | const log = createLoggerWithHistory(); 377 | 378 | void log.adopt(() => { 379 | log('foo'); 380 | 381 | void log.adopt(() => { 382 | log('bar'); 383 | }); 384 | }); 385 | 386 | t.deepEqual(log.messages, [ 387 | { 388 | context: {}, 389 | message: 'foo', 390 | sequence: '0.0', 391 | time, 392 | version, 393 | }, 394 | { 395 | context: {}, 396 | message: 'bar', 397 | sequence: '0.1.0', 398 | time, 399 | version, 400 | }, 401 | ]); 402 | }); 403 | 404 | test.serial('nested adopt increment local sequence (async)', async (t) => { 405 | const log = createLoggerWithHistory(); 406 | 407 | await log.adopt(async () => { 408 | log('foo'); 409 | 410 | await log.adopt(async () => { 411 | log('bar'); 412 | }); 413 | }); 414 | 415 | t.deepEqual(log.messages, [ 416 | { 417 | context: {}, 418 | message: 'foo', 419 | sequence: '0.0', 420 | time, 421 | version, 422 | }, 423 | { 424 | context: {}, 425 | message: 'bar', 426 | sequence: '0.1.0', 427 | time, 428 | version, 429 | }, 430 | ]); 431 | }); 432 | 433 | test.serial('adopted scope maintains reference to local sequence', (t) => { 434 | const log = createLoggerWithHistory(); 435 | 436 | void log.adopt(() => { 437 | log('foo'); 438 | 439 | void log.adopt(() => { 440 | log('bar 0'); 441 | log('bar 1'); 442 | log('bar 2'); 443 | }); 444 | 445 | log('baz'); 446 | }); 447 | 448 | t.deepEqual(log.messages, [ 449 | { 450 | context: {}, 451 | message: 'foo', 452 | sequence: '0.0', 453 | time, 454 | version, 455 | }, 456 | { 457 | context: {}, 458 | message: 'bar 0', 459 | sequence: '0.1.0', 460 | time, 461 | version, 462 | }, 463 | { 464 | context: {}, 465 | message: 'bar 1', 466 | sequence: '0.1.1', 467 | time, 468 | version, 469 | }, 470 | { 471 | context: {}, 472 | message: 'bar 2', 473 | sequence: '0.1.2', 474 | time, 475 | version, 476 | }, 477 | { 478 | context: {}, 479 | message: 'baz', 480 | sequence: '0.2', 481 | time, 482 | version, 483 | }, 484 | ]); 485 | }); 486 | 487 | test.serial( 488 | 'maintains correct local reference in an async scope', 489 | async (t) => { 490 | const log = createLoggerWithHistory(); 491 | 492 | void log.adopt(() => { 493 | log('foo 0'); 494 | void log.adopt(() => { 495 | log('bar 0'); 496 | void log.adopt(() => { 497 | log('baz 0'); 498 | // eslint-disable-next-line promise/prefer-await-to-then 499 | setTimeout(10).then(() => { 500 | log('baz 1'); 501 | }); 502 | }); 503 | log('bar 1'); 504 | }); 505 | }); 506 | 507 | await setTimeout(20); 508 | 509 | t.deepEqual(log.messages, [ 510 | { 511 | context: {}, 512 | message: 'foo 0', 513 | sequence: '0.0', 514 | time: -1, 515 | version: '2.0.0', 516 | }, 517 | { 518 | context: {}, 519 | message: 'bar 0', 520 | sequence: '0.1.0', 521 | time: -1, 522 | version: '2.0.0', 523 | }, 524 | { 525 | context: {}, 526 | message: 'baz 0', 527 | sequence: '0.1.1.0', 528 | time: -1, 529 | version: '2.0.0', 530 | }, 531 | { 532 | context: {}, 533 | message: 'bar 1', 534 | sequence: '0.1.2', 535 | time: -1, 536 | version: '2.0.0', 537 | }, 538 | { 539 | context: {}, 540 | message: 'baz 1', 541 | sequence: '0.1.1.1', 542 | time: -1, 543 | version: '2.0.0', 544 | }, 545 | ]); 546 | }, 547 | ); 548 | -------------------------------------------------------------------------------- /test/roarr/integrations/roarr.ts: -------------------------------------------------------------------------------- 1 | import { createLogger } from '../../../src/factories/createLogger'; 2 | import { createRoarrInitialGlobalState } from '../../../src/factories/createRoarrInitialGlobalState'; 3 | import { type Logger, type Message } from '../../../src/types'; 4 | import { createIntegrationTest } from '../../helpers/createIntegrationTest'; 5 | 6 | const test = createIntegrationTest({ 7 | writeLogs: true, 8 | }); 9 | 10 | const time = -1; 11 | const version = '2.0.0'; 12 | 13 | test.beforeEach(() => { 14 | globalThis.ROARR = createRoarrInitialGlobalState({}); 15 | }); 16 | 17 | const createLoggerWithHistory = (): Logger & { messages: Message[] } => { 18 | const messages: any = []; 19 | 20 | const log: any = createLogger((message) => { 21 | messages.push({ 22 | ...message, 23 | time, 24 | }); 25 | }); 26 | 27 | log.messages = messages; 28 | 29 | return log; 30 | }; 31 | 32 | test('creates a simple message', (t) => { 33 | const log = createLoggerWithHistory(); 34 | 35 | log('foo'); 36 | 37 | t.deepEqual(log.messages, [ 38 | { 39 | context: {}, 40 | message: 'foo', 41 | sequence: '0', 42 | time, 43 | version, 44 | }, 45 | ]); 46 | }); 47 | 48 | test('logs an empty message when first parameter is an object and the second parameter is undefined', (t) => { 49 | const log = createLoggerWithHistory(); 50 | 51 | // @ts-expect-error Invalid invocation 52 | log({}); 53 | 54 | t.deepEqual(log.messages, [ 55 | { 56 | context: {}, 57 | message: '', 58 | sequence: '0', 59 | time, 60 | version, 61 | }, 62 | ]); 63 | }); 64 | 65 | test('throws in case of invalid invocation', (t) => { 66 | const log = createLoggerWithHistory(); 67 | 68 | t.throws( 69 | () => { 70 | // @ts-expect-error Invalid invocation 71 | log({}, {}); 72 | }, 73 | { 74 | message: 'Message must be a string. Received object.', 75 | }, 76 | ); 77 | }); 78 | 79 | test('throws in case of invalid invocation (2)', (t) => { 80 | const log = createLoggerWithHistory(); 81 | 82 | t.throws(() => { 83 | // @ts-expect-error Invalid invocation 84 | log('test', 123); 85 | }); 86 | }); 87 | 88 | test('formats message using sprintf', (t) => { 89 | const log = createLoggerWithHistory(); 90 | 91 | log('foo %s', 'bar'); 92 | 93 | t.deepEqual(log.messages, [ 94 | { 95 | context: {}, 96 | message: 'foo bar', 97 | sequence: '0', 98 | time, 99 | version, 100 | }, 101 | ]); 102 | }); 103 | 104 | test('formats message using sprintf (multiple variables)', (t) => { 105 | const log = createLoggerWithHistory(); 106 | 107 | log('foo %s %s %s', 'bar', 'baz', 'qux'); 108 | 109 | t.deepEqual(log.messages, [ 110 | { 111 | context: {}, 112 | message: 'foo bar baz qux', 113 | sequence: '0', 114 | time, 115 | version, 116 | }, 117 | ]); 118 | }); 119 | 120 | test('formats message using sprintf (digit variables)', (t) => { 121 | const log = createLoggerWithHistory(); 122 | 123 | log('foo %d %d %d', '1', '2', '3'); 124 | 125 | t.deepEqual(log.messages, [ 126 | { 127 | context: {}, 128 | message: 'foo 1 2 3', 129 | sequence: '0', 130 | time, 131 | version, 132 | }, 133 | ]); 134 | }); 135 | 136 | test('creates message with a context', (t) => { 137 | const log = createLoggerWithHistory(); 138 | 139 | log( 140 | { 141 | foo: 'bar', 142 | }, 143 | 'baz', 144 | ); 145 | 146 | t.deepEqual(log.messages, [ 147 | { 148 | context: { 149 | foo: 'bar', 150 | }, 151 | message: 'baz', 152 | sequence: '0', 153 | time, 154 | version, 155 | }, 156 | ]); 157 | }); 158 | 159 | test('formats message using sprintf (with context)', (t) => { 160 | const log = createLoggerWithHistory(); 161 | 162 | log( 163 | { 164 | foo: 'bar', 165 | }, 166 | 'baz %s', 167 | 'qux', 168 | ); 169 | 170 | t.deepEqual(log.messages, [ 171 | { 172 | context: { 173 | foo: 'bar', 174 | }, 175 | message: 'baz qux', 176 | sequence: '0', 177 | time, 178 | version, 179 | }, 180 | ]); 181 | }); 182 | 183 | test('creates logger with a context', (t) => { 184 | const log = createLoggerWithHistory(); 185 | 186 | log.child({ 187 | foo: 'bar', 188 | })('baz'); 189 | 190 | t.deepEqual(log.messages, [ 191 | { 192 | context: { 193 | foo: 'bar', 194 | }, 195 | message: 'baz', 196 | sequence: '0', 197 | time, 198 | version, 199 | }, 200 | ]); 201 | }); 202 | 203 | test('prepends context to the message context', (t) => { 204 | const log = createLoggerWithHistory(); 205 | 206 | log.child({ 207 | foo: 'bar', 208 | })( 209 | { 210 | baz: 'qux', 211 | }, 212 | 'quux', 213 | ); 214 | 215 | t.deepEqual(log.messages, [ 216 | { 217 | context: { 218 | baz: 'qux', 219 | foo: 'bar', 220 | }, 221 | message: 'quux', 222 | sequence: '0', 223 | time, 224 | version, 225 | }, 226 | ]); 227 | }); 228 | 229 | test('prepends context to the message context (is overridden)', (t) => { 230 | const log = createLoggerWithHistory(); 231 | 232 | log.child({ 233 | foo: 'bar 0', 234 | })( 235 | { 236 | foo: 'bar 1', 237 | }, 238 | 'quux', 239 | ); 240 | 241 | t.deepEqual(log.messages, [ 242 | { 243 | context: { 244 | foo: 'bar 1', 245 | }, 246 | message: 'quux', 247 | sequence: '0', 248 | time, 249 | version, 250 | }, 251 | ]); 252 | }); 253 | 254 | test('appends context to the previous child context', (t) => { 255 | const log = createLoggerWithHistory(); 256 | 257 | log 258 | .child({ 259 | foo: 'bar', 260 | }) 261 | .child({ 262 | baz: 'qux', 263 | })('quux'); 264 | 265 | t.deepEqual(log.messages, [ 266 | { 267 | context: { 268 | baz: 'qux', 269 | foo: 'bar', 270 | }, 271 | message: 'quux', 272 | sequence: '0', 273 | time, 274 | version, 275 | }, 276 | ]); 277 | }); 278 | 279 | test('appends context to the previous child context (overrides)', (t) => { 280 | const log = createLoggerWithHistory(); 281 | 282 | log 283 | .child({ 284 | foo: 'bar 0', 285 | }) 286 | .child({ 287 | foo: 'bar 1', 288 | })('qux'); 289 | 290 | t.deepEqual(log.messages, [ 291 | { 292 | context: { 293 | foo: 'bar 1', 294 | }, 295 | message: 'qux', 296 | sequence: '0', 297 | time, 298 | version, 299 | }, 300 | ]); 301 | }); 302 | 303 | test('translates child message', (t) => { 304 | const log = createLoggerWithHistory(); 305 | 306 | log.child((message) => { 307 | return { 308 | ...message, 309 | message: message.message + 'bar', 310 | }; 311 | })('foo'); 312 | 313 | t.deepEqual(log.messages, [ 314 | { 315 | context: {}, 316 | message: 'foobar', 317 | sequence: '0', 318 | time, 319 | version, 320 | }, 321 | ]); 322 | }); 323 | 324 | test('serializes context using a transformer', (t) => { 325 | const log = createLoggerWithHistory(); 326 | 327 | const log1 = log.child<{ error1: Error }>((message) => { 328 | if (!message.context.error1) { 329 | return message; 330 | } 331 | 332 | return { 333 | ...message, 334 | context: { 335 | ...message.context, 336 | error1: 'log1 error', 337 | }, 338 | }; 339 | }); 340 | 341 | log1.error( 342 | { 343 | error1: new Error('foo'), 344 | }, 345 | 'log1', 346 | ); 347 | 348 | // @ts-expect-error error2 is not allowed 349 | log1.error( 350 | { 351 | error2: new Error('foo'), 352 | }, 353 | 'log1', 354 | ); 355 | 356 | const log2 = log1.child<{ error2: Error }>((message) => { 357 | return { 358 | ...message, 359 | context: { 360 | ...message.context, 361 | error2: 'log2 error', 362 | }, 363 | }; 364 | }); 365 | 366 | log2.error( 367 | { 368 | error1: new Error('foo'), 369 | error2: new Error('foo'), 370 | }, 371 | 'log2', 372 | ); 373 | 374 | // @ts-expect-error error2 is not allowed 375 | log2.error( 376 | { 377 | error3: new Error('foo'), 378 | }, 379 | 'log2', 380 | ); 381 | 382 | t.like(log.messages[0], { 383 | context: { 384 | error1: 'log1 error', 385 | }, 386 | message: 'log1', 387 | }); 388 | 389 | t.like(log.messages[1], { 390 | context: { 391 | error2: new Error('foo'), 392 | }, 393 | message: 'log1', 394 | }); 395 | 396 | t.like(log.messages[2], { 397 | context: { 398 | error1: 'log1 error', 399 | error2: 'log2 error', 400 | }, 401 | message: 'log2', 402 | }); 403 | 404 | t.like(log.messages[3], { 405 | context: { 406 | error3: new Error('foo'), 407 | }, 408 | message: 'log2', 409 | }); 410 | }); 411 | 412 | test('does not allow to extend context without a transformer', (t) => { 413 | const log = createLoggerWithHistory(); 414 | 415 | // @ts-expect-error cannot type child without a translator 416 | log.child<{ foo: string }>({}); 417 | 418 | log.child({}); 419 | 420 | t.true(true); 421 | }); 422 | 423 | test('throws an error if child does not return an object', (t) => { 424 | const log = createLoggerWithHistory(); 425 | 426 | t.throws( 427 | () => { 428 | log 429 | 430 | // @ts-expect-error result must be an object 431 | .child(() => { 432 | return ''; 433 | })('foo'); 434 | }, 435 | { 436 | message: 'Message transform function must return a message object.', 437 | }, 438 | ); 439 | }); 440 | 441 | test('convenience methods trace, debug, info, warn, error and fatal prepend a logLevel property', (t) => { 442 | const log = createLoggerWithHistory(); 443 | 444 | log.trace('foo 0'); 445 | log.debug('foo 1'); 446 | log.info('foo 2'); 447 | log.warn('foo 3'); 448 | log.error('foo 4'); 449 | log.fatal('foo 5'); 450 | 451 | t.deepEqual(log.messages, [ 452 | { 453 | context: { 454 | logLevel: 10, 455 | }, 456 | message: 'foo 0', 457 | sequence: '0', 458 | time, 459 | version, 460 | }, 461 | { 462 | context: { 463 | logLevel: 20, 464 | }, 465 | message: 'foo 1', 466 | sequence: '1', 467 | time, 468 | version, 469 | }, 470 | { 471 | context: { 472 | logLevel: 30, 473 | }, 474 | message: 'foo 2', 475 | sequence: '2', 476 | time, 477 | version, 478 | }, 479 | { 480 | context: { 481 | logLevel: 40, 482 | }, 483 | message: 'foo 3', 484 | sequence: '3', 485 | time, 486 | version, 487 | }, 488 | { 489 | context: { 490 | logLevel: 50, 491 | }, 492 | message: 'foo 4', 493 | sequence: '4', 494 | time, 495 | version, 496 | }, 497 | { 498 | context: { 499 | logLevel: 60, 500 | }, 501 | message: 'foo 5', 502 | sequence: '5', 503 | time, 504 | version, 505 | }, 506 | ]); 507 | }); 508 | 509 | test('*Once methods log only once', (t) => { 510 | const log = createLoggerWithHistory(); 511 | 512 | log.traceOnce('foo'); 513 | log.traceOnce('foo'); 514 | 515 | t.deepEqual(log.messages, [ 516 | { 517 | context: { 518 | logLevel: 10, 519 | }, 520 | message: 'foo', 521 | sequence: '0', 522 | time, 523 | version, 524 | }, 525 | ]); 526 | }); 527 | 528 | test('does not produce an error when message contains % without an associated parameter', (t) => { 529 | const log = createLoggerWithHistory(); 530 | log.trace( 531 | 'http://commons.wikimedia.org/wiki/Special:FilePath/Cucumis%20anguria.JPG', 532 | ); 533 | t.deepEqual(log.messages, [ 534 | { 535 | context: { 536 | logLevel: 10, 537 | }, 538 | message: 539 | 'http://commons.wikimedia.org/wiki/Special:FilePath/Cucumis%20anguria.JPG', 540 | sequence: '0', 541 | time, 542 | version, 543 | }, 544 | ]); 545 | }); 546 | -------------------------------------------------------------------------------- /test/roarr/integrations/roarrWriteNotTriggeredWhenRoarrLogIsDisabled.ts: -------------------------------------------------------------------------------- 1 | import { createIntegrationTest } from '../../helpers/createIntegrationTest'; 2 | 3 | const test = createIntegrationTest({ 4 | writeLogs: false, 5 | }); 6 | 7 | test('ROARR.write is not triggered when ROARR_LOG=0', (t) => { 8 | const { Roarr, write } = t.context; 9 | 10 | Roarr.info('foo'); 11 | 12 | t.is(write.callCount, 0); 13 | }); 14 | -------------------------------------------------------------------------------- /test/roarr/integrations/roarrWriteOverridesMessageHandler.ts: -------------------------------------------------------------------------------- 1 | import { createIntegrationTest } from '../../helpers/createIntegrationTest'; 2 | 3 | const test = createIntegrationTest({ 4 | writeLogs: true, 5 | }); 6 | 7 | test('ROARR.write overrides message handler', (t) => { 8 | const { Roarr, write } = t.context; 9 | 10 | Roarr.info('foo'); 11 | 12 | t.is(write.callCount, 1); 13 | t.is(write.firstCall.args.length, 1); 14 | 15 | t.regex( 16 | write.firstCall.args[0], 17 | /\{"context":\{"logLevel":30\},"message":"foo","sequence":"0","time":\d+,"version":"\d\.\d\.\d"\}/u, 18 | ); 19 | }); 20 | -------------------------------------------------------------------------------- /test/roarr/integrations/roarrWriteUpdatesSequence.ts: -------------------------------------------------------------------------------- 1 | import { createIntegrationTest } from '../../helpers/createIntegrationTest'; 2 | 3 | const test = createIntegrationTest({ 4 | writeLogs: true, 5 | }); 6 | 7 | test('updates sequence', (t) => { 8 | const { Roarr, write } = t.context; 9 | 10 | const log = Roarr; 11 | 12 | log.adopt(() => { 13 | log.adopt(() => { 14 | log.info('foo'); 15 | }); 16 | }); 17 | 18 | t.is(write.callCount, 1); 19 | t.is(write.firstCall.args.length, 1); 20 | 21 | t.regex( 22 | write.firstCall.args[0], 23 | /\{"context":\{"logLevel":30\},"message":"foo","sequence":"0.0.0","time":\d+,"version":"\d\.\d\.\d"\}/u, 24 | ); 25 | }); 26 | -------------------------------------------------------------------------------- /test/roarr/integrations/serializeMessage.ts: -------------------------------------------------------------------------------- 1 | import { createIntegrationTest } from '../../helpers/createIntegrationTest'; 2 | 3 | const test = createIntegrationTest({ 4 | writeLogs: true, 5 | }); 6 | 7 | test('serialize message', (t) => { 8 | const { Roarr, ROARR, write } = t.context; 9 | 10 | const log = Roarr; 11 | 12 | ROARR.serializeMessage = (message) => { 13 | return JSON.stringify({ 14 | message: message.message, 15 | }); 16 | }; 17 | 18 | log.info('test'); 19 | 20 | t.is(write.firstCall.args[0], '{"message":"test"}'); 21 | }); 22 | -------------------------------------------------------------------------------- /test/roarr/utilities/stringify.ts: -------------------------------------------------------------------------------- 1 | import { stringify } from '../../../src/utilities/stringify'; 2 | import test from 'ava'; 3 | 4 | test('stringifies key=value (string)', (t) => { 5 | t.is( 6 | stringify({ 7 | foo: 'bar', 8 | }), 9 | '{"foo":"bar"}', 10 | ); 11 | }); 12 | 13 | test('stringifies key=value (number)', (t) => { 14 | t.is( 15 | stringify({ 16 | foo: 123, 17 | }), 18 | '{"foo":123}', 19 | ); 20 | }); 21 | 22 | test('stringifies key=value (function)', (t) => { 23 | t.is( 24 | stringify({ 25 | foo: () => {}, 26 | }), 27 | '{}', 28 | ); 29 | }); 30 | 31 | test('stringifies key=value (undefined)', (t) => { 32 | t.is( 33 | stringify({ 34 | foo: undefined, 35 | }), 36 | '{}', 37 | ); 38 | }); 39 | 40 | test('stringifies key=value (null)', (t) => { 41 | t.is( 42 | stringify({ 43 | foo: null, 44 | }), 45 | '{"foo":null}', 46 | ); 47 | }); 48 | 49 | test('stringifies key=value (Symbol)', (t) => { 50 | t.is( 51 | stringify({ 52 | foo: Symbol('bar'), 53 | }), 54 | '{}', 55 | ); 56 | }); 57 | 58 | test('stringifies key=value (circular)', (t) => { 59 | const foo = {}; 60 | 61 | foo['foo'] = foo; 62 | 63 | t.is(stringify(foo), '{"foo":"[Circular]"}'); 64 | }); 65 | 66 | test('overlapping log members are truncated', (t) => { 67 | t.is( 68 | stringify({ 69 | a0: 'a0', 70 | a1: 'a1', 71 | a2: 'a2', 72 | a3: 'a3', 73 | a4: 'a4', 74 | a5: 'a5', 75 | a6: 'a6', 76 | a7: 'a7', 77 | a8: 'a8', 78 | a9: 'a9', 79 | a10: 'a10', 80 | a11: 'a11', 81 | a12: 'a12', 82 | a13: 'a13', 83 | a14: 'a14', 84 | a15: 'a15', 85 | a16: 'a16', 86 | a17: 'a17', 87 | a18: 'a18', 88 | a19: 'a19', 89 | a20: 'a20', 90 | }), 91 | '{"a0":"a0","a1":"a1","a2":"a2","a3":"a3","a4":"a4","a5":"a5","a6":"a6","a7":"a7","a8":"a8","a9":"a9","a10":"a10","a11":"a11","a12":"a12","a13":"a13","a14":"a14","a15":"a15","a16":"a16","a17":"a17","a18":"a18","a19":"a19","...":"1 item not stringified"}', 92 | ); 93 | }); 94 | -------------------------------------------------------------------------------- /tsconfig.build.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "declaration": true, 4 | "declarationMap": true, 5 | "noEmit": false 6 | }, 7 | "extends": "./tsconfig.json", 8 | "include": [ 9 | "src" 10 | ] 11 | } 12 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "allowSyntheticDefaultImports": true, 4 | "esModuleInterop": true, 5 | "forceConsistentCasingInFileNames": true, 6 | "module": "commonjs", 7 | "moduleResolution": "node", 8 | "noEmit": true, 9 | "noImplicitAny": false, 10 | "noImplicitReturns": true, 11 | "noUnusedLocals": true, 12 | "noUnusedParameters": false, 13 | "outDir": "dist", 14 | "skipLibCheck": true, 15 | "sourceMap": true, 16 | "strict": true, 17 | "target": "es2018" 18 | }, 19 | "include": [ 20 | "src", 21 | "test" 22 | ] 23 | } 24 | --------------------------------------------------------------------------------