js-dev-tool 1.2.11 → 1.2.13

package/README.md

@@ -1,164 +1,330 @@
 # js-dev-tool
 
-A collection of command-line tools to assist in JavaScript project development.
+`js-dev-tool` is a mixed package of `jstool` CLI commands and small Node.js helpers for JavaScript / TypeScript project maintenance.
 
-This utility, `jstool`, provides various functions for file manipulation, versioning, and building.
+The published modules are CommonJS. The examples below use `require(...)` so the runtime behavior matches the package as published.
 
-## Usage
+## Install
 
-The primary way to use these tools is through the `jstool` command, which is an alias for `node tools.js`.
+```bash
+npm i js-dev-tool
+```
+
+## CLI Usage
+
+`jstool` is the package binary and points to `tools.js`.
 
 ```bash
-# General syntax
+jstool -cmd <command_name> [options]
 node tools.js -cmd <command_name> [options]
+node tools.js -help <command_name>
+```
 
-# Or if installed globally or via package.json scripts
-jstool -cmd <command_name> [options]
+## Published Package Layout
+
+This section reflects the current `package.json#exports` and `package.json#files`.
+
+### Stable Entry Points (`exports`)
+
+| Path | Purpose |
+| --- | --- |
+| `js-dev-tool` | Root namespace object with `{ progress, common, utils }` |
+| `js-dev-tool/utils` | File, JSON, CLI, TSV/CSV, and small utility helpers |
+| `js-dev-tool/common` | File-system and terminal rendering primitives |
+| `js-dev-tool/progress` | Progress renderer, spinner helpers, webpack / browserify progress hooks |
+| `js-dev-tool/progress/progress-extras` | Environment and webpack-version helpers |
+| `js-dev-tool/extras/algorithms` | Binary-search helper |
+| `js-dev-tool/extras/cc-map` | Character-code map |
+| `js-dev-tool/extras/jsonl` | JSONL readers, JSONL-to-array/map helpers, and `jsonMinify` |
+| `js-dev-tool/extras/json-minify` | `jsonMinify` |
+| `js-dev-tool/extras/progress-light` | Small fixed-frame spinner |
+| `js-dev-tool/extras/tiny-progress` | Random-frame spinner wrapper |
+| `js-dev-tool/basic-types` | Types-only reference entry |
+
+Notes:
+
+- `js-dev-tool/extras/list-deps-of` is bundled and works at runtime, but it does not ship a `.d.ts`. If you want types, use `listDependenciesOf` from `js-dev-tool/utils`.
+- `package.json` exposes `./progress/*`, but the currently documented typed JS subpath is `js-dev-tool/progress/progress-extras`. Other bundled files under `progress/` should be treated as internal support assets unless you have verified the exact runtime file.
+
+### Additional Bundled Files (`files`)
+
+The publish list is broader than the stable import surface above.
+
+- Root files: `index.js`, `index.d.ts`, `utils.js`, `utils.d.ts`, `tools.js`, `tools.d.ts`, `basic-types.d.ts`, `tsconfig.json`
+- Bundled directories: `common/`, `extras/`, `lib/`, `progress/`, `scripts/`, `tool-lib/`
+
+## Root Namespace
+
+```js
+const { utils, common, progress } = require("js-dev-tool");
 ```
 
-To see the help for a specific command:
-```bash
-node tools.js -help <command_name>
+For clearer dependency boundaries, importing a direct subpath is usually better than pulling from the root namespace.
+
+## `utils`
+
+`js-dev-tool/utils` is the main grab-bag module. A few useful exports:
+
+- `extractVersion(versionString?)`
+- `removeJsonComments(source)`
+- `readText(path)` / `writeText(content, path)`
+- `readJson(path)`
+- `copyText(content, message?)`
+- `indexByCol(tsvSource, options)` and `parseDelimitedToIndex`
+- `listDependenciesOf(packageName)` for Yarn v1 lockfiles
+
+Example:
+
+```js
+const { indexByCol, listDependenciesOf } = require("js-dev-tool/utils");
+
+const map = indexByCol("id\tname\n1\talpha\n2\tbeta\n", {
+  mapKeyCol: 0,
+});
+
+const deps = listDependenciesOf("webpack");
+console.log(map["1"], deps.slice(0, 5));
 ```
 
-## Basic Types
+## `common`
 
-> Optional: a small bag of legacy-ish utility types.  
-> You probably don’t need this — but if you do, it’s handy.
+`js-dev-tool/common` contains the low-level pieces used by the progress helpers.
 
-```ts
-/// <reference types="js-dev-tool/basic-types"/>
+- `checkParentDirectory(dest)`
+- `createLogStreamAndResolvePath(logPath)`
+- `renderLine(msg?, row?)`
+- `cursor(enabled, output?)`
+
+## `progress`
+
+`js-dev-tool/progress` is the main progress API.
+
+- `createProgress(timeSpanMS, frames)`
+- `createProgressSync(frames, formatOpt?)`
+- `createProgressObject(frames, formatOpt, messageEmitter)`
+- `createWebpackProgressPluginHandler(logFilePath?, disableRenderLine?)`
+- `createBrowserifyFileEventLogger(logFilePath)`
+
+`js-dev-tool/progress/progress-extras` adds:
+
+- `checkENV()`
+- `wppHandlerV4`
+- `wppHandlerV5`
+- `isWebpackV5later()`
+
+## Extras Modules
+
+The `extras/` directory is where the smaller standalone modules live. Some are typed and ready to document as public helpers; some are runtime-only and better treated as advanced or legacy entry points.
+
+### `js-dev-tool/extras/algorithms`
+
+Exports:
+
+- `bnSearch(src, value, comparator)`
+
+Use this when you already have a sorted array and want a simple binary search helper.
+
+```js
+const { bnSearch } = require("js-dev-tool/extras/algorithms");
+
+const values = [1, 4, 7, 9];
+const index = bnSearch(values, 7, (left, right) => left - right);
+
+console.log(index); // 2
 ```
 
