js-dev-tool 1.2.2 → 1.2.4

package/basic-types.d.ts

@@ -106,6 +106,7 @@ type PickNumberProperties<T> = PickProperties<number, T>;
 type PickStringProperties<T> = PickProperties<string, T>;
 type NonFunctionPropertyNames<T> = { [K in keyof T]-?: T[K] extends Function ? never : K }[keyof T];
 type NonFunctionProperties<T> = Pick<T, NonFunctionPropertyNames<T>>;
+type ArrayToUnion<T extends readonly unknown[]> = T[number];
 /**
  * for lazy assign class.
  */

package/common/index.js

@@ -9,6 +9,7 @@
  * @file js-dev-scripts/common/index.js
  */
 // @ts-check
+"use strict";
 const fs = require("fs");
 const path = require("path");
 const rl = require("readline");

package/extras/list-deps-of.js

@@ -5,6 +5,7 @@
 //  https://opensource.org/licenses/mit-license.php
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
+"use strict";
 /**
  * @file list-deps-of.js
  * @command node list-deps-of.mjs typescript-jsdoctag-completions-plugin

package/extras/tiny-progress.js

@@ -5,6 +5,7 @@
   https://opensource.org/licenses/mit-license.php
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
+"use strict";
 /** [usage]
 > node -i
 let t = require("./extras/progress-sample");

package/index.js

@@ -5,6 +5,7 @@
   https://opensource.org/licenses/mit-license.php
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
+"use strict";
 const progress = require("./progress");
 const common = require("./common");
 const utils = require("./utils");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-dev-tool",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "bin": {
     "jstool": "tools.js"
   },
@@ -85,11 +85,11 @@
   "dependencies": {
     "colors.ts": "^1.0.20",
     "fflate": "^0.8.2",
-    "literate-regex": "^0.5.1",
-    "mini-semaphore": "^1.4.4",
+    "literate-regex": "^0.6.9",
+    "mini-semaphore": "^1.5.1",
     "replace": "^1.2.2",
-    "rm-cstyle-cmts": "^3.3.26",
-    "terser": "^5.44.1",
-    "tin-args": "^0.1.1"
+    "rm-cstyle-cmts": "^3.4.2",
+    "terser": "^5.46.0",
+    "tin-args": "^0.1.3"
   }
 }

package/progress/index.js

@@ -6,6 +6,7 @@
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 /// <reference path="./index.d.ts" preserve="true"/>
+"use strict";
 const lib = require("../common");
 const {
   checkENV,

package/progress/progress-extras.js

@@ -6,6 +6,7 @@
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 /// <reference path="./index.d.ts"/>
+"use strict";
 const lib = require("../common");
 const checkENV = () => {
   const env = process.env;

package/progress/rnd-spinner.js

@@ -5,6 +5,7 @@
   https://opensource.org/licenses/mit-license.php
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
+"use strict";
 /**
  * @file random spinner
  * @author jeffy-g <hirotom1107@gmail.com>

package/progress/test.js

@@ -5,6 +5,7 @@
   https://opensource.org/licenses/mit-license.php
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
+"use strict";
 /** [usage]
 > node -i
 let t = require("./progress/test");

package/tool-lib/cjbm.js

@@ -6,6 +6,7 @@
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 /// <reference path="./tools.d.ts"/>
+"use strict";
 // @ts-check
 /**
  * @file (C)onvert (J)S to (B)rowser (M)odule
@@ -56,7 +57,7 @@ const reImportExportDetection = compilePCREStyleRegExpLiteral(RE_TEXT);
 /**
  * @typedef {typeof reImportExportDetection} TImportExportDetectorRegex
  * @typedef {TImportExportDetectorRegex["types"]["exec"]} TImportExportDetectorRegexExecResult
- * @typedef {XRegex.StringReplacerFunction<TImportExportDetectorRegex>} TImportExportDetectRegexReplacer
+ * @typedef {XRegex.StringReplacerType<TImportExportDetectorRegex>} TImportExportDetectRegexReplacer
  */
 /**
  * Generates a replacer function to update import/export statements with a new file extension.

package/tool-lib/cmt-trick.js

@@ -6,6 +6,7 @@
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 /// <reference path="./tools.d.ts"/>
+"use strict";
 // @ts-check
 /**
  * @file comment trick toggle

package/tool-lib/ps.js

@@ -7,6 +7,7 @@
 */
 /// <reference path="./tools.d.ts"/>
 // @ts-check
