Composable HTTP Client

Common errors

• TypeError: (0 , _requestCompose.Request) is not a function

  cause Attempting to import `Request` or `Response` as named exports from 'request-compose' when they are properties of the default export.
  fix Use `import compose from 'request-compose'; const { Request, Response } = compose;` (ESM) or `const compose = require('request-compose'); const { Request, Response } = compose;` (CommonJS).

• TypeError: compose is not a function

  cause Trying to import the `compose` function as a named export when it is the default export of the package.
  fix Use `import compose from 'request-compose';` (ESM) or `const compose = require('request-compose');` (CommonJS).

• Error: connect ECONNREFUSED

  cause The underlying HTTP request failed, typically due to an incorrect URL, an unreachable host, or a server that is not running or not listening on the specified port.
  fix Verify the URL, hostname, and port provided to `Request.url()` or within your custom request options. Ensure the target server is operational and network access is permitted.

• SyntaxError: Unexpected token 'export' (when using Node.js)

  cause Attempting to use ESM `import`/`export` syntax in a Node.js environment configured for CommonJS, or in an older Node.js version without explicitly declaring `"type": "module"` in `package.json`.
  fix For CommonJS environments, use `require()` syntax (e.g., `const compose = require('request-compose');`). For ESM in Node.js, ensure your `package.json` contains `"type": "module"` and use `import` statements.

Warnings

• gotcha The `Request` and `Response` middleware factories are properties of the default `compose` export, not named exports. Attempting to destructure them directly from the module like `import { Request } from 'request-compose'` will result in `undefined`.
  Fix: For ESM, use `import compose from 'request-compose'; const { Request, Response } = compose;`. For CommonJS, use `const compose = require('request-compose'); const { Request, Response } = compose;`.
• gotcha `request-compose` offers a composition mechanism and basic middlewares, but it does not bundle a full HTTP client implementation by default. For protocols like HTTPS, you often need to supply your own initial request function that wraps Node.js's native `http` or `https` modules within your composition pipeline.
  Fix: Consult the 'Compose' section in the documentation for advanced examples illustrating how to integrate native `http`/`https` request logic into your custom composed client.
• gotcha Since `request-compose` operations are promise-based, robust error handling with `try...catch` blocks or `.catch()` handlers is critical. Neglecting to handle rejected promises can lead to unhandled promise rejections, potentially crashing Node.js processes in environments prior to Node.js 15 or causing silent failures.
  Fix: Always wrap calls to your composed functions in `try...catch` blocks or chain a `.catch()` handler to the returned promise.

Install

• npm install request-compose npm
• yarn add request-compose yarn
• pnpm add request-compose pnpm

Imports

• compose
  wrong:

  import { compose } from 'request-compose';

  correct:

  import compose from 'request-compose';

  The main composition function (`compose`) is the default export of the package.
• Request
  wrong:

  import { Request } from 'request-compose';

  correct:

  import compose from 'request-compose'; const { Request } = compose;

  The `Request` middleware factories (and `Response`) are properties of the default `compose` export, not named exports themselves. This pattern applies to both ESM and CommonJS usage.
• Response
  wrong:

  import { Response } from 'request-compose';

  correct:

  import compose from 'request-compose'; const { Response } = compose;

  The `Response` middleware factories (and `Request`) are properties of the default `compose` export, not named exports themselves. This pattern applies to both ESM and CommonJS usage.

Quickstart

Demonstrates basic usage of `request-compose` by creating a composed HTTP client, setting default headers, fetching user data from GitHub, and parsing the JSON response. This example leverages the bundled Request and Response middlewares.

import compose from 'request-compose';

const Request = compose.Request;
const Response = compose.Response;

(async () => {
  try {
    const { res, body } = await compose(
      Request.defaults({headers: {'user-agent': 'request-compose'}}),
      Request.url('https://api.github.com/users/simov'),
      Request.send(),
      Response.buffer(),
      Response.string(),
      Response.parse()
    )();
    console.log(res.statusCode, res.statusMessage);
    console.log(res.headers['x-ratelimit-remaining']);
    console.log(body);
  }
  catch (err) {
    console.error(err);
  }
})();