REST Facade Client

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES Module context (`.mjs` file or `"type": "module"` in `package.json`).
  fix Convert your project to CommonJS by setting `"type": "commonjs"` in `package.json`, or use an actively maintained ESM-compatible HTTP client.

• Cannot find module 'superagent-proxy'

  cause The peer dependency `superagent-proxy` is required for proxy functionality but was not installed.
  fix Install the peer dependency: `npm install superagent-proxy`.

• TypeError: rest_facade_1.Client is not a constructor

  cause Incorrect import syntax for an old CommonJS module in an ES Module project, or incorrectly trying to destructure `Client` from `require('rest-facade')` without it being a direct named export.
  fix For CommonJS, use `const rest = require('rest-facade'); const client = new rest.Client(...);`. If in an ESM project, consider `import * as rest from 'rest-facade'; const client = new rest.Client(...);` though full compatibility with older CJS modules may vary. It's recommended to migrate to an ESM-first client.

• (node:xyz) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'length' of undefined

  cause Lack of error handling on Promise-based API calls. The `.then()` block assumes success without handling potential rejections.
  fix Always chain a `.catch()` method to Promise calls, e.g., `UserVideos.getAll({ userId: 4 }).then(...).catch(error => console.error(error));`

Warnings

• breaking This package appears to be unmaintained, with its last commit over six years ago (as of April 2026) and last publish three years ago. Users should exercise caution, as it may not receive critical updates, security patches, or compatibility fixes for newer Node.js versions or dependencies. Consider alternatives for long-term projects.
  Fix: Migrate to an actively maintained HTTP client library like `axios`, `node-fetch`, or a more modern REST client abstraction (e.g., OpenAPI generators).
• gotcha The package declares `superagent-proxy` as a peer dependency. This means users *must* explicitly install `superagent-proxy` alongside `rest-facade` for proxy functionality to work. Forgetting to install it will lead to runtime errors if proxy options are configured.
  Fix: Ensure `superagent-proxy` is installed: `npm install rest-facade superagent-proxy`.
• gotcha This library is primarily designed for CommonJS (CJS) environments and is not officially documented or tested for use with ES Modules (ESM). Attempting to use `import` statements directly might lead to runtime errors or require specific transpilation configurations.
  Fix: Use `const rest = require('rest-facade');` for CJS environments. For ESM, a wrapper might be needed or consider an actively maintained ESM-compatible alternative.
• gotcha While `rest-facade` supports Promises, it also offers a callback-based API. Mixing Promises and callbacks, or relying solely on callbacks, can lead to complex error handling and 'callback hell' in modern async JavaScript.
  Fix: Prefer using the Promise-based API for all operations and leverage `async/await` for cleaner asynchronous code.
• gotcha The library uses a colon notation (e.g., `:id`) for dynamic URL parameters. While convenient, complex parameter values (e.g., containing slashes or special characters that are part of the URL structure) might be incorrectly parsed or require careful encoding outside the library.
  Fix: Thoroughly test URLs with complex parameters. Ensure parameters are URL-encoded before passing them if they might contain reserved URI characters.

Install

• npm install rest-facade npm
• yarn add rest-facade yarn
• pnpm add rest-facade pnpm

Imports

• Client
  wrong:

  import { Client } from 'rest-facade';

  correct:

  const rest = require('rest-facade');
  const client = new rest.Client(...);

  The library exports an object with a 'Client' property via CommonJS. Direct named imports are not supported in ES Modules. The `Client` class is typically accessed as a property of the main module export.
• rest
  wrong:

  import rest from 'rest-facade';

  correct:

  const rest = require('rest-facade');

  This package is primarily a CommonJS module. Attempting a default ESM import will likely fail or require specific ESM compatibility layers.

Quickstart

Demonstrates how to initialize a REST client, create a new resource, retrieve it, update it, and finally delete it using the Promise-based API.

const rest = require('rest-facade');

// Create a client for a specific API endpoint with dynamic parameters
const Users = new rest.Client('http://domain.com/users/:id', {
  headers: {
    Authorization: 'Bearer my-auth-token'
  },
  errorFormatter: {
    name: 'error.title',
    message: 'error.text'
  }
});

const newUser = { firstName: 'Jane', lastName: 'Doe' };

// Example: Create a new user
Users.create(newUser)
  .then(function (user) {
    console.log('User created:', user);
    // Example: Get the created user by ID
    return Users.get({ id: user.id });
  })
  .then(function (retrievedUser) {
    console.log('User retrieved:', retrievedUser);
    // Example: Update the user
    return Users.update({ id: retrievedUser.id }, { firstName: 'Janet' });
  })
  .then(function () {
    console.log('User updated successfully.');
    // Example: Delete the user
    return Users.delete({ id: newUser.id });
  })
  .then(function () {
    console.log('User deleted successfully.');
  })
  .catch(function (error) {
    console.error('API operation failed:', error.message || error);
  });