+"use strict";
 const DEBUG = 0;
 /** @type {(err: NodeJS.ErrnoException, cb: () => void) => void} */
 const handleError = (err, done) => {

package/tool-lib/rws.js

@@ -7,6 +7,7 @@
 */
 /// <reference path="./tools.d.ts"/>
 // @ts-check
+"use strict";
 /**
  * @file (R)ecord(W)ebpack(S)ize
  */

package/tool-lib/tools.d.ts

@@ -5,7 +5,7 @@
   https://opensource.org/licenses/mit-license.php
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
-/// <reference types="literate-regex"/>
+/// <reference types="literate-regex/global"/>
 /**
  * @date 2023-10-25
  */

package/tool-lib/zip-task.js

@@ -7,6 +7,7 @@
 */
 /// <reference path="./tools.d.ts"/>
 // @ts-check
+"use strict";
 /**
  * @file zip compression task
  */

package/tools.js

@@ -8,8 +8,10 @@
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 // @ts-check
+"use strict";
 const fs = require("fs");
 const path = require("path");
+const rmc = require("rm-cstyle-cmts");
 /* utilities module by own. */
 const utils = require("./utils");
 // @ts-expect- error
@@ -203,14 +205,16 @@ const ToolFunctions = {
   rmc: {
     taskName: "rm-cstyle-cmts",
     fn() {
-      const rmc = require("rm-cstyle-cmts");
+      rmc.reset();
       if (params.rmc4ts) {
         const keepBangLine = params.rmc4ts === "keepBangLine";
+        const reMultiLineChcker = /^\/\*(\*|!)\s|^\/\*(?!-).+\*\/$/;
+        const reSingleLineChecer = /^\/\/+!/;
         rmc.setListener(({ event, fragment }) => {
           if (event === /*EScannerEvent.MultiLineComment*/ 1) {
-            return /^\/\*(\*|!)\s|^\/\*(?!-).+\*\/$/.test(fragment);
+            return reMultiLineChcker.test(fragment);
           } else if (keepBangLine && event === /*EScannerEvent.SingleLineComment*/0) {
-            return /^\/\/+!/.test(fragment);
+            return reSingleLineChecer.test(fragment);
           }
           return false;
         });
@@ -220,7 +224,8 @@ const ToolFunctions = {
       processSources(
         /** @type {string} */ (this.taskName),
         (data) => {
-          return rmc(data);
+          let result = rmc(data);
+          return preserveTsReferenceDirectives(result, params.debug);
         },
         {
           bases: basePaths,
@@ -236,12 +241,44 @@ const ToolFunctions = {
     rmc4ts- for typescript source.
       keep comment that start with "/*" when "*/" end mark appears in same line.
       if start with "/*-" remove it
+      keep leading "/// <reference ...>" directives above a top-level "use strict" line in CJS emit.(2026/02/03)
     rmc4ts=keepBangLine (2025/12/24)
           - In addition to the "rmc4ts" processing, it also preserves line comments that start with "//!".
 `,
   },
   zip: require("./tool-lib/zip-task")(utils),
 };
+/**
+ * Preserve TypeScript `/// <reference ...>` directives when a leading
+ * "use strict" line would otherwise push them below the directive zone
+ * after C-style comment stripping.
+ *
+ * It hoists any header reference directives back above "use strict" so the
+ * TypeScript compiler can still see them in CommonJS outputs.
+ *
+ * @param {string} jsSource - JavaScript source after comment removal.
+ * @param {true=} debug - Log when code is executed.
+ * @returns {string} Source with reference directives restored to the header.
+ * @date 2026/02/03 14:45:49
+ */
+function preserveTsReferenceDirectives(jsSource, debug) {
+  const m = /^(["'])use strict\1;?[\r\n]/.exec(jsSource);
+  if (m) {
+    const usLen = m[0].length;
+    const usLine = jsSource.slice(m.index, usLen);
+    /** @type {string[]} */
+    const knownDirectives = [];
+    let purgedSource = jsSource.slice(usLen).replace(/^\/\/\/\s*<reference.+[\r\n]/gm, (match) => {
+      knownDirectives.push(match);
+      return "";
+    });
+    if (knownDirectives.length) {
+      debug && utils.log("preserveTsReferenceDirectives applied");
+      return knownDirectives.join("") + usLine + purgedSource;
+    }
+  }
+  return jsSource;
+}
 /**
  * @param {TJSToolEntry} entry
  * @returns {entry is TJSToolEntry}

package/utils.d.ts

@@ -25,9 +25,9 @@ export type TExtraArgsValue = string | boolean | RegExp | string[];
  * `${content}${suffix}${<str_array element>}`
  * ```
  *
- * @param {string[]} str_array the string array
- * @param {string} content prepend content
- * @param {string} [suffix]
+ * @param str_array the string array
+ * @param content prepend content
+ * @param [suffix]
  * @date 2020/2/16
  * @version 2.0 rename `appendStringTo` -> `prependStringTo`
  */
@@ -44,7 +44,7 @@ export function prependStringTo(str_array: string[], content: string, suffix?: s
  * console.log(nv); // => {major: 10, minor: 9, patch: 0}
  * ```
  *
- * @param {string} versionString default is process.version
+ * @param versionString default is process.version
  */
 export function extractVersion(versionString?: string): {
   major: number;
@@ -53,54 +53,54 @@ export function extractVersion(versionString?: string): {
 };
 /**
  * use toLocaleString
- * @param {any} ymd use simple year month day formant? default `false`
+ * @param ymd use simple year month day formant? default `false`
  *  + should be truthy/falsy value
  */
 export function dateStringForFile(ymd?: any): string;
 /**
  * use "rm-cstyle-cmts"
  * 
- * @param {string} source
+ * @param source
  */
 export function removeJsonComments(source: string): string;
 /**
  * write text content to dest path.
  * when not exists parent directory, creat it.
  *
- * @param {string|NodeJS.ReadableStream|Buffer} content text? content.
- * @param {string} dest content output path
- * @param {() => void} [callback] the callback function
+ * @param content text? content.
+ * @param dest content output path
+ * @param [callback] the callback function
  */
 export function writeText(content: string | NodeJS.ReadableStream | Buffer, dest: string, callback?: () => void): void;
 /**
- * @param {string} from file path.
+ * @param from file path.
  * @param [callback]
  */
 export function readText<C extends TBD<TFsCallback>, R extends undefined extends C ? string : void>(from: string, callback?: C): R;
 /**
  * NOTE: when callback specified, returns undefined
  *
- * @param {string} path
+ * @param path
  * @param [callback]
  */
 export function readJson<T, C extends TBD<TReadJsonCallback<string>>, R extends undefined extends C ? TypedRecord<T> : void>(path: string, callback?: C): R;
 /**
- * @param {string} path
- * @param {(dirent: Dirent) => void} handler
+ * @param path
+ * @param handler
  */
 export function walkDirSync(path: string, handler: (dirent: Dirent) => void): void;
 /**
  * create sourceName zip. (using zip.min.js
  *
- * @param {string} scriptPath simple script file name. e.g - webpack (original path are "./lib/webpack.js")
- * @param {string} comment the zip file comment.
+ * @param scriptPath simple script file name. e.g - webpack (original path are "./lib/webpack.js")
+ * @param comment the zip file comment.
  */
 export function compressScript(scriptPath: string, comment?: string): void;
 /**
  * DEVNOTE: 10/21/2018, 9:15:00 PM - using "archiver" package, this is too fast!.
  *
- * @param {string} scriptPath
- * @param {string} comment
+ * @param scriptPath
+ * @param comment
  */
 export function compressScript2(scriptPath: string, comment?: string): void;
 /**
@@ -109,9 +109,9 @@ export function compressScript2(scriptPath: string, comment?: string): void;
  * + 📝 using "exec" internally
  *   * 🆗️ can use pipe command
  *
- * @param {string} command
- * @param {(result: string) => void} doneCallbackWithArgs gulp callback function.
- * @param {string=} cwd 2025/2/1 current working directory
+ * @param command
+ * @param doneCallbackWithArgs gulp callback function.
+ * @param cwd 2025/2/1 current working directory
  */
 export function execWithOutputResult(command: string, doneCallbackWithArgs: (result: string) => void, cwd?: string): any;
 /**
@@ -131,26 +131,26 @@ export function execWithOutputResult(command: string, doneCallbackWithArgs: (res
  *   console.log("done");
  * });
  * ```
- * @param {import("vinyl")} vinyl
- * @param {string} dest default is "." -> node launched directory. (cwd?)
+ * @param vinyl
+ * @param dest default is "." -> node launched directory. (cwd?)
  */
-export function convertRelativeDir(vinyl: any, dest?: string): string;
+export function convertRelativeDir(vinyl: import("vinyl"), dest?: string): string;
 /**
  * ### command:
  *
  * + windows - chcp 65001 && clip
  * + others  - xclip
  *
- * @param {string} content the copy terget content as string.
- * @param {string} [message] default: "text copied!"
- * @param {boolean} [chcp65001] default `true`
+ * @param content the copy terget content as string.
+ * @param [message] default: "text copied!"
+ * @param [chcp65001] default `true`
  */
 export function copyText(content: string, message?: string, chcp65001?: boolean): void;
 /**
- * @param {RegExp} regex
- * @param {string | Function} replacement
- * @param {string[]} paths Paths that do not exist are ignored
- * @param {boolean} [async]
+ * @param regex
+ * @param replacement
+ * @param paths Paths that do not exist are ignored
+ * @param [async]
  *
  * @date 2019-4-26
  */
@@ -160,4 +160,54 @@ export const CI: boolean;
  * Nothing is logged in a CI environment.
  */
 export const log: typeof console.log;
-export const listDependenciesOf: typeof import("./extras/list-deps-of").listDependenciesOf;
+export const listDependenciesOf: typeof import("./extras/list-deps-of").listDependenciesOf;
+export type TCSVParseOpt = {
+  /**
+   * Zero-based column index to use as the map key.
+   * @default 0
+   */
+  mapKeyCol: number;
+  /**
+   * Zero-based column index to sort by (omit to keep original order).
+   * @default undefined
+   */
+  sortByCol?: number;
+  /**
+   * @default /\t/
+   */
+  separator?: string | RegExp;
+};
+/**
+ * Builds a key -> row index from a delimited text source (TSV by default).
+ * Alias: {@link parseDelimitedToIndex}.
+ *
+ * @template TKey - The key type used to identify each row.
+ * @template TProp - The property-name type for each row field.
+ * @template Entry - A parsed row (key column is omitted).
+ * @template R - The resulting index type.
+ *
+ * @param tsvSource - Delimited text to parse (expects a header row).
+ * @param opt - Parsing options (separator, key column, optional sort column).
+ *
+ * @returns A key-to-row index.
+ *
+ * @example
+ * // Key by the 3rd column (marketGroupName) and sort by name.
+ * const map = indexByCol(_data, { mapKeyCol: 2, sortByCol: 2 });
+ * console.log(map["Gunnery"].description);
+ *
+ * @remarks
+ * - The first line is treated as the header (property names).
+ * - The key column is used only as the map key and is omitted from each Entry.
+ * - Numeric-looking values are coerced to numbers when finite.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries Object.entries (MDN)}
+ * @date 2026/02/05 19:46:19
+ */
+export declare function indexByCol<
+  TKey extends string,
+  TProp extends string,
+  Entry extends Partial<Record<TProp, string | number>>,
+  R extends Record<TKey, Entry>
+>(tsvSource: string, opt?: TCSVParseOpt): R;
+export const parseDelimitedToIndex: typeof indexByCol;

package/utils.js

@@ -20,6 +20,7 @@
 /// <reference types="./basic-types"/>
 /// <reference types="./lib/zlibjs.d.ts"/>
 // @ts-check
+"use strict";
 const fs = require("fs");
 const path = require("path");
 const lib = require("./common");
@@ -302,6 +303,84 @@ function execWithOutputResult(command, doneCallbackWithArgs, cwd) {
     }
   });
 }
+/**
+ * @import { TCSVParseOpt } from "./utils";
+ */
+/**
+ * Builds a key -> row index from a delimited text source (TSV by default).
+ * Alias: {@link parseDelimitedToIndex}.
+ *
+ * @template {string} TKey - The key type used to identify each row.
+ * @template {string} TProp - The property-name type for each row field.
+ * @template {Partial<Record<TProp, string | number>>} Entry - A parsed row (key column is omitted).
+ * @template {Record<TKey, Entry>} R - The resulting index type.
+ *
+ * @param {string} tsvSource - Delimited text to parse (expects a header row).
+ * @param {TCSVParseOpt=} opt - Parsing options (separator, key column, optional sort column).
+ *
+ * @returns {R} A key-to-row index.
+ *
+ * @example
+ * // Key by the 3rd column (marketGroupName) and sort by name.
+ * const map = indexByCol(_data, { mapKeyCol: 2, sortByCol: 2 });
+ * console.log(map["Gunnery"].description);
+ *
+ * @remarks
+ * - The first line is treated as the header (property names).
+ * - The key column is used only as the map key and is omitted from each Entry.
+ * - Numeric-looking values are coerced to numbers when finite.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries Object.entries (MDN)}
+ * @date 2026/02/05 19:46:19
+ */
+function indexByCol(tsvSource, opt) {
+  const lines = tsvSource.split(/[\r\n]+/);
+  const linesLen = lines.length;
+  if (linesLen === 0) return /** @type {R} */({});
+  const {
+    separator = /\t/,
+    mapKeyCol = 0,
+    sortByCol
+  } = opt || {};
+  const propertyList = /** @type {TProp[]} */(lines[0].split(separator));
+  let mapData = /** @type {R} */(Object.create(null));
+  for (let idx = 1; idx < linesLen;) {
+    const line = lines[idx++];
+    if (!line) continue;
+    const cols = /** @type {string[]} */(line.split(separator));
+    const key = /** @type {TKey} */(cols[mapKeyCol]);
+    const currentMap = /** @type {Entry} */({});
+    for (let _idx = 0, pListLen = propertyList.length; _idx  < pListLen; _idx++) {
+      if (_idx === mapKeyCol) continue;
+      const val = cols[_idx];
+      const n = +val;
+      currentMap[
+        propertyList[_idx]
+      ] = /** @type {Entry[TProp]} */((val !== "" && Number.isFinite(n)) ? n : val);
+    }
+    mapData[key] = /** @type {R[TKey]} */(currentMap);
+  }
+  if (typeof sortByCol === "number") {
+    const _mapData = /** @type {R} */(Object.create(null));
+    if (mapKeyCol === sortByCol) {
+      const keys = /** @type {TKey[]} */(Object.keys(mapData).sort());
+      for (const key of keys) _mapData[key] = mapData[key];
+    } else {
+      const propName = propertyList[sortByCol];
+      /*const sortedEntries =*/
+      /** @type {[TKey, Entry][]} */(Object.entries(mapData)).sort(([, a], [, b]) => {
+        const av = a[propName];
+        const bv = b[propName];
+        // @ts-expect-error bv type are same as `av`
+        return typeof av === "string" ? av.localeCompare(bv) : av - bv;
+      }).forEach(entry => {
+        _mapData[entry[0]] = /** @type {R[TKey]} */(entry[1]);
+      });
+    }
+    mapData = _mapData;
+  }
+  return mapData;
+}
 /**
  * ### command:
  *
@@ -407,5 +486,7 @@ module.exports = {
   fireReplace,
   CI,
   log,
-  listDependenciesOf
+  listDependenciesOf,
+  indexByCol,
+  parseDelimitedToIndex: indexByCol
 };