{"id":34510224,"url":"https://github.com/twinedo/app-error","last_synced_at":"2026-02-12T03:16:30.702Z","repository":{"id":330062101,"uuid":"1121446301","full_name":"twinedo/app-error","owner":"twinedo","description":"A framework-agnostic JavaScript/TypeScript library to normalize fetch, axios, and runtime errors into a predictable AppError model.  Open to contributions.","archived":false,"fork":false,"pushed_at":"2026-01-12T07:19:47.000Z","size":11022,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T19:50:13.823Z","etag":null,"topics":["angular","axios","error-handling","fetch","javascript","react","react-native","typescript","vue"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twinedo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-23T02:32:27.000Z","updated_at":"2026-01-12T07:19:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/twinedo/app-error","commit_stats":null,"previous_names":["twinedo/app-error"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/twinedo/app-error","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twinedo%2Fapp-error","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twinedo%2Fapp-error/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twinedo%2Fapp-error/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twinedo%2Fapp-error/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twinedo","download_url":"https://codeload.github.com/twinedo/app-error/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twinedo%2Fapp-error/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28405308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T21:51:37.118Z","status":"ssl_error","status_checked_at":"2026-01-13T21:45:14.585Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","axios","error-handling","fetch","javascript","react","react-native","typescript","vue"],"created_at":"2025-12-24T03:57:03.023Z","updated_at":"2026-01-13T23:41:09.741Z","avatar_url":"https://github.com/twinedo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @twinedo/app-error\n\nA framework-agnostic JavaScript/TypeScript library to normalize fetch, axios, and runtime errors into a predictable AppError model. Open to contributions.\n\n## Why this exists\n\nMost teams talk to more than one backend.\nEach backend returns a different error shape (Project A vs Project B).\nfetch and axios surface errors in different ways.\nSo every project rewrites the same parsing, message, and retry rules.\nThis library produces one predictable AppError for UI, logging, and retries.\n\n## Features\n\n- Predictable `AppError` shape for UI, logging, and retry logic\n- Works with `fetch` responses and axios-like errors\n- Configurable per backend via `defineErrorPolicy`\n- Framework-agnostic (React, React Native, Vue, Angular, Node)\n- TypeScript-first with exported types\n- Defensive normalization that never throws\n- Retry decision helpers like `isRetryable`\n- Zero dependencies\n\n## Guarantees \u0026 Non-Goals\n\n### Guarantees\nThis library guarantees that:\n\n- Every normalization function (`toAppError`, `fromFetch`, `fromFetchResponse`) **never throws**\n- You always receive a **predictable `AppError` shape**\n- `message` is always safe to display in UI\n- Original errors are preserved via `cause` for debugging\n- No input error is mutated\n- Behavior is deterministic and side-effect free\n- Fully TypeScript-friendly with stable public types\n\n### Non-Goals\nThis library intentionally does NOT:\n\n- Automatically guess backend-specific error schemas\n- Perform logging, reporting, or analytics\n- Display UI or toast notifications\n- Enforce localization or translations\n- Replace HTTP clients like fetch or axios\n- Hide errors or swallow failures silently\n\nIf your project has backend-specific error formats, use\n`defineErrorPolicy` to explicitly describe how errors should be interpreted.\n\n## Install\n\n```bash\nnpm install @twinedo/app-error\n```\n\nPublished as the scoped package `@twinedo/app-error`. Ships ESM + CJS builds\nwith TypeScript types and works in Node and browser runtimes.\n\n## Examples\n\n### Example 1 — Axios with try/catch\n\n```ts\nimport axios from \"axios\";\nimport { defineErrorPolicy, isRetryable, toAppError } from \"@twinedo/app-error\";\n\nconst policy = defineErrorPolicy();\n\ntry {\n  const response = await axios.get\u003c{ id: string; name: string }\u003e(\"/api/user\");\n  console.log(\"User:\", response.data.name);\n} catch (err) {\n  const appError = toAppError(err, policy);\n  console.error(appError.message);\n\n  if (isRetryable(appError)) {\n    // show a retry action or schedule a retry\n  }\n}\n```\n\n### Example 2 — Fetch handling non-OK responses\n\n```ts\nimport { defineErrorPolicy, fromFetchResponse, toAppError } from \"@twinedo/app-error\";\n\nconst policy = defineErrorPolicy();\n\ntry {\n  const res = await fetch(\"/api/user\");\n\n  if (!res.ok) {\n    throw await fromFetchResponse(res, policy);\n  }\n\n  const data = await res.json();\n  console.log(\"User:\", data);\n} catch (err) {\n  const appError = toAppError(err, policy);\n  console.error(appError.message);\n}\n```\n\n### Example 3 — Project A vs Project B backend policies\n\n```ts\nimport axios from \"axios\";\nimport {\n  defineErrorPolicy,\n  toAppError,\n  fromFetchResponse,\n} from \"@twinedo/app-error\";\n\n// Tony backend: { error: { message, code } }, x-request-id\nconst policyTony = defineErrorPolicy({\n  http: {\n    message: (data) =\u003e (data as any)?.error?.message,\n    code: (data) =\u003e (data as any)?.error?.code,\n    requestId: (headers) =\u003e (headers as any)?.[\"x-request-id\"],\n  },\n});\n\n// Bobby backend: { message | msg, code }, x-correlation-id\nconst policyBobby = defineErrorPolicy({\n  http: {\n    message: (data) =\u003e (data as any)?.message ?? (data as any)?.msg,\n    code: (data) =\u003e (data as any)?.code,\n    requestId: (headers) =\u003e (headers as any)?.[\"x-correlation-id\"],\n  },\n});\n\n// One handler for UI/logs\nfunction handleError(err: unknown, policy = policyTony) {\n  const e = toAppError(err, policy);\n  console.error(e.message, e.code, e.requestId);\n}\n\n// Request using axios (Tony backend)\nasync function loadUserAxios() {\n  try {\n    await axios.get(\"/api/user\"); // Tony API\n  } catch (err) {\n    handleError(err, policyTony);\n  }\n}\n\n// Request using fetch (Bobby backend)\nasync function loadUserFetch() {\n  try {\n    const res = await fetch(\"/api/user\"); // Bobby API\n    if (!res.ok) throw await fromFetchResponse(res, policyBobby);\n  } catch (err) {\n    handleError(err, policyBobby);\n  }\n}\n```\n\n### Example 4 — attempt() helper\n\n```ts\nimport { attempt } from \"@twinedo/app-error\";\n\nconst result = await attempt(() =\u003e apiCall());\n\nif (result.ok) {\n  console.log(\"Data:\", result.data);\n} else {\n  console.error(result.error.message);\n}\n```\n\n## FAQ\n### 1. Why not just use `try/catch` with `err.message`?\nBecause real-world errors are inconsistent:\n- fetch doesn’t throw on 4xx/5xx (you must check res.ok)\n- axios errors have a different shape (error.response, error.request)\n- network/timeout/runtime errors look different across environments\nThis library normalizes them into one predictable AppError.\n\n### 2. Does `message` always contain the backend error message?\nWhen possible, yes. Otherwise it falls back to a safe default.\u003cbr /\u003e\n`message` is always a non-empty string. If the backend returns no usable message (e.g. `{}`, `null`), it becomes `\"Something went wrong\"`.\n\n### 3. What about status?\n`status` is set only when there is an actual HTTP response (kind \"http\"), e.g. `400`, `404`, `500`.\u003cbr /\u003e\nFor network/timeout/runtime `errors`, `status` is `undefined`.\n\n### 4. Do I need to define a policy?\nOnly if your backend error shape is custom and you want more accurate extraction for:\n- `message`\n- `code`\n- `requestId`\u003cbr /\u003e\nIf your backend already returns `{ message: \"...\" }`, you can usually skip policies.\n\n### 5. Is it framework-agnostic?\nYes. It’s plain JS/TS and can be used in React, React Native, Vue, Svelte, Angular, Node, etc.\n\n### 6. Does it add a lot to bundle size?\nIt’s dependency-free and tree-shakable in modern bundlers. Your app typically includes only what you import.\n\n### 7. Is this a replacement for an HTTP client?\nNo. This library does not send requests or manage retries. It only normalizes errors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwinedo%2Fapp-error","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwinedo%2Fapp-error","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwinedo%2Fapp-error/lists"}