Simplified HTTP Request for Node.js

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module [path] not supported

  cause Attempting to `import` the `ajax-request` package in an ES Module context.
  fix Change `import request from 'ajax-request';` to `const request = require('ajax-request');` and ensure your project is configured for CommonJS or uses dynamic `import()` if mixed modules are necessary.

• TypeError: callback is not a function

  cause The request method (or its variants) was called without providing a callback function as the last argument.
  fix Ensure that a function is passed as the `callback` argument to `request()`, `request.post()`, or `request.download()` methods.

• Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

  cause The Node.js environment failed to verify the SSL certificate of the target server, often due to an outdated root certificate store or a self-signed certificate.
  fix Update Node.js to a recent version. If the server uses a self-signed certificate in a controlled environment, you might temporarily set `NODE_TLS_REJECT_UNAUTHORIZED='0'` (NOT for production) or add the certificate to your trusted store. The best fix is to migrate to a modern, maintained HTTP client library.

Warnings

• gotcha The `ajax-request` package is significantly outdated (v1.2.3, last published ~8 years ago) and appears to be unmaintained. It lacks modern features like Promise-based APIs or `async/await` support, relying solely on callbacks.
  Fix: Consider migrating to a modern HTTP client library for Node.js such as `axios`, `node-fetch`, or the built-in `fetch` API (available in Node.js >= 18) for better security, features, and maintainability.
• breaking The package is CommonJS-only and does not support ES Modules. Attempting to use `import` syntax will result in a runtime `ERR_REQUIRE_ESM` error.
  Fix: Ensure your project uses `require()` for importing `ajax-request`. For new projects, consider using a modern library that supports ES Modules or the native Node.js `fetch` API.
• deprecated The `request.base64` method has been explicitly deprecated and moved to a separate package. Its functionality is no longer part of `ajax-request`.
  Fix: For base64 image functionality, refer to the `base64-img` package or implement the conversion manually using Node.js's built-in `Buffer` and file system modules.
• gotcha Due to its age, `ajax-request` might not correctly handle modern TLS/SSL certificates, leading to `UNABLE_TO_VERIFY_LEAF_SIGNATURE` or similar errors when connecting to contemporary HTTPS endpoints. It also lacks explicit security updates for potential vulnerabilities.
  Fix: Migrate to a actively maintained HTTP client. If immediate migration is not possible, for testing or specific controlled environments, Node.js can be run with `NODE_TLS_REJECT_UNAUTHORIZED='0'` (NOT recommended for production) or a custom agent with `rejectUnauthorized: false` for `http.request` based calls, but this is a significant security risk.
• gotcha The package does not ship with TypeScript type definitions, leading to poor developer experience and lack of type safety in TypeScript projects.
  Fix: Manually create declaration files (e.g., `ajax-request.d.ts`) or use a modern HTTP client that provides official TypeScript support.

Install

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

Imports

• request
  wrong:

  import request from 'ajax-request';

  correct:

  const request = require('ajax-request');

  This package is CommonJS-only and does not support ES module `import` syntax. Attempting to use `import` will result in a runtime error.
• request.post
  wrong:

  import { post } from 'ajax-request';

  correct:

  const request = require('ajax-request');
  request.post(options, callback);

  The `post` method is available as a property of the default `request` export in CommonJS. It is not a named export for ES Modules.
• request.download
  wrong:

  import { download } from 'ajax-request';

  correct:

  const request = require('ajax-request');
  request.download(options, callback);

  The `download` method is available as a property of the default `request` export in CommonJS. It is not a named export for ES Modules.

Quickstart

This quickstart demonstrates how to perform a simple GET request, a POST request with JSON data, and download a file using the callback-based API of `ajax-request`.

const request = require('ajax-request');

// Example 1: Basic GET request
request('https://jsonplaceholder.typicode.com/posts/1', function(err, res, body) {
  if (err) {
    console.error('GET Error:', err);
    return;
  }
  console.log('GET Response (Status Code):', res.statusCode);
  console.log('GET Response (Body):', JSON.parse(body));
});

// Example 2: POST request with data
request({
  url: 'https://jsonplaceholder.typicode.com/posts',
  method: 'POST',
  data: {
    title: 'foo',
    body: 'bar',
    userId: 1
  },
  json: true // Automatically parse response body as JSON
}, function(err, res, body) {
  if (err) {
    console.error('POST Error:', err);
    return;
  }
  console.log('POST Response (Status Code):', res.statusCode);
  console.log('POST Response (Body):', body);
});

// Example 3: Download a file (replace with a real, small file URL for testing)
// NOTE: This will attempt to save a file to the current working directory.
const fs = require('fs');
const tempFilePath = './downloaded-image.png';

request.download({
  url: 'https://via.placeholder.com/150/FF0000/FFFFFF?text=Test',
  destPath: tempFilePath
}, function(err, res, body, destpath) {
  if (err) {
    console.error('Download Error:', err);
    return;
  }
  console.log(`File downloaded to: ${destpath}`);
  // Verify file existence (optional)
  if (fs.existsSync(tempFilePath)) {
    console.log('Downloaded file exists!');
    fs.unlinkSync(tempFilePath); // Clean up
  }
});