@deployanyway/error-translator 0.2.0 → 0.4.0

package/index.d.cts

@@ -0,0 +1,25 @@
+export type ErrorInput =
+  string | Error | { code?: string; name?: string; message?: string };
+export interface TranslationOptions {
+  mode?: "plain" | "rubber-duck";
+}
+export interface Translation {
+  code: string;
+  title: string;
+  explanation: string;
+  likelyCauses: string[];
+  suggestions: string[];
+  mode: "plain" | "rubber-duck";
+}
+export function translateError(
+  error: ErrorInput,
+  options?: TranslationOptions,
+): Translation;
+export function translateErrors(
+  errors: ErrorInput[],
+  options?: TranslationOptions,
+): Translation[];
+export function renderTranslation(result: Translation): string;
+export function listErrors(): string[];
+
+export function errorCatalog(options?: TranslationOptions): Translation[];

package/index.d.ts

@@ -0,0 +1,25 @@
+export type ErrorInput =
+  string | Error | { code?: string; name?: string; message?: string };
+export interface TranslationOptions {
+  mode?: "plain" | "rubber-duck";
+}
+export interface Translation {
+  code: string;
+  title: string;
+  explanation: string;
+  likelyCauses: string[];
+  suggestions: string[];
+  mode: "plain" | "rubber-duck";
+}
+export function translateError(
+  error: ErrorInput,
+  options?: TranslationOptions,
+): Translation;
+export function translateErrors(
+  errors: ErrorInput[],
+  options?: TranslationOptions,
+): Translation[];
+export function renderTranslation(result: Translation): string;
+export function listErrors(): string[];
+
+export function errorCatalog(options?: TranslationOptions): Translation[];

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@deployanyway/error-translator",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Plain-English Node.js error explanations and debugging tips, because the stack trace has chosen violence.",
   "type": "module",
-  "exports": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "bin": {
     "error-translator": "./bin/cli.js"
   },
@@ -12,16 +23,26 @@
     "bin",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "dist",
+    "index.d.ts",
+    "index.d.cts",
+    "MIGRATION.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "build": "node scripts/build.mjs",
+    "pretest": "npm run build",
+    "prepack": "npm run build",
+    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=json-summary --reporter=lcov --check-coverage --lines=90 --statements=90 --functions=90 --branches=85 node --test test/*.test.js",
+    "test:types": "tsc -p tsconfig.json",
+    "verify:package": "node scripts/verify-package.mjs"
   },
   "repository": {
     "type": "git",
@@ -35,8 +56,12 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^26.6.4",
+    "c8": "^12.0.0",
+    "esbuild": "^0.28.2",
     "eslint": "^10.12.0",
-    "prettier": "^3.6.2"
+    "prettier": "^3.6.2",
+    "typescript": "^7.0.2"
   },
   "keywords": [
     "nodejs",
@@ -46,6 +71,12 @@
     "debugging",
     "error-messages",
     "error-translator",
-    "plain-english"
-  ]
+    "plain-english",
+    "typescript",
+    "humor",
+    "deployanyway"
+  ],
+  "main": "./dist/index.cjs",
+  "types": "./index.d.ts",
+  "homepage": "https://deployanyway.github.io/"
 }

package/src/cli.js

@@ -0,0 +1,74 @@
+import { parseArgs } from "node:util";
+import { URL } from "node:url";
+import { readFileSync } from "node:fs";
+import {
+  translateError,
+  renderTranslation,
+  translateErrors,
+  listErrors,
+  errorCatalog,
+} from "./index.js";
+
+import { readStdin } from "./input.js";
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      batch: { type: "boolean" },
+      list: { type: "boolean" },
+      catalog: { type: "boolean" },
+      mode: { type: "string", default: "plain" },
+    },
+  });
+  if (values.help) {
+    console.log(
+      'Usage: error-translator <error code or quoted message> [--json] [--mode plain|rubber-duck]\n\nTranslate errors into human-readable guidance. Without arguments, read stdin (256 KiB). --batch reads a JSON array of 1–100 errors. --list lists supported codes. --catalog prints all explanations and checks.\n\nOptions:\n  -h, --help     Show help\n  -v, --version  Show version\n  --json         Print a structured JSON result\n  --mode plain|rubber-duck   Keep useful guidance; add duck commentary\n\nExamples:\n  error-translator ECONNREFUSED\n  error-translator "TypeError: value is not a function" --json\n\nExit codes: 0 translation/help/version; 2 invalid arguments.',
+    );
+  } else if (values.version) {
+    console.log(
+      JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+  } else if (values.catalog) {
+    if (positionals.length || values.batch || values.list)
+      throw new TypeError(
+        "--catalog does not accept input, --batch or --list.",
+      );
+    const catalog = errorCatalog({ mode: values.mode });
+    console.log(
+      values.json
+        ? JSON.stringify(catalog, null, 2)
+        : catalog
+            .map((item) => item.code + " — " + renderTranslation(item))
+            .join("\n\n---\n\n"),
+    );
+  } else if (values.list) {
+    if (positionals.length || values.batch)
+      throw new TypeError("--list does not accept input or --batch.");
+    console.log(
+      values.json ? JSON.stringify(listErrors()) : listErrors().join("\n"),
+    );
+  } else {
+    const text = positionals.length ? positionals.join(" ") : await readStdin();
+    const result = values.batch
+      ? translateErrors(JSON.parse(text), { mode: values.mode })
+      : translateError(text, { mode: values.mode });
+    console.log(
+      values.json
+        ? JSON.stringify(result, null, 2)
+        : Array.isArray(result)
+          ? result.map(renderTranslation).join("\n\n---\n\n")
+          : renderTranslation(result),
+    );
+  }
+} catch (error) {
+  console.error(
+    `error-translator: ${error.message}\nRun with --help for usage.`,
+  );
+  process.exitCode = 2;
+}

package/src/definitions.js

@@ -1,5 +1,7 @@
+import { extraDefinitions } from "./extra-definitions.js";
 // Keep technical guidance here so contributors can add errors without changing logic.
 export const definitions = {
+  ...extraDefinitions,
   ECONNREFUSED: {
     title: "Connection refused",
     explanation: