rsformat 0.2.3 → 0.2.4

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.d.ts

@@ -10,8 +10,7 @@ export declare function format(str: string, ...params: any[]): string;
  *
  * @param str String used for formatting
  * @param params Parameters to be inserted into the format string
- * @param options Options passed into formatting
- * @param options.colors Whether to use colors in debug formatting
+ * @param options Options passed into formatting (Whether to use colors in debug formatting - false by default)
  */
 export declare function fmt_raw(str: string, params: any[], options?: {
     colors: boolean;

package/lib/format.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fmt_raw = exports.format = void 0;
+exports.format = format;
+exports.fmt_raw = fmt_raw;
 const node_util_1 = require("node:util");
 /**
  * Regex to match for possible formatting insertion points.
@@ -29,14 +30,12 @@ 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.
  *
  * @param str String used for formatting
  * @param params Parameters to be inserted into the format string
- * @param options Options passed into formatting
- * @param options.colors Whether to use colors in debug formatting
+ * @param options Options passed into formatting (Whether to use colors in debug formatting - false by default)
  */
 function fmt_raw(str, params, options = { colors: false }) {
     // Counter used for insertion of unnumbered values
@@ -130,18 +129,14 @@ function fmt_raw(str, params, options = { colors: false }) {
         // Compute radix-point precision on numbers
         if (param_type == 'number' && $precision) {
             let [pre, post] = param.split('.');
-            if (post === undefined) {
-                post = '';
-            }
             let precision = +$precision.substring(1, $precision.length);
-            if (post.length > precision) {
-                post = post.substring(0, precision);
+            if (!precision) { // precision = 0, do not include radix point
+                param = pre;
+            }
+            else {
+                post = ((post || '') + '0'.repeat(precision)).slice(0, precision);
+                param = pre + '.' + post;
             }
-            else
-                while (post.length < precision) {
-                    post = post + '0';
-                }
-            param = pre + '.' + post;
         }
         let width;
         if ($width === undefined) {
@@ -215,4 +210,3 @@ function fmt_raw(str, params, options = { colors: false }) {
     });
     return str;
 }
-exports.fmt_raw = fmt_raw;

package/lib/print.d.ts

@@ -1,5 +1,13 @@
-/// <reference types="node" />
 import { Writable } from 'node:stream';
+/**
+ * Create format printer functions with custom output/error streams.
+ *
+ * @param outStream Output stream (used by print and println - process.stdout by default)
+ * @param errStream Error stream (used by eprint and eprintln - process.stderr by default)
+ * @param options Options for the printer functions (Whether to color the debug formatting in the output - true by default)
+ *
+ * @returns an object with print, println, eprint and eprintln functions that print to the specified streams
+ */
 export declare function Printer(outStream?: Writable, errStream?: Writable, options?: {
     debugColors: boolean;
 }): {
@@ -34,4 +42,33 @@ export declare function Printer(outStream?: Writable, errStream?: Writable, opti
      */
     eprintln: (format_string: string, ...params: any[]) => void;
 };
-export declare const print: (format_string: string, ...params: any[]) => void, println: (format_string: string, ...params: any[]) => void, eprint: (format_string: string, ...params: any[]) => void, eprintln: (format_string: string, ...params: any[]) => void;
+/**
+ * Print a format string to process.stdout.
+ *
+ * @param format_string String used for formatting
+ * @param params Parameters to be inserted into the format string
+ */
+export declare const print: (format_string: string, ...params: any[]) => void;
+/**
+ * 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
+ */
+export declare const println: (format_string: string, ...params: any[]) => void;
+/**
+ * Print a format string to process.stderr.
+ *
+ * @param format_string String used for formatting
+ * @param params Parameters to be inserted into the format string
+ */
+export declare const eprint: (format_string: string, ...params: any[]) => void;
+/**
+ * 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
+ */
+export declare const eprintln: (format_string: string, ...params: any[]) => void;

package/lib/print.js

@@ -2,11 +2,20 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.eprintln = exports.eprint = exports.println = exports.print = exports.Printer = void 0;
+exports.eprintln = exports.eprint = exports.println = exports.print = void 0;
+exports.Printer = Printer;
 const node_process_1 = __importDefault(require("node:process"));
 const format_1 = require("./format");
+/**
+ * Create format printer functions with custom output/error streams.
+ *
+ * @param outStream Output stream (used by print and println - process.stdout by default)
+ * @param errStream Error stream (used by eprint and eprintln - process.stderr by default)
+ * @param options Options for the printer functions (Whether to color the debug formatting in the output - true by default)
+ *
+ * @returns an object with print, println, eprint and eprintln functions that print to the specified streams
+ */
 function Printer(outStream = node_process_1.default.stdout, errStream = node_process_1.default.stderr, options = { debugColors: true }) {
     return {
         /**
@@ -49,5 +58,66 @@ function Printer(outStream = node_process_1.default.stdout, errStream = node_pro
         },
     };
 }
-exports.Printer = Printer;
-_a = Printer(), exports.print = _a.print, exports.println = _a.println, exports.eprint = _a.eprint, exports.eprintln = _a.eprintln;
+// 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();
+const default_printer = Printer();
+/**
+ * Print a format string to process.stdout.
+ *
+ * @param format_string String used for formatting
+ * @param params Parameters to be inserted into the format string
+ */
+exports.print = default_printer.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
+ */
+exports.println = default_printer.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
+ */
+exports.eprint = default_printer.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
+ */
+exports.eprintln = default_printer.eprintln;

package/package.json

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