js-dev-tool

js-dev-tool

js-dev-tool is a mixed package of jstool CLI commands and small Node.js helpers for JavaScript / TypeScript project maintenance.

The published modules are CommonJS. The examples below use require(...) so the runtime behavior matches the package as published.

Install

npm i js-dev-tool

CLI Usage

jstool is the package binary and points to tools.js.

jstool -cmd <command_name> [options]
node tools.js -cmd <command_name> [options]
node tools.js -help <command_name>

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 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
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

const { utils, common, progress } = require("js-dev-tool");

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:

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));

common

js-dev-tool/common contains the low-level pieces used by the progress helpers.

• checkParentDirectory(dest)
• 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)

const { isMain } = require("js-dev-tool/common");

if (isMain(module)) {
  console.log("run only when executed directly");
}

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.

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

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:

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/gzip-tool

Exports:

• gzip(data, useZeroTimestamp?)
• gunzip(data)
• toBase64SourceLiteral(rawData, wrapSize?)
• fromBase64SourceLiteral(sourceLiteral)

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
• gunzip(...) restores raw bytes from gzip-compressed data
• toBase64SourceLiteral(...) wraps Base64 output with trailing \ line continuations so the result can be pasted into a multi-line JavaScript string literal
• fromBase64SourceLiteral(...) reverses the wrapped source-literal form and accepts both LF and CRLF line continuations
• wrapSize must be a finite integer between 1 and 2048

Example:

const {
  gzip, gunzip,
  toBase64SourceLiteral, fromBase64SourceLiteral
} = require("js-dev-tool/extras/gzip-tool");

const compressed = gzip("console.log(\"hello\");");
const sourceLiteral = toBase64SourceLiteral(compressed, 76);
const restored = gunzip(fromBase64SourceLiteral(sourceLiteral));

console.log(compressed.length);
console.log(sourceLiteral);
console.log(restored.toString("utf8"));

js-dev-tool/extras/progress-light

Exports:

• create(fps?, messageEmitter?)

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()

Example:

const { create } = require("js-dev-tool/extras/progress-light");

const progress = create(12, () => "building...");
progress.run();

setTimeout(() => {
  progress.deadline();
  progress.stop();
  progress.newLine();
}, 800);

js-dev-tool/extras/tiny-progress

Exports:

• 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.

Use this when you want a little more visual variety and do not care about choosing the exact frame list yourself.

const { create } = require("js-dev-tool/extras/tiny-progress");

const progress = create(20, () => "waiting for tasks...");
progress.run();

setTimeout(() => {
  progress.stop();
  progress.newLine();
}, 800);

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.

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

const { listDependenciesOf } = require("js-dev-tool/utils");

console.log(listDependenciesOf("typescript"));

Basic Types

js-dev-tool/basic-types is a types-only entry point.

/// <reference types="js-dev-tool/basic-types"/>

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

literate-regex was originally developed as part of this project, but it is now a separate package.

License

Released under the MIT License. See LICENSE for details.