developer-error-message-translator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Developer Error Message Translator Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# 🚀 Developer Error Message Translator
+
+> **Turn cryptic error messages into plain English.**  
+> Instantly understand what went wrong, why it happened, and exactly how to fix it.
+
+![License](https://img.shields.io/npm/l/developer-error-message-translator)
+![Version](https://img.shields.io/npm/v/developer-error-message-translator)
+![Build Status](https://img.shields.io/github/actions/workflow/status/antigravity/developer-error-message-translator/test)
+
+---
+
+## 🧐 The Problem
+We've all been there. You run your code, and the console spits out:
+`TypeError: Cannot read properties of undefined (reading 'map')`
+`Error: Objects are not valid as a React child`
+`ReferenceError: Cannot access 'count' before initialization`
+
+These messages are accurate but **not helpful**. They tell you *what* broke, but rarely *why* or *how* to fix it.
+
+## ✨ The Solution
+**Developer Error Message Translator** takes these raw error strings and returns a structured, human-readable explanation with actionable fixes.
+
+It supports:
+*   ⚛️ **React:** Hook rules, unique keys, re-renders, object rendering.
+*   🟢 **Node.js:** Module errors, ESM vs CommonJS conflicts.
+*   🌐 **Network/API:** Axios errors, Fetch failures, 404/500 codes.
+*   ⚡ **Core JS:** TypeErrors, ReferenceErrors, SyntaxErrors (including TDZ).
+*   📦 **NPM:** Dependency conflicts (ERESOLVE), missing files (ENOENT).
+
+---
+
+## 📦 Installation
+
+```bash
+npm install developer-error-message-translator
+```
+
+---
+
+## 🛠️ Usage
+
+### As a Function
+Use it in your error boundaries, logging services, or CLI tools.
+
+```typescript
+import translateError from 'developer-error-message-translator';
+
+try {
+  // Your buggy code
+  const user = null;
+  console.log(user.name);
+} catch (error) {
+  const helpful = translateError(error.message);
+  
+  console.log("🔍 Exploration:", helpful.explanation);
+  console.log("❓ Possible Causes:", helpful.causes);
+  console.log("✅ How to Fix:", helpful.fixes);
+}
+```
+
+**Output:**
+```text
+🔍 Exploration: You are trying to access the property 'name' on a variable that is currently 'null'.
+❓ Possible Causes:
+  - The variable hasn't been assigned a value yet.
+  - You might be trying to access data from an API call before it has finished loading.
+✅ How to Fix:
+  - Use optional chaining: variable?.name
+  - Check if the variable exists before accessing 'name'.
+  - Initialize the variable with a default value.
+```
+
+### CLI Tool
+You can also valid errors directly from your terminal!
+
+```bash
+npx dev-translate "Error: Objects are not valid as a React child"
+```
+
+---
+
+## 🏆 Supported Errors (30+ Scenarios)
+
+### React
+*   Objects are not valid as a React child
+*   Too many re-renders
+*   Each child in a list should have a unique "key" prop
+*   Invalid hook call
+*   Cannot update a component while rendering a different component
+
+### Node.js & NPM
+*   Cannot find module 'x'
+*   ReferenceError: require is not defined (ESM)
+*   SyntaxError: Unexpected token 'export' (CommonJS)
+*   ENOENT: no such file or directory
+*   npm ERR! ERESOLVE unable to resolve dependency tree
+
+### API & Network
+*   TypeError: Failed to fetch
+*   AxiosError: Network Error
+*   Request failed with status code 404 / 500
+*   EADDRINUSE: address already in use
+
+### Core JavaScript
+*   Cannot read property of undefined / null
+*   X is not a function
+*   Cannot destructure property
+*   Assignment to constant variable
+*   Cannot access 'X' before initialization (TDZ)
+*   Do not know how to serialize a BigInt
+*   Converting circular structure to JSON
+*   Unexpected token '<' (JSX in JS file)
+
+---
+
+## 🤝 Contributing
+We love contributions! If you encounter an error that isn't translated well, please open an issue or submit a PR with a new pattern in `src/patterns`.
+
+1.  Fork the repo
+2.  Create your feature branch (`git checkout -b feature/new-error`)
+3.  Add your pattern and tests
+4.  Commit your changes
+5.  Push to the branch
+6.  Open a Pull Request
+
+---
+
+## 📄 License
+ISC

package/dist/bin/dev-translate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/dev-translate.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chalk_1 = __importDefault(require("chalk"));
+const index_1 = require("../src/index");
+const args = process.argv.slice(2);
+const errorMessage = args.join(' ');
+if (!errorMessage) {
+    console.log(chalk_1.default.red('Please provide an error message to translate.'));
+    console.log(chalk_1.default.yellow('Usage: dev-translate "Error message here"'));
+    process.exit(1);
+}
+const translation = (0, index_1.translateError)(errorMessage);
+console.log(chalk_1.default.bold.blue('\n🔍 What went wrong:'));
+console.log(translation.explanation);
+if (translation.causes.length > 0) {
+    console.log(chalk_1.default.bold.yellow('\n❓ Why it happened:'));
+    translation.causes.forEach(cause => console.log(`- ${cause}`));
+}
+if (translation.fixes.length > 0) {
+    console.log(chalk_1.default.bold.green('\n✅ How to fix it:'));
+    translation.fixes.forEach(fix => console.log(`- ${fix}`));
+}
+console.log('\n');

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './translator';
+export * from './monitor';
+import { translateError } from './translator';
+export default translateError;

package/dist/src/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./translator"), exports);
+__exportStar(require("./monitor"), exports);
+const translator_1 = require("./translator");
+exports.default = translator_1.translateError;

package/dist/src/monitor.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Initializes the error translator to monitor uncaught exceptions and unhandled rejections.
+ * This checks for errors at runtime and prints a friendly explanation before exiting.
+ */
+export declare function init(): void;

package/dist/src/monitor.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const chalk_1 = __importDefault(require("chalk"));
+const translator_1 = require("./translator");
+/**
+ * Initializes the error translator to monitor uncaught exceptions and unhandled rejections.
+ * This checks for errors at runtime and prints a friendly explanation before exiting.
+ */
+function init() {
+    process.on('uncaughtException', (error) => {
+        handleError(error);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        handleError(reason);
+        process.exit(1);
+    });
+    console.log(chalk_1.default.gray('ℹ️  Developer Error Message Translator is monitoring your application...'));
+}
+function handleError(error) {
+    const errorMessage = error instanceof Error ? error.toString() : String(error);
+    const translation = (0, translator_1.translateError)(errorMessage);
+    console.error(chalk_1.default.bgRed.white.bold('\n 💥 APPLICATION CRASHED \n'));
+    console.error(chalk_1.default.bold.blue('🔍 What went wrong:'));
+    console.error(translation.explanation);
+    if (translation.causes.length > 0) {
+        console.error(chalk_1.default.bold.yellow('\n❓ Why it happened:'));
+        translation.causes.forEach(cause => console.error(`- ${cause}`));
+    }
+    if (translation.fixes.length > 0) {
+        console.error(chalk_1.default.bold.green('\n✅ How to fix it:'));
+        translation.fixes.forEach(fix => console.error(`- ${fix}`));
+    }
+    console.error('\n');
+    console.error(chalk_1.default.gray('Original Error Stack:'));
+    console.error(error);
+}

package/dist/src/patterns/api.d.ts

@@ -0,0 +1,6 @@
+import { ErrorPattern } from '../types';
+export declare const failedToFetchPattern: ErrorPattern;
+export declare const axiosNetworkErrorPattern: ErrorPattern;
+export declare const status404Pattern: ErrorPattern;
+export declare const status500Pattern: ErrorPattern;
+export declare const apiPatterns: ErrorPattern[];

package/dist/src/patterns/api.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiPatterns = exports.status500Pattern = exports.status404Pattern = exports.axiosNetworkErrorPattern = exports.failedToFetchPattern = void 0;
+exports.failedToFetchPattern = {
+    // Matches "TypeError: Failed to fetch"
+    regex: /TypeError: Failed to fetch/,
+    handler: () => ({
+        explanation: "The browser or runtime failed to make a network request.",
+        causes: ["The server is down or unreachable.", "You are blocked by CORS (Cross-Origin Resource Sharing).", "You are offline."],
+        fixes: ["Check if the backend server is running.", "Check the browser console for CORS errors.", "Verify your internet connection."]
+    })
+};
+exports.axiosNetworkErrorPattern = {
+    // Matches "AxiosError: Network Error"
+    regex: /AxiosError: Network Error/,
+    handler: () => ({
+        explanation: "Axios failed to connect to the server.",
+        causes: ["The server is offline.", "CORS issues.", "Invalid protocol (http vs https)."],
+        fixes: ["Check the server status.", "Verify the URL endpoint."]
+    })
+};
+exports.status404Pattern = {
+    // Matches "Request failed with status code 404"
+    regex: /Request failed with status code 404/,
+    handler: () => ({
+        explanation: "The requested resource was not found (404).",
+        causes: ["The API endpoint URL is incorrect.", "The ID you provided doesn't exist in the database."],
+        fixes: ["Check the URL path.", "Verify the resource ID."]
+    })
+};
+exports.status500Pattern = {
+    // Matches "Request failed with status code 500"
+    regex: /Request failed with status code 500/,
+    handler: () => ({
+        explanation: "The server encountered an internal error (500).",
+        causes: ["The backend code crashed.", "Database connection failed."],
+        fixes: ["Check the backend server logs for the real error."]
+    })
+};
+exports.apiPatterns = [
+    exports.failedToFetchPattern,
+    exports.axiosNetworkErrorPattern,
+    exports.status404Pattern,
+    exports.status500Pattern
+];

package/dist/src/patterns/mongoose.d.ts

@@ -0,0 +1,5 @@
+import { ErrorPattern } from '../types';
+export declare const mongooseCastErrorPattern: ErrorPattern;
+export declare const mongooseDuplicateKeyPattern: ErrorPattern;
+export declare const mongooseValidationErrorPattern: ErrorPattern;
+export declare const mongoosePatterns: ErrorPattern[];

package/dist/src/patterns/mongoose.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mongoosePatterns = exports.mongooseValidationErrorPattern = exports.mongooseDuplicateKeyPattern = exports.mongooseCastErrorPattern = void 0;
+exports.mongooseCastErrorPattern = {
+    // Matches "Cast to ObjectId failed for value..." or variants
+    regex: /Cast to \w+ failed for value/,
+    handler: (match) => {
+        return {
+            explanation: "A Mongoose 'CastError' occurred. You tried to use a value that couldn't be converted to the expected type (e.g., an invalid string for an ObjectId).",
+            causes: [
+                "You passed an invalid MongoDB ObjectId string to a query like `.findById()`.",
+                "You passed a string to a field expecting a Number or Date."
+            ],
+            fixes: [
+                "Validate input IDs to ensure they are 24-character hex strings.",
+                "Check that your request body matches the schema types."
+            ]
+        };
+    }
+};
+exports.mongooseDuplicateKeyPattern = {
+    // Matches "E11000 duplicate key error..."
+    regex: /E11000 duplicate key error/,
+    handler: (match) => {
+        return {
+            explanation: "A MongoDB 'Duplicate Key' error occurred. You tried to save a record with a field that must be unique, but it already exists.",
+            causes: [
+                "You are registering a user with an email that is already in the database.",
+                "You are creating a document with a unique index that conflicts with existing data."
+            ],
+            fixes: [
+                "Check if the record already exists before creating it.",
+                "Catch this error and show a user-friendly message like 'Email already taken'."
+            ]
+        };
+    }
+};
+exports.mongooseValidationErrorPattern = {
+    // Matches "ValidationError: ..."
+    regex: /ValidationError: /,
+    handler: (match) => {
+        return {
+            explanation: "A Mongoose 'ValidationError' occurred. The data you tried to save didn't match the schema requirements.",
+            causes: [
+                "A required field is missing.",
+                "A field value is shorter/longer than the defined minlength/maxlength.",
+                "Enum validation failed."
+            ],
+            fixes: [
+                "Check the error details to see which field failed.",
+                "Ensure your request body provides all required fields."
+            ]
+        };
+    }
+};
+exports.mongoosePatterns = [
+    exports.mongooseCastErrorPattern,
+    exports.mongooseDuplicateKeyPattern,
+    exports.mongooseValidationErrorPattern
+];

package/dist/src/patterns/network.d.ts

@@ -0,0 +1,4 @@
+import { ErrorPattern } from '../types';
+export declare const addressInUsePattern: ErrorPattern;
+export declare const connectionRefusedPattern: ErrorPattern;
+export declare const networkPatterns: ErrorPattern[];

package/dist/src/patterns/network.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.networkPatterns = exports.connectionRefusedPattern = exports.addressInUsePattern = void 0;
+exports.addressInUsePattern = {
+    // Matches "Error: listen EADDRINUSE: address already in use :::3000"
+    regex: /EADDRINUSE/,
+    handler: (match) => {
+        return {
+            explanation: "The network port you are trying to use is already taken by another process.",
+            causes: [
+                "You have the server running in another terminal window.",
+                "Another application is using the same port (e.g., 3000 or 8080)."
+            ],
+            fixes: [
+                "Close the other terminal where the server is running.",
+                "Kill the process using the port (e.g., `kill -9 <PID>` or task manager).",
+                "Change the port number in your code or `.env` file."
+            ]
+        };
+    }
+};
+exports.connectionRefusedPattern = {
+    // Matches "Error: connect ECONNREFUSED 127.0.0.1:27017"
+    regex: /ECONNREFUSED/,
+    handler: (match) => {
+        return {
+            explanation: "The connection to the server or database was refused. It couldn't be reached.",
+            causes: [
+                "The database server (e.g., MongoDB) is not running.",
+                "You are using the wrong host or port.",
+                "A firewall is blocking the connection."
+            ],
+            fixes: [
+                "Ensure your database server is running (`mongod`, `postgres`, etc.).",
+                "Check your connection string (URI) for typos.",
+                "Check if the service is reachable."
+            ]
+        };
+    }
+};
+exports.networkPatterns = [
+    exports.addressInUsePattern,
+    exports.connectionRefusedPattern
+];

package/dist/src/patterns/node.d.ts

@@ -0,0 +1,7 @@
+import { ErrorPattern } from '../types';
+export declare const moduleNotFoundPattern: ErrorPattern;
+export declare const requireNotDefinedPattern: ErrorPattern;
+export declare const unexpectedExportPattern: ErrorPattern;
+export declare const enoentPattern: ErrorPattern;
+export declare const npmResolvePattern: ErrorPattern;
+export declare const nodePatterns: ErrorPattern[];

package/dist/src/patterns/node.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodePatterns = exports.npmResolvePattern = exports.enoentPattern = exports.unexpectedExportPattern = exports.requireNotDefinedPattern = exports.moduleNotFoundPattern = void 0;
+exports.moduleNotFoundPattern = {
+    // Matches "Error: Cannot find module 'x'"
+    regex: /Cannot find module '([^']+)'/,
+    handler: (match) => {
+        const moduleName = match[1];
+        return {
+            explanation: `Node.js cannot find the module '${moduleName}'.`,
+            causes: [
+                `You forgot to install the package: \`npm install ${moduleName}\`.`,
+                "You misspelled the import path.",
+                "You are trying to import a relative file without `./` (e.g., `import user from 'user'` instead of `'./user'`)."
+            ],
+            fixes: [
+                `Run \`npm install ${moduleName}\`.`,
+                "Check your import path."
+            ]
+        };
+    }
+};
+exports.requireNotDefinedPattern = {
+    // Matches "ReferenceError: require is not defined"
+    regex: /require is not defined/,
+    handler: () => ({
+        explanation: "You are trying to use CommonJS `require()` in an ES Module environment.",
+        causes: ["Your `package.json` has `\"type\": \"module\"` but you are using `require()`.", "You are using a `.mjs` file extension."],
+        fixes: ["Use `import` statements instead.", "Remove `\"type\": \"module\"` from package.json if you want to use CommonJS."]
+    })
+};
+exports.unexpectedExportPattern = {
+    // Matches "SyntaxError: Unexpected token 'export'"
+    regex: /Unexpected token 'export'/,
+    handler: () => ({
+        explanation: "You are trying to use ES Module `export` syntax in a CommonJS environment.",
+        causes: ["You are attempting to use `export` in a generic script or CommonJS file."],
+        fixes: ["Add `\"type\": \"module\"` to your `package.json`.", "Use `module.exports = ...` instead."]
+    })
+};
+exports.enoentPattern = {
+    // Matches "ENOENT: no such file or directory, open '...'"
+    regex: /ENOENT: no such file or directory, open '([^']+)'/,
+    handler: (match) => {
+        const filePath = match[1];
+        return {
+            explanation: `The system cannot find the file or directory at '${filePath}'.`,
+            causes: ["The file path is incorrect.", "The file hasn't been created yet.", "You are running the script from the wrong directory."],
+            fixes: ["Check that the file exists.", "Verify your current working directory."]
+        };
+    }
+};
+exports.npmResolvePattern = {
+    // Matches "npm ERR! ERESOLVE unable to resolve dependency tree"
+    regex: /ERESOLVE unable to resolve dependency tree/,
+    handler: () => ({
+        explanation: "NPM is facing a conflict between dependencies (e.g., Package A needs React 17, but Packet B needs React 18).",
+        causes: ["Incompatible peer dependencies."],
+        fixes: ["Try running `npm install --legacy-peer-deps`.", "Update your dependencies to compatible versions."]
+    })
+};
+exports.nodePatterns = [
+    exports.moduleNotFoundPattern,
+    exports.requireNotDefinedPattern,
+    exports.unexpectedExportPattern,
+    exports.enoentPattern,
+    exports.npmResolvePattern
+];

