{"id":15698,"library":"mappersmith","title":"Mappersmith REST Client","description":"Mappersmith is a lightweight, isomorphic REST client designed for both Node.js and browser environments, currently stable at version 2.47.1. It streamlines API integration by providing a centralized configuration for all HTTP requests, abstracting away complex network configurations. The library emphasizes a clean, declarative approach to defining API resources and their methods, allowing developers to focus on business logic rather than boilerplate. It supports a robust middleware system for extending client capabilities with features like authentication, retry mechanisms, logging, and error handling. While its release cadence isn't explicitly stated, the high patch version suggests continuous, active development with frequent smaller updates. Its key differentiators include its lightweight nature, isomorphic compatibility, and highly configurable middleware architecture, offering a powerful alternative to more opinionated or heavier HTTP clients.","status":"active","version":"2.47.1","language":"javascript","source_language":"en","source_url":"https://github.com/tulios/mappersmith","tags":["javascript","rest","client","rest-client","isomorphic","browser","server","data-mapper","mappersmith","typescript"],"install":[{"cmd":"npm install mappersmith","lang":"bash","label":"npm"},{"cmd":"yarn add mappersmith","lang":"bash","label":"yarn"},{"cmd":"pnpm add mappersmith","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used by internal debugging or utility features, not essential for core client functionality.","package":"diff","optional":true},{"reason":"Used by internal debugging or utility features, not essential for core client functionality.","package":"tty-table","optional":true}],"imports":[{"note":"Mappersmith's primary client factory is a default export. CommonJS users must access it via `require('mappersmith').default`.","wrong":"import { forge } from 'mappersmith';","symbol":"forge","correct":"import forge from 'mappersmith';"},{"note":"The global configuration object is a named export. It is used to set global parameters like the default gateway.","wrong":"import configs from 'mappersmith';","symbol":"configs","correct":"import { configs } from 'mappersmith';"},{"note":"Specific gateways like `Fetch` are default exports from their sub-paths. CommonJS users should use `require('mappersmith/gateway/fetch').default`.","wrong":"import { Fetch } from 'mappersmith/gateway/fetch';","symbol":"Fetch","correct":"import Fetch from 'mappersmith/gateway/fetch';"}],"quickstart":{"code":"import forge, { configs } from 'mappersmith';\nimport Fetch from 'mappersmith/gateway/fetch';\n\n// Configure the Fetch gateway globally\nconfigs.gateway = Fetch;\n\n// Define your API client with resources and methods\nconst githubStatusClient = forge({\n  clientId: 'github-status-api',\n  host: 'https://www.githubstatus.com',\n  resources: {\n    Status: {\n      current: { path: '/api/v2/status.json' },\n      summary: { path: '/api/v2/summary.json' },\n      components: { path: '/api/v2/components.json' }\n    },\n  },\n});\n\n// Make an API call and handle the response\ngithubStatusClient.Status.current()\n  .then((response) => {\n    // response.data() contains the parsed JSON body\n    console.log('Current GitHub Status Summary:', response.data().status.description);\n    console.log('API Request successful.');\n  })\n  .catch((error) => {\n    console.error('Failed to fetch GitHub status:', error);\n    if (error.response) {\n        console.error('Response status:', error.response.status());\n        console.error('Response data:', error.response.data());\n    }\n  });\n","lang":"typescript","description":"Demonstrates how to create a Mappersmith client with the Fetch gateway, define a resource, and make a simple API call to retrieve status data, including error handling."},"warnings":[{"fix":"Refactor custom middleware to avoid using the `context` argument. Consult the latest documentation for the recommended middleware API, typically relying on `request` and `response` objects directly.","message":"The `context` argument within custom middleware creation is deprecated and will be removed in future major versions. Developers should update their middleware implementations to use the current API.","severity":"deprecated","affected_versions":">=2.x"},{"fix":"Always use `require('mappersmith').default` for the `forge` function and `require('mappersmith/gateway/fetch').default` for gateways in CommonJS environments.","message":"When using Mappersmith with CommonJS, the main `forge` function and specific gateways like `Fetch` are exported as default exports. Directly `require('mappersmith')` or `require('mappersmith/gateway/fetch')` will not provide the expected function/class without appending `.default`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all Mappersmith client calls are `await`ed or chained with `.then()` to resolve the Promise before accessing response data: `const response = await client.Resource.method(); console.log(response.data());`","message":"Mappersmith clients return Promises. Directly accessing properties like `response.data()` on the raw Promise object before it resolves will result in `undefined` or a `TypeError`. You must `await` the response or use `.then()`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Understand that `Timeout` middleware is client-side. For server-side request cancellation or resource management, implement corresponding logic within your API's backend.","message":"The built-in `Timeout` middleware configures a client-side timeout for the request. This means the client will stop waiting after the specified duration, but the request might still complete on the server, consuming resources. It does not cancel server-side processing.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Correct the import for CommonJS: `const forge = require('mappersmith').default;`","cause":"Attempting to call the main `mappersmith` module directly as a function in CommonJS, rather than accessing its default export.","error":"TypeError: mappersmith is not a function"},{"fix":"Ensure the client call is `await`ed or chained with `.then()` before accessing response properties: `client.Resource.method().then(response => console.log(response.data()));`","cause":"Attempting to access methods or properties (like `data()`) on the `response` object before the Promise returned by the client call has resolved.","error":"TypeError: Cannot read properties of undefined (reading 'data')"},{"fix":"Use a default import for gateways: `import Fetch from 'mappersmith/gateway/fetch';`","cause":"Attempting to import a gateway (e.g., `Fetch`) as a named export (`import { Fetch } from '...'`) when it is a default export from its specific module path.","error":"TypeError: (0 , mappersmith_gateway_fetch_1.default) is not a constructor"},{"fix":"Review your custom middleware implementation to ensure it always returns a plain object (e.g., `{ request }`, `{ response }`, or both) or a Promise that resolves to such an object.","cause":"A custom middleware function did not return a valid `{ request, response }` object (or a subset) or a Promise resolving to such an object, violating the middleware contract.","error":"Mappersmith: [Middleware] 'YourCustomMiddleware' returned an invalid value. Middleware should return a plain object or a Promise that resolves to a plain object."}],"ecosystem":"npm"}