light-my-request

The module includes handwritten TypeScript declarations. You can import the entire namespace or specific members. The following types are exported:

• inject: standard inject method
• bindInject: creates a new inject function with pre-configured default options
• BoundInjectFunction: return type of bindInject
• DispatchFunc: the fake HTTP dispatch function
• InjectPayload: union type for valid payload types
• isInjection: standard isInjection method
• InjectOptions: options object for inject method
• Request: custom request object interface (extends Node.js stream.Readable by default)
• Response: custom response object interface (extends Node.js http.ServerResponse)

// Option 1: Import as namespace
import * as LightMyRequest from 'light-my-request'

const dispatch: LightMyRequest.DispatchFunc = function (req, res) {
  // ...
}

LightMyRequest.inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
  console.log(res.payload)
})

// Option 2: Named imports
import { inject, DispatchFunc } from 'light-my-request'

const dispatch: DispatchFunc = function (req, res) {
  // ...
}

inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
  console.log(res.payload)
})

When you call inject(dispatchFunc, options) without a callback, it returns a Chain instance. This instance provides a fluent interface to configure the request before executing it.

Available Chain Methods

HTTP Methods (sets the method and URL):

• .get(url)
• .post(url)
• .put(url)
• .patch(url)
• .delete(url)
• .head(url)
• .options(url)
• .trace(url)

Request Configuration:

• .body(value)
• .cookies(value)
• .headers(value)
• .payload(value)
• .query(value)

Executing the Request

To trigger the request, call .end([callback]). If no callback is provided, .end() returns a Promise that resolves to the response.

Note: The Chain object also inherits from Promise, so you can await the result of .end() directly.

const inject = require('light-my-request')

// Fluent chaining pattern
inject(handler)
  .post('/submit')
  .body({ foo: 'bar' })
  .headers({ 'content-type': 'application/json' })
  .end((err, res) => {
    if (err) throw err
    console.log(res.payload)
  })

Use bindInject(dispatchFunc, defaults) to create a new injection function that automatically includes common options (like authentication headers) in every request. The defaults are deeply merged with the options provided to the resulting function, but per-request options take precedence.

This is ideal for authentication flows where you want to log in once and then use a single function for all subsequent authenticated requests.

const { bindInject } = require('light-my-request')

// Create a bound inject function with default authorization header
const boundInject = bindInject(dispatch, {
  headers: { authorization: 'Bearer my-token' }
})

// All requests will include the authorization header
const res1 = await boundInject({ method: 'get', url: '/protected' })

// You can still add additional headers per request
const res2 = await boundInject({
  method: 'get',
  url: '/admin',
  headers: { 'x-custom': 'value' }
})

The inject(dispatchFunc[, options, callback]) function simulates an HTTP request by injecting it directly into a listener function (the dispatchFunc). This is useful for testing HTTP servers without actual network overhead.

Parameters

• dispatchFunc: A listener function with the signature function (req, res). This is the same type of function passed to http.createServer.
  • req: A simulated request object (inherits from Stream.Readable by default).
  • res: A simulated response object (inherits from Node's http.ServerResponse).
• options (Optional): An object to configure the request:
  • url | path: The request URL.
  • method: HTTP method (defaults to 'GET').
  • authority: The HTTP HOST header value (defaults to 'localhost').
  • headers: Object containing request headers. Values can be arrays to simulate multiple headers of the same name.
  • cookies: Key-value pairs to be encoded into the cookie header.
  • remoteAddress: Client remote address (defaults to '127.0.0.1').
  • payload | body: The request payload (string, Buffer, Stream, or object). Objects are automatically serialized to JSON with Content-type: application/json.
  • query: Object or string containing query parameters.
  • simulate: Object to control event behavior:
    • end: Whether to fire the end event.
    • split: Whether to split the payload into chunks.
    • error: Whether to emit an error event.
    • close: Whether to emit a close event.
  • signal: An AbortSignal to abort the request (Node v16+).
  • Request: Custom class for the request object to inherit from.
  • payloadAsStream: If true, response is streamed and res.payload/res.rawPayload will be undefined.
• callback (Optional): A function with signature function (err, res).

Response Object (res)

If using a callback or awaiting the promise, the response object contains:

• raw: { req, res } (the raw simulated objects).
• headers: Response headers.
• statusCode: HTTP status code.
• statusMessage: HTTP status message.
• payload: UTF-8 encoded string of the body.
• body: Alias for payload.
• rawPayload: The payload as a Buffer.
• json(): Function to parse the response payload as JSON.
• stream(): Function providing a Readable stream of the payload.
• cookies: Getter that parses set-cookie headers into an array of metadata.

const { inject } = require('light-my-request')

// Using the shorthand for GET /path
const res = await inject(dispatch, '/path')

// Using full options
const res = await inject(dispatch, {
  method: 'post',
  url: '/api/data',
  payload: { foo: 'bar' }
})

The inject() function is the primary entrypoint for light-my-request. It allows you to simulate HTTP requests against a server handler (dispatch function) without starting a real HTTP server.

It supports two usage patterns:

1. Callback pattern: Pass a callback function as the third argument to receive the response.
2. Promise/Chaining pattern: Omit the callback to receive a Chain object, which allows for a fluent API to build the request and returns a Promise.

Request Options

You can pass an options object to configure the request. Supported keys include:

• url: The target URL (can be a string).
• method: The HTTP method (e.g., 'GET', 'POST').
• body: The request body.
• cookies: An object containing cookies.
• headers: An object containing request headers.
• payload: The request payload.
• query: An object containing query string parameters.
• server: The server instance to bind the request to.
• Request: A custom Request constructor.
• autoStart: Boolean. If false, the request won't start automatically via process.nextTick (useful for manual control via .end()).

const inject = require('light-my-request')

// Example using the Promise/Chaining API
async function test() {
  const response = await inject(myServerHandler)
    .get('/path')
    .query({ id: 123 })
    .headers({ 'x-custom-header': 'value' })
    .end()

  console.log(response.payload)
}