@exodus/errors 3.0.1 → 3.2.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.2.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.1.0...@exodus/errors@3.2.0) (2025-08-07)
+
+### Features
+
+- feat: add more specific JSON parse error handling (#13295)
+
+## [3.1.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.0.1...@exodus/errors@3.1.0) (2025-08-04)
+
+### Features
+
+- feat: support interpolating non-dynamic safeString into safeString on parse (#13003)
+
 ## [3.0.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.0.0...@exodus/errors@3.0.1) (2025-07-08)
 
 **Note:** Version bump only for package @exodus/errors

package/README.md

@@ -45,6 +45,43 @@ Parsing/sanitization of error messages is unreliable and the cost of failure is
 
 Unfortunately, the built-in `.stack` property is mutable and outside of our control. Instead, we use the `Error.prepareStackTrace` API, which enables us to make sure we access the actual call stack and not a cached `err.stack` value that may have already been consumed and modified. We then parse it into a structured format that we can safely sanitize and control. This approach provides consistent, reliable stack traces across different environments (currently supporting both V8 and Hermes).
 
+## Recipes
+
+> [!TIP]
+> Before diving into the recipes, you might want to get familiar with what a 'Safe String' is: https://github.com/ExodusMovement/exodus-hydra/tree/master/libraries/safe-string
+
+### I want to preserve server errors in Safe Errors
+
+Do you control the server? If so, better send short error codes from your server instead. `err.code` will [be passed through](https://github.com/ExodusOSS/hydra/blob/master/libraries/errors/src/safe-error.ts#L32) SafeError coercion.
+
+If you do NOT control the server, and you know the specific error messages returned by the server, you can predefine them wrapped in `safeString`:
+
+```js
+import { safeString } from '@exodus/safe-string'
+
+// From: https://github.com/ethereum/go-ethereum/blob/master/core/txpool/errors.go.
+export const KnownErrors = new Set([
+  safeString`already known`,
+  safeString`invalid sender`,
+  safeString`transaction underpriced`,
+])
+```
+
+You can now handle failed requests like this:
+
+```js
+import { safeString } from '@exodus/safe-string`
+import { KnownErrors } from './errors.js'
+
+const response = await this.request(request)
+const error = response?.error
+
+if (error) {
+  const message = KnownErrors.get(msg) ?? safeString`unknown error`
+  throw new Error(safeString`Bad rpc response: ${message}`)
+}
+```
+
 ## Troubleshooting
 
 ### A SafeError instance returns `undefined` stack trace?

package/lib/common-errors.d.ts

@@ -28,12 +28,21 @@ declare const commonErrors: readonly [{
 }, {
     readonly pattern: RegExp;
     readonly normalized: "Cannot access property of null";
+}, {
+    readonly pattern: RegExp;
+    readonly normalized: "JSON Parse error: Unexpected token";
+}, {
+    readonly pattern: RegExp;
+    readonly normalized: "JSON Parse error: Unexpected token";
 }, {
     readonly pattern: RegExp;
     readonly normalized: "Unexpected token";
 }, {
     readonly pattern: RegExp;
-    readonly normalized: "Unexpected end of input";
+    readonly normalized: "JSON Parse error: Unexpected end of input";
+}, {
+    readonly pattern: RegExp;
+    readonly normalized: "JSON Parse error";
 }];
 export type CommonErrorString = (typeof commonErrors)[number]['normalized'];
 export declare function toCommonErrorMessage(errorMessage: string): CommonErrorString | undefined;

package/lib/common-errors.js

@@ -39,13 +39,25 @@ const commonErrors = [
         pattern: /null is not an object \(evaluating '.*'\)/iu,
         normalized: 'Cannot access property of null',
     },
+    {
+        pattern: /JSON Parse error: Unexpected (token|character)/iu,
+        normalized: 'JSON Parse error: Unexpected token',
+    },
+    {
+        pattern: /Unexpected token.*is not valid JSON/iu,
+        normalized: 'JSON Parse error: Unexpected token',
+    },
     {
         pattern: /unexpected (token|character)/iu,
         normalized: 'Unexpected token',
     },
     {
         pattern: /unexpected end of( JSON)? input/iu,
-        normalized: 'Unexpected end of input',
+        normalized: 'JSON Parse error: Unexpected end of input',
+    },
+    {
+        pattern: /^JSON Parse error:/iu,
+        normalized: 'JSON Parse error',
     },
 ];
 export function toCommonErrorMessage(errorMessage) {

package/lib/safe-error.d.ts

@@ -1,7 +1,7 @@
 import type { Frame } from './types.js';
 import type { CommonErrorString } from './common-errors.js';
 type ReadonlySetValues<S> = S extends ReadonlySet<infer T> ? T : never;
-declare const SAFE_NAMES_SET: ReadonlySet<"Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse" | "TimeoutError">;
+declare const SAFE_NAMES_SET: ReadonlySet<"Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse" | "TimeoutError" | "SyntaxError">;
 type StaticAllowlistString = string & {
     __branded_type: 'StaticAllowlistString';
 };
@@ -21,7 +21,7 @@ declare const FACTORY_SYMBOL: unique symbol;
 export declare class SafeError {
     #private;
     static from<T extends UnknownError>(err: T): SafeError;
-    get name(): "Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse" | "TimeoutError";
+    get name(): "Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse" | "TimeoutError" | "SyntaxError";
     get code(): SafeCode | undefined;
     get hint(): SafeString | undefined;
     get stackFrames(): {

package/lib/safe-error.js

@@ -1,4 +1,4 @@
-import { getAllowlist, isSafe } from '@exodus/safe-string';
+import { getAllowlist, parseString } from '@exodus/safe-string';
 import assert from 'minimalistic-assert';
 import parseStackTraceNatively, { stackFramesToString } from './stack.js';
 import { omitUndefined } from './utils.js';
@@ -15,6 +15,7 @@ const SAFE_NAMES_SET = makeReadonlySet([
     'UnknownError',
     'SafeErrorFailedToParse',
     'TimeoutError',
+    'SyntaxError',
 ]);
 function isSafeName(value) {
     return SAFE_NAMES_SET.has(value);
@@ -26,10 +27,6 @@ function isSafeCode(value) {
     return SAFE_CODES_SET.has(value) || isExodusErrorCode(value);
 }
 const staticAllowlist = getAllowlist();
-function getSafeString(str) {
-    if (isSafe(str))
-        return str;
-}
 const FACTORY_SYMBOL = Symbol('SafeError');
 export class SafeError {
     static from(err) {
@@ -44,7 +41,7 @@ export class SafeError {
             const hintCandidates = [hint, message].filter((str) => typeof str === 'string');
             safeHint =
                 // chicken sacrifice to TypeScript, otherwise would be hintCandidates.find((str) => isSafe(str))
-                hintCandidates.map((str) => getSafeString(str)).find(Boolean) ||
+                hintCandidates.map((str) => parseString(str)).find(Boolean) ||
                     staticAllowlist.find((safePrefix) => hintCandidates.some((str) => str.startsWith(safePrefix))) ||
                     toCommonErrorMessage(message);
             const safeStack = parseStackTraceNatively(err);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exodus/errors",
   "type": "module",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Utilities for error handling in client code, such as sanitization",
   "author": "Exodus Movement, Inc.",
   "repository": {
@@ -34,7 +34,7 @@
     "test:hermes": "EXODUS_TEST_COVERAGE=0 run -T exodus-test --engine hermes:bundle --esbuild --jest src/__tests__/hermes/*.test.ts src/__tests__/engine-agnostic/*.test.ts"
   },
   "dependencies": {
-    "@exodus/safe-string": "^1.0.0",
+    "@exodus/safe-string": "^1.2.0",
     "minimalistic-assert": "^1.0.1"
   },
   "devDependencies": {
@@ -44,5 +44,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7fd991f460540c1396fc68391393ee690269fa7f"
+  "gitHead": "b229da233485c8301fa03c8b189a55f866eb4fe0"
 }