{"id":22899703,"url":"https://github.com/wolfulus/zoya","last_synced_at":"2025-05-08T01:10:14.722Z","repository":{"id":36460128,"uuid":"225307028","full_name":"WoLfulus/zoya","owner":"WoLfulus","description":"Truly highly composable logging utility","archived":false,"fork":false,"pushed_at":"2023-03-07T09:58:10.000Z","size":1244,"stargazers_count":122,"open_issues_count":11,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-08T01:10:00.683Z","etag":null,"topics":["cli","color","colors","express","javascript","json","logging","logs","node","nodejs","server","signale","typescript","winston"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"klaussinani/signale","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WoLfulus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"license.md","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-02T07:00:17.000Z","updated_at":"2023-06-13T07:56:40.000Z","dependencies_parsed_at":"2024-08-01T12:37:08.646Z","dependency_job_id":null,"html_url":"https://github.com/WoLfulus/zoya","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoLfulus%2Fzoya","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoLfulus%2Fzoya/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoLfulus%2Fzoya/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoLfulus%2Fzoya/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WoLfulus","download_url":"https://codeload.github.com/WoLfulus/zoya/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252978768,"owners_count":21834916,"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","color","colors","express","javascript","json","logging","logs","node","nodejs","server","signale","typescript","winston"],"created_at":"2024-12-14T01:15:48.473Z","updated_at":"2025-05-08T01:10:14.666Z","avatar_url":"https://github.com/WoLfulus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"media/logo.png\"\u003e\n\u003c/div\u003e\n\n\u003ch4 align=\"center\"\u003e\n  Truly highly composable logging utility written in TypeScript\n\u003c/h4\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"Header\" src=\"media/header.png\" width=\"90%\"\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://travis-ci.org/wolfulus/zoya\"\u003e\n    \u003cimg alt=\"Build Status\" src=\"https://travis-ci.org/wolfulus/zoya.svg?branch=master\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/WoLfulus/zoya?branch=master\"\u003e\n    \u003cimg alt=\"Coverage Status\" src=\"https://coveralls.io/repos/github/WoLfulus/zoya/badge.svg?branch=master\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/zoya\"\u003e\n    \u003cimg alt=\"NPM Downloads\" src=\"https://img.shields.io/npm/dt/zoya\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Description\n\nZoya is a highly composable logging library used for both client and server applications.\n\nVisit the [contributing guidelines](https://github.com/wolfulus/zoya/blob/master/contributing.md#translating-documentation) to learn more on how to translate this document into more languages.\n\nCome over to [Discord](https://discord.gg/X7gp2kV) or [Twitter](https://twitter.com/wolfulus) to share your thoughts on the project.\n\n\u003e This is a complete rewrite of [Signale](https://github.com/klaussinani/signale), written by [Klaus Siani](https://github.com/klaussinani), and it's **NOT** intended to be a drop-in replacement.\n\n## Highlights\n\n- Easy to setup and compose as you like\n- Easy to control how things look\n- Easy to extend\n- Clean and beautiful output, configure as you wish\n- Supports JSON outputs\n- Extensible fields with several fields built in\n  - Labels, Badge (emoji), Scopes, Level, Separators, Message, Context\n- Multiple configurable writable streams with stream level filtering\n- Simple and minimal syntax\n- Written in TypeScript\n\n## Contents\n\n- [Description](#description)\n- [Highlights](#highlights)\n- [Contents](#contents)\n- [Install](#install)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Development](#development)\n- [Related](#related)\n- [Team](#team)\n- [FAQ](#faq)\n- [Acknowledgements](#acknowledgements)\n- [License](#license)\n\n## Install\n\n### Yarn\n\n```bash\nyarn add zoya\n```\n\n### NPM\n\n```bash\nnpm install zoya\n```\n\n## Usage\n\n### Overview\n\nZoya tries to make it simple to configure and compose your loggers, so you can easily control how the output will look like. This is possible due to the field chain passed to the logger in its creation.\n\nTo use the default exported logger you just import and use it.\n\n```ts\nimport zoya from \"zoya\";\n\nzoya.info(\"Hello world!\");\n```\n\nTo see all the available examples check the [examples folder](./examples)\n\n### Default logger\n\nThe default export of zoya is an instance of a logger (called the default logger). This instance is preconfigured to write to `process.stdout` with all logging levels enabled (so you can use `debug` and `trace` for example).\n\nThese are all the available loggers in the default logger.\n\n```ts\nimport log from \"zoya\";\n\nlog.trace(\"trace messages...\");\nlog.debug(\"debug messages...\");\nlog.info(\"info messages...\");\nlog.success(\"success messages...\");\nlog.warn(\"warn messages...\");\nlog.error(\"error messages...\");\nlog.failed(\"failed messages...\");\nlog.fatal(\"fatal messages...\");\n```\n\nThe fields configured in the default logger are:\n\n\u003e \\[scope\\]\\[separator\\]\\[badge\\]\\[label\\]\\[level\\]\\[message\\]\\[context\\]\n\nMore on _fields_ later.\n\n#### On new instances\n\nTo create a new Zoya instance, use `zoya` function passing the proper configs you want. Note that all first level values uses the default values from the default logger, so you don't need to specify all of them if you want for example to just enable `json` logging.\n\nNote that if you pass value to an object, for example `types`, all the child values are overwritten.\n\n```ts\nimport { zoya, Level } from \"zoya\";\n\n// Just enables json\nconst jsonLogger = zoya({ json: true });\n\n// Only outputs to stderr\nconst stderrLogger = zoya({\n  streams: [\n    {\n      level: Level.error,\n      stream: process.stderr\n    }\n  ]\n});\n```\n\n#### Enhancing loggers\n\nZoya allows you to enhance existing loggers in order to add new logging types. Enhancing logger will create a new logger instance and will keep the old logger intact.\n\n```ts\nimport { bold, underline } from \"chalk\";\nimport log, { Level } from \"zoya\";\n\nconst xmasLogger = log.enhance({\n  santa: {\n    level: Level.info,\n    options: {\n      badge: \"santa\"\n      label: {\n        name: \"santa\",\n        transformer: label =\u003e bold(underline(label))\n      }\n      scope: [\"xmas\"]\n    }\n  }\n});\n\nxmasLogger.santa(\"Hohoho!\");\n```\n\nThe above logger will output something like this\n\n\u003cpre\u003e\n\u003cspan style=\"color: gray;\"\u003e[xmas] »\u003c/span\u003e 🎅  \u003cspan style=\"color: red;\"\u003e\u003cu\u003e\u003cstrong\u003esanta\u003c/strong\u003e\u003c/u\u003e\u003c/span\u003e Hohoho!\n\u003c/pre\u003e\n\n## Configuration\n\n### Fields\n\nZoya has the concept of fields. All log messages are built by a chain of fields that are configured when creating a new logger through `zoya` function. Fields are context sensitive, this means that you can output different things in a field depending on what the message contains.\n\n#### Configuring fields\n\nFor example, if you just want to show the message and its context, you can configure zoya like this:\n\n```ts\nimport { context, message, zoya } from \"zoya\";\n\nconst custom = zoya({\n  fields: [message(), context()]\n});\n\ncustom.info(\"Hello world\", { ip: \"127.0.0.1\" });\n```\n\nThis will output something like this in text mode:\n\n\u003cpre\u003e\nHello world {\n  \"ip\": \"127.0.0.1\"\n}\n\u003c/pre\u003e\n\nAnd this in JSON mode:\n\n\u003cpre\u003e{\"message\":\"Hello world\",\"context\":{\"ip\":\"127.0.0.1\"}}\u003c/pre\u003e\n\n#### Zoya fields\n\nZoya contains several fields that can be imported from `zoya` package.\n\n**Badge**\n\n\u003e Used to display emojis in the log text\n\n**Context**\n\n\u003e Displays the message context\n\n**Label**\n\n\u003e Displays a customizable label for each message type\n\n**Level**\n\n\u003e Adds the message level only on json outputs\n\n**Message**\n\n\u003e Displays the message itself\n\n**Scope**\n\n\u003e Display the message scope(s)\n\n**Separator**\n\n\u003e Displays a customizable separator only in text mode\n\n---\n\n#### Custom fields\n\nYou can easily write custom fields.\n\n\u003e TODO: write example custom fields. For now you can take the bundled ones as an example from [here](./src/fields).\n\n## Development\n\nFor more info on how to contribute to the project, please read the [contributing guidelines](https://github.com/wolfulus/zoya/blob/master/contributing.md).\n\n- Fork the repository and clone it to your machine\n- Navigate to your local fork: `cd zoya`\n- Install the project dependencies: `npm install` or `yarn install`\n- Lint code for errors: `npm test` or `yarn test`\n\n## Related\n\n- [Signale](https://github.com/klaussinani/signale) - Highly configurable logging utility\n\n## Team\n\n- João Biondo [(@wolfulus)](https://github.com/wolfulus)\n\n## FAQ\n\n### Why \"Zoya\"?\n\nBecause I like [Trine](https://store.steampowered.com/franchise/Trine) :)\n\n## Acknowledgements\n\n### Thanks\n\nHuge thanks to **brain** (brain#4221), **Micah** (Micha#6878) and **undefined.toString()** (elderapo#8225) for the helpful insights over [TypeScript discord channel](https://discord.gg/typescript)\n\n## License\n\n[MIT](https://github.com/wolfulus/zoya/blob/master/license.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfulus%2Fzoya","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolfulus%2Fzoya","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolfulus%2Fzoya/lists"}