lil-http: Tiny Browser HTTP Client

Common errors

• TypeError: lil.http is undefined

  cause The `lil` global object or `lil.http` property was not found. This usually happens when the library's script file (`http.js`) hasn't been loaded in the HTML before being accessed, or if CommonJS `require()` was attempted in an environment that doesn't support it and no global fallback was registered.
  fix Ensure `<script src="path/to/http.js"></script>` is placed before any code attempting to use `lil.http`. Alternatively, if using a bundler, ensure `const http = require('lil-http');` is correctly used and bundled.

• Error: Cannot perform the request: 0

  cause This error message (with status 0) often indicates a network error, such as the server being unreachable, a DNS resolution failure, a browser preventing the request due to security policies (e.g., CORS), or the request being aborted before it completes. Status 0 is XHR's way of indicating the request didn't even get to the point of receiving an HTTP status code.
  fix Check the network tab in browser developer tools for more specific errors. Verify the target URL is correct and accessible. Review browser console for CORS related errors. If the issue is CORS, the server configuration needs to be adjusted to allow requests from your origin, or a proxy should be used.

• Access to XMLHttpRequest at 'http://example.com/api' from origin 'http://localhost:8080' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause The browser's Cross-Origin Resource Sharing (CORS) policy is blocking the request because the server at `http://example.com` did not send the necessary `Access-Control-Allow-Origin` header allowing requests from `http://localhost:8080`.
  fix Configure the server (`http://example.com`) to include the `Access-Control-Allow-Origin` header with your origin (`http://localhost:8080`) or `*` for all origins (less secure). For local development, a proxy server can be used to bypass CORS.

Warnings

• breaking The package is effectively abandoned, last published as 0.1.17. It relies on XMLHttpRequest (XHR) and a callback-based API, which are considered legacy in modern JavaScript development, favoring Fetch API and Promises/async-await. Integrating it into a modern codebase would require significant effort or polyfills to align with contemporary asynchronous patterns.
  Fix: For new development, use the native `fetch` API or a modern HTTP client library that supports Promises (e.g., `axios`). If bound to XHR, consider wrapping `lil-http` calls in `Promise` constructors.
• gotcha lil-http is a browser-only library and does not function in Node.js environments. It's built on `XMLHttpRequest`, which is a browser Web API.
  Fix: Ensure `lil-http` is only used in client-side browser code. For Node.js, use built-in `http`/`https` modules or a Node.js-compatible client like `axios` or `node-fetch`.
• gotcha The package uses a global fallback (`lil.http`) if `require()` is not available, which can lead to global namespace pollution or conflicts with other libraries using a similar `lil` object. This pattern is generally discouraged in modern module-based development.
  Fix: When possible, use CommonJS `require('lil-http')` in environments that support it (e.g., via a bundler like Webpack or Browserify). If relying on the global, be mindful of potential conflicts.
• deprecated The README mentions installation via Bower and Component, which are package managers that are largely deprecated or unmaintained in favor of npm/yarn. While `lil-http` is available on npm, its primary suggested installation methods are outdated.
  Fix: Install via npm: `npm install lil-http`. Be aware that even through npm, the underlying library is old and unmaintained.

Install

• npm install lil-http npm
• yarn add lil-http yarn
• pnpm add lil-http pnpm

Imports

• http
  wrong:

  import http from 'lil-http';

  correct:

  const http = require('lil-http');

  This package primarily supports CommonJS via `require()` for module loading, or global access.
• lil.http
  wrong:

  import { http } from 'lil-http';

  correct:

  // When loaded via a <script> tag
  lil.http.get('/api/data', ...);

  If no module loader (like CommonJS `require`) is available, the library exposes itself globally as `lil.http`.
• http.get
  wrong:

  import { get } from 'lil-http';

  correct:

  require('lil-http').get('/api/resource', options, callback);

  Individual HTTP methods like `get`, `post`, etc., are accessed directly from the imported or global `http` object.

Quickstart

This quickstart demonstrates a basic GET request using the globally exposed `lil.http` object, showing how to include authentication and custom headers, and handle the callback-based response.

<html>
<head>
  <title>lil-http Quickstart</title>
  <!-- Assuming lil-http.js is loaded, e.g., from a CDN or local file -->
  <script src="https://cdn.rawgit.com/lil-js/http/0.1.17/http.js"></script>
</head>
<body>
  <h1>lil-http GET Request Example</h1>
  <pre id="output"></pre>

  <script>
    // Mock API endpoint (in a real scenario, this would be a server endpoint)
    // For demonstration, we'll simulate a response after a delay.
    const mockApiResponse = { message: 'Hello from lil-http!', version: '0.1.17' };

    // Simulate a server response for '/sample.json'
    function simulateFetch(url, options, callback) {
      console.log(`Simulating GET request to ${url} with options:`, options);
      setTimeout(() => {
        if (url === '/sample.json') {
          callback(null, { status: 200, data: mockApiResponse, headers: {} });
        } else {
          callback({ status: 404, message: 'Not Found' }, null);
        }
      }, 500);
    }

    // Override lil.http.get for this example to use our simulator
    // In a real browser environment, lil.http.get would make a real XHR.
    lil.http.get = simulateFetch;

    lil.http.get('/sample.json', {
      auth: { user: 'guest', password: 'password' },
      headers: { 'X-Requested-With': 'lil-http' }
    }, function (err, res) {
      const outputDiv = document.getElementById('output');
      if (err) {
        console.error('Request failed:', err);
        outputDiv.textContent = 'Error: ' + (err.message || 'Unknown error') + ' (Status: ' + err.status + ')';
      } else if (res.status === 200) {
        console.log('Response data:', res.data);
        outputDiv.textContent = 'Success! Data: ' + JSON.stringify(res.data, null, 2);
      } else {
        outputDiv.textContent = 'Unexpected status: ' + res.status;
      }
    });
  </script>
</body>
</html>