package/dist/src/patterns/rangeError.d.ts

@@ -0,0 +1,4 @@
+import { ErrorPattern } from '../types';
+export declare const stackOverflowPattern: ErrorPattern;
+export declare const invalidArrayLengthPattern: ErrorPattern;
+export declare const rangeErrorPatterns: ErrorPattern[];

package/dist/src/patterns/rangeError.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rangeErrorPatterns = exports.invalidArrayLengthPattern = exports.stackOverflowPattern = void 0;
+exports.stackOverflowPattern = {
+    // Matches "RangeError: Maximum call stack size exceeded"
+    regex: /RangeError: Maximum call stack size exceeded/,
+    handler: (match) => {
+        return {
+            explanation: "The function called itself too many times (infinite recursion) or the call stack is too deep.",
+            causes: [
+                "You have a recursive function that is missing a base case (an exit condition).",
+                "Two functions are calling each other in a loop."
+            ],
+            fixes: [
+                "Check your recursive functions to ensure they have a condition to stop.",
+                "Use a loop instead of recursion if possible for deep iterations."
+            ]
+        };
+    }
+};
+exports.invalidArrayLengthPattern = {
+    // Matches "RangeError: Invalid array length"
+    regex: /RangeError: Invalid array length/,
+    handler: (match) => {
+        return {
+            explanation: "You tried to create an Array with an invalid length (e.g., negative or too large).",
+            causes: [
+                "You passed a negative number to `new Array()`.",
+                "You passed a non-integer float to `new Array()`."
+            ],
+            fixes: [
+                "Ensure the array length is a positive integer.",
+                "Check variables passed to the Array constructor."
+            ]
+        };
+    }
+};
+exports.rangeErrorPatterns = [
+    exports.stackOverflowPattern,
+    exports.invalidArrayLengthPattern
+];

