HTTP Request/Response File Persistence

1.0.3 verified Thu Apr 23 auth: no javascript

`http-file` is a TypeScript library designed for serializing and deserializing complete HTTP request and response objects to and from a structured file format. It provides core classes like `RequestFile` and `ResponseFile` to encapsulate all relevant HTTP interaction data, including method, URL, headers, and body, along with utility functions such as `readRequestFile`, `writeRequestFile`, `readResponseFile`, and `writeResponseFile` for file system operations. This capability is particularly useful for scenarios requiring the persistence of HTTP traffic, such as creating mock servers from recorded interactions, replaying requests for testing or debugging, or sharing specific HTTP payloads. The package is currently at version 1.0.3. While it ships with full TypeScript types and offers a stable API, its last release was over two years ago, indicating a mature, low-cadence maintenance or stable phase rather than active feature development. Its key differentiator lies in its focused approach to structured file-based storage of entire HTTP dialogues, distinct from general-purpose HTTP clients or static file servers.

Common errors

error Error: ENOENT: no such file or directory, open 'path/to/non-existent-file.json' ↓

cause The specified file path for reading or writing does not exist or refers to an invalid location.

fix

Ensure the directory exists before writing, and the file exists before reading. Use fs.mkdir(path, { recursive: true }) for directories.

error TypeError: The "path" argument must be of type string. Received type object ↓

cause A non-string value (e.g., `null`, `undefined`, an object) was passed as the file path argument to `readRequestFile`, `writeRequestFile`, or related functions.

fix

Always pass a valid string representing the file path to the library's file I/O functions.

Warnings

gotcha Storing sensitive HTTP request or response data (e.g., authorization tokens, user credentials, private data in bodies) directly to files on disk can be a security risk. Ensure these files are stored in secure locations with appropriate access controls and are not committed to version control systems. ↓

fix Never commit files containing sensitive information to public repositories. Implement robust access controls for local storage and consider encrypting files if they contain highly sensitive data.

gotcha The library primarily operates on file paths. Incorrect or invalid file paths (e.g., non-existent directories, permission issues) will result in standard Node.js file system errors (e.g., `ENOENT`, `EACCES`) rather than custom library errors. These errors will be thrown by the underlying `fs/promises` module. ↓

fix Always validate file paths and ensure necessary directory structures exist and have correct permissions before attempting write operations. Wrap file operations in `try-catch` blocks to handle potential `fs` errors gracefully.

gotcha The `body` property for `RequestFile` and `ResponseFile` supports `string | null | Buffer`. When dealing with non-UTF-8 textual content or binary data, it is crucial to pass a `Buffer` instance to preserve data integrity. Storing binary data as a plain string might lead to corruption or incorrect interpretation. ↓

fix For binary HTTP bodies (e.g., images, downloads), ensure you convert the data to a Node.js `Buffer` before assigning it to the `body` property. When reading, check `Buffer.isBuffer(loadedObject.body)` and handle accordingly.

Install

npm install http-file

yarn add http-file

pnpm add http-file

Imports

RequestFile
wrong
```
const RequestFile = require('http-file').RequestFile;
```
correct
```
import { RequestFile } from 'http-file';
```
Primarily designed for ESM and TypeScript; CommonJS requires dot-notation access to named exports.
readRequestFile
wrong
```
import readRequestFile from 'http-file/readRequestFile';
```
correct
```
import { readRequestFile } from 'http-file';
```
All public functions and classes are named exports from the main package entry point.

ResponseFile

wrong

import * as httpFile from 'http-file'; const myResponse = new httpFile.ResponseFile();

correct

import { ResponseFile, writeResponseFile } from 'http-file';

Destructuring named imports is the recommended pattern for clarity and tree-shaking.

Quickstart

This quickstart demonstrates how to create `RequestFile` and `ResponseFile` objects, write them to disk, and then read them back, showcasing the library's core serialization and deserialization capabilities.

import { RequestFile, ResponseFile, writeRequestFile, readRequestFile, writeResponseFile, readResponseFile } from 'http-file';
import * as fs from 'fs/promises'; // For file cleanup

async function exampleUsage() {
  const requestFilePath = 'example-request.http.json';
  const responseFilePath = 'example-response.http.json';

  // 1. Create a RequestFile instance
  const requestData: RequestFile = {
    method: 'GET',
    url: 'https://api.example.com/data/items/1?cache=false',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': `Bearer ${process.env.API_KEY ?? 'YOUR_FALLBACK_TOKEN'}`, // Use env var for sensitive data
    },
    body: null,
  };

  // 2. Write the RequestFile to disk
  await writeRequestFile(requestFilePath, requestData);
  console.log(`Request file written to ${requestFilePath}`);

  // 3. Read the RequestFile from disk
  const loadedRequest = await readRequestFile(requestFilePath);
  console.log('Loaded request URL:', loadedRequest.url);

  // 4. Create a ResponseFile instance
  const responseData: ResponseFile = {
    statusCode: 200,
    headers: {
      'Content-Type': 'application/json',
      'X-Request-ID': 'unique-abc-123',
      'Cache-Control': 'no-cache'
    },
    body: JSON.stringify({ message: 'Data fetched successfully', data: { id: 1, name: 'Item 1' } }),
  };

  // 5. Write the ResponseFile to disk
  await writeResponseFile(responseFilePath, responseData);
  console.log(`Response file written to ${responseFilePath}`);

  // 6. Read the ResponseFile from disk
  const loadedResponse = await readResponseFile(responseFilePath);
  console.log('Loaded response status:', loadedResponse.statusCode);
  console.log('Loaded response body:', loadedResponse.body ? JSON.parse(loadedResponse.body.toString()) : null);

  // Clean up created files
  await fs.unlink(requestFilePath);
  await fs.unlink(responseFilePath);
  console.log('Cleaned up example files.');
}

exampleUsage().catch(console.error);