rsformat 0.2.4 → 0.2.5

package/README.md

@@ -1,170 +1,170 @@
-# 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`.
-
-## 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`.
-
-RSFormat provides alternative functions with standardised behaviour: its `format`, `println` and all other functions will always output in the same manner, and have a standardised syntax which will only print the initial string, formatted with the parameters provided afterwards.
-
-Rust formatting also includes a lot of convenient operators for formatting text, such as padding/alignment, printing numbers in a given base, specifying decimal precision, etc.. This makes it a more ergonomic and convenient approach to printing things to the console.
-
-## Usage
-
-you can install rsformat using [npm](https://www.npmjs.com/package/rsformat):
-
-```
-npm install rsformat
-```
-
-### Basic formatting and printing to console
-
-RSFormat functions are called using a format string, and any number of format arguments following it.
-
-Any instance of `{}` in the format strings will get replaced with a value.
-
-You can specify what value you want in the parameters by using a number inside the insertion point.
-
-```js
-import { format, println } from 'rsformat';      // ESM
-const { format, println } = require('rsformat'); // CommonJS
-
-let name = 'everyone';
-
-let greeting = format('Hello {}!', name); // Evaluates to the string 'Hello, everyone!'
-
-println('I have {1} apples and {0} oranges', 13, 14); // Will print 'I have 14 apples and 13 oranges' to the console
-```
-
-### Format Specifiers
-
-Format specifiers can be used by adding `:` inside the insertion point (after the optional argument number), and will format the value differently inside the string. See the [rust format docs](https://doc.rust-lang.org/std/fmt/#syntax) for more detailed information on format specifiers.
-
-This implementation differs from the rust one in a few ways:
-
-- Named arguments before or in format specifiers or in values aren't allowed, only numbers can be used.
-- The `-` sign (unused in rust) is unsupported.
-- Pointer format type `p` is unsupported.
-- Hexadecimal debug types `x?` and `X?` are unsupported. 
-- Specifying precision with `*` is unsupported.
-
-#### Different formatting types
-
-```js
-// Debug format specifier: ?, uses util.inspect rather than toString
-
-println('{}', { a: 1 }); //prints '[object Object]'
-println('{:?}', { a: 1 }); //prints "{ a:1 }"
-
-// Number base specifiers: x, X, b, o - for lower/uppercase hexadecimal, binary, octal
-
-format('{} is {0:x} in hex, {0:b} in binary and {0:o} in octal', 15); // '15 is f in hex, 1111 in binary and 17 in octal'
-
-// Scientific notation specifiers: e, E - for lower/uppercase scientific notation
-
-let hugeNumber = 1000n;
-format('{:E}', hugeNumber); // '1E3';
-```
-
-#### 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:
-
-```js
-/*
-Will print a pyramid of 'a's:
-'  a  '
-' aaa '
-'aaaaa'
-*/
-let pyramidLevels = ['a', 'aaa', 'aaaaa'];
-for(let value of pyramidLevels) {
-    println('{:^5}', value);
-}
-```
-
-```js
-format('{:.>7}', [1,2]); // '....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 non-compact `util.inspect` for debug printing (spanning multiple lines), and adding 0b/0o/0x as a prefix for the numbers formatted as powers of two.
-
-```js
-format('{:#X}', 255); // '0xFF'
-```
-
-#### Specific Number Formatting
-
-Specifically for `number` and `bigint` values, a 0 can be placed before the width to pad the number with 0s instead. This will account for signs and possible formatting differences.
-
-```js
-format('{:#07x}', 15) // '0x0000F'
-```
-
-Decimal precision can be specified for numbers by adding a . and specifying an integer for precision.
-
-```js
-format('{:.3}', 1.23456789); // '1.234'
-format('{:.3}', -1);         // '-1.000'
-```
-
-Adding a + to the formatting specifier will print the sign regardless of whether the number is negative.
-
-```js
-format('{:+}', 1); // '+1'
-```
-
-## Custom output
-
-If you want to use the print function to output to anything other than `process.stdout` and `process.stderr`, you can import the `Printer` function to create your own print functions, using any output and error streams that are instances of node's `Writable`.
-
-```ts
-// Custom output example (ts)
-import { Printer } from 'rsformat/print';
-import { Writable } from 'stream';
-
-let someOutputStream: Writable = /* ... */;
-let someErrorStream: Writable = /* ... */;
-
-let { print, println, eprint, eprintln } = Printer(someOutputStream, someErrorStream);
-```
-
-## A Note on Performance
-
-You might think that these utilities might have a performance impact on RSFormat's printing functions. And while they do, the functions are still consistently faster than `console.log`.
-
-A simple benchmark setup like the one below will demonstrate that `println` is more performant, even when doing things like base conversions and text alignment, compared to `console.log` logging a simple string:
-
-```js
-// benchmark.mjs
-import { println } from 'rsformat';
-
-const time = (fn, iter) => {
-    let time = Date.now();
-    while (iter-- > 0) {
-        fn();
-    }
-    return Date.now() - time;
-}
-
-let iterations = 100000;
-
-let logTime = time(() => console.log('hello'), iterations);
-let printlnTime = time(() => println('{:>+#7X}', 255), iterations);
-
-println('console.log time for {} executions: {}ms', iterations, logTime);
-println('rsformat.println time for {} executions: {}ms', iterations, printlnTime);
-```
-
-```
-> node benchmark.mjs
-...After a lot of output...
-
-console.log time for 100000 executions: 7217ms
-rsformat.println time for 100000 executions: 5900ms
-```
-
+# 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`.
+
+## 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`.
+
+RSFormat provides alternative functions with standardised behaviour: its `format`, `println` and all other functions will always output in the same manner, and have a standardised syntax which will only print the initial string, formatted with the parameters provided afterwards.
+
+Rust formatting also includes a lot of convenient operators for formatting text, such as padding/alignment, printing numbers in a given base, specifying decimal precision, etc.. This makes it a more ergonomic and convenient approach to printing things to the console.
+
+## Usage
+
+you can install rsformat using [npm](https://www.npmjs.com/package/rsformat):
+
+```
+npm install rsformat
+```
+
+### Basic formatting and printing to console
+
+RSFormat functions are called using a format string, and any number of format arguments following it.
+
+Any instance of `{}` in the format strings will get replaced with a value.
+
+You can specify what value you want in the parameters by using a number inside the insertion point.
+
+```js
+import { format, println } from 'rsformat';      // ESM
+const { format, println } = require('rsformat'); // CommonJS
+
+let name = 'everyone';
+
+let greeting = format('Hello {}!', name); // Evaluates to the string 'Hello, everyone!'
+
+println('I have {1} apples and {0} oranges', 13, 14); // Will print 'I have 14 apples and 13 oranges' to the console
+```
+
+### Format Specifiers
+
+Format specifiers can be used by adding `:` inside the insertion point (after the optional argument number), and will format the value differently inside the string. See the [rust format docs](https://doc.rust-lang.org/std/fmt/#syntax) for more detailed information on format specifiers.
+
+This implementation differs from the rust one in a few ways:
+
+- Named arguments before or in format specifiers or in values aren't allowed, only numbers can be used.
+- The `-` sign (unused in rust) is unsupported.
+- Pointer format type `p` is unsupported.
+- Hexadecimal debug types `x?` and `X?` are unsupported. 
+- Specifying precision with `*` is unsupported.
+
+#### Different formatting types
+
+```js
+// Debug format specifier: ?, uses util.inspect rather than toString
+
+println('{}', { a: 1 }); //prints '[object Object]'
+println('{:?}', { a: 1 }); //prints "{ a:1 }"
+
+// Number base specifiers: x, X, b, o - for lower/uppercase hexadecimal, binary, octal
+
+format('{} is {0:x} in hex, {0:b} in binary and {0:o} in octal', 15); // '15 is f in hex, 1111 in binary and 17 in octal'
+
+// Scientific notation specifiers: e, E - for lower/uppercase scientific notation
+
+let hugeNumber = 1000n;
+format('{:E}', hugeNumber); // '1E3';
+```
+
+#### 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:
+
+```js
+/*
+Will print a pyramid of 'a's:
+'  a  '
+' aaa '
+'aaaaa'
+*/
+let pyramidLevels = ['a', 'aaa', 'aaaaa'];
+for(let value of pyramidLevels) {
+    println('{:^5}', value);
+}
+```
+
+```js
+format('{:.>7}', [1,2]); // '....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 non-compact `util.inspect` for debug printing (spanning multiple lines), and adding 0b/0o/0x as a prefix for the numbers formatted as powers of two.
+
+```js
+format('{:#X}', 255); // '0xFF'
+```
+
+#### Specific Number Formatting
+
+Specifically for `number` and `bigint` values, a 0 can be placed before the width to pad the number with 0s instead. This will account for signs and possible formatting differences.
+
+```js
+format('{:#07x}', 15) // '0x0000F'
+```
+
+Decimal precision can be specified for numbers by adding a . and specifying an integer for precision.
+
+```js
+format('{:.3}', 1.23456789); // '1.234'
+format('{:.3}', -1);         // '-1.000'
+```
+
+Adding a + to the formatting specifier will print the sign regardless of whether the number is negative.
+
+```js
+format('{:+}', 1); // '+1'
+```
+
+## Custom output
+
+If you want to use the print function to output to anything other than `process.stdout` and `process.stderr`, you can import the `Printer` function to create your own print functions, using any output and error streams that are instances of node's `Writable`.
+
+```ts
+// Custom output example (ts)
+import { Printer } from 'rsformat/print';
+import { Writable } from 'stream';
+
+let someOutputStream: Writable = /* ... */;
+let someErrorStream: Writable = /* ... */;
+
+let { print, println, eprint, eprintln } = Printer(someOutputStream, someErrorStream);
+```
+
+## A Note on Performance
+
+You might think that these utilities might have a performance impact on RSFormat's printing functions. And while they do, the functions are still consistently faster than `console.log`.
+
+A simple benchmark setup like the one below will demonstrate that `println` is more performant, even when doing things like base conversions and text alignment, compared to `console.log` logging a simple string:
+
+```js
+// benchmark.mjs
+import { println } from 'rsformat';
+
+const time = (fn, iter) => {
+    let time = Date.now();
+    while (iter-- > 0) {
+        fn();
+    }
+    return Date.now() - time;
+}
+
+let iterations = 100000;
+
+let logTime = time(() => console.log('hello'), iterations);
+let printlnTime = time(() => println('{:>+#7X}', 255), iterations);
+
+println('console.log time for {} executions: {}ms', iterations, logTime);
+println('rsformat.println time for {} executions: {}ms', iterations, printlnTime);
+```
+
+```
+> node benchmark.mjs
+...After a lot of output...
+
+console.log time for 100000 executions: 7217ms
+rsformat.println time for 100000 executions: 5900ms
+```
+
 _Tested on node.js using a Windows laptop on an Intel core I7-1360P, on battery power. Performance will vary, but this benchmark was just to show that RSFormat has no performance penalty._

package/lib/format.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.format = format;
-exports.fmt_raw = fmt_raw;
+exports.fmt_raw = exports.format = void 0;
 const node_util_1 = require("node:util");
 /**
  * Regex to match for possible formatting insertion points.
@@ -30,6 +29,7 @@ const FORMAT_REGEX = (/\{{2}|\}{2}|\{(\d*?)(?::(?:(.?)(\^|>|<))?(\+)?(#)?(0)?(\d
 function format(str, ...params) {
     return fmt_raw(str, params);
 }
+exports.format = format;
 /**
  * Raw formatting behaviour function called by `format` and printing functions.
  *
@@ -104,8 +104,9 @@ function fmt_raw(str, params, options = { colors: false }) {
                 }
                 break;
             case '?':
-                // Do not force sign or align to precision when using inspect
+                // Do not force sign, pad with zeroes or align to precision when using debug formatting
                 $sign = undefined;
+                $pad_zeroes = undefined;
                 $precision = undefined;
                 true_length = (0, node_util_1.inspect)(param, {
                     depth: Infinity,
@@ -136,6 +137,8 @@ function fmt_raw(str, params, options = { colors: false }) {
             else {
                 post = ((post || '') + '0'.repeat(precision)).slice(0, precision);
                 param = pre + '.' + post;
+                // Update true length for fill/align
+                true_length = param.length;
             }
         }
         let width;
@@ -180,8 +183,10 @@ function fmt_raw(str, params, options = { colors: false }) {
                 filled = true;
                 while (param.length < width - maybe_sign.length) {
                     param = '0' + param;
+                    true_length++;
                 }
             }
+            true_length += maybe_sign.length;
             param = maybe_sign + param;
         }
         if (!filled && width > true_length) {
@@ -210,3 +215,4 @@ function fmt_raw(str, params, options = { colors: false }) {
     });
     return str;
 }
+exports.fmt_raw = fmt_raw;

package/lib/print.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { Writable } from 'node:stream';
 /**
  * Create format printer functions with custom output/error streams.

package/lib/print.js

@@ -3,8 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.eprintln = exports.eprint = exports.println = exports.print = void 0;
-exports.Printer = Printer;
+exports.eprintln = exports.eprint = exports.println = exports.print = exports.Printer = void 0;
 const node_process_1 = __importDefault(require("node:process"));
 const format_1 = require("./format");
 /**
@@ -58,38 +57,7 @@ function Printer(outStream = node_process_1.default.stdout, errStream = node_pro
         },
     };
 }
-// export const {
-//     /**
-//      * Print a format string to process.stdout.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     print,
-//     /**
-//      * Print a format string to process.stdout
-//      * and append a newline.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     println,
-//     /**
-//      * Print a format string to process.stderr.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     eprint,
-//     /**
-//      * Print a format string to process.stderr
-//      * and append a newline.
-//      * 
-//      * @param format_string String used for formatting
-//      * @param params Parameters to be inserted into the format string
-//      */
-//     eprintln
-// } = Printer();
+exports.Printer = Printer;
 const default_printer = Printer();
 /**
  * Print a format string to process.stdout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsformat",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
   "files": [
     "lib",
@@ -16,10 +16,6 @@
       "default": "./lib/*.js"
     }
   },
-  "scripts": {
-    "build": "tsc",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
   "keywords": [
     "fmt",
     "format",
@@ -36,5 +32,8 @@
   "devDependencies": {
     "@types/node": "^22.8.6"
   },
-  "packageManager": "pnpm@9.14.2+sha512.6e2baf77d06b9362294152c851c4f278ede37ab1eba3a55fda317a4a17b209f4dbb973fb250a77abc463a341fcb1f17f17cfa24091c4eb319cda0d9b84278387"
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
 }