rsformat 1.2.1 → 1.4.0

package/README.md

@@ -1,163 +1,228 @@
-# RSFormat
-
-RSFormat 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`.
-
-```js
-import { rs, println } from 'rsformat';
-
-let s = rs`${15} is ${15}:#X in hex`;
-// s == '15 is 0xF in hex'
-
-println(rs`${'a'}:^5`);
-// Prints '  a  '
-```
-
-## Motivation
-
-`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`.
-
-This 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.
-
-RSFormat 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.
-
-## Usage
-
-You can install RSFormat from [npm](https://www.npmjs.com/package/rsformat):
-
-```sh
-npm install rsformat
-```
-
-### Basic formatting and printing to console
-
-The `rs` template tag can be used to enable rust-style formatting in a template.
-
-To 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.
-
-```js
-import { rs, println } from 'rsformat';      // ESM
-const { rs, println } = require('rsformat'); // CommonJS
-
-let number = 14;
-
-let info = rs`${number+1} is ${rs.ref(0)}:x in hex`; // info == '15 is f in hex'
-```
-
-> NB: templates tagged with `rs` are instances of a special class `RsString` that extends `String`, rather than a primitive value. This is to enable colors 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`.
-
-The printing functions can be called with plain strings, instances of `String` or templates formatted with `rs`:
-
-```ts
-println('Hello World');
-println(`This template did ${'Not'} need fancy formatting`);
-println(rs`...`);
-```
-
-### Format Specifiers
-
-Format specifiers can be used by adding `:` after the format argument, and will format the value differently inside the string. See the [rust format docs](https://doc.rust-lang.org/std/fmt/) for more detailed information on format specifiers.
-
-This implementation differs from the Rust one in a few ways:
-
-- Rather than escaping the braces using `{{` or `}}`, the formatting colon can be escaped using `::`.
-- Different parameters are referenced using `rs.ref(n)` rather than the number literal `n`.
-- To separate a formatting specifier from the rest of the string without adding a space, an extra closing colon must be added (eg. `:#?:foo` - specifier gets parsed as `:#?`)
-- The `-` sign (unused in Rust) will add a space if the number is positive to align it with negative numbers without showing a `+`.
-- Pointer format type `p` is unsupported.
-- Hexadecimal debug types `x?` and `X?` are unsupported. 
-- Specifying precision dynamically with `*` is unsupported. Instead, precision and width can both be specified dynamically by using a separate number parameter in place of the number.
-- New format types have been added:
-    - `N` for uppercase ordinal suffixing of numbers (rounded to integers)
-    - `n` for lowercase ordinal suffixing of numbers (rounded to integers)
-
-#### Different formatting types
-
-The debug format specifier `?` uses `util.inspect` to stringify the parameter rather than `toString`.
- 
-```js
-let obj = { a: 1 };
-println(rs`${obj}`);   // prints '[object Object]'
-println(rs`${obj}:?`); // prints '{ a: 1 }'
-```
-
-The provided printing functions will display colors in the output of `util.inspect`, but otherwise it will be formatted without color.
-
-The specifiers `b`,`o`,`x`,`X`,`e`,`E`,`n`,`N` will convert a `number` or `bigint` parameter to:
-- `b`: binary 
-- `o`: octal 
-- `x`/`X`: lowercase/uppercase hexadecimal
-- `e`/`E`: lowercase/uppercase scientific notation
-- `n`/`N`: lowercase/uppercase ordinal suffixed string (rounded to integer)
-
-```js
-let advancedInfo = (n) => rs`${n} is ${n}:x in hex, ${n}:b in binary and ${n}:o in octal`;
-
-advancedInfo(15); // '15 is f in hex, 1111 in binary and 17 in octal'
-
-let hugeNumber = 1000n;
-let science = rs`${hugeNumber}:E`; // '1E3'
-let ordinal = rs`${hugeNumber}:n`; // '1000th'
-```
-
-#### Padding, Alignment
-
-Values can be aligned using any fill character (will default to a space ` `), and either left, center or right aligned with `<`, `^` or `>` respectively (will default to right alignment `>`). You will also have to specify a width with an integer after the alignment, or provide a separate number parameter.
-
-```js
-/*
-Will print a pyramid of 'a's:
-'  a  '
-' aaa '
-'aaaaa'
-*/
-let pyramidLevels = ['a', 'aaa', 'aaaaa'];
-for(let value of pyramidLevels) {
-    println(rs`${value}:^5`);
-}
-```
-
-```js
-rs`${[1,2]}:.>${7}` // '....1,2'
-```
-
-#### Pretty Printing
-
-In 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.
-
-```js
-rs`${255}:#X` // '0xFF'
-```
-
-#### Specific Number Formatting
-
-Specifically 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.
-
-```js
-rs`${15}:#07x` // '0x0000F'
-```
-
-Decimal 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.
-
-```js
-rs`${1.23456789}:.3` // '1.234'
-rs`${-1}:.${3}`      // '-1.000'
-```
-
-Adding a `+` to the formatting specifier will print the sign regardless of whether the number is negative.
-Adding a `-` will instead add a space if the number is positive.
-
-```js
-rs`${1}:+` // '+1'
-rs`${1}:-` // ' 1'
-```
-
-## Older versions of RSFormat
-
-Versions 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:
-
-```js
-import { format } from 'rsformat';
-format('{} is {0:#x} in hex', 15); // '15 is 0xf in hex'
-```
-
+# RSFormat
+
+RSFormat 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`.
+
+```js
+import { rs, println } from 'rsformat';
+
+let s = rs`${15} is ${15}:#X in hex`;
+// s == '15 is 0xF in hex'
+
+println(rs`${'a'}:^5`);
+// Prints '  a  '
+```
+
+## Table of Contents
+
+- [Motivation](#motivation)
+- [Usage](#usage)
+    - [Basic formatting and printing to console](#basic-formatting-and-printing-to-console)
+    - [Decorating terminal output](#decorating-terminal-output)
+    - [Format specifiers](#format-specifiers)
+        - [Different formatting types](#different-formatting-types)
+        - [Padding, Alignment](#padding-alignment)
+        - [Pretty printing with `#`](#pretty-printing-with-)
+        - [Specific number formatting](#specific-number-formatting)
+        - [Specific string formatting](#specific-string-formatting)
+    - [Formatting without `rs`](#formatting-without-rs)
+- [Older versions of RSFormat](#older-versions-of-rsformat)
+
+## Motivation
+
+`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`.
+
+This 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.
+
+RSFormat 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.
+
+## Usage
+
+You can install RSFormat from [npm](https://www.npmjs.com/package/rsformat):
+
+```sh
+npm install rsformat
+```
+
+### Basic formatting and printing to console
+
+The `rs` template tag can be used to enable rust-style formatting in a template.
+
+To 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.
+
+```js
+import { rs, println } from 'rsformat';      // ESM
+const { rs, println } = require('rsformat'); // CommonJS
+
+let number = 14;
+
+let info = rs`${number+1} is ${rs.ref(0)}:x in hex`; // info == '15 is f in hex'
+```
+
+> 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`.
+
+The printing functions can be called with plain strings, instances of `String` or templates formatted with `rs`:
+
+```ts
+println('Hello World');
+println(`This template did ${'Not'} need fancy formatting`);
+println(rs`...`);
+```
+
+### Decorating terminal output
+
+If 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).
+
+This is a re-export of node's `util.styleText`, and is thus aware of whether the current stdout will support the provided styles.
+
+```ts
+println(rs.style("red", "I am angry"));
+println(rs.style(["red", "bold", "underline"], "I am very angry"));
+```
+
+This also works if passed inside `rs` tagged templates.
+
+### Format Specifiers
+
+Format specifiers can be used by adding a `:` after the format argument, and will format the value differently inside the string. 
+
+See [docs.md](./docs.md) for a detailed yet quick reference for format specifiers.
+
+#### Different formatting types
+
+The debug format specifier `?` uses `util.inspect` to stringify the parameter rather than `toString`.
+ 
+```js
+let obj = { a: 1 };
+println(rs`${obj}`);   // prints '[object Object]'
+println(rs`${obj}:?`); // prints '{ a: 1 }'
+```
+
+The provided printing functions will display colours in the output of `util.inspect`, but otherwise it will be formatted without colour.
+
+The specifiers `b`,`o`,`x`,`X`,`e`,`E`,`n`,`N` will convert a `number` or `bigint` parameter to:
+- `b`: binary 
+- `o`: octal 
+- `x`/`X`: lowercase/uppercase hexadecimal
+- `e`/`E`: lowercase/uppercase scientific notation
+- `n`/`N`: lowercase/uppercase ordinal suffixed string (rounded to integer)
+
+```js
+let advancedInfo = (n) => rs`${n} is ${n}:x in hex, ${n}:b in binary and ${n}:o in octal`;
+
+advancedInfo(15); // '15 is f in hex, 1111 in binary and 17 in octal'
+
+let hugeNumber = 1000n;
+let science = rs`${hugeNumber}:E`; // '1E3'
+let ordinal = rs`${hugeNumber}:n`; // '1000th'
+```
+
+#### Padding, Alignment
+
+Values can be aligned using any fill character (will default to a space ` `), and either left, center or right aligned with `<`, `^` or `>` respectively (will default to right alignment `>`). You will also have to specify a width with an integer after the alignment, or provide a separate number parameter.
+
+```js
+/*
+Will print a pyramid of 'a's:
+'  a  '
+' aaa '
+'aaaaa'
+*/
+let pyramidLevels = ['a', 'aaa', 'aaaaa'];
+for(let value of pyramidLevels) {
+    println(rs`${value}:^5`);
+}
+
+// More powerful equivalent:
+const character = 'a';
+const baseWidth = 5;
+for(let width = 1; width <= baseWidth; width += 2) {
+    println(rs`${character.repeat(width)}:^${baseWidth}`);
+}
+```
+
+```js
+rs`${[1,2]}:.>7` // '....1,2'
+```
+
+#### Pretty printing with `#`
+
+In 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.
+
+```js
+rs`${255}:#X` // '0xFF'
+```
+
+#### Specific number formatting
+
+Specifically 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.
+
+```js
+rs`${15}:#07x` // '0x0000f'
+```
+
+Decimal 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.
+
+```js
+rs`${1.23456789}:.3` // '1.235'
+rs`${-1}:.${3}`      // '-1.000'
+```
+
+Adding a `+` to the formatting specifier will print the sign regardless of whether the number is negative.
+Adding a `-` will instead add a space if the number is positive.
+
+```js
+rs`${1}:+` // '+1'
+rs`${1}:-` // ' 1'
+```
+
+#### Specific string formatting
+
+Adding a `+` or `-` to a formatting specifier of a string will instead convert it to uppercase or lowercase respectively.
+
+```js
+let str  = "Hello!"
+let str_upper = rs`${str}:+` // 'HELLO!'
+let str_lower = rs`${str}:-` // 'hello!'
+```
+
+Specifying precision will truncate the string to the given length.
+
+```js
+let str  = "Hello!"
+let str_truncated = rs`${str}:.3` // 'Hel'
+```
+
+## Formatting without `rs`
+
+If 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.
+
+> NB: formatParam returns an array with the raw and debug-colored string at indices `0` and `1` respectively.
+
+```ts
+import { formatParam } from "rsformat/format";
+
+// Equivalent to `${255}:+#09X` or `${255}:<+#09.0X`
+let [ pretty255 ] = formatParam(255, {
+    fill: '',
+    align: '<',
+    force_sign: '+',
+    pretty: true,
+    pad_zeroes: true,
+    width: 9,
+    precision: 0,
+    type: "X"
+});
+
+// pretty255 == '+0x0000FF'
+```
+
+## Older versions of RSFormat
+
+Versions 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:
+
+```js
+import { format } from 'rsformat';
+format('{} is {0:#x} in hex', 15); // '15 is 0xf in hex'
+```
+
 See the `old` branch for more detailed documentation. The last version to use this formatting was `0.2.5`.

package/docs.md

@@ -0,0 +1,59 @@
+# rsformat Format Specifier Documentation
+
+A rsformat format specifier is parsed as follows:
+
+- `${value}::` Will escape the colon character and replace it with a single `:`. Stringification of `value` will occur as in normal format strings.
+
+- `${value}:[fill][align][sign][#][0][width][.(precision)][format_type][:]` is an unescaped format specifier and will parse the string as follows:
+
+| Name          | Syntax                                                                 | Purpose                                                                                                                             | Default value |
+| ------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `fill`        | any single character                                                     | The fill character for alignment                                                                                                    | space (` `)   |
+| `align`       | `<`, `^` or `>`                                                        | The alignment direction (left, center, right)                                                                                       | right (`>`)   |
+| `sign`        | `+` or `-`                                                             | Pad a positive number with `+` or a space ` ` (or convert a string to uppercase/lowercase)                                          | None          |
+| `#`           | `#`                                                                    | Pretty printing (Add prefixes `0b`, `0o` and `0x` to binary, octal and hex-formatted numbers, and use non-compact debug formatting) | None          |
+| `0`           | `0`                                                                    | Pads numbers with `0` characters instead of using fill/align                                                                        | None          |
+| `width`       | any positive integer (in string or as ${} parameter)                   | Minimum width for fill/alignment                                                                                                    | 0             |
+| `precision`   | `.` + any positive integer (in string or as ${} parameter)             | Minimum precision for non-integer numbers                                                                                           | 0             |
+| `format_type` | `?`,`o`,`x`,`X`,`b`,`e`,`E`,`n` or `N`                                 | Format type (see [Format types](#format-types))                                                                                     | None          |
+| `:`           | `:`                                                                    | Add to the end of a format specifier to not have to insert a space after it                                                         | None          |
+
+Every single one of the above values is optional, but must be included in that order.
+
+## Format types
+
+| Character | Purpose                                                      | Example                    |
+| :-------: | ------------------------------------------------------------ | -------------------------- |
+|    `?`    | Debug formatting (`util.inspect` rather than `toString`)     | `[10]` -> `[10]`           |
+|    `o`    | Octal number formatting                                      | `10` -> `12` or `0o12`     |
+|    `x`    | Hexadecimal number formatting                                | `10` -> `a` or `0xa`       |
+|    `X`    | Uppercase hexadecimal number formatting                      | `10` -> `A` or `0xA`       |
+|    `b`    | Binary number formatting                                     | `10` -> `1010` or `0b1010` |
+|    `e`    | Scientific notation number formatting                        | `10` -> `1e1`              |
+|    `E`    | Uppercase scientific notation number formatting              | `10` -> `1E1`              |
+|    `n`    | Ordinal-suffixed number formatting                           | `10` -> `10th`             |
+|    `N`    | Uppercase ordinal-suffixed number formatting                 | `10` -> `10TH`             |
+
+## Examples
+
+`${"abc"}:+:!` Will capitalise `"abc"` with an exclamation mark right after it, ie. `ABC!`
+
+`${15}:#08x` Will convert `15` to hexadecimal, add `0x` and pad it with 0s until it is 8 characters wide, ie. `0x00000F`
+
+`${1.2345678}:,^10.${3}` will round `1.2345678` to 3 decimal places and center align it with `,` until it is 10 characters wide, ie. `,,1.234,,,`
+
+## rsformat specifiers for those familiar with Rust formatting
+
+This implementation parses formatting very similarly to Rust, but differing in a few key ways:
+
+- Rather than escaping the braces using `{{` or `}}`, the formatting colon can be escaped using `::`.
+- Different parameters are referenced using `rs.ref(n)` rather than the number literal `n`.
+- To separate a formatting specifier from the rest of the string without adding a space, an extra closing colon must be added (eg. `:#?:foo` - specifier gets parsed as `:#?`)
+- The `-` sign (unused in Rust) will add a space if the number is positive to align it with negative numbers without showing a `+`.
+- When used on strings, `+` and `-` sign specifiers will conver them to uppercase and lowercase respectively
+- Pointer format type `p` is unsupported.
+- Hexadecimal debug types `x?` and `X?` are unsupported. 
+- Specifying precision dynamically with `*` is unsupported. Instead, precision and width can both be specified dynamically by using a separate number parameter in place of the number.
+- New format types have been added:
+    - `N` for uppercase ordinal suffixing of numbers (rounded to integers)
+    - `n` for lowercase ordinal suffixing of numbers (rounded to integers)

package/lib/format.d.ts

@@ -1,3 +1,4 @@
+import util from 'node:util';
 /**
  * Type representing a string formatted by `rs`.
  * An extension of `String`.
@@ -43,4 +44,6 @@ type FormatSpecifier = {
  * @returns `param` as a debug-colored and raw formatted string
  */
 export declare function formatParam(param: any, format: FormatSpecifier): [string, string];
+/** Re-export of node's `util.styleText`. */
+export declare const style: typeof util.styleText;
 export {};

package/lib/format.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RsString = void 0;
+exports.style = exports.RsString = void 0;
 exports.buildString = buildString;
 exports.formatParam = formatParam;
 const node_util_1 = __importDefault(require("node:util"));
@@ -103,7 +103,7 @@ function buildString(strings, params) {
                 idx++;
             width = Number(string.substring(width_substring_start, idx));
         }
-        else if (idx == string.length) {
+        else if (idx == string.length && i < params.length) {
             // Grab the next parameter and fuse the string with the next one
             width = params[i];
             if (typeof width != 'number')
@@ -116,7 +116,7 @@ function buildString(strings, params) {
                 // Grab the next parameter and fuse the string with the next one
                 precision = params[i];
                 if (typeof precision != 'number')
-                    throw error(i - 1, idx, `Expected a number or number parameter for precision specifier after . (found ${string[idx] ? "'" + string[idx] + "'" : typeof width + ' parameter'}).\nIf the next parameter was not meant to be a precision number, add a : to the end of the formatting specifier.`);
+                    throw error(i - 1, idx, `Expected a number or number parameter for precision specifier after . (found ${string[idx] ? "'" + string[idx] + "'" : typeof precision + ' parameter'}).\nIf the next parameter was not meant to be a precision number, add a : to the end of the formatting specifier.`);
                 string += strings[++i];
             }
             else {
@@ -176,69 +176,80 @@ function buildString(strings, params) {
  */
 function formatParam(param, format) {
     let param_type = typeof param;
+    let base = 10;
+    switch (format.type) {
+        case 'o':
+            base = 8;
+            break;
+        case 'x':
+        case 'X':
+            base = 16;
+            break;
+        case 'b':
+            base = 2;
+            break;
+    }
+    let param_raw;
     let param_colored = "";
-    // embed RsStrings directly
+    // embed Strings directly
     if (param instanceof String && format.type != '?') {
+        param_raw = param.toString(false);
         param_colored = param.toString(true);
-        param = param.toString(false);
     }
     else
         switch (format.type) {
             // Process format type
             case 'o':
-                param = param.toString(8);
-                break;
             case 'x':
-                param = param.toString(16);
-                break;
             case 'X':
-                param = param.toString(16).toUpperCase();
-                break;
             case 'b':
-                param = param.toString(2);
+                param_raw = roundInBase(param, base, format.precision);
+                if (format.type == "X")
+                    param_raw = param_raw.toUpperCase();
                 break;
             case 'e':
             case 'E':
                 if (param_type != 'number' && param_type != 'bigint') {
-                    param = param.toString();
+                    param_raw = param.toString();
                     break;
                 }
-                param = param.toLocaleString('en-US', { notation: 'scientific', maximumFractionDigits: 20 });
+                param_raw = param.toLocaleString('en-US', { notation: 'scientific', maximumFractionDigits: 20 });
                 if (format.type == 'e')
-                    param = param.toLowercase();
+                    param_raw = param_raw.toLowerCase();
+                // Do not pad with zeroes when using scientific formatting
+                format.pad_zeroes = false;
                 break;
             case 'n':
             case 'N':
                 if (param_type != 'number' && param_type != 'bigint') {
-                    param = param.toString();
+                    param_raw = param.toString();
                     break;
                 }
                 // Round and add suffix
                 if (param_type == 'number')
                     param = Math.round(param);
-                param = param.toString();
-                let last_2_digits = param.substring(param.length - 2);
+                param_raw = param.toString();
+                let last_2_digits = param_raw.substring(param_raw.length - 2);
                 if (last_2_digits == '11' || last_2_digits == '12' || last_2_digits == '13') {
-                    param = param + 'th';
+                    param_raw += 'th';
                 }
                 else
                     switch (last_2_digits[last_2_digits.length - 1]) {
                         case '1':
-                            param = param + 'st';
+                            param_raw += 'st';
                             break;
                         case '2':
-                            param = param + 'nd';
+                            param_raw += 'nd';
                             break;
                         case '3':
-                            param = param + 'rd';
+                            param_raw += 'rd';
                             break;
-                        default: param = param + 'th';
+                        default: param_raw += 'th';
                     }
                 if (format.type == 'N')
-                    param = param.toUpperCase();
-                // Do not pad with zeroes or align to precision when using ordinal formatting
+                    param_raw = param_raw.toUpperCase();
+                // Do not pad with zeroes  when using ordinal formatting
                 format.pad_zeroes = false;
-                format.precision = -1;
                 break;
             case '?':
                 param_colored = node_util_1.default.inspect(param, {
@@ -246,32 +257,25 @@ function formatParam(param, format) {
                     colors: true,
                     compact: !format.pretty
                 });
-                param = node_util_1.default.stripVTControlCharacters(param_colored);
+                param_raw = node_util_1.default.stripVTControlCharacters(param_colored);
                 // Do not force sign, pad with zeroes or align to precision when using debug formatting
                 param_type = 'string';
+                // format.force_sign = '';
                 break;
             default:
-                param = param.toString();
+                param_raw = roundInBase(param, base, format.precision);
                 break;
         }
     ;
-    // Compute radix-point precision on numbers
-    if (param_type == 'number' && format.precision != -1) {
-        let [pre, post] = param.split('.');
-        if (!format.precision) { // precision = 0, do not include radix point
-            param = pre;
-        }
-        else {
-            post = ((post || '') + '0'.repeat(format.precision)).slice(0, format.precision);
-            param = pre + '.' + post;
-        }
+    if (param_type == 'string' && format.force_sign != '') {
+        param_raw = format.force_sign == '+' ? param_raw.toUpperCase() : param_raw.toLowerCase();
     }
     // let filled = false;
     if ((param_type == 'number') || (param_type == 'bigint')) {
         // Compute parameter sign
-        let maybe_sign = param.substring(0, 1);
+        let maybe_sign = param_raw.substring(0, 1);
         if (maybe_sign === '-') {
-            param = param.substring(1, param.length);
+            param_raw = param_raw.substring(1, param_raw.length);
         }
         else if (format.force_sign == '+') {
             maybe_sign = '+';
@@ -300,19 +304,20 @@ function formatParam(param, format) {
         //pad with zeroes if specified  
         if (format.pad_zeroes) {
             // filled = true;
-            while (param.length < format.width - maybe_sign.length) {
-                param = '0' + param;
+            while (param_raw.length < format.width - maybe_sign.length) {
+                param_raw = '0' + param_raw;
             }
         }
-        param = maybe_sign + param;
+        param_raw = maybe_sign + param_raw;
     }
     if (param_colored == "")
-        param_colored = param;
-    if (format.width > param.length) {
+        param_colored = param_raw;
+    let visible_length = [...param_raw].length;
+    if (format.width > visible_length) {
         // Compute fill/align
         let left = '';
         let right = '';
-        let diff = format.width - param.length;
+        let diff = format.width - visible_length;
         switch (format.align) {
             case '>':
                 left = format.fill.repeat(diff);
@@ -326,8 +331,37 @@ function formatParam(param, format) {
                 right = format.fill.repeat(diff / 2 + diff % 2);
                 break;
         }
-        param = left + param + right;
+        param_raw = left + param_raw + right;
         param_colored = left + param_colored + right;
     }
-    return [param_colored, param];
+    return [param_colored, param_raw];
+}
+/**
+ * Helper function to round a number to a given precision in a given base.
+ * Will also truncate strings to the desired length.
+ */
+function roundInBase(n, base, precision) {
+    if (typeof n == "string") {
+        if (precision == -1)
+            return n;
+        return n.slice(0, precision);
+    }
+    if (typeof n != "number" && typeof n != "bigint") {
+        return n.toString();
+    }
+    if (precision < 0) {
+        return n.toString(base);
+    }
+    if (precision == 0) {
+        return (typeof n == "bigint" ? n : Math.round(n)).toString(base);
+    }
+    const factor = base ** precision;
+    const rounded = typeof n == "bigint" ? n * BigInt(factor) : Math.round((n + Number.EPSILON) * factor);
+    const str = rounded.toString(base);
+    // Insert radix point from the right
+    const intPart = str.slice(0, -precision) || "0";
+    const fracPart = str.slice(-precision).padStart(precision, "0");
+    return intPart + "." + fracPart;
 }
+/** Re-export of node's `util.styleText`. */
+exports.style = node_util_1.default.styleText;

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { RsString } from './format';
+import { RsString, style } from './format';
 export { print, println, eprint, eprintln, dbg } from './print';
 type ParameterReference = {
     __rs_param_ref: number;
@@ -25,6 +25,11 @@ type rs = {
      * @returns A reference to the `n`th parameter
      */
     ref: (n: number) => ParameterReference;
+    /**
+     * Format a string using one or more of [the modifiers provided by node's `util` module](https://nodejs.org/docs/latest-v22.x/api/util.html#modifiers).
+     * This is a re-export of `util.styleText`.
+     */
+    style: typeof style;
 };
 /**
 * Tag to use Rust-style formatting in a template literal.

package/lib/index.js

@@ -23,3 +23,4 @@ Object.defineProperty(exports, "dbg", { enumerable: true, get: function () { ret
 exports.rs = ((strings, ...params) => new format_1.RsString(strings, params));
 exports.rs.raw = (strings, ...params) => (0, format_1.buildString)(strings, params).raw;
 exports.rs.ref = (n) => ({ __rs_param_ref: n });
+exports.rs.style = format_1.style;

package/lib/print.js

@@ -72,6 +72,6 @@ function eprintln(string) {
  * @param value Value to debug print
  */
 function dbg(value) {
-    eprintln((0, _1.rs) `${value}:?`);
+    eprintln((0, _1.rs) `${value}:#?`);
     return value;
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "rsformat",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
   "files": [
     "lib",
-    "README.MD"
+    "README.md",
+    "docs.md"
   ],
   "exports": {
     ".": {
@@ -30,11 +31,16 @@
   "author": "Alfio (https://github.com/p2js)",
   "license": "ISC",
   "devDependencies": {
-    "@types/node": "^22.8.6"
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.8.6",
+    "jest": "^30.2.0",
+    "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "tsc",
-    "prepublish": "pnpm build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "pnpm exec tsc",
+    "build:test": "pnpm exec tsc -p tsconfig.test.json",
+    "pretest": "pnpm build && pnpm build:test",
+    "test": "pnpm exec jest test-build",
+    "posttest": "rm -r test-build"
   }
 }