Tiny JSON HTTP Client

Common errors

• TypeError: tiny.get is not a function

  cause Attempting to use `import` syntax (e.g., `import tiny from 'tiny-json-http'`) in a pure CommonJS environment, or incorrect destructuring of the required module.
  fix For CommonJS, use `const tiny = require('tiny-json-http')`. If you must use `import`, ensure your bundler or Node.js environment is configured to handle CommonJS module imports correctly.

• SyntaxError: Unexpected token < in JSON at position 0 (or similar JSON parsing error)

  cause The server responded with an HTML page (e.g., an error page), plain text, or an empty body, but tiny-json-http automatically attempted to parse it as JSON.
  fix If the response is not expected to be JSON, set the `buffer: true` option to receive the raw response body. You can then check its content type or parse it manually if desired.

• getaddrinfo ENOTFOUND example.com (or similar network error like ECONNREFUSED)

  cause The specified `url` is incorrect, the domain could not be resolved (DNS error), or the target server is unreachable or refused the connection.
  fix Verify the URL for typos, check your network connectivity, and ensure the target server is online and accessible from where your application is running. Implement retry logic for transient network issues.

• UnhandledPromiseRejectionWarning: [error message]

  cause A promise returned by tiny-json-http was rejected due to an error (e.g., network failure, server error response), but there was no `.catch()` handler or `try...catch` block to handle the error.
  fix Always add a `.catch()` method to promise chains (e.g., `tiny.get(...).then(...).catch(err => ...)`) or wrap `await` calls in a `try...catch` block to gracefully handle errors.

Warnings

• gotcha tiny-json-http automatically attempts to parse responses as JSON. If the server returns a non-JSON body (e.g., HTML error pages, plain text, or empty responses), this will result in a JSON parsing error.
  Fix: For non-JSON responses, set `buffer: true` in the options to receive the raw response body as a Buffer, which you can then parse manually if needed. E.g., `tiny.get({ url, buffer: true })`.
• gotcha The `del` (DELETE) method accepts a `data` object, which is sent as the request body. Some REST APIs expect DELETE parameters in the URL query string rather than the request body, which can lead to unexpected behavior or API rejection.
  Fix: For APIs expecting DELETE parameters in the URL, manually construct the URL with query string parameters: `tiny.del({ url: 'https://example.com/item?id=123' })`. Avoid sending sensitive data in query strings.
• gotcha While tiny-json-http supports both callbacks and Promises, failing to handle errors in either pattern can lead to unhandled promise rejections or uncaught exceptions, potentially crashing your application.
  Fix: Always include a `catch` block with Promises (e.g., `.catch(err => console.error(err))`) or wrap `await` calls in a `try...catch` block. When using callbacks, always check the `err` argument: `function(err, data) { if (err) { /* handle error */ } }`.
• gotcha The library does not expose options for configuring request timeouts directly in the public API excerpt provided. This means requests could hang indefinitely in cases of unresponsive servers, affecting application stability.
  Fix: Implement external timeout mechanisms (e.g., `Promise.race` with a `setTimeout` promise) or wrap tiny-json-http calls in a mechanism that handles long-running requests, especially in critical path operations.

Install

• npm install tiny-json-http npm
• yarn add tiny-json-http yarn
• pnpm add tiny-json-http pnpm

Imports

• tiny
  wrong:

  import tiny from 'tiny-json-http'

  correct:

  const tiny = require('tiny-json-http')

  tiny-json-http is primarily a CommonJS module. Direct ESM `import` statements may require bundler configuration or specific `import` paths (e.g., `import tiny from 'tiny-json-http/index.js'`) for full compatibility, though bundlers often handle this seamlessly.
• get
  wrong:

  import { get } from 'tiny-json-http'

  correct:

  const { get } = require('tiny-json-http')

  Individual methods like `get`, `post`, etc., are available directly on the module export object.
• post
  wrong:

  import { post } from 'tiny-json-http'

  correct:

  const { post } = require('tiny-json-http')

  When using ESM `import`, ensure your environment or bundler correctly resolves CJS named exports for these methods.

Quickstart

Demonstrates making a GET request to an external API using async/await syntax and robust error handling.

const tiny = require('tiny-json-http');
const url = 'https://jsonplaceholder.typicode.com/posts/1';

(async function _iife() {
  try {
    const result = await tiny.get({ url });
    console.log('Successfully fetched data:');
    console.log('Headers:', result.headers);
    console.log('Body:', result.body);
  } catch (err) {
    console.error('Error fetching data:', err.message);
    if (err.statusCode) {
      console.error('Status Code:', err.statusCode);
      console.error('Error Body:', err.body); // Server error body if available
    }
  }
})();