js-dev-tool 1.2.10 → 1.2.12

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

@@ -0,0 +1,141 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2026 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file extras/cc-map.d.ts
+ */
+export declare type TCC_MAP = {
+  /** `\u0000` */ NULL: 0;
+  /** `\u0001` */ SOH: 1;
+  /** `\u0002` */ STX: 2;
+  /** `\u0003` */ ETX: 3;
+  /** `\u0004` */ EOT: 4;
+  /** `\u0005` */ ENQ: 5;
+  /** `\u0006` */ ACK: 6;
+  /** `\u0007` */ BEL: 7;
+  /** `\u0008` */ BS: 8;
+  /** `\t` */     TAB: 9;
+  /** `\n` */     LF: 10;
+  /** `\u000b` */ VT: 11;
+  /** `\f` */     FF: 12;
+  /** `\r` */     CR: 13;
+  /** `\u000e` */ SO: 14;
+  /** `\u000f` */ SI: 15;
+  /** `\u0010` */ DLE: 16;
+  /** `\u0011` */ DC1: 17;
+  /** `\u0012` */ DC2: 18;
+  /** `\u0013` */ DC3: 19;
+  /** `\u0014` */ DC4: 20;
+  /** `\u0015` */ NAK: 21;
+  /** `\u0016` */ SYN: 22;
+  /** `\u0017` */ ETB: 23;
+  /** `\u0018` */ CAN: 24;
+  /** `\u0019` */ EM: 25;
+  /** `\u001a` */ SUB: 26;
+  /** `\u001b` */ ESC: 27;
+  /** `\u001c` */ FS: 28;
+  /** `\u001d` */ GS: 29;
+  /** `\u001e` */ RS: 30;
+  /** `\u001f` */ US: 31;
+  /** ` ` */ SPACE: 32;
+  /** `!` */ EXCLAMATION: 33;
+  /** `"` */ DOUBLE_QUOTE: 34;
+  /** `#` */ HASH: 35;
+  /** `$` */ DOLLAR: 36;
+  /** `%` */ PERCENT: 37;
+  /** `&` */ AMPERSAND: 38;
+  /** `'` */ SINGLE_QUOTE: 39;
+  /** `(` */ LEFT_PAREN: 40;
+  /** `)` */ RIGHT_PAREN: 41;
+  /** `*` */ ASTERISK: 42;
+  /** `+` */ PLUS: 43;
+  /** `,` */ COMMA: 44;
+  /** `-` */ MINUS: 45;
+  /** `.` */ PERIOD: 46;
+  /** `/` */ SLASH: 47;
+  /** `0` */ ZERO: 48;
+  /** `1` */ ONE: 49;
+  /** `2` */ TWO: 50;
+  /** `3` */ THREE: 51;
+  /** `4` */ FOUR: 52;
+  /** `5` */ FIVE: 53;
+  /** `6` */ SIX: 54;
+  /** `7` */ SEVEN: 55;
+  /** `8` */ EIGHT: 56;
+  /** `9` */ NINE: 57;
+  /** `:` */ COLON: 58;
+  /** `;` */ SEMICOLON: 59;
+  /** `<` */ LESS_THAN: 60;
+  /** `=` */ EQUAL: 61;
+  /** `>` */ GREATER_THAN: 62;
+  /** `?` */ QUESTION: 63;
+  /** `@` */ AT: 64;
+  /** `A` */ A: 65;
+  /** `B` */ B: 66;
+  /** `C` */ C: 67;
+  /** `D` */ D: 68;
+  /** `E` */ E: 69;
+  /** `F` */ F: 70;
+  /** `G` */ G: 71;
+  /** `H` */ H: 72;
+  /** `I` */ I: 73;
+  /** `J` */ J: 74;
+  /** `K` */ K: 75;
+  /** `L` */ L: 76;
+  /** `M` */ M: 77;
+  /** `N` */ N: 78;
+  /** `O` */ O: 79;
+  /** `P` */ P: 80;
+  /** `Q` */ Q: 81;
+  /** `R` */ R: 82;
+  /** `S` */ S: 83;
+  /** `T` */ T: 84;
+  /** `U` */ U: 85;
+  /** `V` */ V: 86;
+  /** `W` */ W: 87;
+  /** `X` */ X: 88;
+  /** `Y` */ Y: 89;
+  /** `Z` */ Z: 90;
+  /** `[` */ LEFT_BRACKET: 91;
+  /** `\` */ BACKSLASH: 92;
+  /** `]` */ RIGHT_BRACKET: 93;
+  /** `^` */ CARET: 94;
+  /** `_` */ UNDERSCORE: 95;
+  /** __`__ */ GRAVE: 96;
+  /** `a` */ a: 97;
+  /** `b` */ b: 98;
+  /** `c` */ c: 99;
+  /** `d` */ d: 100;
+  /** `e` */ e: 101;
+  /** `f` */ f: 102;
+  /** `g` */ g: 103;
+  /** `h` */ h: 104;
+  /** `i` */ i: 105;
+  /** `j` */ j: 106;
+  /** `k` */ k: 107;
+  /** `l` */ l: 108;
+  /** `m` */ m: 109;
+  /** `n` */ n: 110;
+  /** `o` */ o: 111;
+  /** `p` */ p: 112;
+  /** `q` */ q: 113;
+  /** `r` */ r: 114;
+  /** `s` */ s: 115;
+  /** `t` */ t: 116;
+  /** `u` */ u: 117;
+  /** `v` */ v: 118;
+  /** `w` */ w: 119;
+  /** `x` */ x: 120;
+  /** `y` */ y: 121;
+  /** `z` */ z: 122;
+  /** `{` */ LEFT_BRACE: 123;
+  /** `|` */ PIPE: 124;
+  /** `}` */ RIGHT_BRACE: 125;
+  /** `~` */ TILDE: 126;
+};
+declare const CC_MAP: TCC_MAP;
+export = CC_MAP;