package/dist/src/patterns/react.d.ts

@@ -0,0 +1,7 @@
+import { ErrorPattern } from '../types';
+export declare const objectsNotValidChildPattern: ErrorPattern;
+export declare const tooManyRerendersPattern: ErrorPattern;
+export declare const uniqueKeyPattern: ErrorPattern;
+export declare const invalidHookCallPattern: ErrorPattern;
+export declare const updateWhileRenderingPattern: ErrorPattern;
+export declare const reactPatterns: ErrorPattern[];

package/dist/src/patterns/react.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reactPatterns = exports.updateWhileRenderingPattern = exports.invalidHookCallPattern = exports.uniqueKeyPattern = exports.tooManyRerendersPattern = exports.objectsNotValidChildPattern = void 0;
+exports.objectsNotValidChildPattern = {
+    // Matches "Error: Objects are not valid as a React child..."
+    regex: /Objects are not valid as a React child/,
+    handler: () => ({
+        explanation: "You are trying to render a JavaScript Object directly in JSX. React only renders strings, numbers, or elements.",
+        causes: ["You used `<div>{obj}</div>` instead of `<div>{obj.name}</div>`.", "You forgot to map over an array."],
+        fixes: ["Render a specific property.", "Use `JSON.stringify()` for debugging.", "Use `.map()` for arrays."]
+    })
+};
+exports.tooManyRerendersPattern = {
+    // Matches "Error: Too many re-renders"
+    regex: /Too many re-renders/,
+    handler: () => ({
+        explanation: "Your component is caught in an infinite update loop.",
+        causes: ["You are setting state directly inside the render body (e.g., `setCount(0)`).", "You have a `useEffect` without a dependency array that updates state."],
+        fixes: ["Wrap state updates in `useEffect` or event handlers.", "Check your `useEffect` dependency array."]
+    })
+};
+exports.uniqueKeyPattern = {
+    // Matches "Warning: Each child in a list should have a unique 'key' prop"
+    regex: /Each child in a list should have a unique "key" prop/,
+    handler: () => ({
+        explanation: "You are rendering a list of elements but forgot to give each one a unique `key` prop.",
+        causes: ["You are using `.map()` without adding `key={id}` to the returned element."],
+        fixes: ["Add a unique `key` prop (e.g., `<li key={item.id}>`).", "Avoid using index as a key if the list can change order."]
+    })
+};
+exports.invalidHookCallPattern = {
+    // Matches "Error: Invalid hook call"
+    regex: /Invalid hook call/,
+    handler: () => ({
+        explanation: "You tried to use a React Hook (like `useState` or `useEffect`) in an invalid place.",
+        causes: [
+            "You called a hook inside a loop, condition, or nested function.",
+            "You called a hook from a regular JavaScript function (not a component).",
+            "You likely have mismatched versions of React and React DOM."
+        ],
+        fixes: [
+            "Move the hook to the top level of your function component.",
+            "Ensure you aren't calling hooks conditionally."
+        ]
+    })
+};
+exports.updateWhileRenderingPattern = {
+    // Matches "Warning: Cannot update a component (`X`) while rendering a different component (`Y`)"
+    regex: /Cannot update a component .* while rendering a different component/,
+    handler: () => ({
+        explanation: "You are triggering a state update in a parent component purely as a side effect of a child rendering.",
+        causes: ["A child component is calling a state-setter prop (e.g., `setParentState`) directly in its body."],
+        fixes: ["Wrap the update in `useEffect`.", "Move the logic to an event handler."]
+    })
+};
+exports.reactPatterns = [
+    exports.objectsNotValidChildPattern,
+    exports.tooManyRerendersPattern,
+    exports.uniqueKeyPattern,
+    exports.invalidHookCallPattern,
+    exports.updateWhileRenderingPattern
+];

