{"_id":"@danielrlimax/retrofit-js","name":"@danielrlimax/retrofit-js","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@danielrlimax/retrofit-js","version":"1.0.0","description":"A lightweight, self-healing HTTP client wrapper that dynamically repairs API drift and schema mismatches.","author":{"name":"Daniel de Lima","email":"danielrlima@proton.me"},"license":"MIT","keywords":["api","resilience","fetch","axios","self-healing","json","schema","interceptor"],"repository":{"type":"git","url":"git+https://github.com/danielrlimax/retrofit-js.git"},"bugs":{"url":"https://github.com/danielrlimax/retrofit-js/issues"},"homepage":"https://github.com/danielrlimax/retrofit-js#readme","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","exports":{".":{"import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup src/index.js --format cjs,esm --clean --dts","test":"vitest run","test:watch":"vitest","lint":"npx @biomejs/biome check src/","lint:fix":"npx @biomejs/biome check --write src/"},"devDependencies":{"@biomejs/biome":"^1.8.3","tsup":"^8.0.0","typescript":"^6.0.3","vitest":"^2.0.0"},"gitHead":"c6138e56c5f851a7c5b52397e2e44d0c810a17a7","types":"./dist/index.d.ts","_id":"@danielrlimax/retrofit-js@1.0.0","_nodeVersion":"24.17.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-+4eJ6fSX6yC7sl86E3ypbRAD5eHXBXJEKmeC5YuSQSCslWY5hp4eC6JJ0dtFYle8J5AppITr6jIi77h2m4oUFg==","shasum":"3088ca3dfc156647eb21c04df2fcdf627270a52f","tarball":"https://registry.npmjs.org/@danielrlimax/retrofit-js/-/retrofit-js-1.0.0.tgz","fileCount":6,"unpackedSize":28653,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDHzgaZBMyTGw6aKAwiT0W+pqLsIG0fCqFLUikMm18FrwIgdu+VRj8PSnfIZJuPI6gjHGatZcXPmHbFhN44LyYUi3c="}]},"_npmUser":{"name":"danielrlimax","email":"danielrlima@proton.me"},"directories":{},"maintainers":[{"name":"danielrlimax","email":"danielrlima@proton.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/retrofit-js_1.0.0_1782238050931_0.43542317093555805"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-23T18:07:30.721Z","1.0.0":"2026-06-23T18:07:31.073Z","modified":"2026-06-23T18:07:31.268Z"},"maintainers":[{"name":"danielrlimax","email":"danielrlima@proton.me"}],"description":"A lightweight, self-healing HTTP client wrapper that dynamically repairs API drift and schema mismatches.","homepage":"https://github.com/danielrlimax/retrofit-js#readme","keywords":["api","resilience","fetch","axios","self-healing","json","schema","interceptor"],"repository":{"type":"git","url":"git+https://github.com/danielrlimax/retrofit-js.git"},"author":{"name":"Daniel de Lima","email":"danielrlima@proton.me"},"bugs":{"url":"https://github.com/danielrlimax/retrofit-js/issues"},"license":"MIT","readme":"# 🩹 Retrofit.js\r\n\r\n> A lightweight, zero-dependency, self-healing HTTP client wrapper that dynamically repairs API drift and schema mismatches in real time.\r\n\r\n![npm version](https://img.shields.io/npm/v/retrofit-js.svg?style=flat-cache)\r\n![License](https://img.shields.io/badge/License-MIT-yellow.svg)\r\n![Bundle Size](https://img.shields.io/bundlephobia/minzip/retrofit-js)\r\n\r\n---\r\n\r\n## 💡 What is Retrofit.js?\r\n\r\nModern applications often depend on third-party APIs that can change unexpectedly. A backend deployment that renames a property from `user_id` to `userId` may silently break frontend code and trigger runtime errors such as:\r\n\r\n```javascript\r\nCannot read properties of undefined\r\n```\r\n\r\n**Retrofit.js** acts as a protective layer between your application and external APIs.\r\n\r\nIt intercepts HTTP responses (`fetch` or `Axios`) and applies lightweight fuzzy-matching heuristics to automatically remap deviated response keys back to the contract your frontend expects.\r\n\r\nThis allows applications to remain functional even when API providers introduce minor schema changes.\r\n\r\n---\r\n\r\n## ✨ Features\r\n\r\n### 📦 Ultra Lightweight\r\n\r\n* Zero external dependencies\r\n* Less than 2KB minified and gzipped\r\n\r\n### 🧠 Intelligent Key Matching\r\n\r\nAutomatically maps common naming variations:\r\n\r\n```text\r\nuser_id\r\nuser-id\r\nUserID\r\nUSER_ID\r\n```\r\n\r\ninto:\r\n\r\n```javascript\r\nuserId\r\n```\r\n\r\n### 🛡️ Self-Healing Fallbacks\r\n\r\nInjects safe fallback values when expected properties are missing:\r\n\r\n| Type    | Default Value |\r\n| ------- | ------------- |\r\n| string  | `\"\"`          |\r\n| number  | `0`           |\r\n| boolean | `false`       |\r\n| object  | `{}`          |\r\n| array   | `[]`          |\r\n\r\n### 🔌 Universal Adapters\r\n\r\nWorks seamlessly with:\r\n\r\n* Native Fetch API\r\n* Axios instances\r\n* Custom HTTP layers\r\n\r\n### 🌲 Deep Recursive Mapping\r\n\r\nSupports:\r\n\r\n* Nested objects\r\n* Arrays of objects\r\n* Complex API response trees\r\n\r\n---\r\n\r\n# 🚀 Installation\r\n\r\n```bash\r\nnpm install retrofit-js\r\n```\r\n\r\n---\r\n\r\n# Quick Start\r\n\r\n## 1. Global Fetch Interception\r\n\r\nInstall Retrofit.js once at application startup.\r\n\r\n```javascript\r\nimport { hookFetch } from 'retrofit-js';\r\n\r\nconst userSchema = {\r\n  userId: 'number',\r\n  fullName: 'string',\r\n  preferences: {\r\n    themeMode: 'string'\r\n  }\r\n};\r\n\r\nhookFetch({\r\n  expectedSchema: userSchema,\r\n  urlFilter: '/api/v1'\r\n});\r\n```\r\n\r\nNow every matching request is automatically normalized.\r\n\r\n```javascript\r\nconst response = await fetch('/api/v1/profile');\r\nconst user = await response.json();\r\n\r\nconsole.log(user.userId);\r\nconsole.log(user.fullName);\r\nconsole.log(user.preferences.themeMode);\r\n```\r\n\r\nEven if the backend returns:\r\n\r\n```json\r\n{\r\n  \"user_id\": 42,\r\n  \"full_name\": \"John Doe\",\r\n  \"preferences\": {\r\n    \"theme_mode\": \"dark\"\r\n  }\r\n}\r\n```\r\n\r\nYour frontend receives:\r\n\r\n```json\r\n{\r\n  \"userId\": 42,\r\n  \"fullName\": \"John Doe\",\r\n  \"preferences\": {\r\n    \"themeMode\": \"dark\"\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 2. Axios Integration\r\n\r\nFor projects using custom Axios instances:\r\n\r\n```javascript\r\nimport axios from 'axios';\r\nimport { hookAxios } from 'retrofit-js';\r\n\r\nconst apiClient = axios.create({\r\n  baseURL: 'https://api.domain.com'\r\n});\r\n\r\nhookAxios(apiClient, {\r\n  expectedSchema: {\r\n    productId: 'number',\r\n    tags: []\r\n  },\r\n  silent: true\r\n});\r\n```\r\n\r\nAll responses passing through the instance will be normalized automatically.\r\n\r\n---\r\n\r\n# 🛠️ Schema Definition\r\n\r\nSchemas describe the structure your application expects.\r\n\r\n## Primitive Types\r\n\r\n```javascript\r\nconst schema = {\r\n  userId: 'number',\r\n  fullName: 'string',\r\n  active: 'boolean'\r\n};\r\n```\r\n\r\n## Nested Objects\r\n\r\n```javascript\r\nconst schema = {\r\n  userId: 'number',\r\n  preferences: {\r\n    themeMode: 'string'\r\n  }\r\n};\r\n```\r\n\r\n## Arrays\r\n\r\n```javascript\r\nconst schema = {\r\n  tags: [],\r\n  categories: []\r\n};\r\n```\r\n\r\n---\r\n\r\n# 📊 Architecture\r\n\r\n```text\r\nRaw API Response\r\n        │\r\n        ▼\r\nRetrofit.js Interceptor\r\n        │\r\n        ▼\r\nFuzzy Matching Engine\r\n        │\r\n        ▼\r\nSchema Normalization\r\n        │\r\n        ▼\r\nUI-Ready Application State\r\n```\r\n\r\n---\r\n\r\n# ⚙️ How It Works\r\n\r\nRetrofit.js performs three core operations:\r\n\r\n1. **Key Normalization**\r\n\r\n   * Converts keys into a canonical format.\r\n\r\n2. **Similarity Matching**\r\n\r\n   * Detects equivalent property names using lightweight heuristics.\r\n\r\n3. **Fallback Injection**\r\n\r\n   * Provides safe defaults for missing values.\r\n\r\nThis process helps applications tolerate minor API contract drift without introducing runtime failures.\r\n\r\n---\r\n\r\n# 📈 Performance\r\n\r\nDesigned for high-throughput applications:\r\n\r\n* Zero dependencies\r\n* Minimal memory overhead\r\n* Recursive traversal optimized for nested structures\r\n* Sub-millisecond processing for typical API payloads\r\n\r\n---\r\n\r\n# 🤝 Contributing\r\n\r\nContributions are welcome.\r\n\r\nYou can help by:\r\n\r\n* Reporting bugs\r\n* Suggesting new features\r\n* Improving documentation\r\n* Submitting pull requests\r\n\r\nBefore opening a pull request, please ensure:\r\n\r\n```bash\r\nnpm run lint\r\nnpm test\r\n```\r\n\r\n---\r\n\r\n# 📄 License\r\n\r\nThis project is licensed under the MIT License.\r\n\r\nSee the `LICENSE` file for details.\r\n\r\n---\r\n\r\n## 👨‍💻 Author\r\n\r\nDeveloped with ❤️ by **Daniel de Lima**.\r\n","readmeFilename":"README.md","_rev":"1-83bf5c40d7a8b5f0b1e4c034b9012936"}