{"id":16485865,"url":"https://github.com/zamotany/cli-tag-logger","last_synced_at":"2025-03-21T07:31:06.837Z","repository":{"id":36465934,"uuid":"225240234","full_name":"zamotany/cli-tag-logger","owner":"zamotany","description":"Log messages in CLI apps using tagged template literals.","archived":false,"fork":false,"pushed_at":"2023-01-13T01:55:13.000Z","size":8445,"stargazers_count":9,"open_issues_count":17,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-26T22:42:34.540Z","etag":null,"topics":["cli","command-line","logger","logging","node","nodejs","tag","tagged-template-literals","terminal"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zamotany.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-01T22:27:01.000Z","updated_at":"2020-02-06T17:51:37.000Z","dependencies_parsed_at":"2023-01-17T02:00:35.071Z","dependency_job_id":null,"html_url":"https://github.com/zamotany/cli-tag-logger","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fcli-tag-logger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fcli-tag-logger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fcli-tag-logger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fcli-tag-logger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zamotany","download_url":"https://codeload.github.com/zamotany/cli-tag-logger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244757502,"owners_count":20505409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","logger","logging","node","nodejs","tag","tagged-template-literals","terminal"],"created_at":"2024-10-11T13:27:33.152Z","updated_at":"2025-03-21T07:31:06.293Z","avatar_url":"https://github.com/zamotany.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `cli-tag-logger`\n\n[![GitHub Workflow Status][build-badge]][build] [![Version][version]][package] [![MIT License][license-badge]][license]\n\n[![PRs Welcome][prs-welcome-badge]][prs-welcome]\n[![Code of Conduct][coc-badge]][coc]\n\nLog messages in CLI apps using tagged template literals.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Showcase GIF\" src=\"https://raw.githubusercontent.com/zamotany/cli-tag-logger/master/cli_tag_logger_showcase.gif\" width=\"512\"\u003e\n\u003c/p\u003e\n\n## Installation \u0026 usage\n\nInstall the package:\n```bash\nyarn add cli-tag-logger\n```\n\nThen:\n```js\nimport * as log from 'cli-tag-logger';\n\nlog.print(log.info`Hello world`);\nlog.print(\n  log.debug`Current env: ${{\n    SHELL: process.env.SHELL,\n    TERM: process.env.TERM,\n  }}`\n);\n\nlog.print(\n  log.compose(\n    log.styles.magenta`Custom message`,\n    ' '.repeat(4),\n    { my: 'object' },\n    class A {},\n    /regex/\n  )\n);\n```\n\nResult:\n\n![screenshot](https://raw.githubusercontent.com/zamotany/cli-tag-logger/master/screenshot.png)\n\n\n## Examples\n\nYou can start examples from `examples/` directory running:\n\n```bash\nyarn example \u003cexample_name\u003e\n```\n\nFor instance:\n\n```\nyarn example spinners\n```\n\n## API\n\n### Logging\n\nOut of the box `cli-tag-logger` exports the following logging tags:\n\n- `debug`\n- `info`\n- `success`\n- `warn`\n- `error`\n\nAdditionally use can use:\n\n- `trace` - similar to `console.trace`\n- `inspect` - similar to `util.inspect` with some better defaults\n\nAll of the tags return strings. You can use provided [`print`](#print) function, but you can also use `console.log`, [custom writer](#writers) or anything you want. \n\nIf you want to have custom tag, you can use `createTag` function, which accepts `prefix: string` as a first argument and returns a tag function:\n\n```js\nimport { createTag, styles, print } from 'cli-tag-logger';\n\nconst custom = createTag(styles.cyan`custom `);\n\nprint(custom`Hello World`);\n```\n\n![screenshot](https://raw.githubusercontent.com/zamotany/cli-tag-logger/master/custom.png)\n\n### Styling\n\n`cli-tag-logger` uses [colorette](https://www.npmjs.com/package/colorette) under the hood, and exposes all styling functions like `green`, `bold`, `bgBlue`, `italic` as tags functions with inspect and nesting support:\n\n```js\nimport { styles } from 'cli-tag-logger';\n\nconsole.log(styles.blue`${styles.bold`Hello`}`);\nconsole.log(styles.green(styles.underline`World`));\n```\n\n![screenshot](https://raw.githubusercontent.com/zamotany/cli-tag-logger/master/styles.png)\n\n### `print`\n\n`print` function is used to print values to `process.stdout`. You can pass multiple values:\n\n```js\nimport { print, debug } from 'cli-tag-logger';\n\nprint(debug`Hello`, { a: 1, b: 2 });\n```\n\n`print` function should be used only if you want to write messages to `process.stdout`. If you wan to customize this behavior use predefined writes or create your own. \n\n### Filtering messages\n\nSome writers like `ConsoleWriter` support filter messages. You can filter messages for specific tag or exclude unwanted messages.\n\nWriters which support filtering accept an optional `filter` property in their constructor:\n\n```ts\nimport { info, debug, success, ConsoleWriter } from 'cli-tag-logger';\n\nconst { print } = new ConsoleWriter({\n  filter: {\n    exclude: 'debug',\n  },\n});\n\nprint('will be logged');\nprint(info`will be logged as well`);\nprint(debug`won't be logged`);\n```\n\n`filter` property accepts these properties:\n\n- `only?: LevelTag | LevelTag[]` - if the message matches the value at least a single value (if array is passed), the message will pass filtering and be logged (in case of `ConsoleWriter`)\n- `exclude?: LevelTag | LevelTag[]` - if the message matches the value at least a single value (if array is passed), the message will not pass filtering and won't be logged (in case of `ConsoleWriter`)\n\nIf you combine both `only` and `exclude`, the message must satisfy both to pass filtering:\n\n```ts\nimport { info, debug, success, ConsoleWriter } from 'cli-tag-logger';\n\nconst { print } = new ConsoleWriter({\n  filter: {\n    only: ['debug', 'info', 'success'],\n    exclude: 'debug',\n  },\n});\n\nprint(info`will be logged`);\nprint(success`will be logged as well`);\nprint(debug`won't be logged`);\n```\n\n`LevelTag` can be `debug`, `info`, `success`, `warn`, `error` or RegExp. For custom tags (created using `createTag`) use RegExp:\n\n```ts\nimport { createTag ConsoleWriter } from 'cli-tag-logger';\n\nconst custom = createTag('custom ');\n\nconst { print } = new ConsoleWriter({\n  filter: {\n    only: /^custom/,\n  },\n});\n\nprint(custom`will be logged`);\nprint(`won't be logged`);\n```\n\n### Writers\n\n`Writer` class allows to customize where the messages are written. There are 3 predefined writers:\n\n- `ConsoleWriter({ filter }?: { filer?: FilterConfig })` - writes messages to `process.stdout` (this writer is used by exported `print` function); supports filtering\n- `FileWriter(filename: string, { filter, json }?: { filer?: FilterConfig; json?: boolean })` - writes messages to a file; supports filtering\n- `InteractiveWriter` - writes messages to `process.stdout` and allows to draw a spinner at the bottom:\n  - `startSpinner(message: string, { type, interval }?: SpinnerOptions): void` - starts a spinner with a given `message` next to it; supports all spinners from [cli-spinners](https://github.com/sindresorhus/cli-spinners)\n  - `updateSpinner(...values: ComposableValues): void` - updates a message printed next to the spinner\n  - `stopSpinner(...values: ComposableValues): void` - stops a running spinner and prints given `values` in it's place\n  \nand a single abstract class `Writer`.\n\n#### Composing writers\n\nYou can compose multiple writes together using `composeWriters` function.\n\n\nTo write messages to both `process.stdout` and file you would need to compose both `ConsoleWriter` and `FileWriter`:\n\n```ts\nimport { success, ConsoleWriter, FileWriter, composeWriters } from 'cli-tag-logger';\nimport path from 'path';\n\nconst { print } = composeWriters(\n  new ConsoleWriter(),\n  new FileWriter('output.log')\n);\n\nprint(success`This will be printed in your terminal as well as in ${path.resolve('output.log')}`);\n```\n\n`composeWriters` function accepts unlimited amount of writers, but the first writer is called a _main_ writer. All of the functions (except for `print` and `onPrint`) from the _main_ writer will be exposed inside returned object.\n\n\nTake `InteractiveWriter` for example - it has additional 3 methods: `startSpinner`, `updateSpinner` and `stopSpinner`. If `InteractiveWriter` is the _main_ writer, all of those 3 functions will be available for you:\n\n```ts\nimport { info, InteractiveWriter, FileWriter, composeWriters } from 'cli-tag-logger';\n\nconst { print, startSpinner, updateSpinner, stopSpinner } = composeWriters(\n  new InteractiveWriter(),\n  new FileWriter()\n);\n\nprint(info`Hello`)\nstartSpinner(info`I'm spinning`);\n\nsetTimeout(() =\u003e {\n  updateSpinner(info`I'm getting dizzy...`);\n}, 1000);\n\nsetTimeout(() =\u003e {\n  stopSpinner(`Done`);\n}, 2000);\n```\n\nHowever if you change the order and `FileWriter` will come first, only `print` function will be exposed, since this is the only function that `FileWriter` provides:\n\n```ts\nimport { info, InteractiveWriter, FileWriter, composeWriters } from 'cli-tag-logger';\n\nconst { print } = composeWriters(\n  new FileWriter(),\n  new InteractiveWriter()\n);\n\nprint(info`I'm the only function available`);\n```\n\n#### Creating custom writer\n\nIf you want to create your own writer, you need to extend abstract `Writer` class and implement `onPrint` function:\n\n```ts\nimport { success, Writer } from 'cli-tag-logger';\n\nclass StderrWriter extends Writer {\n  onPrint(message: string) {\n    process.stderr.write(message + '\\n');\n  }\n}\n\nconst { print } = new StderrWriter();\n\nprint(success`This will be printed to process.stderr`);\n```\n\nYou can compose your custom writer with predefined ones:\n\n```ts\nimport { success, Writer, FileWriter, composeWriters  } from 'cli-tag-logger';\n\nclass StderrWriter extends Writer {\n  onPrint(message: string) {\n    process.stderr.write(message + '\\n');\n  }\n}\n\nconst { print } = composeWriters(\n  new StderrWriter(),\n  new FileWriter('output.log')\n);\n\nprint(success`This will be printed to process.stderr and to a file`);\n```\n\n[version]: https://img.shields.io/npm/v/cli-tag-logger.svg?style=flat-square\n[package]: https://www.npmjs.com/package/cli-tag-logger\n[build]: https://github.com/zamotany/cli-tag-logger/actions\n[build-badge]: https://img.shields.io/github/workflow/status/zamotany/cli-tag-logger/Node%20CI?style=flat-square\n[license-badge]: https://img.shields.io/npm/l/cli-tag-logger.svg?style=flat-square\n[license]: https://opensource.org/licenses/MIT\n[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[prs-welcome]: http://makeapullrequest.com\n[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square\n[coc]: https://github.com/zamotany/cli-tag-logger/blob/master/CODE_OF_CONDUCT.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzamotany%2Fcli-tag-logger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzamotany%2Fcli-tag-logger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzamotany%2Fcli-tag-logger/lists"}