package/dist/src/patterns/referenceError.d.ts

@@ -0,0 +1,4 @@
+import { ErrorPattern } from '../types';
+export declare const notDefinedPattern: ErrorPattern;
+export declare const accessBeforeInitPattern: ErrorPattern;
+export declare const referenceErrorPatterns: ErrorPattern[];

package/dist/src/patterns/referenceError.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.referenceErrorPatterns = exports.accessBeforeInitPattern = exports.notDefinedPattern = void 0;
+exports.notDefinedPattern = {
+    // Matches "ReferenceError: x is not defined"
+    regex: /ReferenceError: (.+) is not defined/,
+    handler: (match) => {
+        const variableName = match[1];
+        return {
+            explanation: `The variable '${variableName}' is being used, but it hasn't been defined or is out of scope.`,
+            causes: [
+                "You misspelled the variable name.",
+                "You are using a variable declared in a different function or block (scope issue).",
+                "You forgot to import the variable."
+            ],
+            fixes: [
+                `Check the spelling of '${variableName}'.`,
+                "Ensure the variable is declared (let, const, var) before use.",
+                "Check if you need to import it from another file."
+            ]
+        };
+    }
+};
+exports.accessBeforeInitPattern = {
+    // Matches "ReferenceError: Cannot access 'x' before initialization"
+    regex: /Cannot access '([^']+)' before initialization/,
+    handler: (match) => {
+        const variableName = match[1];
+        return {
+            explanation: `You are trying to use the variable '${variableName}' before it has been initialized in the code.`,
+            causes: [
+                "You are using a `let` or `const` variable before the line where it is declared.",
+                "You have a circular dependency where two files import each other."
+            ],
+            fixes: [
+                "Move the declaration of the variable above the line where you use it.",
+                "Check for circular dependencies in your imports."
+            ]
+        };
+    }
+};
+exports.referenceErrorPatterns = [
+    exports.notDefinedPattern,
+    exports.accessBeforeInitPattern
+];

