{"id":16485795,"url":"https://github.com/zamotany/ansi-fragments","last_synced_at":"2025-03-16T18:31:45.622Z","repository":{"id":33970083,"uuid":"164521088","full_name":"zamotany/ansi-fragments","owner":"zamotany","description":"A tiny library with builders to help making logs/CLI pretty with a nice DX","archived":false,"fork":false,"pushed_at":"2023-01-03T19:15:27.000Z","size":903,"stargazers_count":1,"open_issues_count":17,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-07T05:15:39.861Z","etag":null,"topics":["ansi","cli","dx","javascript","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zamotany.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-08T00:36:56.000Z","updated_at":"2019-07-30T12:06:45.000Z","dependencies_parsed_at":"2023-01-15T03:41:44.853Z","dependency_job_id":null,"html_url":"https://github.com/zamotany/ansi-fragments","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fansi-fragments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fansi-fragments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fansi-fragments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zamotany%2Fansi-fragments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zamotany","download_url":"https://codeload.github.com/zamotany/ansi-fragments/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242940015,"owners_count":20209883,"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":["ansi","cli","dx","javascript","nodejs","typescript"],"created_at":"2024-10-11T13:27:16.237Z","updated_at":"2025-03-16T18:31:45.088Z","avatar_url":"https://github.com/zamotany.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ansi-fragments\n\n[![Version][version]][package]   \n\n[![PRs Welcome][prs-welcome-badge]][prs-welcome]\n[![MIT License][license-badge]][license]\n[![Chat][chat-badge]][chat]\n[![Code of Conduct][coc-badge]][coc]\n\nA tiny library with builders to help making logs/CLI pretty with a nice DX.\n\n- [ansi-fragments](#ansi-fragments)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [API](#api)\n      - [`color`](#color)\n      - [`modifier`](#modifier)\n      - [`container`](#container)\n      - [`pad`](#pad)\n      - [`fixed`](#fixed)\n      - [`ifElse`](#ifElse)\n      - [`provide`](#provide)\n\n## Installation\n\n```bash\nyarn add ansi-fragments\n```\n\n## Usage\n\n```js\nimport { color, modifier, pad, container } from 'ansi-fragments';\n\nconst prettyLog = (level, message) =\u003e container(\n  color('green', modifier('italic', level)),\n  pad(1),\n  message\n).build();\n\nconsole.log(prettyLog('success', 'Yay!'));\n```\n\n## API\n\nEach fragment implements `IFragment` interface:\n\n```ts\ninterface IFragment {\n  build(): string;\n}\n```\n\nThe `build` method is responsible for traversing the tree of fragments and create a string representation with ANSI escape codes.\n\n\n#### `color`\n\n```ts\ncolor(\n  ansiColor: AnsiColor,\n  ...children: Array\u003cstring | IFragment\u003e\n): IFragment\n```\n\nCreates fragment for standard ANSI [colors](./src/fragments/Color.ts).\n\n```js\ncolor('red', 'Oh no');\ncolor('bgBlue', color('brightBlue', 'Hey'));\ncolor('green', modifier('bold', 'Sup!'));\n```\n\n#### `modifier`\n\n```ts\nmodifier(\n  ansiModifier: AnsiModifier,\n  ...children: Array\u003cstring | IFragment\u003e\n): IFragment\n```\n\nCreates fragment for standard ANSI [modifiers](./src/fragments/Modifier.ts): `dim`, `bold`, `hidden`, `italic`, `underline`, `strikethrough`.\n\n```js\nmodifier('underline', 'Hello', 'World');\nmodifier('italic', modifier('bold', 'Hey'));\nmodifier('bold', color('green', 'Sup!'));\n```\n\n#### `container`\n\n```ts\ncontainer(...children: Array\u003cstring | IFragment\u003e): IFragment\n```\n\nCreates fragment, which sole purpose is to hold and build nested fragments.\n\n```js\ncontainer(\n  color('gray', '[08/01/18 12:00]'),\n  pad(1),\n  color('green', 'success'),\n  pad(1),\n  'Some message'\n)\n```\n\n#### `pad`\n\n```ts\npad(count: number, separator?: string): IFragment\n```\n\nCreates fragment, which repeats given separator (default: ` `) given number of times.\n\n```js\npad(1);\npad(2, '#')\npad(1, '\\n')\n```\n\n#### `fixed`\n\n```ts\nfixed(\n  value: number,\n  bias: 'start' | 'end',\n  ...children: Array\u003cstring | IFragment\u003e\n): IFragment\n```\n\nCreates fragment, which makes sure the children will always build to given number of non-ANSI characters. It will either trim the results or add necessary amount of spaces. The `bias` control if trimming/padding should be done at the start of the string representing built children or at the end.\n\n```js\nfixed(5, 'start', 'ERR'); // =\u003e '  ERR'\nfixed(8, 'end', color('green', 'success')); // equals to color('green', 'success') + ' '\nfixed(10, 'end', 'Hello', pad(2), 'World') // =\u003e 'Hello  Wor'\n```\n\n#### `ifElse`\n\n```ts\nifElse(\n  condition: Condition,\n  ifTrueFragment: string | IFragment,\n  elseFragment: string | IFragment\n): IFragment\n\ntype ConditionValue = boolean | string | number | null | undefined;\ntype Condition = ConditionValue | (() =\u003e ConditionValue);\n```\n\nChange the output based on condition. Condition can ba a primitive value, which can be casted to boolean or a function. If conation or return value of condition is evaluated to `true`, the first argument - `ifTrueFragment` will be used, otherwise `elseFragment`.\n\n```js\nlet condition = getConditionValue()\nifElse(\n  () =\u003e condition,\n  color('red', 'ERROR'),\n  color('yellow', 'WARNING')\n)\n```\n\n#### `provide`\n\n```ts\nprovide\u003cT\u003e(\n  value: T,\n  builder: (value: T) =\u003e string | IFragment\n): IFragment\n```\n\nProvides given value to a builder function, which should return `string` or fragment. Useful in situations when the output is connected with some calculated value - using `provide` you only need to calculate final value once and forward it to custom styling logic.\n\n```js\nprovide(getMessageFromSomewhere(), value =\u003e {\n  switch (value.level) {\n    case 'error':\n      return container(\n        color('red', modifier('bold', value.level.toUpperCase())),\n        pad(2),\n        value.log\n      );\n    case 'info':\n      return container(\n        color('blue', value.level.toUpperCase()),\n        pad(2),\n        value.log\n      );\n    default:\n      return container(value.level.toUpperCase(), pad(2), value.log);\n  }\n})\n```\n\n\n\u003c!-- badges (common) --\u003e\n\n[license-badge]: https://img.shields.io/npm/l/ansi-fragments.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/ansi-fragments/blob/master/CODE_OF_CONDUCT.md\n[chat-badge]: https://img.shields.io/badge/chat-discord-brightgreen.svg?style=flat-square\u0026colorB=7289DA\u0026logo=discord\n[chat]: https://discord.gg/zwR2Cdh\n\n[version]: https://img.shields.io/npm/v/ansi-fragments.svg?style=flat-square\n[package]: https://www.npmjs.com/package/ansi-fragments\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzamotany%2Fansi-fragments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzamotany%2Fansi-fragments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzamotany%2Fansi-fragments/lists"}