-## Related Libraries
+### `js-dev-tool/extras/cc-map`
 
-### [`literate-regex`](https://www.npmjs.com/package/literate-regex)
+Exports a character-code map object. It is most useful when you want named constants for ASCII / control-character comparisons.
 
-`literate-regex` was originally developed as part of this project, but it has now been separated into an independent library.  
-It allows you to write readable, commented regular expressions and provides powerful type-level normalization.
+```js
+const CC_MAP = require("js-dev-tool/extras/cc-map");
 
-## Commands
+console.log(CC_MAP.LF); // 10
+console.log(CC_MAP.DOUBLE_QUOTE); // 34
+```
 
-Here is a list of available commands registered in `ToolFunctions`:
+### `js-dev-tool/extras/jsonl`
+
+Exports:
+
+- `resolveJsonlPath(fileName, options?)`
+- `readJsonlLines(fileName, onLine, options?)`
+- `readJsonl(fileName, onRow, options?)`
+- `readJsonlArray(fileName, options?)`
+- `readJsonlMapByKey(fileName, options?)`
+- `fastGetIntFieldCheap(line, key)`
+- `jsonMinify(source)`
+
+This is the richest `extras` entry and the main one worth documenting. It covers three related jobs:
+
+- streaming JSONL line reads
+- JSON parse + row transformation
+- whitespace minification for JSON and JSONL
+
+Key behaviors:
+
+- `readJsonlLines` splits by `"\n"` and trims a trailing `"\r"` from each physical line
+- empty lines are skipped by default
+- `readJsonl` reports parse failures through `onParseError` when provided, otherwise it logs to `stderr`
+- `readJsonlMapByKey` defaults to `"_key"` and lets later rows overwrite earlier rows
+- `fastGetIntFieldCheap` is intentionally narrow: it is meant for top-level integer fields on hot paths
+- `jsonMinify` accepts either a single JSON value or multiple top-level JSON values and returns minified JSONL in the multi-value case
+
+Example:
+
+```js
+const {
+  readJsonlArray,
+  readJsonlMapByKey,
+  fastGetIntFieldCheap,
+  jsonMinify,
+} = require("js-dev-tool/extras/jsonl");
+
+async function main() {
+  const rows = await readJsonlArray("logs/app.jsonl", {
+    filter: (row) => row.level !== "debug",
+    map: (row) => ({
+      id: row.id,
+      level: row.level,
+    }),
+  });
+
+  const byId = await readJsonlMapByKey("logs/app.jsonl", {
+    keyField: "id",
+  });
+
+  console.log(rows.length, Object.keys(byId).length);
+  console.log(fastGetIntFieldCheap("{\"count\":42}", "count"));
+  console.log(jsonMinify("{ \"a\": 1 }\n{ \"a\": 2 }"));
+}
+
+main().catch(console.error);
+```
 
----
+### `js-dev-tool/extras/progress-light`
 
-### `rws`
-Records the size of webpack bundles or other files. The name stands for (r)ecord(W)ebpack(S)ize.
-*   **Usage:** `jstool -cmd rws -webpack lib/webpack.js -dest "./dev-extras/webpack-size.json"`
+Exports:
 
----
+- `create(fps?, messageEmitter?)`
 
-### `cjbm`
-Converts JavaScript files to browser-compatible modules. The name stands for (C)onvert (J)S to (B)rowser (M)odule.
-*   **Usage:** `jstool -cmd cjbm -basePath <source_dir> -targets "['file1.js', 'file2.js']"`
+`progress-light` is the simpler spinner. It uses a fixed dot-style frame set and returns a progress object with:
 
----
+- `run()`
+- `stop()`
+- `renderSync()`
+- `setFPS(fps)`
+- `updateOptions(newFrames?, newOpt?)`
+- `deadline()`
+- `newLine()`
+- `isRunning()`
 
-### `cmtTrick`
-Toggles "comment tricks" in the code, useful for conditional code execution during development.
-*   **Usage:** `jstool -cmd cmtTrick -basePath <source_dir> -targets "['file1.js', 'file2.js']"`
+Example:
 
----
+```js
+const { create } = require("js-dev-tool/extras/progress-light");
 
-### `replace`
-Performs generic string replacement on a set of target files using a regular expression.
-*   **Usage:** `jstool -cmd replace [-after <replacement>] -regex "<regex>" [-targets "<path1>,<path2>" | <file1> <file2> ...]`
-*   **Note:** It's often better to pass target files as direct arguments instead of using the `-targets` option.
+const progress = create(12, () => "building...");
+progress.run();
 
----
+setTimeout(() => {
+  progress.deadline();
+  progress.stop();
+  progress.newLine();
+}, 800);
+```
 