package/dist/src/patterns/syntaxError.d.ts

@@ -0,0 +1,5 @@
+import { ErrorPattern } from '../types';
+export declare const jsonParsePattern: ErrorPattern;
+export declare const unexpectedTokenPattern: ErrorPattern;
+export declare const unexpectedTokenReactPattern: ErrorPattern;
+export declare const syntaxErrorPatterns: ErrorPattern[];

package/dist/src/patterns/syntaxError.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syntaxErrorPatterns = exports.unexpectedTokenReactPattern = exports.unexpectedTokenPattern = exports.jsonParsePattern = void 0;
+exports.jsonParsePattern = {
+    // Matches "SyntaxError: Unexpected token X in JSON at position Y"
+    // OR "SyntaxError: Unexpected end of JSON input"
+    regex: /Unexpected (token|end) .* JSON/,
+    handler: (match) => {
+        return {
+            explanation: "The text you are trying to parse as JSON is not valid JSON.",
+            causes: [
+                "You are trying to parse an HTML response (common when 404/500 errors return HTML pages).",
+                "The JSON string is empty or incomplete.",
+                "The JSON is malformed (e.g., trailing commas, single quotes instead of double quotes)."
+            ],
+            fixes: [
+                "Log the response text before parsing it to see what it actually contains.",
+                "Check if the API returned an error page (HTML) instead of JSON."
+            ]
+        };
+    }
+};
+exports.unexpectedTokenPattern = {
+    // Matches "SyntaxError: Unexpected token }"
+    regex: /Unexpected token ('|")?([^'"]+)('|")?/,
+    handler: (match) => {
+        const token = match[2];
+        return {
+            explanation: `The code contains a character or sequence '${token}' that the JavaScript engine didn't expect.`,
+            causes: [
+                `You might be missing a closing brace '}', parenthesis ')', or bracket ']'.`,
+                "You might have an extra comma or semicolon."
+            ],
+            fixes: [
+                "Check for mismatched brackets or parentheses.",
+                "Look for extra characters near usage of the reported token."
+            ]
+        };
+    }
+};
+exports.unexpectedTokenReactPattern = {
+    // Matches "SyntaxError: Unexpected token '<'"
+    regex: /Unexpected token '<'/,
+    handler: () => ({
+        explanation: "You are trying to use JSX (like `<div>`) in a file that is not compiled as React/JSX.",
+        causes: ["You are using a `.js` extension instead of `.jsx` or `.tsx`.", "Your build tool (Babel/Webpack) is not configured for React."],
+        fixes: ["Rename the file to `.jsx` or `.tsx`.", "Check your Babel configuration."]
+    })
+};
+exports.syntaxErrorPatterns = [
+    exports.jsonParsePattern,
+    exports.unexpectedTokenReactPattern, // specific check first
+    exports.unexpectedTokenPattern
+];

