lilreq

Your stupid, dependency-free, minimalist HTTP request library.

• Lilreq
  • Quickstart
  • API
    • request
    • Convenience Methods
  • Examples
  • Why I Made This
  • Handling Responses
    • Handling JSON Responses
    • Handling Errors
  • Installation

Quickstart

Install it:

npm install lilreq
# pnpm
pnpm add lilreq
# yarn
yarn add lilreq

Use it:

import lilreq from 'lilreq';

lilreq.get('http://example.com').then(res => {
  console.log(res);
}).catch(error => {
  console.error(error);
});

API

request

request(url, method = 'GET', parameters = {})

• url: string - The URL to which the request is sent.
• method: string - The HTTP method (GET, POST, PUT, etc.).
• parameters: object - Configuration object with optional headers and payload.

Returns

A Promise that resolves with the response object or rejects with an error.

Response Object Structure

• headers: object - The response headers.
• status: number - The HTTP status code.
• statusText: string - The HTTP status text.
• config: object - The original request configuration.
• payload: any - The parsed response payload.
• error (optional): string - If there was an error (e.g., JSON parse failure).

Convenience Methods

Lilreq provides several convenience methods for common HTTP methods:

get

get(url, parameters = {})

Sends a GET request to the specified URL.

head

head(url, parameters = {})

Sends a HEAD request to the specified URL.

post

post(url, parameters = {})

Sends a POST request to the specified URL.

put

put(url, parameters = {})

Sends a PUT request to the specified URL.

trace

trace(url, parameters = {})

Sends a TRACE request to the specified URL.

options

options(url, parameters = {})

Sends an OPTIONS request to the specified URL.

patch

patch(url, parameters = {})

Sends a PATCH request to the specified URL.

Examples

Simple GET Request

import lilreq from 'lilreq';

lilreq.get('http://example.com')
  .then(res => console.log(res.payload))
  .catch(error => console.error(error));

POST Request with JSON Payload

import lilreq from 'lilreq';

lilreq.post('http://example.com/api', {
  headers: { 'Content-Type': 'application/json' },
  payload: { key: 'value' }
}).then(res => {
  console.log(res.payload);
}).catch(error => {
  console.error(error);
});

Handling JSON Responses

Lilreq automatically parses JSON responses. If the response isn't valid JSON, an error will be included in the response.

lilreq.get('http://example.com/api/data')
  .then(res => {
    if (!res.error) {
      console.log('Parsed JSON:', res.payload);
    } else {
      console.error('Failed to parse JSON:', res.payload);
    }
  })
  .catch(error => console.error('Request failed:', error));

Handling Errors

Lilreq rejects the promise with an error object if there's a failure, such as a network error or an invalid JSON payload.

lilreq.post('http://example.com/api', {
  headers: { 'Content-Type': 'application/json' },
  payload: { invalid: 'json' },
}).catch(error => {
  console.error('Error:', error.error); // lilreq: Failure: Invalid JSON payload
});

Handling Responses

Handling JSON Responses

If the Content-Type of the response is application/json, lilreq will automatically attempt to parse it into a JavaScript object. If parsing fails, an error will be included in the response object.

Handling Errors

Lilreq handles different error scenarios gracefully:

• Network Errors: If the request fails due to a network issue, the promise is rejected with an error message like lilreq: Failure: Network error.
• Invalid JSON Payloads: If the provided JSON payload cannot be stringified, the promise is rejected but just passes the JSON as a string.
• JSON Parse Failures: If the response cannot be parsed as JSON, the error field will be added to the response object.