@hardlydifficult/http 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/http
 
-HTTP utilities for safe request/response handling: constant-time string comparison, body reading with 1MB limit, and JSON responses with CORS.
+HTTP utilities for safe request/response handling, including constant-time string comparison, body reading with size limits, and JSON responses with CORS headers.
 
 ## Installation
 
@@ -11,88 +11,75 @@ npm install @hardlydifficult/http
 ## Quick Start
 
 ```typescript
-import { safeCompare, readBody, sendJson, MAX_BODY_BYTES } from "@hardlydifficult/http";
-import http from "http";
+import { readBody, sendJson, safeCompare } from '@hardlydifficult/http';
 
-const server = http.createServer(async (req, res) => {
-  // Read request body with default 1MB limit
-  const body = await readBody(req);
+// Safe string comparison
+const isMatch = safeCompare('secret', 'secret'); // true
 
-  // Example: compare secrets safely
-  const isValid = safeCompare(body, "secret");
+// Read request body with 1MB limit
+const body = await readBody(req); // max 1MB
 
-  // Send JSON response with CORS support
-  sendJson(res, isValid ? 200 : 401, { valid: isValid }, "https://example.com");
-});
-
-server.listen(3000);
+// Send JSON response with CORS headers
+sendJson(res, { status: 'ok' });
 ```
 
-## Constant-Time String Comparison
-
-Protects against timing attacks by using `crypto.timingSafeEqual` internally.
+## HTTP Utilities
 
-### `safeCompare(a: string, b: string): boolean`
+### Safe String Comparison
 
-Compares two strings in constant time.
+Performs constant-time comparison of two strings to prevent timing attacks.
 
 ```typescript
-import { safeCompare } from "@hardlydifficult/http";
+import { safeCompare } from '@hardlydifficult/http';
 
-safeCompare("hello", "hello");     // true
-safeCompare("hello", "world");     // false
-safeCompare("", "something");      // false
-safeCompare("héllo", "héllo");     // true (unicode-safe)
+const result = safeCompare('abc123', 'abc123'); // true
+const fail = safeCompare('abc123', 'abc124');   // false
 ```
 
-## Request Body Reading
+| Parameter | Type   | Description         |
+|-----------|--------|---------------------|
+| a         | string | First string to compare |
+| b         | string | Second string to compare |
 
-Reads full request body as string with configurable size limit.
+### Reading Request Body
 
-### `readBody(req: IncomingMessage, maxBytes?: number): Promise<string>`
-
-Parses incoming request body up to `maxBytes` (default: `MAX_BODY_BYTES`).
+Reads and returns the request body as a string, enforcing a maximum size limit of 1 MB.
 
 ```typescript
-import { readBody, MAX_BODY_BYTES } from "@hardlydifficult/http";
-import type { IncomingMessage } from "http";
-
-// Use default limit (1MB)
-const body1 = await readBody(req);
+import { readBody, MAX_BODY_BYTES } from '@hardlydifficult/http';
 
-// Use custom limit (e.g., 512KB)
-const body2 = await readBody(req, 512 * 1024);
+const body = await readBody(req); // max 1,048,576 bytes (1 MB)
+// Throws Error if body exceeds MAX_BODY_BYTES
 ```
 
-## JSON Response with CORS
+| Parameter | Type               | Description                    |
+|-----------|--------------------|--------------------------------|
+| req       | IncomingMessage    | Node.js HTTP request object    |
 
-Sends JSON responses with CORS headers enabled.
+### Sending JSON Responses
 
-### `sendJson(res: ServerResponse, status: number, body: unknown, corsOrigin: string): void`
-
-Writes JSON response with proper headers and CORS support.
+Sends a JSON response with appropriate `Content-Type` and `Access-Control-Allow-Origin` headers.
 
 ```typescript
-import { sendJson } from "@hardlydifficult/http";
-import type { ServerResponse } from "http";
-
-sendJson(res, 200, { message: "OK" }, "https://example.com");
-// Sends:
-//   Content-Type: application/json
-//   Access-Control-Allow-Origin: https://example.com
-//   Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
-//   Access-Control-Allow-Headers: Content-Type, Authorization
-// Body: {"message":"OK"}
+import { sendJson } from '@hardlydifficult/http';
+
+sendJson(res, { message: 'Hello world' });
+// Sends: {"message":"Hello world"} with CORS headers
 ```
 
-## Constants
+| Parameter | Type     | Description                     |
+|-----------|----------|---------------------------------|
+| res       | ServerResponse | Node.js HTTP response object |
+| data      | unknown  | Data to serialize as JSON       |
 
-### `MAX_BODY_BYTES`
+## Appendix
 
-Default maximum body size in bytes (1 MB = 1048576).
+### Body Size Limit Behavior
 
-```typescript
-import { MAX_BODY_BYTES } from "@hardlydifficult/http";
+The `readBody` function enforces a strict 1 MB (`MAX_BODY_BYTES = 1024 * 1024`) limit. If the request body exceeds this, it throws an error:
 
-MAX_BODY_BYTES; // 1048576
+```typescript
+if (received > MAX_BODY_BYTES) {
+  throw new Error(`Body exceeded maximum size of ${MAX_BODY_BYTES} bytes`);
+}
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/http",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [