🏷️ v1.0.3 — Actionable Suggestions for Every Error

What's New

Every AppError now includes a suggestion field — a required, always-present string that provides actionable, user-friendly advice on how to resolve the error.

While message tells users what went wrong, suggestion tells them what to do about it.

Example Output

{
  "kind": "http",
  "message": "Not Found",
  "suggestion": "The requested resource could not be found. Please verify your request.",
  "status": 404,
  "retryable": false
}

{
  "kind": "network",
  "message": "Something went wrong",
  "suggestion": "Please check your internet connection and try again.",
  "retryable": true
}

Default Suggestions

HTTP Errors (configurable via defineErrorPolicy)

Status	Suggestion
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.

Non-HTTP Errors (built-in)

Kind	Suggestion
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.

Custom Suggestions Per Backend

Override defaults using defineErrorPolicy:

const policy = defineErrorPolicy({
  http: {
    suggestion: (status, data) => {
      if (status === 404) return "The item may have been deleted. Check your dashboard.";
      if (status === 503) return "We're performing maintenance. Back soon!";
      // Falls back to defaults for other statuses
    },
  },
});

Breaking Changes

• suggestion is now a required field on AppError (previously absent). If you construct AppError objects manually, you must include suggestion.
• isAppError() now checks for suggestion being a string.

Files Changed

• src/types.ts — suggestion: string added to AppError
• src/policy.ts — suggestion extractor added to HttpPolicy
• src/toAppError.ts — suggestion wired into all error paths
• src/fromFetch.ts — suggestion wired into fetch error path
• package.json — version bumped to 1.0.3

🏷️ v1.0.2 — Updated README

• Updated One line Description
• Updated Example 3 section of README.md

🏷️ v1.0.1 — Fetch DX improvement

• Added: fromFetchResponse(response, policy?) helper to read fetch error bodies (JSON/text) inside the library.
• Docs: Updated README fetch example to remove custom readBody boilerplate.
• No breaking changes.

🏷️ v1.0.0 — Initial release

✨ What this is

@twinedo/app-error is a small, framework-agnostic library that normalizes
errors from fetch, axios-like clients, and unknown runtime errors into a single, predictable AppError model.

It’s designed for projects where:

• Different backends return different error shapes
• HTTP clients behave differently
• Teams want consistent UI messaging, retry logic, and logging inputs

📦 Included in this release

Core API

• toAppError(error, policy?)
  Normalize any thrown value into a predictable AppError

• fromFetch(response, body?, policy?)
  Convert non-OK fetch responses into AppError

• defineErrorPolicy(config)
  Configure backend-specific error extraction rules

• isAppError(value)
  Type guard for normalized errors

• errorKey(error)
  Stable fingerprint for deduping and logging

• isRetryable(error)
  Centralized retry decision helper

• attempt(fn)
  Safe execution helper returning { ok, data | error }

✅ Guarantees

This release guarantees that:

• Normalization never throws
• Output shape is always predictable
• message is always safe to display in UI
• Original errors are preserved via cause
• No input error is mutated
• Fully TypeScript-friendly
• Framework-agnostic (React, React Native, Vue, Angular, Node)

🚫 Non-Goals

This library intentionally does not:

• Perform logging, reporting, or analytics
• Display UI or toast notifications
• Guess backend-specific error schemas
• Replace HTTP clients like fetch or axios
• Enforce localization or translations
• Hide or swallow errors silently

🚦 Status

This is an initial release (v0.1.0).

• The public API is intentionally small and stable
• Feedback and real-world use cases are welcome before moving toward v1.0

🔗 Links

• npm: https://www.npmjs.com/package/@twinedo/app-error
• Repository: https://github.com/twinedo/app-error

🙏 Thank you

Thanks for checking out the project!
If you find issues or have suggestions, please open an issue or discussion.