package/dist/src/patterns/typeError.d.ts

@@ -0,0 +1,8 @@
+import { ErrorPattern } from '../types';
+export declare const cannotReadPropertyPattern: ErrorPattern;
+export declare const isNotAFunctionPattern: ErrorPattern;
+export declare const destructuringPattern: ErrorPattern;
+export declare const assignmentToConstantPattern: ErrorPattern;
+export declare const bigIntSerializationPattern: ErrorPattern;
+export declare const circularJsonPattern: ErrorPattern;
+export declare const typeErrorPatterns: ErrorPattern[];

package/dist/src/patterns/typeError.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeErrorPatterns = exports.circularJsonPattern = exports.bigIntSerializationPattern = exports.assignmentToConstantPattern = exports.destructuringPattern = exports.isNotAFunctionPattern = exports.cannotReadPropertyPattern = void 0;
+exports.cannotReadPropertyPattern = {
+    // Matches "Cannot read property 'x' of undefined" OR "of null"
+    regex: /Cannot read propert(?:y|ies) (?:'([^']+)' )?of (undefined|null)(?: \(reading '([^']+)'\))?/,
+    handler: (match) => {
+        const property = match[1] || match[3] || 'unknown';
+        const valueType = match[2]; // 'undefined' or 'null'
+        return {
+            explanation: `You are trying to access the property '${property}' on a variable that is currently '${valueType}'.`,
+            causes: [
+                "The variable hasn't been assigned a value yet.",
+                "You might be trying to access data from an API call before it has finished loading.",
+                "You are accessing a nested property (e.g., user.address.city) where the parent (user.address) doesn't exist."
+            ],
+            fixes: [
+                `Use optional chaining: variable?.${property}`,
+                `Check if the variable exists before accessing '${property}': if (variable) { ... }`,
+                "Initialize the variable with a default value."
+            ]
+        };
+    }
+};
+exports.isNotAFunctionPattern = {
+    // Matches "TypeError: X is not a function"
+    regex: /TypeError: (.+) is not a function/,
+    handler: (match) => {
+        const variableName = match[1];
+        return {
+            explanation: `You are trying to call '${variableName}' as a function, but it is not one.`,
+            causes: [
+                `'${variableName}' might be undefined or null.`,
+                `'${variableName}' might be an object or a string, not a function.`,
+                "You might have a typo in the function name."
+            ],
+            fixes: [
+                `Log '${variableName}' to see what it actually contains.`,
+                "Check if you imported the function correctly."
+            ]
+        };
+    }
+};
+exports.destructuringPattern = {
+    // Matches "TypeError: Cannot destructure property 'name' of 'user' as it is undefined"
+    regex: /Cannot destructure property '([^']+)' of '([^']+)' as it is (undefined|null)/,
+    handler: (match) => {
+        const property = match[1];
+        const variableName = match[2];
+        const valueType = match[3];
+        return {
+            explanation: `You tried to extract (destructure) the property '${property}' from '${variableName}', but '${variableName}' is ${valueType}.`,
+            causes: [
+                `The variable '${variableName}' is ${valueType}, so you cannot pull properties from it.`,
+                "An API response might be missing the expected object structure."
+            ],
+            fixes: [
+                `Ensure '${variableName}' is defined before destructuring.`,
+                `Use default values: const { ${property} = 'default' } = ${variableName} || {};`
+            ]
+        };
+    }
+};
+exports.assignmentToConstantPattern = {
+    // Matches "TypeError: Assignment to constant variable."
+    regex: /Assignment to constant variable/,
+    handler: () => ({
+        explanation: "You are trying to reassign a value to a variable declared with `const`.",
+        causes: ["You used `const` but then tried to change the value later (e.g., `x = 10`)."],
+        fixes: ["Change `const` to `let` if you need to reassign it.", "Don't reassign the variable."]
+    })
+};
+exports.bigIntSerializationPattern = {
+    // Matches "TypeError: Do not know how to serialize a BigInt"
+    regex: /Do not know how to serialize a BigInt/,
+    handler: () => ({
+        explanation: "You are trying to use `JSON.stringify()` on an object containing a BigInt (e.g., `10n`). JSON doesn't support BigInt.",
+        causes: ["Your data contains BigInt values."],
+        fixes: ["Convert BigInts to strings or numbers before stringifying: `.toString()`."]
+    })
+};
+exports.circularJsonPattern = {
+    // Matches "TypeError: Converting circular structure to JSON"
+    regex: /Converting circular structure to JSON/,
+    handler: () => ({
+        explanation: "You are trying to `JSON.stringify()` an object that refers to itself.",
+        causes: ["Object A references Object B, and Object B references Object A."],
+        fixes: ["Remove the circular reference.", "Use a custom serializer (replacer function) for `JSON.stringify`."]
+    })
+};
+exports.typeErrorPatterns = [
+    exports.cannotReadPropertyPattern,
+    exports.isNotAFunctionPattern,
+    exports.destructuringPattern,
+    exports.assignmentToConstantPattern,
+    exports.bigIntSerializationPattern,
+    exports.circularJsonPattern
+];

package/dist/src/patterns/uriError.d.ts

@@ -0,0 +1,3 @@
+import { ErrorPattern } from '../types';
+export declare const uriMalformedPattern: ErrorPattern;
+export declare const uriErrorPatterns: ErrorPattern[];

package/dist/src/patterns/uriError.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uriErrorPatterns = exports.uriMalformedPattern = void 0;
+exports.uriMalformedPattern = {
+    // Matches "URIError: URI malformed"
+    regex: /URIError: URI malformed/,
+    handler: (match) => {
+        return {
+            explanation: "The URL encoding or decoding failed because the sequence was not valid.",
+            causes: [
+                "You passed a string with a '%' character not followed by two hex digits to `decodeURIComponent` or `decodeURI`.",
+                "You are trying to parse a URL param that wasn't encoded properly."
+            ],
+            fixes: [
+                "Ensure strings containing '%' are properly escaped (e.g., use '%25' for a literal percent sign).",
+                "Check that the input to decodeURIComponent is a valid UTF-8 sequence."
+            ]
+        };
+    }
+};
+exports.uriErrorPatterns = [
+    exports.uriMalformedPattern
+];

package/dist/src/translator.d.ts

@@ -0,0 +1,2 @@
+import { ErrorExplanation } from './types';
+export declare function translateError(errorMessage: string): ErrorExplanation;

package/dist/src/translator.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateError = translateError;
+const typeError_1 = require("./patterns/typeError");
+const referenceError_1 = require("./patterns/referenceError");
+const syntaxError_1 = require("./patterns/syntaxError");
+const uriError_1 = require("./patterns/uriError");
+const rangeError_1 = require("./patterns/rangeError");
+const mongoose_1 = require("./patterns/mongoose");
+const network_1 = require("./patterns/network");
+const react_1 = require("./patterns/react");
+const node_1 = require("./patterns/node");
+const api_1 = require("./patterns/api");
+const allPatterns = [
+    // Specific frameworks/environments first
+    ...node_1.nodePatterns,
+    ...api_1.apiPatterns,
+    ...react_1.reactPatterns,
+    ...mongoose_1.mongoosePatterns,
+    ...network_1.networkPatterns,
+    // Generic JS errors last
+    ...typeError_1.typeErrorPatterns,
+    ...referenceError_1.referenceErrorPatterns,
+    ...syntaxError_1.syntaxErrorPatterns,
+    ...uriError_1.uriErrorPatterns,
+    ...rangeError_1.rangeErrorPatterns
+];
+function translateError(errorMessage) {
+    for (const pattern of allPatterns) {
+        const match = errorMessage.match(pattern.regex);
+        if (match) {
+            return pattern.handler(match);
+        }
+    }
+    // Fallback for unknown errors
+    return {
+        explanation: "I couldn't recognize this specific error message.",
+        causes: ["This might be a custom error or a less common edge case."],
+        fixes: [
+            "Copy and paste the error into Google or StackOverflow.",
+            "Check the line number mentioned in the stack trace to narrow down the issue."
+        ]
+    };
+}

package/dist/src/types.d.ts

@@ -0,0 +1,9 @@
+export interface ErrorExplanation {
+    explanation: string;
+    causes: string[];
+    fixes: string[];
+}
+export interface ErrorPattern {
+    regex: RegExp;
+    handler: (match: RegExpMatchArray) => ErrorExplanation;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "developer-error-message-translator",
+  "version": "1.0.0",
+  "description": "Translate cryptic developer errors (React, Node, TypeScript) into plain English with causes and fixes.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "dev-translate": "./dist/bin/dev-translate.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "start": "ts-node bin/dev-translate.ts"
+  },
+  "keywords": [
+    "error",
+    "translator",
+    "debugging",
+    "react",
+    "node",
+    "typescript",
+    "developer-tools"
+  ],
+  "author": "Antigravity",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^4.1.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.24",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}