@yuhere/js-strings 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) @yuhere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# String Utilities
+
+A utility library aimed at providing common language-level helper functions (strings, dates, vars, etc.) in JavaScript/TypeScript projects.
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm install @yuhere/js-strings
+```
+
+## Usage
+
+Import the functions you need from the library:
+
+```javascript
+import {
+    s_pad,
+    s_left,
+    s_right,
+    s_ellipsis,
+    s_ellipsis_o,
+    s_xprint_extract_fmt,
+    s_xprint_fmts,
+    s_xprint,
+    s_glob
+} from '@yuhere/js-strings';
+```
+
+### String Utilities
+
+#### s_pad
+
+Pad a string to a fixed width.
+
+- `which`: padding direction, supports `'l'`, `'r'`, `'c'`
+- `padchar`: padding character, default is space
+- `is_trunc`: when `true`, truncates the string if it exceeds `width`
+
+```javascript
+import { s_pad } from '@yuhere/js-strings';
+
+console.log(s_pad('hello', 10, 'l', '-')); // '-----hello'
+console.log(s_pad('hello', 10, 'r', '-')); // 'hello-----'
+console.log(s_pad('hello', 10, 'c')); // '  hello   '
+console.log(s_pad('hello world', 5, 'r', ' ', true)); // 'hello'
+```
+
+#### s_left
+
+Get the leftmost characters of a string.
+
+```javascript
+import { s_left } from '@yuhere/js-strings';
+
+console.log(s_left('hello world', 5)); // 'hello'
+console.log(s_left('hello', 0)); // ''
+```
+
+#### s_right
+
+Get the rightmost characters of a string.
+
+```javascript
+import { s_right } from '@yuhere/js-strings';
+
+console.log(s_right('hello world', 5)); // 'world'
+console.log(s_right('hello', 0)); // ''
+```
+
+#### s_ellipsis
+
+Pad or truncate a string to a fixed width. When truncation happens, `...` is inserted according to the alignment.
+
+- `'l'`: keep the left part and put `...` at the end
+- `'r'`: keep the right part and put `...` at the beginning
+- `'c'`: keep both ends and put `...` in the middle
+
+```javascript
+import { s_ellipsis } from '@yuhere/js-strings';
+
+console.log(s_ellipsis('hello', 8)); // 'hello   '
+console.log(s_ellipsis('abcdefghijklmnopqrstuvwxyz', 10, 'l')); // 'abcdefg...'
+console.log(s_ellipsis('abcdefghijklmnopqrstuvwxyz', 10, 'r')); // '...tuvwxyz'
+console.log(s_ellipsis('abcdefghijklmnopqrstuvwxyz', 10, 'c')); // 'abcd...xyz'
+```
+
+#### s_ellipsis_o
+
+Options-object form of `s_ellipsis`, suitable when parameters come from configuration.
+
+```javascript
+import { s_ellipsis_o } from '@yuhere/js-strings';
+
+console.log(s_ellipsis_o('hello', { width: 8 })); // 'hello   '
+console.log(s_ellipsis_o('abcdefghijklmnopqrstuvwxyz', { width: 10, align: 'r' })); // '...tuvwxyz'
+```
+
+#### s_xprint_extract_fmt
+
+Parse a column format definition used by `s_xprint`.
+
+- string form: `"<width>[<align><padchar>]"`
+- object form: `{ width, align, padchar }`
+
+```javascript
+import { s_xprint_extract_fmt } from '@yuhere/js-strings';
+
+console.log(s_xprint_extract_fmt('8')); // { width: 8, align: 'l', padchar: undefined }
+console.log(s_xprint_extract_fmt('8r0')); // { width: 8, align: 'r', padchar: '0' }
+console.log(s_xprint_extract_fmt({ width: 12, align: 'l', padchar: '_' }));
+// { width: 12, align: 'l', padchar: '_' }
+```
+
+#### s_xprint_fmts
+
+Batch-convert multiple format definitions into normalized format objects.
+
+```javascript
+import { s_xprint_fmts } from '@yuhere/js-strings';
+
+console.log(s_xprint_fmts(['8', '6r0', { width: 10, align: 'l', padchar: '_' }]));
+// [
+//   { width: 8, align: 'l', padchar: undefined },
+//   { width: 6, align: 'r', padchar: '0' },
+//   { width: 10, align: 'l', padchar: '_' }
+// ]
+```
+
+#### s_xprint
+
+Format multiple columns into one line of fixed-width text. This is useful for CLI table rows, aligned logs, and report output.
+
+- `columns`: values to output
+- `formats`: per-column format definitions
+- `sep`: separator inserted between columns
+- `ellipsisEnd`: whether the last column should also be padded/truncated
+
+```javascript
+import { s_xprint } from '@yuhere/js-strings';
+
+console.log(
+    s_xprint({
+        columns: ['id', 7, 'abcdefghijklmnopqrstuvwxyz'],
+        formats: ['6l ', '4r0', '10l '],
+        sep: ' | '
+    })
+);
+// 'id     | 0007 | abcdefg...'
+
+console.log(
+    s_xprint({
+        columns: ['INFO', 'startup ok', 'this part is not truncated'],
+        formats: ['6l ', '12l ', '8l '],
+        sep: ' ',
+        ellipsisEnd: false
+    })
+);
+// 'INFO   startup ok   this part is not truncated'
+```
+
+#### s_glob
+
+Match a string against a simple glob pattern.
+
+Current public wrapper behavior uses the default glob conversion rules, which are suitable for common `*` pattern matching.
+
+```javascript
+import { s_glob } from '@yuhere/js-strings';
+
+console.log(s_glob('*.ts', 'index.ts')); // true
+console.log(s_glob('*.ts', 'index.js')); // false
+console.log(s_glob('src/*', 'src/strings.ts')); // true
+```
+
+## License
+
+MIT

package/lib/strings.d.ts

@@ -0,0 +1,228 @@
+type SAlign = "l" | "r" | "c";
+type SXPrintAlign = "l" | "r";
+interface SEllipsisOptions {
+    width: number;
+    align?: SAlign;
+    padchar?: string;
+}
+interface SXPrintFormat {
+    width: number;
+    align?: SXPrintAlign;
+    padchar?: string;
+}
+interface SXPrintParams {
+    columns: Array<string | number | null | undefined>;
+    formats?: Array<string | SXPrintFormat>;
+    sep?: string;
+    ellipsisEnd?: boolean;
+}
+/**
+ * String padding.
+ *
+ * @param text - Input text.
+ * @param width - Target width. If `undefined`, defaults to `text.length`.
+ * @param which - Padding side:
+ * - `"r"`: pad on the right (left-justified)
+ * - `"l"`: pad on the left (right-justified)
+ * - `"c"`: pad both sides (center)
+ * @param padchar - Padding character (single-column). Defaults to `" "`.
+ * @param is_trunc - If `true`, truncate `text` when it exceeds `width`.
+ * @returns Padded (or truncated) string with length `width`.
+ */
+export declare function s_pad(text: string, width?: number, which?: SAlign, padchar?: string, is_trunc?: boolean): string;
+/**
+ * Returns a string containing the specified number of characters from the left side of `str`.
+ *
+ * @param str - The source string.
+ * @param length - Number of characters to return.
+ * - If `length <= 0`, returns an empty string (`""`).
+ * - If `length >= str.length`, returns the entire `str`.
+ * @returns The leftmost `length` characters of `str`.
+ */
+export declare function s_left(str: string, length: number): string;
+/**
+ * Returns a string containing the specified number of characters from the right side of `str`.
+ *
+ * @param str - The source string.
+ * @param length - Number of characters to return.
+ * - If `length <= 0`, returns an empty string (`""`).
+ * - If `length >= str.length`, returns the entire `str`.
+ * @returns The rightmost `length` characters of `str`.
+ */
+export declare function s_right(str: string, length: number): string;
+/**
+ * Truncate or pad a string to a fixed width, using an ellipsis (`"..."`) when truncation happens.
+ *
+ * - If `str.length < width`, pads with `padchar` according to `align`.
+ * - If `str.length > width`, truncates and inserts `"..."` based on `align`:
+ *   - `"l"`: keep left part + `"..."` at end
+ *   - `"r"`: `"..."` at start + keep right part
+ *   - `"c"`: keep head and tail with `"..."` in the middle
+ *
+ * @param str - Input value to format. Non-string values are coerced to string.
+ * @param width - Target width (in characters).
+ * @param align - Alignment mode: `"l"` (left), `"r"` (right), `"c"` (center). Defaults to `"l"`.
+ * @param padchar - Padding character used when `str` is shorter than `width`. Defaults to `" "`.
+ * @returns The formatted string with exact length `width` (unless `width` is too small to hold content).
+ */
+export declare function s_ellipsis(str: string, width: number, align?: SAlign, padchar?: string): string;
+/**
+ * Convenience wrapper around {@link s_ellipsis} that accepts an options object.
+ *
+ * @param str - Input value to format. Non-string values are coerced to string by {@link s_ellipsis}.
+ * @param opts - Formatting options.
+ * @param opts.width - Target width (in characters).
+ * @param opts.align - Alignment mode: `"l"` (left), `"r"` (right), `"c"` (center).
+ * @param opts.padchar - Padding character used when `str` is shorter than `width`.
+ * @returns The formatted string as produced by {@link s_ellipsis}.
+ *
+ * @example
+ * // Pad (left aligned) to width 8 with spaces
+ * s_ellipsis_o("abc", { width: 8, align: "l", padchar: " " })
+ * // => "abc     "
+ *
+ * @example
+ * // Pad (right aligned) to width 8 with '0'
+ * s_ellipsis_o("abc", { width: 8, align: "r", padchar: "0" })
+ * // => "00000abc"
+ *
+ * @example
+ * // Truncate with ellipsis at end (left align behavior for truncation)
+ * s_ellipsis_o("abcdefghijklmnopqrstuvwxyz", { width: 10, align: "l", padchar: " " })
+ * // => "abcdefg..."
+ *
+ * @example
+ * // Truncate with ellipsis at start (right align behavior for truncation)
+ * s_ellipsis_o("abcdefghijklmnopqrstuvwxyz", { width: 10, align: "r", padchar: " " })
+ * // => "...tuvwxyz"
+ *
+ * @example
+ * // Truncate with ellipsis in the middle (center)
+ * s_ellipsis_o("abcdefghijklmnopqrstuvwxyz", { width: 10, align: "c", padchar: " " })
+ * // => "abcd...xyz"
+ */
+export declare function s_ellipsis_o(str: string, opts: SEllipsisOptions): string;
+/**
+ * Parse an `s_xprint` format specifier into a normalized format object.
+ *
+ * Supports either:
+ * - A compact string spec: `"<width>[<align><padchar>]"`, where:
+ *   - `width` is a positive integer (required)
+ *   - `align` is optional: `"l"` (left) or `"r"` (right)
+ *   - `padchar` is optional: a single character used for padding
+ * - An already-constructed format object, which is returned as-is.
+ *
+ * The string form is matched by: `/^(\\d+)(?:([lr])(.?))?$/`
+ *
+ * @param fmt - Format specifier as a string (e.g. `"10l_"`) or a format object
+ * (e.g. `{ width: 10, align: "l", padchar: "_" }`).
+ * @returns A format object `{ width, align, padchar }`.
+ * @throws {Error} If `fmt` is a string but does not match the expected format.
+ *
+ * @example
+ * // String form: width only
+ * s_xprint_extract_fmt("8")
+ * // => { width: 8, align: undefined, padchar: undefined }
+ *
+ * @example
+ * // String form: width + align
+ * s_xprint_extract_fmt("8l")
+ * // => { width: 8, align: "l", padchar: "" }
+ *
+ * @example
+ * // String form: width + align + padchar
+ * s_xprint_extract_fmt("8r0")
+ * // => { width: 8, align: "r", padchar: "0" }
+ *
+ * @example
+ * // Object form: returned unchanged
+ * s_xprint_extract_fmt({ width: 12, align: "l", padchar: " " })
+ * // => { width: 12, align: "l", padchar: " " }
+ */
+export declare function s_xprint_extract_fmt(fmt: string | SXPrintFormat): SXPrintFormat;
+/**
+ * Normalize a list of `s_xprint` format specifiers into format objects.
+ *
+ * This is a convenience helper that applies {@link s_xprint_extract_fmt} to each
+ * element in `fmts`.
+ *
+ * Supported input items:
+ * - String form: `"<width>[<align><padchar>]"`, e.g. `"8"`, `"10l"`, `"6r0"`
+ * - Object form: `{ width, align, padchar }`
+ *
+ * @param fmts - An array of format specifiers (strings or format objects).
+ * @returns An array of normalized format objects: `{ width, align, padchar }`.
+ * @throws {Error} If any string format does not match the expected pattern.
+ *
+ * @example
+ * // String formats
+ * s_xprint_fmts(["8", "10l_", "6r0"])
+ * // => [
+ * //   { width: 8,  align: undefined, padchar: undefined },
+ * //   { width: 10, align: "l",       padchar: "_" },
+ * //   { width: 6,  align: "r",       padchar: "0" }
+ * // ]
+ *
+ * @example
+ * // Mixed formats (object formats are returned as-is)
+ * s_xprint_fmts([{ width: 4, align: "l", padchar: " " }, "3r0"])
+ * // => [
+ * //   { width: 4, align: "l", padchar: " " },
+ * //   { width: 3, align: "r", padchar: "0" }
+ * // ]
+ */
+export declare function s_xprint_fmts(fmts: Array<string | SXPrintFormat>): SXPrintFormat[];
+/**
+ * Format and join a list of columns into a single fixed-width string (table-like output).
+ *
+ * Each column is formatted using {@link s_ellipsis} with the corresponding `formats` entry.
+ * Columns are then joined by `sep`.
+ *
+ * - `formats` entries accept the same specifiers as {@link s_xprint_extract_fmt}:
+ *   - String form: `"<width>[<align><padchar>]"`, e.g. `"10"`, `"8l_"`, `"6r0"`
+ *   - Object form: `{ width, align, padchar }`
+ * - The last column can optionally skip ellipsis formatting when `ellipsisEnd === false`.
+ *
+ * @param params - Options object.
+ * @param params.columns - Column values to print. `null`/`undefined` become `""`.
+ * @param params.formats - Per-column format specifiers (same length as `columns` is recommended).
+ * @param params.sep - Separator string inserted between formatted columns. Defaults to `" "`.
+ * @param params.ellipsisEnd - Whether to apply ellipsis formatting to the last column.
+ * Defaults to `true`. When `false`, the last column is returned as-is (no padding/truncation).
+ * @returns A single formatted line string.
+ *
+ * @example
+ * // Basic usage with string formats (width + align + padchar)
+ * // - 1st: width 6, left align, pad with space
+ * // - 2nd: width 4, right align, pad with '0'
+ * // - 3rd: width 10, left align (will ellipsis if too long)
+ * s_xprint({
+ *   columns: ["id", 7, "abcdefghijklmnopqrstuvwxyz"],
+ *   formats: ["6l ", "4r0", "10l "],
+ *   sep: " | "
+ * })
+ * // => "id     | 0007 | abcdefg..."
+ *
+ * @example
+ * // Skip formatting for the last column (useful for "message" / "tail" fields)
+ * s_xprint({
+ *   columns: ["INFO", "startup ok", "this part is not truncated"],
+ *   formats: ["6l ", "12l ", "8l "],
+ *   sep: " ",
+ *   ellipsisEnd: false
+ * })
+ * // => "INFO   startup ok   this part is not truncated"
+ */
+export declare function s_xprint({ columns, formats, sep, ellipsisEnd }?: SXPrintParams): string;
+/**
+ * Test whether a string matches a glob pattern.
+ *
+ * This is a small wrapper around {@link glob_to_regexp} that converts the given
+ * glob `pattern` to a {@link RegExp} and then checks it against `str`.
+ *
+ * @param pattern - Glob pattern e.g. `"*.ts"`.
+ * @param str - The input string to test.
+ * @returns `true` if `str` matches `pattern`; otherwise `false`.
+ */
+export declare function s_glob(pattern: string, str: string): boolean;
+export {};

package/lib/strings.js

@@ -0,0 +1,200 @@
+function s_pad(text, width, which = "l", padchar = " ", is_trunc = false) {
+  if (typeof width !== "number") width = text.length;
+  let w = text.length;
+  if (is_trunc && w > width) {
+    text = text.substring(0, width);
+    w = width;
+  } else {
+    var r = Math.max(0, width - w);
+    if (which === "l") {
+      text = padchar.repeat(r) + text;
+    } else if (which === "c") {
+      let n = Math.floor(r / 2);
+      text = padchar.repeat(n) + text + padchar.repeat(r - n);
+    } else {
+      text = text + padchar.repeat(r);
+    }
+  }
+  return text;
+}
+function s_left(str, length) {
+  if (length <= 0) return "";
+  let str_length = str.length;
+  if (length > str_length) {
+    return str;
+  }
+  return str.substring(0, length);
+}
+function s_right(str, length) {
+  if (length <= 0) return "";
+  let str_length = str.length;
+  if (length > str_length) {
+    return str;
+  }
+  return str.substring(str_length - length);
+}
+function s_ellipsis(str, width, align = "l", padchar = " ") {
+  str = typeof str === "string" ? str : str + "";
+  width = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+  if (width === 0) return "";
+  align = align != void 0 ? align : "l";
+  const _align = align.substring(0, 1);
+  align = _align === "l" || _align === "r" || _align === "c" ? _align : "l";
+  padchar = typeof padchar === "string" ? padchar ? padchar : " " : " ";
+  str = str.replace(/\r ?\n/g, "");
+  let length = str.length;
+  if (length === width) {
+    return str;
+  } else if (length < width) {
+    if (align === "r") {
+      str = s_pad(str, width, "l", padchar);
+    } else if (align === "l") {
+      str = s_pad(str, width, "r", padchar);
+    } else {
+      str = s_pad(str, width, "c", padchar);
+    }
+  } else {
+    if (width <= 3) {
+      return ".".repeat(width);
+    }
+    if (align === "r") {
+      str = "..." + s_right(str, width - 3);
+    } else if (align === "c") {
+      let m_odd = width % 2;
+      let m_mid_len = Math.floor(width / 2);
+      let head_str = s_left(str, m_mid_len - 1);
+      let tail_str = s_right(str, m_mid_len - (m_odd ? 1 : 2));
+      str = head_str + "..." + tail_str;
+    } else {
+      str = s_left(str, width - 3) + "...";
+    }
+  }
+  return str;
+}
+function s_ellipsis_o(str, opts) {
+  const { width, align, padchar } = opts;
+  return s_ellipsis(str, width, align, padchar);
+}
+function s_xprint_extract_fmt(fmt) {
+  if (typeof fmt === "string") {
+    const mmm = /^(\d+)(?:([lr])(.?))?$/.exec(fmt);
+    if (mmm == null) {
+      throw Error("wrong foramt of s_xprint [" + fmt + "]");
+    }
+    const _align = mmm[2] === "l" || mmm[2] === "r" ? mmm[2] : "l";
+    return {
+      width: parseInt(mmm[1], 10),
+      align: _align,
+      padchar: mmm[3]
+    };
+  } else {
+    return fmt;
+  }
+}
+function s_xprint_fmts(fmts) {
+  return fmts.map(s_xprint_extract_fmt);
+}
+function s_xprint({ columns, formats = [], sep = " ", ellipsisEnd = true } = { columns: [], formats: [], sep: " ", ellipsisEnd: true }) {
+  const fmts = formats.map(s_xprint_extract_fmt);
+  return columns.map((column, idx) => {
+    const column_str = column == null ? "" : String(column);
+    const fmt = fmts[idx] ?? { width: column_str.length, align: "l", padchar: " " };
+    const { width, align, padchar } = fmt;
+    if (!ellipsisEnd && idx === columns.length - 1) {
+      return column_str;
+    } else {
+      return s_ellipsis(column_str, width, align, padchar);
+    }
+  }).join(sep);
+}
+function glob_to_regexp(glob, opts = {}) {
+  if (typeof glob !== "string") {
+    throw new TypeError("Expected a string");
+  }
+  var str = String(glob);
+  var reStr = "";
+  var extended = opts ? !!opts.extended : false;
+  var globstar = opts ? !!opts.globstar : false;
+  var inGroup = false;
+  var flags = opts && typeof opts.flags === "string" ? opts.flags : "";
+  var c;
+  for (var i = 0, len = str.length; i < len; i++) {
+    c = str[i];
+    switch (c) {
+      case "/":
+      case "$":
+      case "^":
+      case "+":
+      case ".":
+      case "(":
+      case ")":
+      case "=":
+      case "!":
+      case "|":
+        reStr += "\\" + c;
+        break;
+      case "?":
+        if (extended) {
+          reStr += ".";
+          break;
+        }
+      case "[":
+      case "]":
+        if (extended) {
+          reStr += c;
+          break;
+        }
+      case "{":
+        if (extended) {
+          inGroup = true;
+          reStr += "(";
+          break;
+        }
+      case "}":
+        if (extended) {
+          inGroup = false;
+          reStr += ")";
+          break;
+        }
+      case ",":
+        if (inGroup) {
+          reStr += "|";
+          break;
+        }
+        reStr += "\\" + c;
+        break;
+      case "*":
+        var prevChar = str[i - 1];
+        var starCount = 1;
+        while (str[i + 1] === "*") {
+          starCount++;
+          i++;
+        }
+        var nextChar = str[i + 1];
+        if (!globstar) {
+          reStr += ".*";
+        } else {
+          var isGlobstar = starCount > 1 && (prevChar === "/" || prevChar === void 0) && (nextChar === "/" || nextChar === void 0);
+          if (isGlobstar) {
+            reStr += "((?:[^/]*(?:/|$))*)";
+            i++;
+          } else {
+            reStr += "([^/]*)";
+          }
+        }
+        break;
+      default:
+        reStr += c;
+    }
+  }
+  if (!flags || !~flags.indexOf("g")) {
+    reStr = "^" + reStr + "$";
+  }
+  return new RegExp(reStr, flags);
+}
+function s_glob(pattern, str) {
+  const regex = glob_to_regexp(pattern, {});
+  return regex.test(str);
+}
+
+export { s_ellipsis, s_ellipsis_o, s_glob, s_left, s_pad, s_right, s_xprint, s_xprint_extract_fmt, s_xprint_fmts };

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@yuhere/js-strings",
+    "type": "module",
+    "description": "utility library aimed at providing common helper functions for strings in JavaScript/TypeScript projects.",
+    "version": "1.0.2",
+    "publisher": "yuhere",
+    "repository": "https://github.com/yuhere/js-strings.git",
+    "license": "MIT",
+    "main": "lib/strings.js",
+    "module": "lib/strings.js",
+    "types": "lib/strings.d.ts",
+    "files": [
+        "bin/",
+        "lib/",
+        "src/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "npm-run-all -p build:*",
+        "build:rollup": "rollup --config rollup.config.js",
+        "build:types": "tsc -p tsconfig.types.json",
+        "lint": "eslint src",
+        "test": "npm run build && npx c8 mocha"
+    },
+    "devDependencies": {
+        "@types/chai": "^5.2.3",
+        "@types/mocha": "^10.0.10",
+        "@types/node": "^24.6.1",
+        "@typescript-eslint/eslint-plugin": "^7.14.1",
+        "@typescript-eslint/parser": "^7.11.0",
+        "eslint": "^8.57.0",
+        "npm-run-all": "^4.1.5",
+        "rollup": "^4.53.3",
+        "c8": "^10.1.3",
+        "chai": "^4.3.7",
+        "mocha": "^10.2.0",
+        "typescript": "^5.9.3",
+        "tsx": "^4.21.0",
+        "rollup-plugin-esbuild": "^6.2.1"
+    }
+}

package/src/strings.ts

@@ -0,0 +1,513 @@
+
+// ########################################
+// # STRINGS
+// ########################################
+
+type SAlign = "l" | "r" | "c"
+type SXPrintAlign = "l" | "r"
+
+interface SEllipsisOptions {
+    width: number
+    align?: SAlign
+    padchar?: string
+}
+
+interface SXPrintFormat {
+    width: number
+    align?: SXPrintAlign
+    padchar?: string
+}
+
+interface SXPrintParams {
+    columns: Array<string | number | null | undefined>
+    formats?: Array<string | SXPrintFormat>
+    sep?: string
+    ellipsisEnd?: boolean
+}
+
+interface GlobToRegExpOptions {
+    extended?: boolean
+    globstar?: boolean
+    flags?: string
+}
+
+/**
+ * String padding.
+ *
+ * @param text - Input text.
+ * @param width - Target width. If `undefined`, defaults to `text.length`.
+ * @param which - Padding side:
+ * - `"r"`: pad on the right (left-justified)
+ * - `"l"`: pad on the left (right-justified)
+ * - `"c"`: pad both sides (center)
+ * @param padchar - Padding character (single-column). Defaults to `" "`.
+ * @param is_trunc - If `true`, truncate `text` when it exceeds `width`.
+ * @returns Padded (or truncated) string with length `width`.
+ */
+export function s_pad(text: string, width?: number, which: SAlign = "l", padchar: string = " ", is_trunc: boolean = false): string {
+    if (typeof (width) !== "number") width = text.length
+    // ####
+    let w = text.length;
+    if (is_trunc && w > width) {
+        text = text.substring(0, width)
+        w = width;
+    } else {
+        var r = Math.max(0, width - w)
+        if (which === 'l') {
+            text = padchar.repeat(r) + text
+        } else if (which === 'c') {
+            let n = Math.floor(r / 2)
+            text = padchar.repeat(n) + text + padchar.repeat(r - n)
+        } else {
+            text = text + (padchar.repeat(r));
+        }
+    }
+    // ####
+    return text
+}
+
+/**
+ * Returns a string containing the specified number of characters from the left side of `str`.
+ *
+ * @param str - The source string.
+ * @param length - Number of characters to return.
+ * - If `length <= 0`, returns an empty string (`""`).
+ * - If `length >= str.length`, returns the entire `str`.
+ * @returns The leftmost `length` characters of `str`.
+ */
+export function s_left(str: string, length: number): string {
+    if (length <= 0) return ""
+    let str_length = str.length
+    if (length > str_length) {
+        return str;
+    }
+    return str.substring(0, length);
+}
+
+/**
+ * Returns a string containing the specified number of characters from the right side of `str`.
+ *
+ * @param str - The source string.
+ * @param length - Number of characters to return.
+ * - If `length <= 0`, returns an empty string (`""`).
+ * - If `length >= str.length`, returns the entire `str`.
+ * @returns The rightmost `length` characters of `str`.
+ */
+export function s_right(str: string, length: number): string {
+    if (length <= 0) return "";
+    let str_length = str.length;
+    if (length > str_length) {
+        return str;
+    }
+    return str.substring(str_length - length);
+}
+
+/**
+ * Truncate or pad a string to a fixed width, using an ellipsis (`"..."`) when truncation happens.
+ *
+ * - If `str.length < width`, pads with `padchar` according to `align`.
+ * - If `str.length > width`, truncates and inserts `"..."` based on `align`:
+ *   - `"l"`: keep left part + `"..."` at end
+ *   - `"r"`: `"..."` at start + keep right part
+ *   - `"c"`: keep head and tail with `"..."` in the middle
+ *
+ * @param str - Input value to format. Non-string values are coerced to string.
+ * @param width - Target width (in characters).
+ * @param align - Alignment mode: `"l"` (left), `"r"` (right), `"c"` (center). Defaults to `"l"`.
+ * @param padchar - Padding character used when `str` is shorter than `width`. Defaults to `" "`.
+ * @returns The formatted string with exact length `width` (unless `width` is too small to hold content).
+ */
+export function s_ellipsis(str: string, width: number, align: SAlign = "l", padchar: string = " "): string {
+    str = typeof (str) === "string" ? str : str + ""
+    width = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0
+    if (width === 0) return ""
+    align = align != undefined ? align : "l";
+    const _align = align.substring(0, 1);
+    align = _align === "l" || _align === "r" || _align === "c" ? _align : "l";
+    // ##
+    padchar = typeof (padchar) === "string" ? (padchar ? padchar : " ") : " ";
+    // ##
+    // $str = ~s /\r ?\n//g;
+    str = str.replace(/\r ?\n/g, "")
+    // ##
+    let length = str.length
+    // #
+    if (length === width) {
+        return str;
+    } else if (length < width) {
+        if (align === "r") {
+            str = s_pad(str, width, "l", padchar)
+        } else if (align === "l") {
+            str = s_pad(str, width, "r", padchar)
+        } else { // "c"
+            str = s_pad(str, width, "c", padchar);
+        }
+    } else {
+        if (width <= 3) {
+            return ".".repeat(width)
+        }
+        if (align === "r") {
+            str = "..." + s_right(str, width - 3);
+        } else if (align === "c") {
+            let m_odd = width % 2;
+            let m_mid_len = Math.floor(width / 2);
+            let head_str = s_left(str, m_mid_len - 1);
+            let tail_str = s_right(str, m_mid_len - (m_odd ? 1 : 2));
+            str = head_str + "..." + tail_str;
+        } else {
+            str = s_left(str, width - 3) + "...";
+        }
+    }
+    return str;
+}
+
+/**
+ * Convenience wrapper around {@link s_ellipsis} that accepts an options object.
+ *
+ * @param str - Input value to format. Non-string values are coerced to string by {@link s_ellipsis}.
+ * @param opts - Formatting options.
+ * @param opts.width - Target width (in characters).
+ * @param opts.align - Alignment mode: `"l"` (left), `"r"` (right), `"c"` (center).
+ * @param opts.padchar - Padding character used when `str` is shorter than `width`.
+ * @returns The formatted string as produced by {@link s_ellipsis}.
+ *
+ * @example
+ * // Pad (left aligned) to width 8 with spaces
+ * s_ellipsis_o("abc", { width: 8, align: "l", padchar: " " })
+ * // => "abc     "
+ *
+ * @example
+ * // Pad (right aligned) to width 8 with '0'
+ * s_ellipsis_o("abc", { width: 8, align: "r", padchar: "0" })
+ * // => "00000abc"
+ *
+ * @example
+ * // Truncate with ellipsis at end (left align behavior for truncation)
+ * s_ellipsis_o("abcdefghijklmnopqrstuvwxyz", { width: 10, align: "l", padchar: " " })
+ * // => "abcdefg..."
+ *
+ * @example
+ * // Truncate with ellipsis at start (right align behavior for truncation)
+ * s_ellipsis_o("abcdefghijklmnopqrstuvwxyz", { width: 10, align: "r", padchar: " " })
+ * // => "...tuvwxyz"
+ *
+ * @example
+ * // Truncate with ellipsis in the middle (center)
+ * s_ellipsis_o("abcdefghijklmnopqrstuvwxyz", { width: 10, align: "c", padchar: " " })
+ * // => "abcd...xyz"
+ */
+export function s_ellipsis_o(str: string, opts: SEllipsisOptions): string {
+    const { width, align, padchar } = opts
+    return s_ellipsis(str, width, align, padchar)
+}
+
+/**
+ * Parse an `s_xprint` format specifier into a normalized format object.
+ *
+ * Supports either:
+ * - A compact string spec: `"<width>[<align><padchar>]"`, where:
+ *   - `width` is a positive integer (required)
+ *   - `align` is optional: `"l"` (left) or `"r"` (right)
+ *   - `padchar` is optional: a single character used for padding
+ * - An already-constructed format object, which is returned as-is.
+ *
+ * The string form is matched by: `/^(\\d+)(?:([lr])(.?))?$/`
+ *
+ * @param fmt - Format specifier as a string (e.g. `"10l_"`) or a format object
+ * (e.g. `{ width: 10, align: "l", padchar: "_" }`).
+ * @returns A format object `{ width, align, padchar }`.
+ * @throws {Error} If `fmt` is a string but does not match the expected format.
+ *
+ * @example
+ * // String form: width only
+ * s_xprint_extract_fmt("8")
+ * // => { width: 8, align: undefined, padchar: undefined }
+ *
+ * @example
+ * // String form: width + align
+ * s_xprint_extract_fmt("8l")
+ * // => { width: 8, align: "l", padchar: "" }
+ *
+ * @example
+ * // String form: width + align + padchar
+ * s_xprint_extract_fmt("8r0")
+ * // => { width: 8, align: "r", padchar: "0" }
+ *
+ * @example
+ * // Object form: returned unchanged
+ * s_xprint_extract_fmt({ width: 12, align: "l", padchar: " " })
+ * // => { width: 12, align: "l", padchar: " " }
+ */
+export function s_xprint_extract_fmt(fmt: string | SXPrintFormat): SXPrintFormat {
+    if (typeof (fmt) === "string") {
+        const mmm = /^(\d+)(?:([lr])(.?))?$/.exec(fmt)
+        if (mmm == null) {
+            throw Error("wrong foramt of s_xprint [" + fmt + "]")
+        }
+        const _align = mmm[2] === "l" || mmm[2] === "r" ? mmm[2] : "l";
+        return {
+            width: parseInt(mmm[1], 10),
+            align: _align,
+            padchar: mmm[3]
+        }
+    } else {
+        return fmt
+    }
+}
+
+/**
+ * Normalize a list of `s_xprint` format specifiers into format objects.
+ *
+ * This is a convenience helper that applies {@link s_xprint_extract_fmt} to each
+ * element in `fmts`.
+ *
+ * Supported input items:
+ * - String form: `"<width>[<align><padchar>]"`, e.g. `"8"`, `"10l"`, `"6r0"`
+ * - Object form: `{ width, align, padchar }`
+ *
+ * @param fmts - An array of format specifiers (strings or format objects).
+ * @returns An array of normalized format objects: `{ width, align, padchar }`.
+ * @throws {Error} If any string format does not match the expected pattern.
+ *
+ * @example
+ * // String formats
+ * s_xprint_fmts(["8", "10l_", "6r0"])
+ * // => [
+ * //   { width: 8,  align: undefined, padchar: undefined },
+ * //   { width: 10, align: "l",       padchar: "_" },
+ * //   { width: 6,  align: "r",       padchar: "0" }
+ * // ]
+ *
+ * @example
+ * // Mixed formats (object formats are returned as-is)
+ * s_xprint_fmts([{ width: 4, align: "l", padchar: " " }, "3r0"])
+ * // => [
+ * //   { width: 4, align: "l", padchar: " " },
+ * //   { width: 3, align: "r", padchar: "0" }
+ * // ]
+ */
+export function s_xprint_fmts(fmts: Array<string | SXPrintFormat>): SXPrintFormat[] {
+    return fmts.map(s_xprint_extract_fmt)
+}
+
+/**
+ * Format and join a list of columns into a single fixed-width string (table-like output).
+ *
+ * Each column is formatted using {@link s_ellipsis} with the corresponding `formats` entry.
+ * Columns are then joined by `sep`.
+ *
+ * - `formats` entries accept the same specifiers as {@link s_xprint_extract_fmt}:
+ *   - String form: `"<width>[<align><padchar>]"`, e.g. `"10"`, `"8l_"`, `"6r0"`
+ *   - Object form: `{ width, align, padchar }`
+ * - The last column can optionally skip ellipsis formatting when `ellipsisEnd === false`.
+ *
+ * @param params - Options object.
+ * @param params.columns - Column values to print. `null`/`undefined` become `""`.
+ * @param params.formats - Per-column format specifiers (same length as `columns` is recommended).
+ * @param params.sep - Separator string inserted between formatted columns. Defaults to `" "`.
+ * @param params.ellipsisEnd - Whether to apply ellipsis formatting to the last column.
+ * Defaults to `true`. When `false`, the last column is returned as-is (no padding/truncation).
+ * @returns A single formatted line string.
+ *
+ * @example
+ * // Basic usage with string formats (width + align + padchar)
+ * // - 1st: width 6, left align, pad with space
+ * // - 2nd: width 4, right align, pad with '0'
+ * // - 3rd: width 10, left align (will ellipsis if too long)
+ * s_xprint({
+ *   columns: ["id", 7, "abcdefghijklmnopqrstuvwxyz"],
+ *   formats: ["6l ", "4r0", "10l "],
+ *   sep: " | "
+ * })
+ * // => "id     | 0007 | abcdefg..."
+ *
+ * @example
+ * // Skip formatting for the last column (useful for "message" / "tail" fields)
+ * s_xprint({
+ *   columns: ["INFO", "startup ok", "this part is not truncated"],
+ *   formats: ["6l ", "12l ", "8l "],
+ *   sep: " ",
+ *   ellipsisEnd: false
+ * })
+ * // => "INFO   startup ok   this part is not truncated"
+ */
+export function s_xprint({ columns, formats = [], sep = " ", ellipsisEnd = true }: SXPrintParams = { columns: [], formats: [], sep: " ", ellipsisEnd: true }): string {
+    const fmts = formats.map(s_xprint_extract_fmt)
+    return columns.map((column, idx) => {
+        const column_str = column == null ? "" : String(column);
+        const fmt = fmts[idx] ?? { width: column_str.length, align: "l" as SXPrintAlign, padchar: " " }
+        const { width, align, padchar } = fmt
+        if (!ellipsisEnd && idx === columns.length - 1) {
+            return column_str
+        } else {
+            return s_ellipsis(column_str, width, align, padchar)
+        }
+    }).join(sep)
+}
+
+/**
+ * Convert a glob pattern string to a {@link RegExp}.
+ *
+ * Supports basic glob syntax (`*`) by default, and optionally "extended" glob
+ * syntax (e.g. `?`, `[]`, `{a,b}`) and "globstar" (`**`) via {@link opts}.
+ *
+ * Notes:
+ * - When `opts.flags` does not include `g`, the generated regexp is wrapped with
+ *   `^` and `$` to match the whole input.
+ * - When `opts.globstar` is enabled, `**` matches zero or more path segments.
+ *
+ * @param glob - Glob pattern to convert (must be a string).
+ * @param opts - Options controlling how the glob is translated.
+ * @param opts.extended - Enable extended glob features: `?`, character classes
+ * (`[a-z]`), and groups (`{a,b}`).
+ * @param opts.globstar - Enable globstar behavior for `**` (path segment aware).
+ * @param opts.flags - RegExp flags passed to the {@link RegExp} constructor
+ * (e.g. `"i"`, `"m"`, `"g"`).
+ * @returns A {@link RegExp} equivalent to the provided glob.
+ * @throws {TypeError} If `glob` is not a string.
+ */
+function glob_to_regexp(glob: string, opts: GlobToRegExpOptions = {}): RegExp {
+    if (typeof glob !== 'string') {
+        throw new TypeError('Expected a string');
+    }
+
+    var str = String(glob);
+
+    // The regexp we are building, as a string.
+    var reStr = "";
+
+    // Whether we are matching so called "extended" globs (like bash) and should
+    // support single character matching, matching ranges of characters, group
+    // matching, etc.
+    var extended = opts ? !!opts.extended : false;
+
+    // When globstar is _false_ (default), '/foo/*' is translated a regexp like
+    // '^\/foo\/.*$' which will match any string beginning with '/foo/'
+    // When globstar is _true_, '/foo/*' is translated to regexp like
+    // '^\/foo\/[^/]*$' which will match any string beginning with '/foo/' BUT
+    // which does not have a '/' to the right of it.
+    // E.g. with '/foo/*' these will match: '/foo/bar', '/foo/bar.txt' but
+    // these will not '/foo/bar/baz', '/foo/bar/baz.txt'
+    // Lastely, when globstar is _true_, '/foo/**' is equivelant to '/foo/*' when
+    // globstar is _false_
+    var globstar = opts ? !!opts.globstar : false;
+
+    // If we are doing extended matching, this boolean is true when we are inside
+    // a group (eg {*.html,*.js}), and false otherwise.
+    var inGroup = false;
+
+    // RegExp flags (eg "i" ) to pass in to RegExp constructor.
+    var flags = opts && typeof (opts.flags) === "string" ? opts.flags : "";
+
+    var c;
+    for (var i = 0, len = str.length; i < len; i++) {
+        c = str[i];
+
+        switch (c) {
+            case "/":
+            case "$":
+            case "^":
+            case "+":
+            case ".":
+            case "(":
+            case ")":
+            case "=":
+            case "!":
+            case "|":
+                reStr += "\\" + c;
+                break;
+
+            case "?":
+                if (extended) {
+                    reStr += ".";
+                    break;
+                }
+
+            case "[":
+            case "]":
+                if (extended) {
+                    reStr += c;
+                    break;
+                }
+
+            case "{":
+                if (extended) {
+                    inGroup = true;
+                    reStr += "(";
+                    break;
+                }
+
+            case "}":
+                if (extended) {
+                    inGroup = false;
+                    reStr += ")";
+                    break;
+                }
+
+            case ",":
+                if (inGroup) {
+                    reStr += "|";
+                    break;
+                }
+                reStr += "\\" + c;
+                break;
+
+            case "*":
+                // Move over all consecutive "*"'s.
+                // Also store the previous and next characters
+                var prevChar = str[i - 1];
+                var starCount = 1;
+                while (str[i + 1] === "*") {
+                    starCount++;
+                    i++;
+                }
+                var nextChar = str[i + 1];
+
+                if (!globstar) {
+                    // globstar is disabled, so treat any number of "*" as one
+                    reStr += ".*";
+                } else {
+                    // globstar is enabled, so determine if this is a globstar segment
+                    var isGlobstar = starCount > 1                      // multiple "*"'s
+                        && (prevChar === "/" || prevChar === undefined)   // from the start of the segment
+                        && (nextChar === "/" || nextChar === undefined)   // to the end of the segment
+
+                    if (isGlobstar) {
+                        // it's a globstar, so match zero or more path segments
+                        reStr += "((?:[^/]*(?:\/|$))*)";
+                        i++; // move over the "/"
+                    } else {
+                        // it's not a globstar, so only match one path segment
+                        reStr += "([^/]*)";
+                    }
+                }
+                break;
+
+            default:
+                reStr += c;
+        }
+    }
+
+    // When regexp 'g' flag is specified don't
+    // constrain the regular expression with ^ & $
+    if (!flags || !~flags.indexOf('g')) {
+        reStr = "^" + reStr + "$";
+    }
+
+    return new RegExp(reStr, flags);
+}
+
+/**
+ * Test whether a string matches a glob pattern.
+ *
+ * This is a small wrapper around {@link glob_to_regexp} that converts the given
+ * glob `pattern` to a {@link RegExp} and then checks it against `str`.
+ *
+ * @param pattern - Glob pattern e.g. `"*.ts"`.
+ * @param str - The input string to test.
+ * @returns `true` if `str` matches `pattern`; otherwise `false`.
+ */
+export function s_glob(pattern: string, str: string): boolean {
+    const regex = glob_to_regexp(pattern, {})
+    return regex.test(str)
+}