Mappersmith REST Client

Common errors

• TypeError: mappersmith is not a function

  cause Attempting to call the main `mappersmith` module directly as a function in CommonJS, rather than accessing its default export.
  fix Correct the import for CommonJS: `const forge = require('mappersmith').default;`

• TypeError: Cannot read properties of undefined (reading 'data')

  cause Attempting to access methods or properties (like `data()`) on the `response` object before the Promise returned by the client call has resolved.
  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()));`

• TypeError: (0 , mappersmith_gateway_fetch_1.default) is not a constructor

  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.
  fix Use a default import for gateways: `import Fetch from 'mappersmith/gateway/fetch';`

• Mappersmith: [Middleware] 'YourCustomMiddleware' returned an invalid value. Middleware should return a plain object or a Promise that resolves to a plain 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.
  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.

Warnings

• deprecated 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.
  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.
• gotcha 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`.
  Fix: Always use `require('mappersmith').default` for the `forge` function and `require('mappersmith/gateway/fetch').default` for gateways in CommonJS environments.
• gotcha 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()`.
  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());`
• gotcha 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.
  Fix: Understand that `Timeout` middleware is client-side. For server-side request cancellation or resource management, implement corresponding logic within your API's backend.

Install

• npm install mappersmith npm
• yarn add mappersmith yarn
• pnpm add mappersmith pnpm

Imports

• forge
  wrong:

  import { forge } from 'mappersmith';

  correct:

  import forge from 'mappersmith';

  Mappersmith's primary client factory is a default export. CommonJS users must access it via `require('mappersmith').default`.
• configs
  wrong:

  import configs from 'mappersmith';

  correct:

  import { configs } from 'mappersmith';

  The global configuration object is a named export. It is used to set global parameters like the default gateway.
• Fetch
  wrong:

  import { Fetch } from 'mappersmith/gateway/fetch';

  correct:

  import Fetch from 'mappersmith/gateway/fetch';

  Specific gateways like `Fetch` are default exports from their sub-paths. CommonJS users should use `require('mappersmith/gateway/fetch').default`.

Quickstart

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.

import forge, { configs } from 'mappersmith';
import Fetch from 'mappersmith/gateway/fetch';

// Configure the Fetch gateway globally
configs.gateway = Fetch;

// Define your API client with resources and methods
const githubStatusClient = forge({
  clientId: 'github-status-api',
  host: 'https://www.githubstatus.com',
  resources: {
    Status: {
      current: { path: '/api/v2/status.json' },
      summary: { path: '/api/v2/summary.json' },
      components: { path: '/api/v2/components.json' }
    },
  },
});

// Make an API call and handle the response
githubStatusClient.Status.current()
  .then((response) => {
    // response.data() contains the parsed JSON body
    console.log('Current GitHub Status Summary:', response.data().status.description);
    console.log('API Request successful.');
  })
  .catch((error) => {
    console.error('Failed to fetch GitHub status:', error);
    if (error.response) {
        console.error('Response status:', error.response.status());
        console.error('Response data:', error.response.data());
    }
  });