{"id":25301620,"url":"https://github.com/p2js/rsformat","last_synced_at":"2026-05-04T07:41:23.184Z","repository":{"id":260508356,"uuid":"881469420","full_name":"p2js/rsformat","owner":"p2js","description":"Formatting/printing library for JavaScript that takes after rust's string formatting","archived":false,"fork":false,"pushed_at":"2026-02-15T00:25:54.000Z","size":111,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-15T06:18:21.113Z","etag":null,"topics":["fmt","format","javascript","printf","println","string-manipulation","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/rsformat","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/p2js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-31T16:25:49.000Z","updated_at":"2026-02-15T00:25:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"b976fdac-c9a5-4cb5-8198-65c1859e640a","html_url":"https://github.com/p2js/rsformat","commit_stats":null,"previous_names":["p2js/rsformat"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/p2js/rsformat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p2js%2Frsformat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p2js%2Frsformat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p2js%2Frsformat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p2js%2Frsformat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/p2js","download_url":"https://codeload.github.com/p2js/rsformat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/p2js%2Frsformat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32599413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["fmt","format","javascript","printf","println","string-manipulation","typescript"],"created_at":"2025-02-13T06:48:10.280Z","updated_at":"2026-05-04T07:41:23.172Z","avatar_url":"https://github.com/p2js.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RSFormat\n\nRSFormat is a string formatting/printing library for JavaScript. It offers a minimal, yet powerful and flexible alternative to the string formatting and printing provided by `console.log`.\n\n```js\nimport { rs, println } from 'rsformat';\n\nlet s = rs`${15} is ${15}:#X in hex`;\n// s == '15 is 0xF in hex'\n\nprintln(rs`${'a'}:^5`);\n// Prints '  a  '\n```\n\n## Table of Contents\n\n- [Motivation](#motivation)\n- [Usage](#usage)\n    - [Basic formatting and printing to console](#basic-formatting-and-printing-to-console)\n    - [Decorating terminal output](#decorating-terminal-output)\n    - [Format specifiers](#format-specifiers)\n        - [Different formatting types](#different-formatting-types)\n        - [Padding, Alignment](#padding-alignment)\n        - [Pretty printing with `#`](#pretty-printing-with-)\n        - [Specific number formatting](#specific-number-formatting)\n        - [Specific string formatting](#specific-string-formatting)\n    - [Formatting without `rs`](#formatting-without-rs)\n- [Older versions of RSFormat](#older-versions-of-rsformat)\n\n## Motivation\n\n`console.log` is an odd method: its output can be affected by functions called before/after it (such as `console.group`), or their order affected by what parameters there are. For example, when calling `console.log(string, number)`, number can come either after or inside `string` depending on the value of `string`.\n\nThis behaviour has largely been superseded at a language level by template literals, which allow formatting of parameters directly inside the templates, causing these methods to have unnecessary overhead and undesired behaviour.\n\nRSFormat builds onto template literals by implementing Rust-style format specifiers and lightweight printing functions. Rust formatting includes a lot of convenient operators for formatting text, such as padding/alignment, printing numbers in a given base, specifying decimal precision, etc.\n\n## Usage\n\nYou can install RSFormat from [npm](https://www.npmjs.com/package/rsformat):\n\n```sh\nnpm install rsformat\n```\n\n### Basic formatting and printing to console\n\nThe `rs` template tag can be used to enable rust-style formatting in a template.\n\nTo reference a previous or following argument, use `rs.ref` with the argument number. This is useful if you want to reuse a complicated expression without having to declare it separately.\n\n```js\nimport { rs, println } from 'rsformat';      // ESM\nconst { rs, println } = require('rsformat'); // CommonJS\n\nlet number = 14;\n\nlet info = rs`${number+1} is ${rs.ref(0)}:x in hex`; // info == '15 is f in hex'\n```\n\n\u003e NB: templates tagged with `rs` are instances of a special class `RsString` that extends `String`, rather than a primitive value. This is to enable colours for debug formatting inside the printing functions. This difference should not affect normal usage, but `rs.raw` can be used as an alternative tag to get a primitive `string`.\n\nThe printing functions can be called with plain strings, instances of `String` or templates formatted with `rs`:\n\n```ts\nprintln('Hello World');\nprintln(`This template did ${'Not'} need fancy formatting`);\nprintln(rs`...`);\n```\n\n### Decorating terminal output\n\nIf you want to decorate text for terminal output, you can use `rs.style`, which will format a string using one (or more with an array) of [the modifiers provided by node's `util` module](https://nodejs.org/docs/latest-v22.x/api/util.html#modifiers).\n\nThis is a re-export of node's `util.styleText`, and is thus aware of whether the current stdout will support the provided styles.\n\n```ts\nprintln(rs.style(\"red\", \"I am angry\"));\nprintln(rs.style([\"red\", \"bold\", \"underline\"], \"I am very angry\"));\n```\n\nThis also works if passed inside `rs` tagged templates.\n\n### Format Specifiers\n\nFormat specifiers can be used by adding a `:` after the format argument, and will format the value differently inside the string. \n\nSee [docs.md](./docs.md) for a detailed yet quick reference for format specifiers.\n\n#### Different formatting types\n\nThe debug format specifier `?` uses `util.inspect` to stringify the parameter rather than `toString`.\n \n```js\nlet obj = { a: 1 };\nprintln(rs`${obj}`);   // prints '[object Object]'\nprintln(rs`${obj}:?`); // prints '{ a: 1 }'\n```\n\nThe provided printing functions will display colours in the output of `util.inspect`, but otherwise it will be formatted without colour.\n\nThe specifiers `b`,`o`,`x`,`X`,`e`,`E`,`n`,`N` will convert a `number` or `bigint` parameter to:\n- `b`: binary \n- `o`: octal \n- `x`/`X`: lowercase/uppercase hexadecimal\n- `e`/`E`: lowercase/uppercase scientific notation\n- `n`/`N`: lowercase/uppercase ordinal suffixed string (rounded to integer)\n\n```js\nlet advancedInfo = (n) =\u003e rs`${n} is ${n}:x in hex, ${n}:b in binary and ${n}:o in octal`;\n\nadvancedInfo(15); // '15 is f in hex, 1111 in binary and 17 in octal'\n\nlet hugeNumber = 1000n;\nlet science = rs`${hugeNumber}:E`; // '1E3'\nlet ordinal = rs`${hugeNumber}:n`; // '1000th'\n```\n\n#### Padding, Alignment\n\nValues can be aligned using any fill character (will default to a space ` `), and either left, center or right aligned with `\u003c`, `^` or `\u003e` respectively (will default to right alignment `\u003e`). You will also have to specify a width with an integer after the alignment, or provide a separate number parameter.\n\n```js\n/*\nWill print a pyramid of 'a's:\n'  a  '\n' aaa '\n'aaaaa'\n*/\nlet pyramidLevels = ['a', 'aaa', 'aaaaa'];\nfor(let value of pyramidLevels) {\n    println(rs`${value}:^5`);\n}\n\n// More powerful equivalent:\nconst character = 'a';\nconst baseWidth = 5;\nfor(let width = 1; width \u003c= baseWidth; width += 2) {\n    println(rs`${character.repeat(width)}:^${baseWidth}`);\n}\n```\n\n```js\nrs`${[1,2]}:.\u003e7` // '....1,2'\n```\n\n#### Pretty printing with `#`\n\nIn some instances (namely debug, binary, octal and hexadecimal formatting), adding a `#` before the format specifier will use an alternative 'pretty' printing style. This amounts to using multiline `util.inspect` for debug printing (spanning multiple lines), and adding `0b`/`0o`/`0x` as a prefix for the numbers in the respective bases.\n\n```js\nrs`${255}:#X` // '0xFF'\n```\n\n#### Specific number formatting\n\nSpecifically for `number` and `bigint` values, a `0` can be placed before the width to pad the number with zeroes instead. This will account for signs and possible formatting differences.\n\n```js\nrs`${15}:#07x` // '0x0000f'\n```\n\nDecimal precision can be specified for numbers by adding a `.` and specifying an integer for precision. An additional parameter can also be provided to do this dynamically.\n\n```js\nrs`${1.23456789}:.3` // '1.235'\nrs`${-1}:.${3}`      // '-1.000'\n```\n\nAdding a `+` to the formatting specifier will print the sign regardless of whether the number is negative.\nAdding a `-` will instead add a space if the number is positive.\n\n```js\nrs`${1}:+` // '+1'\nrs`${1}:-` // ' 1'\n```\n\n#### Specific string formatting\n\nAdding a `+` or `-` to a formatting specifier of a string will instead convert it to uppercase or lowercase respectively.\n\n```js\nlet str  = \"Hello!\"\nlet str_upper = rs`${str}:+` // 'HELLO!'\nlet str_lower = rs`${str}:-` // 'hello!'\n```\n\nSpecifying precision will truncate the string to the given length.\n\n```js\nlet str  = \"Hello!\"\nlet str_truncated = rs`${str}:.3` // 'Hel'\n```\n\n## Formatting without `rs`\n\nIf you want to format a single value without using an `rs` template, you can use the `formatParam` function. It provides a more explicit, object‑based API and avoids parsing format specifiers.\n\n\u003e NB: formatParam returns an array with the raw and debug-colored string at indices `0` and `1` respectively.\n\n```ts\nimport { formatParam } from \"rsformat/format\";\n\n// Equivalent to `${255}:+#09X` or `${255}:\u003c+#09.0X`\nlet [ pretty255 ] = formatParam(255, {\n    fill: '',\n    align: '\u003c',\n    force_sign: '+',\n    pretty: true,\n    pad_zeroes: true,\n    width: 9,\n    precision: 0,\n    type: \"X\"\n});\n\n// pretty255 == '+0x0000FF'\n```\n\n## Older versions of RSFormat\n\nVersions of RSFormat on npm prior to `1.0.0` provide formatting and printing functions that are more similar in syntax to Rust, using plain strings instead of tagged templates:\n\n```js\nimport { format } from 'rsformat';\nformat('{} is {0:#x} in hex', 15); // '15 is 0xf in hex'\n```\n\nSee the `old` branch for more detailed documentation. The last version to use this formatting was `0.2.5`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp2js%2Frsformat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fp2js%2Frsformat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fp2js%2Frsformat/lists"}