console-toolkit 1.2.8 → 1.2.10

package/README.md

@@ -1,19 +1,19 @@
 # console-toolkit [![NPM version][npm-img]][npm-url]
 
-[npm-img]:      https://img.shields.io/npm/v/console-toolkit.svg
-[npm-url]:      https://npmjs.org/package/console-toolkit
+[npm-img]: https://img.shields.io/npm/v/console-toolkit.svg
+[npm-url]: https://npmjs.org/package/console-toolkit
 
 `console-toolkit` is a set of tools to create rich CLI-based applications. It provides:
 
-* Styles based on [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code):
-  * [SGR](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR): colors and text styles
-  * [CSI](https://en.wikipedia.org/wiki/ANSI_escape_code#CSIsection): cursor and screen control
-* Bitmap graphics
-* Vector graphics based on [Turtle graphics](https://en.wikipedia.org/wiki/Turtle_graphics)
-* Curated sets of Unicode symbols
-* Tables with themes
-* Bar and column charts with themes
-* Various helpers and examples
+- Styles based on [ANSI escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code):
+  - [SGR](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR): colors and text styles
+  - [CSI](https://en.wikipedia.org/wiki/ANSI_escape_code#CSIsection): cursor and screen control
+- Bitmap graphics
+- Vector graphics based on [Turtle graphics](https://en.wikipedia.org/wiki/Turtle_graphics)
+- Curated sets of Unicode symbols
+- Tables with themes
+- Bar and column charts with themes
+- Various helpers and examples
 
 ## Visual examples
 
@@ -54,7 +54,15 @@ console.log(c`{{bold}}Hello, {{bright.cyan}}world!`);
 
 // chart
 
-const chart = drawChart([[2, 1, 2], [5, 1, 4], [1, 1], [3, 1, 3]], 50);
+const chart = drawChart(
+  [
+    [2, 1, 2],
+    [5, 1, 4],
+    [1, 1],
+    [3, 1, 3]
+  ],
+  50
+);
 for (const line of chart) console.log(line);
 
 // table
@@ -79,9 +87,44 @@ The output of the code is:
 npm install --save console-toolkit
 ```
 
+## Modules
+
+### Text containers
+
+| Module      | Import                    | Description                                                    |
+| ----------- | ------------------------- | -------------------------------------------------------------- |
+| **strings** | `console-toolkit/strings` | String array utilities: `getLength`, `clip`, `toStrings`       |
+| **Box**     | `console-toolkit/box`     | Rectangular text container — all lines equal width. Immutable. |
+| **Panel**   | `console-toolkit/panel`   | 2D cell grid with per-cell SGR state. Mutable.                 |
+
+### Styling and drawing
+
+| Module              | Import                               | Description                                               |
+| ------------------- | ------------------------------------ | --------------------------------------------------------- |
+| **Style**           | `console-toolkit/style`              | Fluent SGR styling API + `s`/`c` tagged template literals |
+| **draw-block**      | `console-toolkit/draw-block.js`      | Draw filled blocks and frames with block themes           |
+| **draw-block-frac** | `console-toolkit/draw-block-frac.js` | Fractional-width/height blocks (1/8th Unicode steps)      |
+| **symbols**         | `console-toolkit/symbols.js`         | Curated Unicode constants (blocks, shades, math, marks)   |
+
+### Packages
+
+| Package          | Import                             | Description                                                  |
+| ---------------- | ---------------------------------- | ------------------------------------------------------------ |
+| **ansi**         | `console-toolkit/ansi`             | Low-level ANSI CSI/SGR escape sequence handling              |
+| **table**        | `console-toolkit/table`            | Table renderer with line themes                              |
+| **charts**       | `console-toolkit/charts/...`       | Bar and column charts (plain, block, frac, stacked, grouped) |
+| **themes**       | `console-toolkit/themes/...`       | Line and block themes (unicode, ascii variants)              |
+| **plot**         | `console-toolkit/plot`             | Bitmap plotting (quadrant and braille characters)            |
+| **turtle**       | `console-toolkit/turtle`           | Turtle graphics for vector line drawing                      |
+| **spinner**      | `console-toolkit/spinner`          | Spinner animations and updatable output                      |
+| **output**       | `console-toolkit/output/...`       | Output helpers: Writer (streaming), Updater (in-place)       |
+| **alphanumeric** | `console-toolkit/alphanumeric/...` | Decorative Unicode number and letter sets                    |
+
 ## Documentation
 
-See [wiki](https://github.com/uhop/console-toolkit/wiki) for more details.
+See [wiki](https://github.com/uhop/console-toolkit/wiki) for detailed usage docs.
+
+For project internals see [ARCHITECTURE.md](./ARCHITECTURE.md). For development setup see [CONTRIBUTING.md](./CONTRIBUTING.md). For AI agent rules see [AGENTS.md](./AGENTS.md).
 
 ## License
 
@@ -89,15 +132,17 @@ BSD 3-Clause License
 
 ## Release history
 
-* 1.2.8 *Updated dev deps.*
-* 1.2.7 *Updated dev deps.*
-* 1.2.6 *Updated dev deps.*
-* 1.2.5 *Updated dev deps.*
-* 1.2.4 *Updated deps.*
-* 1.2.3 *Updated deps + more tests.*
-* 1.2.2 *Updated deps.*
-* 1.2.1 *Added support for `Bun.stringWidth()`.*
-* 1.2.0 *Refactored `strings`.*
-* 1.1.1 *Minor bugfixes in `Table`, some improvements, updated deps.*
-* 1.1.0 *Minor improvements, enhanced `Writer` and `Updater`.*
-* 1.0.0 *Initial release.*
+- 1.2.10 _Added TypeScript typings, JSDoc, minor bug fixes, updated dev deps._
+- 1.2.9 _Updated dev deps._
+- 1.2.8 _Updated dev deps._
+- 1.2.7 _Updated dev deps._
+- 1.2.6 _Updated dev deps._
+- 1.2.5 _Updated dev deps._
+- 1.2.4 _Updated deps._
+- 1.2.3 _Updated deps + more tests._
+- 1.2.2 _Updated deps._
+- 1.2.1 _Added support for `Bun.stringWidth()`._
+- 1.2.0 _Refactored `strings`._
+- 1.1.1 _Minor bugfixes in `Table`, some improvements, updated deps._
+- 1.1.0 _Minor improvements, enhanced `Writer` and `Updater`._
+- 1.0.0 _Initial release._

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "console-toolkit",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "description": "Toolkit to produce a fancy console output (boxes, tables, charts, colors).",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
+  "types": "src/index.d.ts",
   "exports": {
     "./*": "./src/*",
     "./ansi": "./src/ansi/index.js",
@@ -22,8 +23,14 @@
     "test:bun": "tape6-bun --flags FO",
     "test:deno": "tape6-deno --flags FO",
     "test:proc": "tape6-proc --flags FO",
-    "test:proc:bun": "bun run `npx tape6-proc --self` --flags FO",
-    "test:proc:deno": "deno run -A `npx tape6-proc --self` --flags FO -r -A"
+    "test:proc:bun": "bun run `tape6-proc --self` --flags FO",
+    "test:proc:deno": "deno run -A `tape6-proc --self` --flags FO -r -A",
+    "test:seq": "tape6-seq --flags FO",
+    "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
+    "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO",
+    "ts-check": "tsc --noEmit",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write ."
   },
   "github": "http://github.com/uhop/console-toolkit",
   "repository": {
@@ -32,15 +39,25 @@
   },
   "keywords": [
     "console",
+    "terminal",
+    "ansi",
+    "SGR",
+    "escape-sequences",
     "color",
     "colors",
+    "styled-text",
+    "text-formatting",
+    "unicode",
     "box",
     "boxes",
+    "panel",
     "table",
     "tables",
     "chart",
     "charts",
+    "plot",
     "turtle",
+    "spinner",
     "CLI",
     "TUI"
   ],
@@ -63,9 +80,12 @@
     ]
   },
   "devDependencies": {
+    "@types/node": "^25.3.0",
     "emoji-regex": "^10.6.0",
-    "get-east-asian-width": "^1.4.0",
-    "tape-six": "^1.5.1",
-    "tape-six-proc": "^1.2.1"
+    "get-east-asian-width": "^1.5.0",
+    "prettier": "^3.8.1",
+    "tape-six": "^1.7.2",
+    "tape-six-proc": "^1.2.3",
+    "typescript": "^5.9.3"
   }
 }

package/src/alphanumeric/arrows.d.ts

@@ -0,0 +1,48 @@
+/** Direction index for left-pointing arrows. */
+export const LEFT: 0;
+/** Direction index for up-pointing arrows. */
+export const UP: 1;
+/** Direction index for right-pointing arrows. */
+export const RIGHT: 2;
+/** Direction index for down-pointing arrows. */
+export const DOWN: 3;
+
+/** Simple arrows [left, up, right, down]. */
+export const simple: string[];
+/** Arrows with stroke [left, up, right, down]. */
+export const withStroke: string[];
+/** Wave arrows [left, up, right, down]. */
+export const wave: string[];
+/** Two-headed arrows [left, up, right, down]. */
+export const twoHeaded: string[];
+/** Arrows with tail [left, up, right, down]. */
+export const withTail: string[];
+/** Arrows from bar [left, up, right, down]. */
+export const fromBar: string[];
+/** Arrows with loop [left, up, right, down]. */
+export const withLoop: string[];
+/** Double arrows [left, up, right, down]. */
+export const double: string[];
+/** Triple arrows [left, up, right, down]. */
+export const triple: string[];
+/** Squiggle arrows [left, up, right, down]. */
+export const squiggle: string[];
+/** Dashed arrows [left, up, right, down]. */
+export const dashed: string[];
+/** Arrows to bar [left, up, right, down]. */
+export const toBar: string[];
+/** White (outline) arrows [left, up, right, down]. */
+export const white: string[];
+/** Arrows with vertical stroke [left, up, right, down]. */
+export const withVStroke: string[];
+/** Arrows with double vertical stroke [left, up, right, down]. */
+export const withDoubleVStroke: string[];
+/** Open-headed arrows [left, up, right, down]. */
+export const openHeaded: string[];
+
+/** Arrows with barb up [left, up, right, down]. */
+export const withBarbUp: string[];
+/** Arrows with barb down [left, up, right, down]. */
+export const withBarbDown: string[];
+/** Double arrows with stroke [left, up, right, down]. */
+export const doubleWithStroke: string[];

package/src/alphanumeric/arrows.js

@@ -1,6 +1,10 @@
+/** Direction index for left-pointing arrows. */
 export const LEFT = 0,
+  /** Direction index for up-pointing arrows. */
   UP = 1,
+  /** Direction index for right-pointing arrows. */
   RIGHT = 2,
+  /** Direction index for down-pointing arrows. */
   DOWN = 3;
 
 const toSymbol = (...args) => args.map(x => (typeof x == 'number' ? String.fromCodePoint(x) : x));
@@ -9,23 +13,42 @@ const makeArrowsH = codePoint => toSymbol(codePoint, ' ', codePoint + 1, ' ');
 
 // Arrows
 
+/** Simple arrows [left, up, right, down]. */
 export const simple = makeArrows(0x2190);
+/** Arrows with stroke [left, up, right, down]. */
 export const withStroke = makeArrowsH(0x219a);
+/** Wave arrows [left, up, right, down]. */
 export const wave = makeArrowsH(0x219c);
+/** Two-headed arrows [left, up, right, down]. */
 export const twoHeaded = makeArrows(0x219e);
+/** Arrows with tail [left, up, right, down]. */
 export const withTail = makeArrowsH(0x21a2);
+/** Arrows from bar [left, up, right, down]. */
 export const fromBar = makeArrows(0x21a4);
+/** Arrows with loop [left, up, right, down]. */
 export const withLoop = makeArrowsH(0x21ab);
+/** Double arrows [left, up, right, down]. */
 export const double = makeArrows(0x21d0);
+/** Triple arrows [left, up, right, down]. */
 export const triple = makeArrowsH(0x21da);
+/** Squiggle arrows [left, up, right, down]. */
 export const squiggle = makeArrowsH(0x21dc);
+/** Dashed arrows [left, up, right, down]. */
 export const dashed = makeArrows(0x21e0);
+/** Arrows to bar [left, up, right, down]. */
 export const toBar = makeArrowsH(0x21e4);
+/** White (outline) arrows [left, up, right, down]. */
 export const white = makeArrows(0x21e6);
+/** Arrows with vertical stroke [left, up, right, down]. */
 export const withVStroke = makeArrowsH(0x21f7);
+/** Arrows with double vertical stroke [left, up, right, down]. */
 export const withDoubleVStroke = makeArrowsH(0x21fa);
+/** Open-headed arrows [left, up, right, down]. */
 export const openHeaded = makeArrowsH(0x21fd);
 
+/** Arrows with barb up [left, up, right, down]. */
 export const withBarbUp = toSymbol(0x21bc, 0x21be, 0x21c1, 0x21c3);
+/** Arrows with barb down [left, up, right, down]. */
 export const withBarbDown = toSymbol(0x21bd, 0x21bf, 0x21c0, 0x21c2);
+/** Double arrows with stroke [left, up, right, down]. */
 export const doubleWithStroke = toSymbol(0x21cd, ' ', 0x21cf, ' ');

package/src/alphanumeric/fractions.d.ts

@@ -0,0 +1,65 @@
+/** A Unicode fraction character descriptor. */
+export interface Fraction {
+  /** The numerator of the fraction. */
+  numerator: number;
+  /** The denominator of the fraction. */
+  denominator: number;
+  /** The Unicode fraction symbol. */
+  symbol: string;
+  /** The numeric value of the fraction. */
+  value: number;
+}
+
+/** All available Unicode fraction characters, sorted by value. */
+export const fractions: Fraction[];
+/** Unicode fraction characters with denominator 3. */
+export const thirds: Fraction[];
+/** Unicode fraction characters with denominator 4. */
+export const quarters: Fraction[];
+/** Unicode fraction characters with denominator 5. */
+export const fifths: Fraction[];
+/** Unicode fraction characters with denominator 6. */
+export const sixths: Fraction[];
+/** Unicode fraction characters with denominator 8. */
+export const eighths: Fraction[];
+
+export {quarters as fourths};
+
+/** Finds the closest Unicode fraction symbol for a given value from all fractions.
+ * @param value - The value to approximate.
+ * @param useFractionForZero - If true, use a fraction symbol even for zero.
+ * @returns The integer part plus the closest fraction symbol.
+ */
+export function getFraction(value: number, useFractionForZero?: boolean): string;
+/** Finds the closest Unicode fraction symbol from thirds.
+ * @param value - The value to approximate.
+ * @param useFractionForZero - If true, use a fraction symbol even for zero.
+ * @returns The integer part plus the closest fraction symbol.
+ */
+export function getThirds(value: number, useFractionForZero?: boolean): string;
+/** Finds the closest Unicode fraction symbol from quarters.
+ * @param value - The value to approximate.
+ * @param useFractionForZero - If true, use a fraction symbol even for zero.
+ * @returns The integer part plus the closest fraction symbol.
+ */
+export function getQuarters(value: number, useFractionForZero?: boolean): string;
+/** Finds the closest Unicode fraction symbol from fifths.
+ * @param value - The value to approximate.
+ * @param useFractionForZero - If true, use a fraction symbol even for zero.
+ * @returns The integer part plus the closest fraction symbol.
+ */
+export function getFifths(value: number, useFractionForZero?: boolean): string;
+/** Finds the closest Unicode fraction symbol from sixths.
+ * @param value - The value to approximate.
+ * @param useFractionForZero - If true, use a fraction symbol even for zero.
+ * @returns The integer part plus the closest fraction symbol.
+ */
+export function getSixths(value: number, useFractionForZero?: boolean): string;
+/** Finds the closest Unicode fraction symbol from eighths.
+ * @param value - The value to approximate.
+ * @param useFractionForZero - If true, use a fraction symbol even for zero.
+ * @returns The integer part plus the closest fraction symbol.
+ */
+export function getEighths(value: number, useFractionForZero?: boolean): string;
+
+export {getQuarters as getFourths};

package/src/alphanumeric/fractions.js

@@ -1,3 +1,7 @@
+/** All available Unicode fraction characters, sorted by value.
+ * Each entry has `numerator`, `denominator`, `symbol`, and `value` properties.
+ * @type {{numerator: number, denominator: number, symbol: string, value: number}[]}
+ */
 export const fractions = [
   [1, 7, '\u2150'],
   [1, 9, '\u2151'],
@@ -24,10 +28,25 @@ export const fractions = [
 
 const pick = denominator => fractions.filter(x => !(denominator % x.denominator));
 
+/** Unicode fraction characters with denominator 3.
+ * @type {import('./fractions.js').Fraction[]}
+ */
 export const thirds = pick(3);
+/** Unicode fraction characters with denominator 4.
+ * @type {import('./fractions.js').Fraction[]}
+ */
 export const quarters = [{numerator: 0, denominator: 4, symbol: '0', value: 0}, ...pick(4)];
+/** Unicode fraction characters with denominator 5.
+ * @type {import('./fractions.js').Fraction[]}
+ */
 export const fifths = [{numerator: 0, denominator: 5, symbol: '0', value: 0}, ...pick(5)];
+/** Unicode fraction characters with denominator 6.
+ * @type {import('./fractions.js').Fraction[]}
+ */
 export const sixths = pick(6);
+/** Unicode fraction characters with denominator 8.
+ * @type {import('./fractions.js').Fraction[]}
+ */
 export const eighths = [{numerator: 0, denominator: 8, symbol: '0', value: 0}, ...pick(8)];
 
 export {quarters as fourths};
@@ -72,11 +91,41 @@ const findSymbol = (fractions, value, useFractionForZero) => {
   return (int || '') + chosen.symbol;
 };
 
+/** Finds the closest Unicode fraction symbol for a given value.
+ * @param {number} value - The value to approximate.
+ * @param {boolean} [useFractionForZero] - If true, use a fraction symbol even for zero.
+ * @returns {string} The integer part plus the closest fraction symbol.
+ */
 export const getFraction = (value, useFractionForZero) => findSymbol(fractions, value, useFractionForZero);
+/** Finds the closest Unicode fraction symbol from thirds.
+ * @param {number} value - The value to approximate.
+ * @param {boolean} [useFractionForZero] - If true, use a fraction symbol even for zero.
+ * @returns {string} The integer part plus the closest fraction symbol.
+ */
 export const getThirds = (value, useFractionForZero) => findSymbol(thirds, value, useFractionForZero);
+/** Finds the closest Unicode fraction symbol from quarters.
+ * @param {number} value - The value to approximate.
+ * @param {boolean} [useFractionForZero] - If true, use a fraction symbol even for zero.
+ * @returns {string} The integer part plus the closest fraction symbol.
+ */
 export const getQuarters = (value, useFractionForZero) => findSymbol(quarters, value, useFractionForZero);
+/** Finds the closest Unicode fraction symbol from fifths.
+ * @param {number} value - The value to approximate.
+ * @param {boolean} [useFractionForZero] - If true, use a fraction symbol even for zero.
+ * @returns {string} The integer part plus the closest fraction symbol.
+ */
 export const getFifths = (value, useFractionForZero) => findSymbol(fifths, value, useFractionForZero);
+/** Finds the closest Unicode fraction symbol from sixths.
+ * @param {number} value - The value to approximate.
+ * @param {boolean} [useFractionForZero] - If true, use a fraction symbol even for zero.
+ * @returns {string} The integer part plus the closest fraction symbol.
+ */
 export const getSixths = (value, useFractionForZero) => findSymbol(sixths, value, useFractionForZero);
+/** Finds the closest Unicode fraction symbol from eighths.
+ * @param {number} value - The value to approximate.
+ * @param {boolean} [useFractionForZero] - If true, use a fraction symbol even for zero.
+ * @returns {string} The integer part plus the closest fraction symbol.
+ */
 export const getEighths = (value, useFractionForZero) => findSymbol(eighths, value, useFractionForZero);
 
 export {getQuarters as getFourths};

package/src/alphanumeric/number-formatters.d.ts

@@ -0,0 +1,91 @@
+/** Configuration for formatting time values. */
+export interface TimeFormat {
+  /** The scale factor to apply to values. */
+  scale: number;
+  /** Number of decimal places. */
+  precision: number;
+  /** The time unit suffix (e.g., 'ms', 's', 'μs'). */
+  unit: string;
+}
+
+/** Prepares a time format configuration for a set of values.
+ * @param values - The time values to analyze.
+ * @param scale - Initial scale factor (default: 1).
+ * @param useUnicode - If true, use Unicode unit symbols (e.g., μs).
+ * @returns A TimeFormat configuration.
+ */
+export function prepareTimeFormat(values: number[], scale?: number, useUnicode?: boolean): TimeFormat;
+
+/** Options for `formatTime()`. */
+export interface FormatTimeOptions extends TimeFormat {
+  /** If true, do not round the fractional part. */
+  keepFractionAsIs?: boolean;
+}
+
+/** Formats a time value using a prepared format configuration.
+ * @param value - The time value to format.
+ * @param format - The format configuration from `prepareTimeFormat()`.
+ * @returns The formatted time string.
+ */
+export function formatTime(value: number, format: FormatTimeOptions): string;
+
+/** Options for number formatting functions. */
+export interface FormatNumberOptions {
+  /** Thousands separator character (default: ','). */
+  comma?: string;
+  /** If true, always show the sign. */
+  keepSign?: boolean;
+  /** Number of decimal places. */
+  decimals?: number;
+  /** If true, do not round the fractional part. */
+  keepFractionAsIs?: boolean;
+  /** Decimal point character (default: '.'). */
+  dot?: string;
+}
+
+/** Formats an integer with optional comma separators and sign.
+ * @param value - The integer to format.
+ * @param options - Formatting options.
+ * @returns The formatted string.
+ */
+export function formatInteger(value: number, options?: FormatNumberOptions): string;
+/** Formats a number with optional decimals, comma separators, and sign.
+ * @param value - The number to format.
+ * @param options - Formatting options.
+ * @returns The formatted string.
+ */
+export function formatNumber(value: number, options?: FormatNumberOptions): string;
+/** Formats a number with SI abbreviations (k, M, G, T).
+ * @param value - The number to format.
+ * @param options - Formatting options.
+ * @returns The abbreviated string.
+ */
+export function abbrNumber(value: number, options?: FormatNumberOptions): string;
+
+/** Simplifies the exponent notation of a number string.
+ * @param s - The number or string to simplify.
+ * @param options - Options.
+ * @returns The simplified string.
+ */
+export function simplifyExponent(s: string | number, options?: {keepExpPlus?: boolean}): string;
+
+/** Result of comparing two numbers. */
+export interface CompareDifferenceResult {
+  /** True if `a < b`. */
+  less: boolean;
+  /** True if the values are effectively equal. */
+  equality?: boolean;
+  /** True if the difference is infinite. */
+  infinity?: boolean;
+  /** Formatted percentage difference, if applicable. */
+  percentage?: string;
+  /** Formatted ratio string, if applicable. */
+  ratio?: string;
+}
+
+/** Compares two positive numbers and returns a description of their difference.
+ * @param a - First number.
+ * @param b - Second number.
+ * @returns An object describing the difference.
+ */
+export function compareDifference(a: number, b: number): CompareDifferenceResult;

package/src/alphanumeric/number-formatters.js

@@ -3,6 +3,12 @@
 const units = ['s', 'ms', 'μs', 'ns', 'ps'],
   unicodeUnits = ['s', '㎳', '㎲', '㎱', '㎰'];
 
+/** Prepares a time format configuration for a set of values.
+ * @param {number[]} values - Array of time values.
+ * @param {number} [scale=1] - Scale factor.
+ * @param {boolean} [useUnicode] - If true, use Unicode unit symbols.
+ * @returns {{scale: number, precision: number, unit: string}} Format configuration.
+ */
 export const prepareTimeFormat = (values, scale = 1, useUnicode) => {
   let mx = -1000,
     mn = 1000;
@@ -22,6 +28,11 @@ export const prepareTimeFormat = (values, scale = 1, useUnicode) => {
   return {scale, precision: digits - mx, unit: (useUnicode ? unicodeUnits : units)[i]};
 };
 
+/** Formats a time value using a prepared format configuration.
+ * @param {number} value - The time value.
+ * @param {{scale: number, precision: number, unit: string}} format - Format from `prepareTimeFormat`.
+ * @returns {string} Formatted time string.
+ */
 export const formatTime = (value, format) => {
   let result = (value * format.scale).toFixed(format.precision);
   if (format.precision > 0 && !format.keepFractionAsIs) result = result.replace(/\.0+$/, '');
@@ -41,11 +52,28 @@ const putCommasIn = (s, options) => {
   );
 };
 
+/** Formats an integer with optional comma separators and sign.
+ * @param {number} value - The integer value.
+ * @param {object} [options] - Options.
+ * @param {string} [options.comma=','] - Thousands separator.
+ * @param {boolean} [options.keepSign] - If true, prefix positive numbers with '+'.
+ * @returns {string} Formatted string.
+ */
 export const formatInteger = (value, options) =>
   isNaN(value)
     ? ''
     : (value < 0 ? '-' : options?.keepSign ? '+' : '') + putCommasIn(Math.abs(value).toFixed(0), options);
 
+/** Formats a number with optional decimals, comma separators, and sign.
+ * @param {number} value - The number.
+ * @param {object} [options] - Options.
+ * @param {number} [options.decimals=0] - Number of decimal places.
+ * @param {string} [options.comma=','] - Thousands separator.
+ * @param {string} [options.dot='.'] - Decimal separator.
+ * @param {boolean} [options.keepSign] - If true, prefix positive numbers with '+'.
+ * @param {boolean} [options.keepFractionAsIs] - If true, don't strip trailing zeros.
+ * @returns {string} Formatted string.
+ */
 export const formatNumber = (value, options) => {
   if (isNaN(value)) return '';
   const decimals = options?.decimals ?? 0;
@@ -65,6 +93,11 @@ export const formatNumber = (value, options) => {
 const exp = [0, 0, 0, 0, 3, 3, 6, 6, 6, 9, 9, 9, 12];
 const abbr = '***k**M**G**T';
 
+/** Formats a number with SI abbreviations (k, M, G, T).
+ * @param {number} value - The number.
+ * @param {object} [options] - Options (same as `formatNumber`).
+ * @returns {string} Abbreviated formatted string.
+ */
 export const abbrNumber = (value, options) => {
   if (isNaN(value)) return '';
   const decimals = options?.decimals ?? 0;
@@ -93,9 +126,20 @@ export const abbrNumber = (value, options) => {
   );
 };
 
+/** Simplifies the exponent notation of a number string.
+ * @param {string|number} s - The number or string.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.keepExpPlus] - If true, keep the '+' in the exponent.
+ * @returns {string} Simplified string.
+ */
 export const simplifyExponent = (s, {keepExpPlus} = {}) =>
   String(s).replace(new RegExp('\\.?0*e' + (keepExpPlus ? '' : '\\+?'), 'i'), 'e');
 
+/** Compares two positive numbers and returns a description of their difference.
+ * @param {number} a - First value.
+ * @param {number} b - Second value.
+ * @returns {{less: boolean, equality?: boolean, infinity?: boolean, percentage?: string, ratio?: string}}
+ */
 export const compareDifference = (a, b) => {
   // works only on positive numbers
   a = Math.abs(a);
@@ -111,7 +155,7 @@ export const compareDifference = (a, b) => {
   if (diff === Infinity) return {less, infinity: true};
 
   if (diff < 2) {
-    const percentage = absDiff / (less ? a : b) * 100;
+    const percentage = (absDiff / (less ? a : b)) * 100;
     if (percentage < 0.001) return {less, equality: true};
     if (percentage < 1) return {less, percentage: formatNumber(percentage, {decimals: 3})};
     if (percentage < 10) return {less, percentage: formatNumber(percentage, {decimals: 2})};

package/src/alphanumeric/roman.d.ts

@@ -0,0 +1,15 @@
+/** Converts a positive integer (1-3999) to a Roman numeral string using ASCII characters.
+ * @param value - The integer to convert.
+ * @returns The Roman numeral string.
+ */
+export function toRoman(value: number): string;
+/** Converts a positive integer (1-3999) to a Roman numeral string using Unicode characters.
+ * @param value - The integer to convert.
+ * @returns The Unicode Roman numeral string.
+ */
+export function toRomanUnicode(value: number): string;
+/** Converts a positive integer (1-3999) to a lowercase Unicode Roman numeral string.
+ * @param value - The integer to convert.
+ * @returns The lowercase Unicode Roman numeral string.
+ */
+export function toRomanLowerUnicode(value: number): string;

package/src/alphanumeric/roman.js

@@ -24,6 +24,10 @@ const romanGroup = (value, one, five, ten) => {
   return one + ten;
 };
 
+/** Converts a positive integer (1-3999) to a Roman numeral string using ASCII characters.
+ * @param {number} value - Integer between 1 and 3999.
+ * @returns {string} Roman numeral string.
+ */
 export const toRoman = value => {
   value = Math.round(value);
   if (value < 1 || value > 3999)
@@ -82,5 +86,13 @@ const toRomanUnicodeFn = (roman, L, C, D, M) => value => {
   return result.reverse().join('');
 };
 
+/** Converts a positive integer (1-3999) to a Roman numeral string using Unicode Roman numeral characters.
+ * @param {number} value - Integer between 1 and 3999.
+ * @returns {string} Unicode Roman numeral string.
+ */
 export const toRomanUnicode = toRomanUnicodeFn(roman, upperL, upperC, upperD, upperM);
+/** Converts a positive integer (1-3999) to a lowercase Unicode Roman numeral string.
+ * @param {number} value - Integer between 1 and 3999.
+ * @returns {string} Lowercase Unicode Roman numeral string.
+ */
 export const toRomanLowerUnicode = toRomanUnicodeFn(romanLower, lowerL, lowerC, lowerD, lowerM);