HTTP Codex

Common errors

• TypeError: httpStatus.text is not a function

  cause Attempting to call `text()` on `httpStatus` after importing it from `'http-codex/status'`.
  fix Change the import to `import { httpStatus } from 'http-codex'` to access the `statusText()` helper, or manually map status codes to text if `http-codex/status` is specifically required for bundle size.

• ERR_MODULE_NOT_FOUND: Cannot find module 'http-codex' from '...' or SyntaxError: Cannot use import statement outside a module

  cause Attempting to `require('http-codex')` in a CommonJS environment or mixing CJS and ESM import styles.
  fix Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) and use `import { ... } from 'http-codex'` syntax. If a CommonJS environment is strictly required, consider using a bundler like Webpack or Rollup to transpile.

Warnings

• gotcha The `statusText()` helper function is only available when importing `httpStatus` from the main `http-codex` package entry point. It is *not* exported when importing `httpStatus` specifically from `http-codex/status` to reduce bundle size.
  Fix: Ensure you import `httpStatus` from `'http-codex'` if you need the `statusText()` method, or implement status text handling manually if using the smaller `'http-codex/status'` import.
• gotcha For optimal bundle size, avoid importing the entire `http-codex` package if you only need HTTP methods or status codes. Importing directly from `http-codex/method` or `http-codex/status` significantly reduces the payload.
  Fix: Use `import { httpMethod } from 'http-codex/method'` or `import { httpStatus } from 'http-codex/status'` for targeted imports, then import other helpers like `isNullBodyStatus` from the main package if needed.
• gotcha This library is designed to mimic Go's `net/http` package API. Developers accustomed to Node.js-specific HTTP libraries or other JavaScript HTTP utilities might find the API patterns slightly different.
  Fix: Refer to the `http-codex` documentation and examples, keeping in mind its Go-inspired design principles, rather than assuming direct parity with other JavaScript HTTP libraries.

Install

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

Imports

• httpStatus
  wrong:

  const httpStatus = require('http-codex')

  correct:

  import { httpStatus } from 'http-codex'

  Main entry point provides all features including `statusText()` helper.
• httpMethod
  wrong:

  import { httpMethod } from 'http-codex'

  correct:

  import { httpMethod } from 'http-codex/method'

  For smallest bundle size, import methods directly from 'http-codex/method'. The main export also includes it.
• isNullBodyStatus
  wrong:

  import { isNullBodyStatus } from 'http-codex/status'

  correct:

  import { isNullBodyStatus } from 'http-codex'

  This helper is part of the main `http-codex` export, not the status-only subpath.

Quickstart

This quickstart demonstrates how to use `http-codex` to construct `Response` objects with proper status codes and texts, use HTTP method constants, and apply the `isNullBodyStatus` helper function.

import { httpMethod, httpStatus, isNullBodyStatus } from 'http-codex';

// Example: Creating a simple HTTP response
const createResponse = (body: string | null, statusCode: number) => {
  const statusText = httpStatus.text(statusCode);
  return new Response(body, {
    status: statusCode,
    statusText: statusText,
    headers: { 'Content-Type': 'text/plain' }
  });
};

const successResponse = createResponse('Operation successful!', httpStatus.OK); // Status 200, "OK"
const notFoundResponse = createResponse('Resource not found', httpStatus.NOT_FOUND); // Status 404, "Not Found"
const noContentResponse = createResponse(null, httpStatus.NO_CONTENT); // Status 204, no body

console.log('Success Response:', successResponse.status, successResponse.statusText);
console.log('Not Found Response:', notFoundResponse.status, notFoundResponse.statusText);
console.log('No Content Response:', noContentResponse.status, noContentResponse.statusText);

// Example: Using HTTP methods
const currentMethod = httpMethod.GET; // 'GET'
const allowedMethods = [httpMethod.GET, httpMethod.POST, httpMethod.PUT];

if (!allowedMethods.includes(currentMethod)) {
  console.error(`Method ${currentMethod} is not allowed.`);
} else {
  console.log(`Method ${currentMethod} is allowed.`);
}

// Example: Handling null body statuses
const mockFetchResult = { status: httpStatus.NO_CONTENT, body: 'unwanted content' };
const finalBody = isNullBodyStatus(mockFetchResult.status) ? null : mockFetchResult.body;
console.log('Final body after null body check:', finalBody);