js-dev-tool 1.2.19 → 1.2.20

package/README.md

@@ -30,10 +30,11 @@ This section reflects the current `package.json#exports` and `package.json#files
 | --- | --- |
 | `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/common` | File-system helpers, terminal rendering primitives, and `isMain` |
 | `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/gzip-tool` | Deterministic gzip + Base64 source-literal helpers |
 | `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 |
@@ -93,6 +94,20 @@ console.log(map["1"], deps.slice(0, 5));
 - `createLogStreamAndResolvePath(logPath)`
 - `renderLine(msg?, row?)`
 - `cursor(enabled, output?)`
+- `isMain(moduleOrPathOrMeta)`
+
+`isMain(...)` is the cross-module-system entry-point check. It accepts:
+
+- CommonJS: `module` or `__filename`
+- ESM: `import.meta` or `fileURLToPath(import.meta.url)`
+
+```js
+const { isMain } = require("js-dev-tool/common");
+
+if (isMain(module)) {
+  console.log("run only when executed directly");
+}
+```
 
 ## `progress`
 
@@ -190,6 +205,34 @@ async function main() {
 main().catch(console.error);
 ```
 
+### `js-dev-tool/extras/gzip-tool`
+
+Exports:
+
+- `gzip(data, useZeroTimestamp?)`
+- `toBase64SourceLiteral(rawData, wrapSize?)`
+
+Use this module when you want deterministic gzip output and a clean way to embed the compressed bytes into JavaScript source.
+
+Key behaviors:
+
+- `gzip(...)` compresses with gzip level `9`
+- `gzip(..., true)` zeroes the gzip `mtime` header so repeated builds with the same input stay byte-stable
+- `toBase64SourceLiteral(...)` wraps Base64 output with trailing `\` line continuations so the result can be pasted into a multi-line JavaScript string literal
+- `wrapSize` must be a finite integer between `1` and `2048`
+
+Example:
+
+```js
+const { gzip, toBase64SourceLiteral } = require("js-dev-tool/extras/gzip-tool");
+
+const compressed = gzip("console.log(\"hello\");");
+const sourceLiteral = toBase64SourceLiteral(compressed, 76);
+
+console.log(compressed.length);
+console.log(sourceLiteral);
+```
+
 ### `js-dev-tool/extras/progress-light`
 
 Exports:

package/common/index.d.ts

@@ -43,17 +43,29 @@ export function renderLine(msg?: string, row?: number): void;
  */
 export function cursor(enabled: boolean, output?: NodeJS.WriteStream): void;
 /**
- * Returns `true` if the given module is the entry point of the current process.
+ * Minimal `import.meta`-compatible shape accepted by `isMain`.
  *
- * Accepts either a `module` object (CommonJS) or a file path string,
- * making it usable from both CommonJS and ESM contexts.
+ * Only `url` is required. `resolve` stays optional so the same shape works
+ * across older and newer Node.js ESM runtimes.
+ */
+declare type TImportMeta = {
+  url: string;
+  resolve?: (filePath: string) => string;
+ };
+/**
+ * Returns `true` when the provided CommonJS module, absolute file path, or
+ * ESM `import.meta` object represents the current process entry point.
+ *
+ * This gives one API that works across both module systems:
+ * - CommonJS: `module` or `__filename`
+ * - ESM: `import.meta` or `fileURLToPath(import.meta.url)`
  *
  * Equivalent to `import.meta.main` in Deno / Bun,
  * or `process.argv[1] === fileURLToPath(import.meta.url)` in ESM.
  *
- * @param {Partial<NodeJS.Module> | string} modOrFilePath
- *   Pass `module` or `__filename` (CommonJS),
- *   or `fileURLToPath(import.meta.url)` (ESM).
+ * @param {Partial<NodeJS.Module> | TImportMeta | string} modOrPathOrMeta
+ *   Pass `module` or `__filename` from CommonJS,
+ *   or `import.meta` / `fileURLToPath(import.meta.url)` from ESM.
  * @returns {boolean} `true` if the calling module is the entry point.
  *
  * @example
@@ -67,7 +79,12 @@ export function cursor(enabled: boolean, output?: NodeJS.WriteStream): void;
  * if (isMain(__filename)) { main(); }
  *
  * @example
- * // ESM — via fileURLToPath:
+ * // ESM — via import.meta object:
+ * import { isMain } from "js-dev-tool/common";
+ * if (isMain(import.meta)) { main(); }
+ *
+ * @example
+ * // ESM — via fileURLToPath(import.meta.url):
  * import { isMain } from "js-dev-tool/common";
  * import { fileURLToPath } from "node:url";
  * if (isMain(fileURLToPath(import.meta.url))) { main(); }
@@ -76,4 +93,4 @@ export function cursor(enabled: boolean, output?: NodeJS.WriteStream): void;
  * @verified CJS: Confirmed working on Node.js v11.15.0 — v26.3.0.
  * @verified ESM: Confirmed working on Node.js v12.22.11 — v26.3.0.
  */
-export function isMain(modOrFilePath: Partial<NodeJS.Module> | string): boolean;
+export function isMain(modOrPathOrMeta: Partial<NodeJS.Module> | TImportMeta | string): boolean;

package/common/index.js

@@ -13,6 +13,7 @@
 const fs = require("fs");
 const path = require("path");
 const rl = require("readline");
+const { fileURLToPath } = require("url");
 /**
  * @param {string} dest
  */
@@ -56,17 +57,30 @@ const cursor = (enabled, output = process.stderr) => {
   }
 };
 /**
- * Returns `true` if the given module is the entry point of the current process.
+ * Minimal `import.meta`-compatible shape accepted by {@link isMain}.
  *
- * Accepts either a `module` object (CommonJS) or a file path string,
- * making it usable from both CommonJS and ESM contexts.
+ * Only `url` is required. `resolve` stays optional so the same shape works
+ * across older and newer Node.js ESM runtimes.
+ *
+ * @typedef {{
+ *   url: string;
+ *   resolve?: (filePath: string) => string;
+ * }} TImportMeta
+ */
+/**
+ * Returns `true` when the provided CommonJS module, absolute file path, or
+ * ESM `import.meta` object represents the current process entry point.
+ *
+ * This gives one API that works across both module systems:
+ * - CommonJS: `module` or `__filename`
+ * - ESM: `import.meta` or `fileURLToPath(import.meta.url)`
  *
  * Equivalent to `import.meta.main` in Deno / Bun,
  * or `process.argv[1] === fileURLToPath(import.meta.url)` in ESM.
  *
- * @param {Partial<NodeJS.Module> | string} modOrFilePath
- *   Pass `module` or `__filename` (CommonJS),
- *   or `fileURLToPath(import.meta.url)` (ESM).
+ * @param {Partial<NodeJS.Module> | TImportMeta | string} modOrPathOrMeta
+ *   Pass `module` or `__filename` from CommonJS,
+ *   or `import.meta` / `fileURLToPath(import.meta.url)` from ESM.
  * @returns {boolean} `true` if the calling module is the entry point.
  *
  * @example
@@ -80,7 +94,12 @@ const cursor = (enabled, output = process.stderr) => {
  * if (isMain(__filename)) { main(); }
  *
  * @example
- * // ESM — via fileURLToPath:
+ * // ESM — via import.meta object:
+ * import { isMain } from "js-dev-tool/common";
+ * if (isMain(import.meta)) { main(); }
+ *
+ * @example
+ * // ESM — via fileURLToPath(import.meta.url):
  * import { isMain } from "js-dev-tool/common";
  * import { fileURLToPath } from "node:url";
  * if (isMain(fileURLToPath(import.meta.url))) { main(); }
@@ -89,11 +108,18 @@ const cursor = (enabled, output = process.stderr) => {
  * @verified CJS: Confirmed working on Node.js v11.15.0 — v26.3.0.
  * @verified ESM: Confirmed working on Node.js v12.22.11 — v26.3.0.
  */
-function isMain(modOrFilePath) {
-  if (typeof modOrFilePath === "string") {
-    return process.argv[1] === modOrFilePath;
+function isMain(modOrPathOrMeta) {
+  /** @type {string=} */
+  let pathString;
+  if (typeof modOrPathOrMeta === "string") {
+    pathString = modOrPathOrMeta;
+  } else if ("url" in modOrPathOrMeta /* && "resolve" in modOrPathOrMeta */) {
+    pathString = fileURLToPath(modOrPathOrMeta.url);
+  }
+  if (pathString) {
+    return process.argv[1] === pathString;
   }
-  return require.main === modOrFilePath;
+  return require.main === modOrPathOrMeta;
 }
 module.exports = {
   checkParentDirectory,

package/extras/gzip-tool.js

@@ -49,11 +49,16 @@ function toBase64SourceLiteral(rawData, wrapSize = 100) {
   if (wrapSize > 2048) throw new Error(`"wrapSize" is expected to be 2048 or less - ${wrapSize}`);
   if (wrapSize < 1) throw new Error(`A wrapSize of 0 or less will result in an infinite loop, so please make it 1 or greater. - ${wrapSize}`);
   const base64 = Buffer.from(rawData).toString("base64");
-  let wrapped = "";
-  for (let offset = 0, L = base64.length; offset < L;) {
-    wrapped += `${base64.slice(offset, offset += wrapSize)}\\\n`;
+  const L = base64.length;
+  if (!L) return "";
+  let wrapped = "", lineSuffix = "\\\n";
+  for (let offset = 0; offset < L;) {
+    if (
+      (offset + wrapSize) >= L
+    ) lineSuffix = "";
+    wrapped += (base64.slice(offset, offset += wrapSize) + lineSuffix);
   }
-  return wrapped.slice(0, -2);
+  return wrapped;
 }
 module.exports = {
   gzip, toBase64SourceLiteral

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-dev-tool",
-  "version": "1.2.19",
+  "version": "1.2.20",
   "type": "commonjs",
   "bin": {
     "jstool": "tools.js",
@@ -84,7 +84,7 @@
     "!tool.sh"
   ],
   "peerDependencies": {
-    "archiver": "^4.0.1",
+    "archiver": "^7.0.1",
     "webpack": "*"
   },
   "dependencies": {
@@ -95,7 +95,7 @@
     "replace": "^1.2.2",
     "rm-cstyle-cmts": "^3.4.4",
     "terser": "^5.48.0",
-    "tin-args": "^0.1.6",
+    "tin-args": "^0.1.7",
     "ts-cc-map": "^1.1.0"
   }
 }