Scoped HTTP Client for Node.js

Common errors

• Error: Cannot find module 'scoped-http-client'

  cause The package has not been installed or is not correctly listed in `package.json`.
  fix Run `npm install scoped-http-client` in your project directory.

• TypeError: client.get is not a function

  cause This error likely means `client.get()` was called without the final `()` to execute the request builder, or `client` was not correctly initialized from `scopedClient.create()`.
  fix Ensure the HTTP method call is immediately invoked to trigger the request, e.g., `client.get()(function(err, resp, body){...})`.

• Error: connect ECONNREFUSED <IP_ADDRESS>:<PORT>

  cause The client could not establish a connection to the target server, often due to the server being offline, incorrect host/port, or firewall issues.
  fix Verify the target URL, port, and ensure the server is running and accessible from the client's environment.

Warnings

• breaking This package targets Node.js version 0.8.0 and has not been updated since 2015. It is highly probable that it is incompatible with modern Node.js runtimes (e.js., Node.js v10+), especially due to changes in Node.js's internal `http` module and removal of deprecated APIs like `http.createClient` in Node.js v0.10.0.
  Fix: Migrate to a actively maintained HTTP client library such as `axios`, `node-fetch`, `got`, or the native `fetch` API available in recent Node.js versions.
• gotcha The API is entirely callback-based, meaning it does not support Promises, `async/await`, or modern error handling patterns. This can lead to callback hell and make integration with contemporary JavaScript codebases challenging.
  Fix: Refactor logic to use modern Promise-based HTTP clients or wrap `scoped-http-client` calls in custom Promise functions (though this is not recommended due to the package's abandonment).
• gotcha The package is unmaintained, meaning it will not receive updates for security vulnerabilities, bug fixes, or performance improvements. Using abandoned libraries can introduce significant security risks into an application's dependency tree.
  Fix: Avoid using this package in new projects. For existing projects, prioritize migration to a secure, actively maintained alternative.
• deprecated The `util.puts` function, used in the quickstart and README examples, is a deprecated Node.js API. It behaves similarly to `console.log` but with some historical differences in output buffering and newline handling.
  Fix: Replace `util.puts()` with `console.log()` for output in modern Node.js applications.
• gotcha This client lacks advanced features common in modern HTTP libraries, such as automatic JSON parsing, request retries, rate limiting, interceptors, or comprehensive timeout configurations, making it less suitable for complex or resilient applications.
  Fix: Consider alternatives like `axios` or `got` for projects requiring robust HTTP client features.

Install

• npm install scoped-http-client npm
• yarn add scoped-http-client yarn
• pnpm add scoped-http-client pnpm

Imports

• scopedClient
  wrong:

  import scopedClient from 'scoped-http-client';

  correct:

  const scopedClient = require('scoped-http-client');

  This package uses CommonJS `require()` syntax; ESM `import` is not supported.
• create
  wrong:

  const client = require('scoped-http-client').create('https://api.example.com');

  correct:

  const client = scopedClient.create('https://api.example.com');

  The `create` method is accessed via the default export of the module. While `require().create` works, assigning the module export first is conventional.
• Client Methods (.get, .post, .header, .path)
  wrong:

  client.get(callback); // Missing () to execute the request builder

  correct:

  client.header('Accept', 'application/json').get()(callback);

  HTTP method calls like `.get()` or `.post()` return a function that must be immediately invoked with `()` to execute the request, passing the callback to the invoked function.

Quickstart

Demonstrates creating a client, chaining methods for headers and paths, executing a GET request, and making a POST request within a scoped context, including basic error handling.

const scopedClient = require('scoped-http-client');
const util = require('util'); // Node.js built-in module

// Example 1: Basic GET request
const githubClient = scopedClient.create('https://api.github.com')
  .header('accept', 'application/json')
  .path('users/technoweenie')
  .get()(function(err, resp, body) {
    if (err) {
      console.error('Error fetching user:', err);
      return;
    }
    console.log('GET Response Status:', resp.statusCode);
    util.puts('User Info: ' + body);
  });

// Example 2: POST request within a scope
const token = process.env.GITHUB_TOKEN ?? 'YOUR_DUMMY_GITHUB_TOKEN'; // Replace with a real token or handle auth
const scopedBaseClient = scopedClient.create('https://api.github.com')
  .query({ token: token });

scopedBaseClient.scope('user/repos', function(cli) {
  const data = JSON.stringify({ name: 'my-new-repo', description: 'A test repository' });
  cli.post(data)(function(err, resp, body) {
    if (err) {
      console.error('Error creating repo:', err);
      return;
    }
    console.log('POST Response Status:', resp.statusCode);
    util.puts('Repo creation response: ' + body);
  });
});