js-dev-tool 1.2.3 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-dev-tool",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "bin": {
     "jstool": "tools.js"
   },
@@ -90,6 +90,6 @@
     "replace": "^1.2.2",
     "rm-cstyle-cmts": "^3.4.2",
     "terser": "^5.46.0",
-    "tin-args": "^0.1.1"
+    "tin-args": "^0.1.3"
   }
 }

package/tools.js

@@ -225,7 +225,7 @@ const ToolFunctions = {
         /** @type {string} */ (this.taskName),
         (data) => {
           let result = rmc(data);
-          return preserveTsReferenceDirectives(result);
+          return preserveTsReferenceDirectives(result, params.debug);
         },
         {
           bases: basePaths,
@@ -268,8 +268,7 @@ function preserveTsReferenceDirectives(jsSource, debug) {
     const usLine = jsSource.slice(m.index, usLen);
     /** @type {string[]} */
     const knownDirectives = [];
-    const reReferenceDirectiveChecker = /^\/\/\/\s*<reference.+[\r\n]/gm;
-    let purgedSource = jsSource.slice(usLen).replace(reReferenceDirectiveChecker, (match) => {
+    let purgedSource = jsSource.slice(usLen).replace(/^\/\/\/\s*<reference.+[\r\n]/gm, (match) => {
       knownDirectives.push(match);
       return "";
     });

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

@@ -303,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:
  *
@@ -408,5 +486,7 @@ module.exports = {
   fireReplace,
   CI,
   log,
-  listDependenciesOf
+  listDependenciesOf,
+  indexByCol,
+  parseDelimitedToIndex: indexByCol
 };