@twinedo/app-error 1.0.2 → 1.0.3

package/README.md

@@ -168,3 +168,35 @@ if (result.ok) {
   console.error(result.error.message);
 }
 ```
+
+## FAQ
+### 1. Why not just use `try/catch` with `err.message`?
+Because real-world errors are inconsistent:
+- fetch doesn’t throw on 4xx/5xx (you must check res.ok)
+- axios errors have a different shape (error.response, error.request)
+- network/timeout/runtime errors look different across environments
+This library normalizes them into one predictable AppError.
+
+### 2. Does `message` always contain the backend error message?
+When possible, yes. Otherwise it falls back to a safe default.<br />
+`message` is always a non-empty string. If the backend returns no usable message (e.g. `{}`, `null`), it becomes `"Something went wrong"`.
+
+### 3. What about status?
+`status` is set only when there is an actual HTTP response (kind "http"), e.g. `400`, `404`, `500`.<br />
+For network/timeout/runtime `errors`, `status` is `undefined`.
+
+### 4. Do I need to define a policy?
+Only if your backend error shape is custom and you want more accurate extraction for:
+- `message`
+- `code`
+- `requestId`<br />
+If your backend already returns `{ message: "..." }`, you can usually skip policies.
+
+### 5. Is it framework-agnostic?
+Yes. It’s plain JS/TS and can be used in React, React Native, Vue, Svelte, Angular, Node, etc.
+
+### 6. Does it add a lot to bundle size?
+It’s dependency-free and tree-shakable in modern bundlers. Your app typically includes only what you import.
+
+### 7. Is this a replacement for an HTTP client?
+No. This library does not send requests or manage retries. It only normalizes errors.

package/dist/index.cjs

@@ -156,11 +156,30 @@ var defaultHttpRetryable = (status) => {
   if (typeof status !== "number") return false;
   return status >= 500 && status <= 599;
 };
+var DEFAULT_HTTP_SUGGESTIONS = {
+  400: "Please review your request and ensure all fields are correct.",
+  401: "Please ensure you have valid credentials and try again.",
+  403: "You do not have permission to perform this action.",
+  404: "The requested resource could not be found. Please verify your request.",
+  408: "The request took too long. Please try again shortly.",
+  409: "A conflict occurred. Please refresh and try again.",
+  422: "Some of the provided data is invalid. Please review your input.",
+  429: "Too many requests. Please wait a moment and try again.",
+  500: "An internal server error occurred. Please try again later or contact support.",
+  502: "The server received an invalid response. Please try again later.",
+  503: "The service is temporarily unavailable. Please try again later.",
+  504: "The server did not respond in time. Please try again later."
+};
+var defaultHttpSuggestion = (status) => {
+  if (typeof status !== "number") return void 0;
+  return DEFAULT_HTTP_SUGGESTIONS[status];
+};
 var DEFAULT_HTTP_POLICY = {
   message: defaultHttpMessage,
   code: defaultHttpCode,
   requestId: defaultRequestId,
-  retryable: defaultHttpRetryable
+  retryable: defaultHttpRetryable,
+  suggestion: defaultHttpSuggestion
 };
 var defineErrorPolicy = (...configs) => {
   const merged = {};
@@ -173,7 +192,8 @@ var defineErrorPolicy = (...configs) => {
       message: merged.message ?? DEFAULT_HTTP_POLICY.message,
       code: merged.code ?? DEFAULT_HTTP_POLICY.code,
       requestId: merged.requestId ?? DEFAULT_HTTP_POLICY.requestId,
-      retryable: merged.retryable ?? DEFAULT_HTTP_POLICY.retryable
+      retryable: merged.retryable ?? DEFAULT_HTTP_POLICY.retryable,
+      suggestion: merged.suggestion ?? DEFAULT_HTTP_POLICY.suggestion
     }
   };
 };
@@ -192,7 +212,9 @@ var isAppError = (value) => {
   if (!isRecord2(value)) return false;
   const kind = value.kind;
   if (typeof kind !== "string" || !(kind in APP_ERROR_KINDS)) return false;
-  return typeof value.message === "string";
+  if (typeof value.message !== "string") return false;
+  if (typeof value.suggestion !== "string") return false;
+  return true;
 };
 
 // src/fromFetch.ts
@@ -216,20 +238,30 @@ var safeInvoke = (fn) => {
 var fromFetch = (response, body, policy) => {
   const resolvedPolicy = defineErrorPolicy(policy);
   const status = typeof response.status === "number" ? response.status : void 0;
+  const httpResponse = {
+    ...status !== void 0 ? { status } : {},
+    ...response.statusText ? { statusText: response.statusText } : {},
+    ...response.headers !== void 0 ? { headers: response.headers } : {}
+  };
   const message = normalizeMessage(
-    safeInvoke(() => resolvedPolicy.http.message(body, response))
+    safeInvoke(() => resolvedPolicy.http.message(body, httpResponse))
   ) ?? DEFAULT_MESSAGE;
   const code = normalizeMessage(
-    safeInvoke(() => resolvedPolicy.http.code(body, response))
+    safeInvoke(() => resolvedPolicy.http.code(body, httpResponse))
   );
   const requestId = normalizeMessage(
     safeInvoke(() => resolvedPolicy.http.requestId(response.headers))
   );
   const retryable = safeInvoke(() => resolvedPolicy.http.retryable(status)) ?? defaultRetryable(status);
+  const DEFAULT_SUGGESTION = "An unexpected error occurred. Please try again or contact support.";
+  const suggestion = normalizeMessage(
+    safeInvoke(() => resolvedPolicy.http.suggestion(status, body, httpResponse))
+  ) ?? DEFAULT_SUGGESTION;
   return {
     kind: "http",
     message,
     retryable,
+    suggestion,
     ...status !== void 0 ? { status } : {},
     ...code ? { code } : {},
     ...requestId ? { requestId } : {},
@@ -332,6 +364,14 @@ var toHttpResponseLike = (info) => {
 
 // src/toAppError.ts
 var DEFAULT_MESSAGE2 = "Something went wrong";
+var DEFAULT_KIND_SUGGESTIONS = {
+  network: "Please check your internet connection and try again.",
+  timeout: "The request took too long. Please try again shortly.",
+  parse: "The server returned an unexpected response. Please try again or contact support.",
+  validation: "Please review your input and correct any errors.",
+  unknown: "An unexpected error occurred. Please try again or contact support.",
+  http: ""
+};
 var NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
   "ENOTFOUND",
   "ECONNREFUSED",
@@ -401,16 +441,19 @@ var isValidationError = (error, name) => {
 var normalizeExisting = (error) => {
   const message = normalizeMessage2(error.message) ?? DEFAULT_MESSAGE2;
   const retryable = typeof error.retryable === "boolean" ? error.retryable : defaultRetryable2(error.kind, error.status);
+  const suggestion = normalizeMessage2(error.suggestion) ?? (DEFAULT_KIND_SUGGESTIONS[error.kind] || "An unexpected error occurred. Please try again or contact support.");
   return {
     ...error,
     message,
-    retryable
+    retryable,
+    suggestion
   };
 };
 var buildAppError = (options) => ({
   kind: options.kind,
   message: options.message,
   retryable: options.retryable,
+  suggestion: options.suggestion,
   ...options.status !== void 0 ? { status: options.status } : {},
   ...options.code ? { code: options.code } : {},
   ...options.requestId ? { requestId: options.requestId } : {},
@@ -433,9 +476,13 @@ var fromStatusObject = (error, policy) => {
   const code = safeInvoke2(() => policy.http.code(details, response));
   const requestId = safeInvoke2(() => policy.http.requestId(response.headers));
   const retryable = safeInvoke2(() => policy.http.retryable(status)) ?? defaultRetryable2("http", status);
+  const suggestion = normalizeMessage2(
+    safeInvoke2(() => policy.http.suggestion(status, details, response))
+  ) ?? DEFAULT_KIND_SUGGESTIONS.unknown;
   return buildAppError({
     kind: "http",
     message,
+    suggestion,
     status,
     code: normalizeMessage2(code),
     retryable,
@@ -462,9 +509,13 @@ var toAppError = (error, policy) => {
           () => resolvedPolicy.http.requestId(axiosInfo.headers)
         );
         const retryable = safeInvoke2(() => resolvedPolicy.http.retryable(axiosInfo.status)) ?? defaultRetryable2("http", axiosInfo.status);
+        const suggestion = normalizeMessage2(
+          safeInvoke2(() => resolvedPolicy.http.suggestion(axiosInfo.status, axiosInfo.data, response))
+        ) ?? DEFAULT_KIND_SUGGESTIONS.unknown;
         return buildAppError({
           kind: "http",
           message: message2,
+          suggestion,
           status: axiosInfo.status,
           code: normalizeMessage2(code2),
           retryable,
@@ -477,6 +528,7 @@ var toAppError = (error, policy) => {
         return buildAppError({
           kind: "timeout",
           message: DEFAULT_MESSAGE2,
+          suggestion: DEFAULT_KIND_SUGGESTIONS.timeout,
           retryable: false,
           cause: error
         });
@@ -485,6 +537,7 @@ var toAppError = (error, policy) => {
         return buildAppError({
           kind: "network",
           message: DEFAULT_MESSAGE2,
+          suggestion: DEFAULT_KIND_SUGGESTIONS.network,
           retryable: true,
           cause: error
         });
@@ -495,6 +548,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "timeout",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.timeout,
         retryable: false,
         cause: error
       });
@@ -503,6 +557,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "network",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.network,
         retryable: true,
         cause: error
       });
@@ -511,6 +566,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "parse",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.parse,
         retryable: false,
         cause: error
       });
@@ -519,6 +575,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "validation",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.validation,
         retryable: false,
         cause: error,
         details: error
@@ -531,6 +588,7 @@ var toAppError = (error, policy) => {
   return buildAppError({
     kind: "unknown",
     message: DEFAULT_MESSAGE2,
+    suggestion: DEFAULT_KIND_SUGGESTIONS.unknown,
     retryable: false,
     cause: error
   });

package/dist/index.d.cts

@@ -2,6 +2,7 @@ type AppErrorKind = "http" | "network" | "timeout" | "parse" | "validation" | "u
 type AppError = {
     kind: AppErrorKind;
     message: string;
+    suggestion: string;
     status?: number;
     code?: string;
     retryable?: boolean;
@@ -24,6 +25,7 @@ type HttpPolicy = {
     code: (data: unknown, response?: HttpResponseLike) => string | undefined;
     requestId: (headers?: HeadersLike) => string | undefined;
     retryable: (status?: number) => boolean;
+    suggestion: (status?: number, data?: unknown, response?: HttpResponseLike) => string | undefined;
 };
 type ErrorPolicy = {
     http?: Partial<HttpPolicy>;

package/dist/index.d.ts

@@ -2,6 +2,7 @@ type AppErrorKind = "http" | "network" | "timeout" | "parse" | "validation" | "u
 type AppError = {
     kind: AppErrorKind;
     message: string;
+    suggestion: string;
     status?: number;
     code?: string;
     retryable?: boolean;
@@ -24,6 +25,7 @@ type HttpPolicy = {
     code: (data: unknown, response?: HttpResponseLike) => string | undefined;
     requestId: (headers?: HeadersLike) => string | undefined;
     retryable: (status?: number) => boolean;
+    suggestion: (status?: number, data?: unknown, response?: HttpResponseLike) => string | undefined;
 };
 type ErrorPolicy = {
     http?: Partial<HttpPolicy>;

package/dist/index.js

@@ -123,11 +123,30 @@ var defaultHttpRetryable = (status) => {
   if (typeof status !== "number") return false;
   return status >= 500 && status <= 599;
 };
+var DEFAULT_HTTP_SUGGESTIONS = {
+  400: "Please review your request and ensure all fields are correct.",
+  401: "Please ensure you have valid credentials and try again.",
+  403: "You do not have permission to perform this action.",
+  404: "The requested resource could not be found. Please verify your request.",
+  408: "The request took too long. Please try again shortly.",
+  409: "A conflict occurred. Please refresh and try again.",
+  422: "Some of the provided data is invalid. Please review your input.",
+  429: "Too many requests. Please wait a moment and try again.",
+  500: "An internal server error occurred. Please try again later or contact support.",
+  502: "The server received an invalid response. Please try again later.",
+  503: "The service is temporarily unavailable. Please try again later.",
+  504: "The server did not respond in time. Please try again later."
+};
+var defaultHttpSuggestion = (status) => {
+  if (typeof status !== "number") return void 0;
+  return DEFAULT_HTTP_SUGGESTIONS[status];
+};
 var DEFAULT_HTTP_POLICY = {
   message: defaultHttpMessage,
   code: defaultHttpCode,
   requestId: defaultRequestId,
-  retryable: defaultHttpRetryable
+  retryable: defaultHttpRetryable,
+  suggestion: defaultHttpSuggestion
 };
 var defineErrorPolicy = (...configs) => {
   const merged = {};
@@ -140,7 +159,8 @@ var defineErrorPolicy = (...configs) => {
       message: merged.message ?? DEFAULT_HTTP_POLICY.message,
       code: merged.code ?? DEFAULT_HTTP_POLICY.code,
       requestId: merged.requestId ?? DEFAULT_HTTP_POLICY.requestId,
-      retryable: merged.retryable ?? DEFAULT_HTTP_POLICY.retryable
+      retryable: merged.retryable ?? DEFAULT_HTTP_POLICY.retryable,
+      suggestion: merged.suggestion ?? DEFAULT_HTTP_POLICY.suggestion
     }
   };
 };
@@ -159,7 +179,9 @@ var isAppError = (value) => {
   if (!isRecord2(value)) return false;
   const kind = value.kind;
   if (typeof kind !== "string" || !(kind in APP_ERROR_KINDS)) return false;
-  return typeof value.message === "string";
+  if (typeof value.message !== "string") return false;
+  if (typeof value.suggestion !== "string") return false;
+  return true;
 };
 
 // src/fromFetch.ts
@@ -183,20 +205,30 @@ var safeInvoke = (fn) => {
 var fromFetch = (response, body, policy) => {
   const resolvedPolicy = defineErrorPolicy(policy);
   const status = typeof response.status === "number" ? response.status : void 0;
+  const httpResponse = {
+    ...status !== void 0 ? { status } : {},
+    ...response.statusText ? { statusText: response.statusText } : {},
+    ...response.headers !== void 0 ? { headers: response.headers } : {}
+  };
   const message = normalizeMessage(
-    safeInvoke(() => resolvedPolicy.http.message(body, response))
+    safeInvoke(() => resolvedPolicy.http.message(body, httpResponse))
   ) ?? DEFAULT_MESSAGE;
   const code = normalizeMessage(
-    safeInvoke(() => resolvedPolicy.http.code(body, response))
+    safeInvoke(() => resolvedPolicy.http.code(body, httpResponse))
   );
   const requestId = normalizeMessage(
     safeInvoke(() => resolvedPolicy.http.requestId(response.headers))
   );
   const retryable = safeInvoke(() => resolvedPolicy.http.retryable(status)) ?? defaultRetryable(status);
+  const DEFAULT_SUGGESTION = "An unexpected error occurred. Please try again or contact support.";
+  const suggestion = normalizeMessage(
+    safeInvoke(() => resolvedPolicy.http.suggestion(status, body, httpResponse))
+  ) ?? DEFAULT_SUGGESTION;
   return {
     kind: "http",
     message,
     retryable,
+    suggestion,
     ...status !== void 0 ? { status } : {},
     ...code ? { code } : {},
     ...requestId ? { requestId } : {},
@@ -299,6 +331,14 @@ var toHttpResponseLike = (info) => {
 
 // src/toAppError.ts
 var DEFAULT_MESSAGE2 = "Something went wrong";
+var DEFAULT_KIND_SUGGESTIONS = {
+  network: "Please check your internet connection and try again.",
+  timeout: "The request took too long. Please try again shortly.",
+  parse: "The server returned an unexpected response. Please try again or contact support.",
+  validation: "Please review your input and correct any errors.",
+  unknown: "An unexpected error occurred. Please try again or contact support.",
+  http: ""
+};
 var NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
   "ENOTFOUND",
   "ECONNREFUSED",
@@ -368,16 +408,19 @@ var isValidationError = (error, name) => {
 var normalizeExisting = (error) => {
   const message = normalizeMessage2(error.message) ?? DEFAULT_MESSAGE2;
   const retryable = typeof error.retryable === "boolean" ? error.retryable : defaultRetryable2(error.kind, error.status);
+  const suggestion = normalizeMessage2(error.suggestion) ?? (DEFAULT_KIND_SUGGESTIONS[error.kind] || "An unexpected error occurred. Please try again or contact support.");
   return {
     ...error,
     message,
-    retryable
+    retryable,
+    suggestion
   };
 };
 var buildAppError = (options) => ({
   kind: options.kind,
   message: options.message,
   retryable: options.retryable,
+  suggestion: options.suggestion,
   ...options.status !== void 0 ? { status: options.status } : {},
   ...options.code ? { code: options.code } : {},
   ...options.requestId ? { requestId: options.requestId } : {},
@@ -400,9 +443,13 @@ var fromStatusObject = (error, policy) => {
   const code = safeInvoke2(() => policy.http.code(details, response));
   const requestId = safeInvoke2(() => policy.http.requestId(response.headers));
   const retryable = safeInvoke2(() => policy.http.retryable(status)) ?? defaultRetryable2("http", status);
+  const suggestion = normalizeMessage2(
+    safeInvoke2(() => policy.http.suggestion(status, details, response))
+  ) ?? DEFAULT_KIND_SUGGESTIONS.unknown;
   return buildAppError({
     kind: "http",
     message,
+    suggestion,
     status,
     code: normalizeMessage2(code),
     retryable,
@@ -429,9 +476,13 @@ var toAppError = (error, policy) => {
           () => resolvedPolicy.http.requestId(axiosInfo.headers)
         );
         const retryable = safeInvoke2(() => resolvedPolicy.http.retryable(axiosInfo.status)) ?? defaultRetryable2("http", axiosInfo.status);
+        const suggestion = normalizeMessage2(
+          safeInvoke2(() => resolvedPolicy.http.suggestion(axiosInfo.status, axiosInfo.data, response))
+        ) ?? DEFAULT_KIND_SUGGESTIONS.unknown;
         return buildAppError({
           kind: "http",
           message: message2,
+          suggestion,
           status: axiosInfo.status,
           code: normalizeMessage2(code2),
           retryable,
@@ -444,6 +495,7 @@ var toAppError = (error, policy) => {
         return buildAppError({
           kind: "timeout",
           message: DEFAULT_MESSAGE2,
+          suggestion: DEFAULT_KIND_SUGGESTIONS.timeout,
           retryable: false,
           cause: error
         });
@@ -452,6 +504,7 @@ var toAppError = (error, policy) => {
         return buildAppError({
           kind: "network",
           message: DEFAULT_MESSAGE2,
+          suggestion: DEFAULT_KIND_SUGGESTIONS.network,
           retryable: true,
           cause: error
         });
@@ -462,6 +515,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "timeout",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.timeout,
         retryable: false,
         cause: error
       });
@@ -470,6 +524,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "network",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.network,
         retryable: true,
         cause: error
       });
@@ -478,6 +533,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "parse",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.parse,
         retryable: false,
         cause: error
       });
@@ -486,6 +542,7 @@ var toAppError = (error, policy) => {
       return buildAppError({
         kind: "validation",
         message: DEFAULT_MESSAGE2,
+        suggestion: DEFAULT_KIND_SUGGESTIONS.validation,
         retryable: false,
         cause: error,
         details: error
@@ -498,6 +555,7 @@ var toAppError = (error, policy) => {
   return buildAppError({
     kind: "unknown",
     message: DEFAULT_MESSAGE2,
+    suggestion: DEFAULT_KIND_SUGGESTIONS.unknown,
     retryable: false,
     cause: error
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinedo/app-error",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A configurable error normalization layer for fetch, axios-like, and runtime errors.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -40,4 +40,4 @@
     "url": "https://github.com/twinedo/app-error/issues"
   },
   "homepage": "https://github.com/twinedo/app-error#readme"
-}
+}