-### `version`
-Bumps the version number in `package.json` and optionally in other files.
-*   **Usage:** `jstool -cmd version [-major | -minor] [-pkgJsons "./package.json,../other/package.json"] [-extras "file.html"]`
-*   **Note:** Bumps the patch version by default. Use `-major` or `-minor` to bump those instead.
+### `js-dev-tool/extras/tiny-progress`
 
----
+Exports:
 
-### `minify`
-Minifies JavaScript files using Terser.
-*   **Usage:** `jstool -cmd minify -basePath <source_dir> [-test "<regex>"] [-suffix ".min"]`
-*   **Note:** `basePath` can be a comma-separated list. The default suffix is `.mini`.
+- `create(fps?, messageEmitter?)`
 
----
+`tiny-progress` is similar to `progress-light`, but it delegates to `js-dev-tool/progress` and uses a random spinner frame set from the bundled progress resources.
 
-### `rmc`
-Removes C-style comments from files.
-*   **Usage:** `jstool -cmd rmc -basePath "./dist/cjs,./dist/other" -test "/\\.(js|d\\.ts)$/"`
-*   **Note:** Use the `-rmc4ts` flag for special handling of TypeScript comments (e.g., `/// <reference>`).
+Use this when you want a little more visual variety and do not care about choosing the exact frame list yourself.
 
----
+```js
+const { create } = require("js-dev-tool/extras/tiny-progress");
 
-### `zip`
-Creates a zip archive of specified files.
-*   **Usage:** `jstool -cmd zip [-comment "the comment"] file1.js file2.js ...`
+const progress = create(20, () => "waiting for tasks...");
+progress.run();
 
----
+setTimeout(() => {
+  progress.stop();
+  progress.newLine();
+}, 800);
+```
 
