rsformat 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # RSFormat
 
-RSFormat is a string formatting/printing library for JavaScript. It offers an alternative to the string formatting and printing provided by `console.log`.
+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
 
@@ -123,11 +123,48 @@ If you want to use the print function to output to anything other than `process.
 
 ```ts
 // Custom output example (ts)
-import { Printer } from 'rsformat-local/print';
+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

@@ -5,3 +5,14 @@
  * @param params Parameters to be inserted into the format string
  */
 export declare function format(str: string, ...params: any[]): string;
+/**
+ * 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
+ */
+export declare function fmt_raw(str: string, params: any[], options?: {
+    colors: boolean;
+}): string;

package/lib/format.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.format = void 0;
-const util_1 = require("util");
+exports.fmt_raw = exports.format = void 0;
+const node_util_1 = require("node:util");
 /**
  * Regex to match for possible formatting insertion points.
  * Similar to the way formatting is parsed in rust,
@@ -27,6 +27,18 @@ const FORMAT_REGEX = (/\{{2}|\}{2}|\{(\d*?)(?::(?:(.?)(\^|>|<))?(\+)?(#)?(0)?(\d
  * @param params Parameters to be inserted into the format string
  */
 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
+ */
+function fmt_raw(str, params, options = { colors: false }) {
     // Counter used for insertion of unnumbered values
     let param_counter = 0;
     str = str.replace(FORMAT_REGEX, ($, $param_number, $fill_character, $align_direction, $sign, $pretty, $pad_zeroes, $width, $precision, $type) => {
@@ -92,9 +104,9 @@ function format(str, ...params) {
                 }
                 break;
             case "?":
-                param = (0, util_1.inspect)(param, {
+                param = (0, node_util_1.inspect)(param, {
                     depth: Infinity,
-                    colors: true,
+                    colors: options.colors,
                     compact: $pretty !== '#'
                 });
                 break;
@@ -184,4 +196,4 @@ function format(str, ...params) {
     });
     return str;
 }
-exports.format = format;
+exports.fmt_raw = fmt_raw;

package/lib/print.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { Writable } from 'stream';
+import { Writable } from 'node:stream';
 export declare function Printer(outStream?: Writable, errStream?: Writable): {
     /**
      * Print a format string to an output stream (usually process.stdout).

package/lib/print.js

@@ -1,9 +1,13 @@
 "use strict";
+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;
+const node_process_1 = __importDefault(require("node:process"));
 const format_1 = require("./format");
-function Printer(outStream = process.stdout, errStream = process.stderr) {
+function Printer(outStream = node_process_1.default.stdout, errStream = node_process_1.default.stderr) {
     return {
         /**
          * Print a format string to an output stream (usually process.stdout).
@@ -12,7 +16,7 @@ function Printer(outStream = process.stdout, errStream = process.stderr) {
          * @param params Parameters to be inserted into the format string
          */
         print: function print(format_string, ...params) {
-            outStream.write((0, format_1.format)(format_string, ...params));
+            outStream.write((0, format_1.fmt_raw)(format_string, params, { colors: true }));
         },
         /**
          * Print a format string to an output stream (usually process.stdout)
@@ -22,7 +26,7 @@ function Printer(outStream = process.stdout, errStream = process.stderr) {
          * @param params Parameters to be inserted into the format string
          */
         println: function println(format_string, ...params) {
-            outStream.write((0, format_1.format)(format_string, ...params) + "\n");
+            outStream.write((0, format_1.fmt_raw)(format_string, params, { colors: true }) + '\n');
         },
         /**
          * Print a format string to an error stream (usually process.stderr).
@@ -31,7 +35,7 @@ function Printer(outStream = process.stdout, errStream = process.stderr) {
          * @param params Parameters to be inserted into the format string
          */
         eprint: function eprint(format_string, ...params) {
-            errStream.write((0, format_1.format)(format_string, ...params));
+            errStream.write((0, format_1.fmt_raw)(format_string, params, { colors: true }));
         },
         /**
          * Print a format string to an error stream (usually process.stderr)
@@ -41,7 +45,7 @@ function Printer(outStream = process.stdout, errStream = process.stderr) {
          * @param params Parameters to be inserted into the format string
          */
         eprintln: function eprintln(format_string, ...params) {
-            errStream.write((0, format_1.format)(format_string, ...params) + "\n");
+            errStream.write((0, format_1.fmt_raw)(format_string, params, { colors: true }) + '\n');
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rsformat",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Formatting/printing library for JavaScript that takes after rust's string formatting ",
   "files": [
     "lib",
@@ -28,11 +28,13 @@
     "println",
     "printf",
     "console",
-    "log"
+    "log",
+    "console.log"
   ],
   "author": "Alfio (https://github.com/p2js)",
   "license": "ISC",
   "devDependencies": {
     "@types/node": "^22.8.6"
-  }
+  },
+  "packageManager": "pnpm@9.14.2+sha512.6e2baf77d06b9362294152c851c4f278ede37ab1eba3a55fda317a4a17b209f4dbb973fb250a77abc463a341fcb1f17f17cfa24091c4eb319cda0d9b84278387"
 }