HTTPSnippet-lite

Common errors

• TypeError: httpsnippet_lite_1.HTTPSnippet is not a constructor

  cause Attempting to use CommonJS `require` syntax or incorrect destructuring for an ESM-focused library, especially in TypeScript projects or modern Node.js environments.
  fix Use ESM named imports: `import { HTTPSnippet } from 'httpsnippet-lite';`. If operating in a pure CommonJS environment, ensure your build setup correctly handles ESM interop or verify `httpsnippet-lite`'s CJS export behavior.

• (node:...) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'convert' of undefined

  cause Forgetting to `await` the asynchronous `snippet.convert()` method, leading to `convert` being called on an unresolved Promise.
  fix Always `await` the result of `snippet.convert(...)`. For example: `const output = await snippet.convert('shell', 'curl', options);`

• Error: Invalid HAR format: Headers property must be an array

  cause The input HAR object (e.g., `HarRequest` or `HarEntry`) contains malformed data, such as a non-array value for the `headers` property, which `httpsnippet-lite` does not validate.
  fix Ensure your HAR input strictly adheres to the HAR specification. For `headers`, it must be an array of objects, each with `name` and `value` properties. Review HAR documentation for correct structure.

Warnings

• breaking The `convert()` method is asynchronous and returns a Promise. Failing to `await` its result will lead to unhandled promise rejections or incorrect output.
  Fix: Always use `await snippet.convert(...)` or handle the Promise explicitly with `.then()` and `.catch()`.
• gotcha HTTPSnippet-lite does *not* perform validation on the input HAR (HTTP Archive) object. It assumes the provided `HarRequest` or `HarEntry` is strictly compliant with the HAR specification. Providing malformed HAR data can lead to unexpected output or runtime errors without explicit warnings.
  Fix: Thoroughly validate your HAR input against the HAR 1.2 specification (or the corresponding TypeScript types like `har-format`) before passing it to `HTTPSnippet` to ensure correctness.
• gotcha This package (`httpsnippet-lite`) is a fork of the original `Kong/httpsnippet` and is independently maintained. Key differences include no reliance on Node.js core modules, the `convert()` method being async, and the absence of HAR validation. Users migrating from or accustomed to the original `httpsnippet` should review the documentation for behavioral changes and feature set differences.
  Fix: Consult the `httpsnippet-lite` README for a detailed list of differences if you are familiar with `Kong/httpsnippet`.
• breaking This package specifies a Node.js engine requirement of `>=14.13`. Running the library on older Node.js versions may result in compatibility issues, runtime errors, or unexpected behavior.
  Fix: Ensure your project's Node.js environment is version `14.13.0` or higher.

Install

• npm install httpsnippet-lite npm
• yarn add httpsnippet-lite yarn
• pnpm add httpsnippet-lite pnpm

Imports

• HTTPSnippet
  wrong:

  const HTTPSnippet = require('httpsnippet-lite');

  correct:

  import { HTTPSnippet } from 'httpsnippet-lite';

  The library is primarily designed for ESM/TypeScript environments. While dual packaging might be available, `require` can lead to interop issues depending on your environment and bundler configuration. It's recommended to use ESM `import`.
• HarRequest
  wrong:

  import { HarRequest } from 'httpsnippet-lite';

  correct:

  import type { HarRequest } from 'httpsnippet-lite';

  HarRequest is a TypeScript interface/type. Use `import type` for type-only imports to prevent accidental runtime imports and optimize bundle size, especially crucial with bundlers.
• addTarget
  wrong:

  const { addTarget } = require('httpsnippet-lite');

  correct:

  import { addTarget } from 'httpsnippet-lite';

  Used for extending the library's functionality by registering custom code generation targets. Follows the same import guidance as `HTTPSnippet`.

Quickstart

This quickstart demonstrates how to instantiate `HTTPSnippet` with a basic HAR request object and then convert it into a cURL snippet using specific formatting options.

import { HTTPSnippet } from 'httpsnippet-lite';

const snippet = new HTTPSnippet({
  method: 'GET',
  url: 'http://mockbin.com/request',
  headers: [
    { name: 'Accept', value: 'application/json' }
  ],
  queryString: [
    { name: 'foo', value: 'bar' }
  ]
});

const options = { indent: '\t' };
const output = await snippet.convert('shell', 'curl', options);

console.log(output);
/* Expected output:
curl -X GET 'http://mockbin.com/request?foo=bar' \
	-H 'Accept: application/json'
*/