-```bash
-zip help: jstool -cmd zip [-comment "the comment"] lib/webpack.js lib/type-ids.js
-rws help: (R)ecord(W)ebpack(S)ize
-  ex - jstool -cmd rws [-webpack lib/webpack.js -umd umd/webpack.js -dest "./dev-extras/webpack-size.json"] [-rws-tags "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"]
-  note:
-    webpack  - if not specified then apply "./dist/webpack/index.js"
-    umd      - if not specified then apply "./dist/umd/index.js"
-    bin      - if not specified then apply "./dist/bin/index.js"
-    rws-tags - It is treated as parameter array separated by ":", e.g - "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"
-    dest     - if not specified then apply "./logs/webpack-size.json"
-
-cjbm help: (C)onvert (J)S to (B)rowser (M)odule
-  ex - jstool -cmd cjbm [-root ./build | -basePath "./dist/esm,extra-tests/mini-semaphore"] [-ext js] [-test /\.js$/] [-targets "['core.js', 'object.js']"]
-  note:
-    root     - Recursively searches for files.
-               This option is useful, but if there are directories that need to be avoided, use the 'basePath' option
-    basePath - can be "<path>,<path>,..." (array type arg)
-    ext      - specifies the module extension for import/export clauses. default is "js"
-    test     - Any file extension can be specified. (The default is /\.js$/)
-    targets  - specify this if you want to apply it only to a specific file.
-               the file specified here should be directly under `basePath`!
-               value must be array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."
-
-cmtTrick help: Do comment trick toggle
-  It recognizes three markers: `ctt | comment-toggle-trick | https://coderwall`
-  jstool -cmd cmtTrick[:clean] (-base <source dir> | -bases "<source dir>,<source dir>,...") [-test re/\\.js$/]
-  note:
-    :clean - remove comment token etc leaving the currently enabled code
-    base (or root) - scan single source folder
-    bases          - must be array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."
-    test           - terget extension, default is /\\.js$/
-
-replace help: jstool -cmd replace [-after <replacement>] -regex "/^\s+<!--[\s\S]+?-->(?:\r?\n)?/gm" [-targets "<path>,<path>,..." | <args: file, file file...>]
-  note:
-    targets - must be array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."
-    note: targets - can use args parameter instead
-       It is better to use the <args: file, file file...>
-       e.g - jstool -cmd replace -after ".." -regex "re/(?<=reference path=")(\.)(?=\/index.d.ts")/" build/**/*.js
-                                                                                                         ^^^^^^^^^^^^^
-
-version help: jstool -cmd version [-major | -minor] [-pkgJsons "./package.json,../package.json"] [-extras "test/web/index.html"]
-  bump top level package.json version(can specify "package.json" paths by `pkgJsons` option if need), specify patch version is unnecessary.
-  note:
-    extras - can be "<path>,<path>,..." (array type arg)
-
-minify help: jstool -cmd minify -basePath extra-tests/web/mini-semaphore [-test "re/\.js$/"] [-suffix ".mini"]
-  note:
-    basePath - can be "<path>,<path>,..." (array type arg)
-    test     - can be omit, default is `/\.js$/`
-    suffix   - can be omit, default is ".mini"
-
-rmc help: $ jstool -cmd rmc [-rmc4ts[:keepBangLine]] -basePath "./dist/cjs,./dist/cjs/gulp" -test "/\.(js|d\.ts)$/"
-  note: basePath - can be "<path>,<path>,..." (array type arg)
-    test  - can be omit, defulat `/.js$/`
-    rmc4ts- for typescript source.
-      keep comment that start with "/*" when "*/" end mark appears in same line.
-      if start with "/*-" remove it
-    rmc4ts=keepBangLine (2025/12/24)
-          - In addition to the "rmc4ts" processing, it also preserves line comments that start with "//!".
+### Runtime-Only Extras
+
+These modules are currently bundled, but they are not typed as standalone subpaths.
+
+#### `js-dev-tool/extras/json-minify`
+
+Exports:
+
+- `jsonMinify(source)`
+
+This is the direct runtime entry for the JSON / JSONL whitespace remover. Prefer `js-dev-tool/extras/jsonl` if you want the same function with TypeScript support.
+
+```js
+const { jsonMinify } = require("js-dev-tool/extras/json-minify");
+
+console.log(jsonMinify("{ \"name\": \"alpha\" }"));
+```
+
+#### `js-dev-tool/extras/list-deps-of`
+
+Exports:
+
+- `listDependenciesOf(packageName)`
 
+This helper reads `yarn.lock` from `process.cwd()` and collects transitive dependencies for the named package.
+
+Constraints:
+
+- Yarn v1 lockfile only
+- current working directory must contain the target `yarn.lock`
+- if you want types, import `listDependenciesOf` from `js-dev-tool/utils` instead
+
+```js
+const { listDependenciesOf } = require("js-dev-tool/utils");
+
+console.log(listDependenciesOf("typescript"));
+```
+
+## Basic Types
+
+`js-dev-tool/basic-types` is a types-only entry point.
+
+```ts
+/// <reference types="js-dev-tool/basic-types"/>
 ```
 
-## 📜 License
+It is a small bag of utility types kept mainly for compatibility with older code.
+
+## Commands
+
+Available `jstool` commands:
+
+- `rws`: record webpack or other bundle sizes
+- `cjbm`: convert JavaScript files to browser-compatible modules
+- `cmtTrick`: toggle comment-trick markers in source
+- `replace`: regex-based multi-file replacement
+- `version`: bump `package.json` versions and optional extra files
+- `minify`: minify JavaScript files with Terser
+- `rmc`: remove C-style comments
+- `zip`: create zip archives with an optional comment
+
+Use `jstool -help <command_name>` for the full option list of each command.
+
+## Related Libraries
+
+### [`literate-regex`](https://www.npmjs.com/package/literate-regex)
+
+`literate-regex` was originally developed as part of this project, but it is now a separate package.
 
-Released under the MIT License.  
-See [LICENSE](./LICENSE) for details.
+## License
 
+Released under the MIT License. See [LICENSE](./LICENSE) for details.

package/extras/cc-map.d.ts

@@ -9,7 +9,7 @@
  * @file extras/cc-map.d.ts
  */
 export declare type TCC_MAP = {
-  /** `\u0001` */ NULL: 0;
+  /** `\u0000` */ NULL: 0;
   /** `\u0001` */ SOH: 1;
   /** `\u0002` */ STX: 2;
   /** `\u0003` */ ETX: 3;
@@ -41,7 +41,7 @@ export declare type TCC_MAP = {
   /** `\u001d` */ GS: 29;
   /** `\u001e` */ RS: 30;
   /** `\u001f` */ US: 31;
-  /** " " */ SPACE: 32;
+  /** ` ` */ SPACE: 32;
   /** `!` */ EXCLAMATION: 33;
   /** `"` */ DOUBLE_QUOTE: 34;
   /** `#` */ HASH: 35;
@@ -103,8 +103,8 @@ export declare type TCC_MAP = {
   /** `[` */ LEFT_BRACKET: 91;
   /** `\` */ BACKSLASH: 92;
   /** `]` */ RIGHT_BRACKET: 93;
-  /** "^" */ CARET: 94;
-  /** "_" */ UNDERSCORE: 95;
+  /** `^` */ CARET: 94;
+  /** `_` */ UNDERSCORE: 95;
   /** __`__ */ GRAVE: 96;
   /** `a` */ a: 97;
   /** `b` */ b: 98;

package/extras/cc-map.js

@@ -10,7 +10,7 @@
  * @import { TCC_MAP } from "./cc-map";
  */
 module.exports = /** @type {TCC_MAP}  */({
-  /** `\u0001` */ NULL: 0,
+  /** `\u0000` */ NULL: 0,
   /** `\u0001` */ SOH: 1,
   /** `\u0002` */ STX: 2,
   /** `\u0003` */ ETX: 3,
@@ -104,8 +104,8 @@ module.exports = /** @type {TCC_MAP}  */({
   /** `[` */ LEFT_BRACKET: 91,
   /** `\` */ BACKSLASH: 92,
   /** `]` */ RIGHT_BRACKET: 93,
-  /** "^" */ CARET: 94,
-  /** "_" */ UNDERSCORE: 95,
+  /** `^` */ CARET: 94,
+  /** `_` */ UNDERSCORE: 95,
   /** __`__ */ GRAVE: 96,
   /** `a` */ a: 97,
   /** `b` */ b: 98,

package/extras/json-minify.d.ts

@@ -0,0 +1,29 @@
+export type TJsonSourceEnvelop = {
+    src: string;
+};
+export type TBlacketPairCode = [open: number, close: number];
+export type TScannerFunction = (source: string, offset: number, out: TJsonSourceEnvelop) => number;
+/**
+ * Minify JSON or JSONL text by removing JSON whitespace outside double-quoted strings.
+ *
+ * - A single top-level value is returned as minified JSON.
+ * - Multiple top-level values are returned as minified JSONL separated by `"\n"`.
+ *
+ * @param {string} source
+ * @returns {string}
+ * @version 2.0
+ */
+export function jsonMinify(source: string): string;
+/**
+ * Parse JSON or JSONL text into an array of top-level JSON values.
+ *
+ * - A single top-level value is returned as a one-element array.
+ * - Multiple top-level values separated by whitespace are returned in order.
+ * - Whitespace-only input returns an empty array.
+ *
+ * @template {unknown} T
+ * @param {string} source
+ * @returns {T[]}
+ * @since 2026/04/10 19:51:10
+ */
+export function parseJsonl<T extends unknown>(source: string): T[];

package/extras/json-minify.js

@@ -0,0 +1,287 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2026 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+"use strict";
+/**
+ * @file extras/json-minify.js
+ * @version 2.3 2026/04/06 16:11:36
+ * @version 2.4 2026/04/08 08:31:11 - expand `sjv` to v25x
+ */
+const ccMap = require("./cc-map");
+/**
+ * @typedef {{ src: string }} TJsonSourceEnvelop
+ * @typedef {[ open: number, close: number ]} TBlacketPairCode
+ */
+/** @type {TBlacketPairCode} */
+const array = [ccMap.LEFT_BRACKET, ccMap.RIGHT_BRACKET];
+/** @type {TBlacketPairCode} */
+const object = [ccMap.LEFT_BRACE, ccMap.RIGHT_BRACE];
+/**
+ * ### (O)thers (M)ap
+ *
+ * @type {(0 | 1)[]} 
+ */
+const om = Array(127).fill(0);
+om[ccMap.DOUBLE_QUOTE] = 1;
+om[ccMap.COMMA] = 1;
+om[ccMap.COLON] = 1;
+om[ccMap.LEFT_BRACKET] = 1;
+om[ccMap.RIGHT_BRACKET] = 1;
+om[ccMap.LEFT_BRACE] = 1;
+om[ccMap.RIGHT_BRACE] = 1;
+/**
+ * @param {string} message
+ * @param {number} offset
+ * @returns {never}
+ * @throws {SyntaxError}
+ */
+const throwJsonSyntaxError = (message, offset) => {
+  throw new SyntaxError(`${message}, offset=${offset}`);
+};
+/**
+ * Minify JSON or JSONL text by removing JSON whitespace outside double-quoted strings.
+ *
+ * - A single top-level value is returned as minified JSON.
+ * - Multiple top-level values are returned as minified JSONL separated by `"\n"`.
+ *
+ * @param {string} source
+ * @returns {string}
+ * @version 2.0
+ */
+function v25x(source) {
+  if (typeof source !== "string") {
+    throw new TypeError("jsonMinify(source): source must be a string");
+  }
+  /** @type {TJsonSourceEnvelop} */
+  const out = { src: "" };
+  const sourceLen = source.length;
+  let offset = 0;
+  let count = 0;
+  while (true) {
+    const next = skipWhitespaces(source, offset);
+    if (next >= sourceLen) {
+      break;
+    }
+    if (count > 0) {
+      if (next === offset) {
+        throwJsonSyntaxError("Missing whitespace between top-level JSON values", next);
+      }
+      out.src += "\n";
+    }
+    switch (source.charCodeAt(next)) {
+      case ccMap.DOUBLE_QUOTE: {
+        const skiped = sqs(source, next);
+        out.src += source.slice(next, skiped);
+        offset = skiped;
+        break;
+      }
+      case ccMap.LEFT_BRACKET:
+      case ccMap.LEFT_BRACE:
+        offset = sjoCode(source, next, out);
+        break;
+      default: {
+        const skiped = skipOthers(source, next);
+        out.src += source.slice(next, skiped);
+        offset = skiped;
+        break;
+      }
+    }
+    count++;
+  }
+  return out.src;
+}
+/**
+ * @param {string} source
+ * @param {number} offset
+ * @param {TJsonSourceEnvelop} out
+ * @returns {number}
+ * @remarks for node v25.x
+ */
+function sjv(source, offset, out) {
+  switch (source.charCodeAt(offset)) {
+    case ccMap.LEFT_BRACE:
+    case ccMap.LEFT_BRACKET: return sjoCode(source, offset, out);
+    case ccMap.DOUBLE_QUOTE: {
+      const next = sqs(source, offset);
+      out.src += source.slice(offset, next);
+      return next;
+    }
+    default: {
+      const next = skipOthers(source, offset);
+      out.src += source.slice(offset, next);
+      return next;
+    }
+  }
+}
+void sjv;
+/**
+ * (S)can (J)son (O)bject
+ * 
+ * @param {string} source
+ * @param {number} offset
+ * @param {TJsonSourceEnvelop} out
+ * @returns {number}
+ * @throws {SyntaxError}
+ * @version 2.2 `charCodeAt` version
+ */
+function sjoCode(source, offset, out) {
+  let sourceRef = out.src, nest = 0;
+  const bracket = source[offset] === "[" ? array : object;
+  const open = bracket[0];
+  const close = bracket[1];
+  const sourceLen = source.length;
+  while (offset < sourceLen) {
+    const code = source.charCodeAt(offset++);
+    if (code <= 32 /* ccMap.SPACE */) continue;
+    if (code === 34 /* ccMap.DOUBLE_QUOTE */) {
+      const next = sqs(source, offset - 1);
+      sourceRef += source.slice(offset - 1, next);
+      offset = next;
+      continue;
+    }
+    sourceRef += source[offset - 1];
+    if (code === open) {
+      nest++;
+    } else if (code === close) {
+      if (--nest === 0) break;
+    }
+  }
+  out.src = sourceRef;
+  return offset;
+}
+/**
+ * @param {string} source
+ * @param {number} offset
+ * @returns {number}
+ */
+function skipOthers(source, offset) {
+  const sourceLen = source.length;
+  let next = offset;
+  while (next < sourceLen) {
+    const code = source.charCodeAt(next++);
+    if (
+      code <= 32 || om[code]
+    ) {
+      next -= 1;
+      break;
+    }
+  }
+  if (next === offset) throwJsonSyntaxError("Invalid JSON primitive", offset);
+  return next;
+}
+/**
+ * ### (S)can (Q)uoted (S)tring
+ * 
+ * Scan a JSON double-quoted string and return the next offset.
+ *
+ * @param {string} source
+ * @param {number} offset
+ * @returns {number} `"` next offset
+ */
+function sqs(source, offset) {
+  const srcLen = source.length;
+  let next = offset + 1;
+  let inEscape = false;
+  while (next < srcLen) {
+    const code = source.charCodeAt(next++);
+    if (code === 92 /* ccMap.BACKSLASH */) {
+      inEscape = !inEscape;
+    } else if (inEscape) {
+      inEscape = false;
+    } else if (code === 34 /* ccMap.DOUBLE_QUOTE */) {
+      return next;
+    }
+  }
+  throwJsonSyntaxError("Incomplete JSON string", offset);
+}
+/**
+ * @param {number} code
+ * @returns {boolean}
+ */
+const isWhitespaceCode = (code) => code <= 32;
+/**
+ * @param {string} source
+ * @param {number} offset
+ * @returns {number}
+ */
+const skipWhitespaces = (source, offset) => {
+  const srcLen = source.length;
+  while (offset < srcLen) {
+    if (!isWhitespaceCode(source.charCodeAt(offset++))) {
+      offset -= 1;
+      break;
+    }
+  }
+  return offset;
+};
+const jsonMinify = v25x;
+const jparse = JSON.parse;
+/**
+ * Parse JSON or JSONL text into an array of top-level JSON values.
+ *
+ * - A single top-level value is returned as a one-element array.
+ * - Multiple top-level values separated by whitespace are returned in order.
+ * - Whitespace-only input returns an empty array.
+ *
+ * @template {unknown} T
+ * @param {string} source
+ * @returns {T[]}
+ * @since 2026/04/10 19:51:10
+ */
+function parseJsonl(source) {
+  if (typeof source !== "string") {
+    throw new TypeError("parseJsonl(source): source must be a string");
+  }
+  /** @type {TJsonSourceEnvelop} */
+  const out = { src: "" };
+  const sourceLen = source.length;
+  let offset = 0;
+  let count = 0;
+  /** @type {T[]} */
+  const jsons = [];
+  while (true) {
+    const next = skipWhitespaces(source, offset);
+    if (next >= sourceLen) {
+      break;
+    }
+    if (count > 0) {
+      if (next === offset) {
+        throwJsonSyntaxError("Missing whitespace between top-level JSON values", next);
+      }
+      jsons.push(
+        jparse(out.src)
+      );
+      out.src = "";
+    }
+    switch (source.charCodeAt(next)) {
+      case ccMap.DOUBLE_QUOTE: {
+        const skiped = sqs(source, next);
+        out.src += source.slice(next, skiped);
+        offset = skiped;
+        break;
+      }
+      case ccMap.LEFT_BRACKET:
+      case ccMap.LEFT_BRACE:
+        offset = sjoCode(source, next, out);
+        break;
+      default: {
+        const skiped = skipOthers(source, next);
+        out.src += source.slice(next, skiped);
+        offset = skiped;
+        break;
+      }
+    }
+    count++;
+  }
+  count && jsons.push(
+    jparse(out.src)
+  );
+  return jsons;
+}
+module.exports = {
+  jsonMinify, parseJsonl
+};

package/extras/jsonl.d.ts

@@ -115,9 +115,26 @@ export function readJsonlMapByKey<TRow = any, TOut = TRow>(fileName: string, opt
  */
 export function fastGetIntFieldCheap(line: string, key: string): number | undefined;
 /**
- * Minify JSON or JSONL text by removing JSON whitespace outside strings.
+ * Minify JSON or JSONL text by removing JSON whitespace outside double-quoted strings.
  *
  * - A single top-level value is returned as minified JSON.
  * - Multiple top-level values are returned as minified JSONL separated by `"\n"`.
+ *
+ * @param {string} source
+ * @returns {string}
+ * @version 2.0
+ */
+export function jsonMinify(source: string): string;
+/**
+ * Parse JSON or JSONL text into an array of top-level JSON values.
+ *
+ * - A single top-level value is returned as a one-element array.
+ * - Multiple top-level values separated by whitespace are returned in order.
+ * - Whitespace-only input returns an empty array.
+ *
+ * @template {unknown} T
+ * @param {string} source
+ * @returns {T[]}
+ * @since 2026/04/10 19:51:10
  */
-export function jsonMinify(source: string): string;
+export function parseJsonl<T extends unknown>(source: string): T[];

package/extras/jsonl.js

@@ -11,7 +11,7 @@
  */
 const fs = require("fs");
 const path = require("path");
-const ccMap = require("./cc-map");
+const { jsonMinify, parseJsonl } = require("./json-minify.js");
 /**
  * @import { TJsonlReadOption, TJsonlReadBaseOption } from "./jsonl.js";
  */
@@ -72,231 +72,6 @@ function fastGetIntFieldCheap(line, key) {
   }
   return ok ? sign * n : undefined;
 }
-/**
- * @typedef {{ src: string }} TJsonSourceEnvelop
- */
-/**
- * Minify JSON or JSONL text by removing JSON whitespace outside double-quoted strings.
- *
- * - A single top-level value is returned as minified JSON.
- * - Multiple top-level values are returned as minified JSONL separated by `"\n"`.
- *
- * @param {string} source
- * @returns {string}
- */
-function jsonMinify(source) {
-  if (typeof source !== "string") {
-    throw new TypeError("jsonMinify(source): source must be a string");
-  }
-  /** @type {TJsonSourceEnvelop} */
-  const out = { src: "" };
-  const sourceLen = source.length;
-  let offset = 0;
-  let count = 0;
-  while (true) {
-    const next = skipWhitespaces(source, offset);
-    if (next >= sourceLen) {
-      break;
-    }
-    if (count > 0) {
-      if (next === offset) {
-        throwJsonSyntaxError("Missing whitespace between top-level JSON values", next);
-      }
-      out.src += "\n";
-    }
-    offset = scanJsonValue(source, next, out);
-    count++;
-  }
-  return out.src;
-}
-/**
- * @param {string} source
- * @param {number} offset
- * @param {TJsonSourceEnvelop} out
- * @returns {number}
- */
-function scanJsonValue(source, offset, out) {
-  offset = skipWhitespaces(source, offset);
-  if (offset >= source.length) {
-    throwJsonSyntaxError("Unexpected end of JSON input", offset);
-  }
-  switch (source[offset]) {
-    case "\"": {
-      const next = skipQuotedString(source, offset);
-      out.src += source.slice(offset, next);
-      return next;
-    }
-    case "{": return scanJsonObject(source, offset, out);
-    case "[": return scanJsonArray(source, offset, out);
-    default: {
-      const next = skipOthers(source, offset);
-      out.src += source.slice(offset, next);
-      return next;
-    }
-  }
-}
-/**
- * @param {string} source
- * @param {number} offset
- * @param {TJsonSourceEnvelop} out
- * @returns {number}
- * @throws {SyntaxError}
- */
-function scanJsonObject(source, offset, out) {
-  out.src += "{";
-  offset = skipWhitespaces(source, offset + 1);
-  if (offset >= source.length) {
-    throwJsonSyntaxError("Unterminated JSON object", offset);
-  }
-  if (source[offset] === "}") {
-    out.src += "}";
-    return offset + 1;
-  }
-  while (offset < source.length) {
-    if (source.charCodeAt(offset) !== ccMap.DOUBLE_QUOTE) {
-      throwJsonSyntaxError("JSON object key must start with a double quote", offset);
-    }
-    const keyEnd = skipQuotedString(source, offset);
-    out.src += source.slice(offset, keyEnd);
-    offset = skipWhitespaces(source, keyEnd);
-    if (source[offset] !== ":") {
-      throwJsonSyntaxError("Missing colon after JSON object key", offset);
-    }
-    out.src += ":";
-    offset = scanJsonValue(source, offset + 1, out);
-    offset = skipWhitespaces(source, offset);
-    if (offset >= source.length) {
-      break;
-    }
-    const ch = source[offset];
-    if (ch === ",") {
-      out.src += ",";
-      offset = skipWhitespaces(source, offset + 1);
-      continue;
-    }
-    if (ch === "}") {
-      out.src += "}";
-      return offset + 1;
-    }
-    throwJsonSyntaxError("Unexpected token in JSON object", offset);
-  }
-  throwJsonSyntaxError("Unterminated JSON object", offset);
-}
-/**
- * @param {string} source
- * @param {number} offset
- * @param {TJsonSourceEnvelop} out
- * @returns {number}
- */
-function scanJsonArray(source, offset, out) {
-  out.src += "[";
-  offset = skipWhitespaces(source, offset + 1);
-  if (offset >= source.length) {
-    throwJsonSyntaxError("Unterminated JSON array", offset);
-  }
-  if (source[offset] === "]") {
-    out.src += "]";
-    return offset + 1;
-  }
-  while (offset < source.length) {
-    offset = scanJsonValue(source, offset, out);
-    offset = skipWhitespaces(source, offset);
-    if (offset >= source.length) {
-      break;
-    }
-    const ch = source[offset];
-    if (ch === ",") {
-      out.src += ",";
-      offset = skipWhitespaces(source, offset + 1);
-      continue;
-    }
-    if (ch === "]") {
-      out.src += "]";
-      return offset + 1;
-    }
-    throwJsonSyntaxError("Unexpected token in JSON array", offset);
-  }
-  throwJsonSyntaxError("Unterminated JSON array", offset);
-}
-/**
- * @param {string} source
- * @param {number} offset
- * @returns {number}
- */
-function skipOthers(source, offset) {
-  const sourceLen = source.length;
-  let next = offset;
-  while (next < sourceLen) {
-    const code = source.charCodeAt(next++);
-    if (
-      isWhitespaceCode(code) ||
-      code === ccMap.COMMA ||
-      code === ccMap.COLON ||
-      code === ccMap.LEFT_BRACKET ||
-      code === ccMap.RIGHT_BRACKET ||
-      code === ccMap.LEFT_BRACE ||
-      code === ccMap.RIGHT_BRACE ||
-      code === ccMap.DOUBLE_QUOTE
-    ) {
-      next -= 1;
-      break;
-    }
-  }
-  if (next === offset) throwJsonSyntaxError("Invalid JSON primitive", offset);
-  return next;
-}
-/**
- * Scan a JSON double-quoted string and return the next offset.
- *
- * @param {string} source
- * @param {number} offset
- * @returns {number}
- */
-function skipQuotedString(source, offset) {
-  const srcLen = source.length;
-  let next = offset + 1;
-  let inEscape = false;
-  while (next < srcLen) {
-    const ch = source[next++];
-    if (ch === "\\") {
-      inEscape = !inEscape;
-    } else if (inEscape) {
-      inEscape = false;
-    } else if (ch === "\"") {
-      return next;
-    }
-  }
-  throwJsonSyntaxError("Incomplete JSON string", offset);
-}
-/**
- * @param {number} code
- * @returns {boolean}
- */
-const isWhitespaceCode = (code) => code === ccMap.SPACE || code === ccMap.TAB || code === ccMap.LF || code === ccMap.CR;
-/**
- * @param {string} source
- * @param {number} offset
- * @returns {number}
- */
-const skipWhitespaces = (source, offset) => {
-  const srcLen = source.length;
-  while (offset < srcLen) {
-    if (!isWhitespaceCode(source.charCodeAt(offset++))) {
-      offset -= 1;
-      break;
-    }
-  }
-  return offset;
-};
-/**
- * @param {string} message
- * @param {number} offset
- * @returns {never}
- * @throws {SyntaxError}
- */
-const throwJsonSyntaxError = (message, offset) => {
-  throw new SyntaxError(`${message}, offset=${offset}`);
-};
 const HIGHWATERMARK_MIN = 128;
 /**
  * @param {unknown} n 
@@ -366,12 +141,12 @@ async function readJsonl(fileName, onRow, options = {}) {
       try {
         const row = jsonParse(line);
         onRow(row, lineNo);
-      } catch (error) {
+      } catch (e) {
         if (onParseError) {
-          onParseError(error, line, lineNo);
+          onParseError(e, line, lineNo);
           return;
         }
-        console.error("jsonl parse error:", fileName, `line=${lineNo}`, error);
+        console.error("jsonl parse error:", fileName, `line=${lineNo}`, e);
       }
     },
     options
@@ -427,5 +202,5 @@ module.exports = {
   readJsonlArray,
   readJsonlMapByKey,
   fastGetIntFieldCheap,
-  jsonMinify,
+  jsonMinify, parseJsonl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-dev-tool",
-  "version": "1.2.11",
+  "version": "1.2.13",
   "bin": {
     "jstool": "tools.js"
   },
@@ -76,6 +76,8 @@
     "!regex-test.ts",
     "!extras/npm",
     "!/**/*.png",
+    "!*@*.*",
+    "!*fragments*",
     "!tool.sh"
   ],
   "peerDependencies": {
@@ -89,7 +91,7 @@
     "mini-semaphore": "^1.5.4",
     "replace": "^1.2.2",
     "rm-cstyle-cmts": "^3.4.4",
-    "terser": "^5.46.0",
-    "tin-args": "^0.1.4"
+    "terser": "^5.46.1",
+    "tin-args": "^0.1.5"
   }
 }

package/tools.js

@@ -93,14 +93,14 @@ const ToolFunctions = {
     get help() {
       return `jstool -cmd replace [-after <replacement>] -regex \"/^\\s+<!--[\\s\\S]+?-->(?:\\r?\\n)?/gm\" [-targets "<path>,<path>,..." | <args: file, file file...>]
 
-${"Options:".red}
-  ${"after".cyan}  ${`: If omitted, "" (empty string) is used, meaning that the matched string is deleted.`.gray(16)}
-  ${"targets".cyan}${`: Single path string or Array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."`.gray(16)}
+${"  Options:".red}
+  ${"  after".cyan}  ${`: If omitted, "" (empty string) is used, meaning that the matched string is deleted.`.gray(16)}
+  ${"  targets".cyan}${`: Single path string or Array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."`.gray(16)}
 
-${"remarks".magenta}${": targets - can use args parameter instead".gray(16)}${`
-  It is better to use the <args: file, file file...>
-  e.g - ${"jstool".yellow} ${"-cmd".green} ${"replace".cyan} ${"-after".green} ${`".."`.red} ${"-regex".green} ${String.raw`'re/(?<=reference path=")(\.)(?=\/index.d.ts")/'`.magenta} ${"build/**/*.js".gray(16)}
-                                                                                                ^^^^^^^^^^^^^
+${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${`
+    It is better to use the <args: file, file file...>
+    e.g - ${"jstool".yellow} ${"-cmd".green} ${"replace".cyan} ${"-after".green} ${`".."`.red} ${"-regex".green} ${String.raw`'re/(?<=reference path=")(\.)(?=\/index.d.ts")/'`.magenta} ${"build/**/*.js".gray(16)}
+                                                                                                  ^^^^^^^^^^^^^
 `.gray(16)}`;
     },
   },