@hardlydifficult/http 1.0.1 → 1.0.3

package/README.md

@@ -11,88 +11,85 @@ 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, MAX_BODY_BYTES } from "@hardlydifficult/http";
+import { createServer } from "http";
 
-const server = http.createServer(async (req, res) => {
-  // Read request body with default 1MB limit
+const server = createServer(async (req, res) => {
   const body = await readBody(req);
-
-  // Example: compare secrets safely
-  const isValid = safeCompare(body, "secret");
-
-  // Send JSON response with CORS support
-  sendJson(res, isValid ? 200 : 401, { valid: isValid }, "https://example.com");
+  const isValid = safeCompare(body, "expected-secret");
+  
+  sendJson(res, isValid ? 200 : 403, { authorized: isValid }, "https://example.com");
 });
 
 server.listen(3000);
+// → Server starts and safely compares incoming request bodies
 ```
 
-## Constant-Time String Comparison
-
-Protects against timing attacks by using `crypto.timingSafeEqual` internally.
-
-### `safeCompare(a: string, b: string): boolean`
+## Body Reading with Size Limit
 
-Compares two strings in constant time.
+Reads the full HTTP request body as a string, enforcing a configurable maximum size (default 1 MB). Throws an error if the payload exceeds the limit.
 
 ```typescript
-import { safeCompare } from "@hardlydifficult/http";
+import { readBody, MAX_BODY_BYTES } from "@hardlydifficult/http";
+
+// Default limit: 1 MB
+const body = await readBody(request);
 
-safeCompare("hello", "hello");     // true
-safeCompare("hello", "world");     // false
-safeCompare("", "something");      // false
-safeCompare("héllo", "héllo");     // true (unicode-safe)
+// Custom limit: 500 KB
+const body = await readBody(request, 1024 * 500);
 ```
 
-## Request Body Reading
+### Error Handling
 
-Reads full request body as string with configurable size limit.
+If the body exceeds the specified limit, the promise rejects with an `"Payload too large"` error.
 
-### `readBody(req: IncomingMessage, maxBytes?: number): Promise<string>`
+## JSON Response with CORS
 
-Parses incoming request body up to `maxBytes` (default: `MAX_BODY_BYTES`).
+Sends a JSON response with CORS headers enabled.
 
-```typescript
-import { readBody, MAX_BODY_BYTES } from "@hardlydifficult/http";
-import type { IncomingMessage } from "http";
+| Parameter | Type | Description |
+|---------|------|-------------|
+| `res` | `ServerResponse` | Node.js HTTP response object |
+| `status` | `number` | HTTP status code |
+| `body` | `unknown` | Any serializable data |
+| `corsOrigin` | `string` | Allowed origin for CORS (e.g., `"*"` or `"https://example.com"`) |
 
-// Use default limit (1MB)
-const body1 = await readBody(req);
+```typescript
+import { sendJson } from "@hardlydifficult/http";
 
-// Use custom limit (e.g., 512KB)
-const body2 = await readBody(req, 512 * 1024);
+sendJson(
+  res,
+  201,
+  { id: 123, message: "Created" },
+  "https://frontend.example.com"
+);
+// → Sets headers: Content-Type, Access-Control-Allow-Origin, etc.
 ```
 
-## JSON Response with CORS
-
-Sends JSON responses with CORS headers enabled.
-
-### `sendJson(res: ServerResponse, status: number, body: unknown, corsOrigin: string): void`
+## Constant-Time String Comparison
 
-Writes JSON response with proper headers and CORS support.
+Performs secure string comparison using `crypto.timingSafeEqual` to prevent timing attacks.
 
 ```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 { safeCompare } from "@hardlydifficult/http";
+
+const isMatch = safeCompare(userProvidedToken, storedToken);
+// → true if strings are identical, false otherwise
 ```
 
-## Constants
+### Behavior Details
 
-### `MAX_BODY_BYTES`
+- Returns `true` only for identical strings (including empty strings).
+- Returns `false` for different-length strings, with constant-time behavior.
+- Handles Unicode correctly by comparing UTF-8 encoded buffers.
 
-Default maximum body size in bytes (1 MB = 1048576).
+### Example Edge Cases
 
 ```typescript
-import { MAX_BODY_BYTES } from "@hardlydifficult/http";
-
-MAX_BODY_BYTES; // 1048576
+safeCompare("", "");               // true
+safeCompare("abc", "abc");         // true
+safeCompare("abc", "abd");         // false
+safeCompare("short", "longer");    // false
+safeCompare("héllo", "héllo");     // true
+safeCompare("héllo", "hello");     // false
 ```

package/package.json

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