@centralping/ergo 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -1,8 +1,8 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-wordmark-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="assets/logo-wordmark-light.svg">
-    <img alt="ergo" src="assets/logo-wordmark-light.svg" width="240">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/CentralPing/ergo/main/assets/logo-wordmark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/CentralPing/ergo/main/assets/logo-wordmark-light.svg">
+    <img alt="ergo" src="https://raw.githubusercontent.com/CentralPing/ergo/main/assets/logo-wordmark-light.svg" width="240">
   </picture>
 </p>
 
@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/@centralping/ergo.svg)](https://www.npmjs.com/package/@centralping/ergo)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/CentralPing/ergo/badge)](https://scorecard.dev/viewer/?uri=github.com/CentralPing/ergo)
 [![Node.js >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/CentralPing/ergo/blob/main/LICENSE)
 
 A **Fast Fail** REST API toolkit for Node.js. _ergo_ (error or go) provides composable, stream-native middleware organized around the principle that a server should fail as early as possible -- before doing any expensive work -- through four ordered stages: **Negotiation, Authorization, Validation, and Execution**. Every behavior is backed by an IETF RFC or industry standard, not invented conventions.
 
@@ -57,20 +57,19 @@ Requires **Node.js >= 22**.
 
 ```js
 import {createServer} from 'node:http';
-import {compose, handler, logger, cors, authorization, body, send} from '@centralping/ergo';
+import {compose, handler, logger, cors, authorization, body} from '@centralping/ergo';
 
 const pipeline = compose(
-  [logger(), [], 'log'],
-  [cors(), [], 'cors'],
+  [logger(), 'log'],
+  [cors(), 'cors'],
   [authorization({strategies: [{type: 'Bearer', authorizer: (_, token) =>
     token === 'my-token' ? {authorized: true, info: {uid: 1}} : {}
-  }]}), [], 'auth'],
-  [body(), [], 'body'],
-  (req, res, {auth, body}) => ({body: {user: auth, data: body.parsed}}),
-  send()
+  }]}), 'auth'],
+  [body(), 'body'],
+  (req, res, acc) => ({response: {body: {user: acc.auth, data: acc.body.parsed}}})
 );
 
-createServer(handler(pipeline, send())).listen(3000);
+createServer(handler(pipeline)).listen(3000);
 ```
 
 ## Middleware Overview
@@ -96,7 +95,7 @@ createServer(handler(pipeline, send())).listen(3000);
 | `cacheControl()` | Cache-Control header management | [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) |
 | `jsonApiQuery()` | JSON:API query parameter validation | [JSON:API](https://jsonapi.org/) |
 
-See the [full API reference](https://centralping.github.io/api/ergo/) for detailed options and examples.
+See the [full API reference](https://centralping.github.io/packages/ergo/) for detailed options and examples.
 
 ## Standards Compliance
 
@@ -120,8 +119,8 @@ See the [full API reference](https://centralping.github.io/api/ergo/) for detail
 ## Documentation
 
 - [Getting Started](https://centralping.github.io/getting-started/)
-- [API Reference](https://centralping.github.io/api/ergo/)
-- [Architecture & Design](https://centralping.github.io/architecture/)
+- [API Reference](https://centralping.github.io/packages/ergo/)
+- [Fast Fail Pipeline](https://centralping.github.io/concepts/fast-fail/)
 - [Benchmarks](https://centralping.github.io/benchmarks/)
 
 ## Development

package/http/accepts.js

@@ -10,13 +10,12 @@
  * Fast Fail pipeline.
  *
  * @module http/accepts
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/accepts.js
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, accepts} from 'ergo';
+ * import {compose, accepts} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [accepts({types: ['application/json']}), 'accepts'],

package/http/authorization.js

@@ -10,13 +10,12 @@
  * response header (RFC 7235).
  *
  * @module http/authorization
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/authorization.js
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, authorization} from 'ergo';
+ * import {compose, authorization} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [authorization({

package/http/body.js

@@ -17,7 +17,6 @@
  * 3-stream pipeline for reduced per-request overhead.
  *
  * @module http/body
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:stream
  * @requires node:zlib
@@ -29,7 +28,7 @@
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, body} from 'ergo';
+ * import {compose, body} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [body({limit: 2 * 1024 * 1024}), 'body'],

package/http/cache-control.js

@@ -6,11 +6,10 @@
  * a raw directive string or structured options that are assembled into a directive.
  *
  * @module http/cache-control
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import {compose, cacheControl} from 'ergo';
+ * import {compose, cacheControl} from '@centralping/ergo';
  *
  * // String shorthand
  * const pipeline = compose(

package/http/compress.js

@@ -13,13 +13,12 @@
  * - Bodies below the configurable `threshold` byte count (default 1 KiB)
  *
  * @module http/compress
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:zlib
  * @requires negotiator
  *
  * @example
- * import {compose, compress} from 'ergo';
+ * import {compose, compress} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   compress({threshold: 1024, encodings: ['br', 'gzip', 'deflate']}),

package/http/cookie.js

@@ -12,12 +12,11 @@
  * and other cookie-based workflows.
  *
  * @module http/cookie
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/cookie/index.js
  *
  * @example
- * import {compose, cookie} from 'ergo';
+ * import {compose, cookie} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [cookie(), 'cookies'],

package/http/cors.js

@@ -10,13 +10,12 @@
  * Pre-flight `OPTIONS` requests should be handled at the router level using `ergo-router`.
  *
  * @module http/cors
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/cors.js
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, cors} from 'ergo';
+ * import {compose, cors} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [cors({

package/http/csrf.js

@@ -11,13 +11,12 @@
  * The CSRF UUID is stored in a separate cookie so the token can be regenerated independently.
  *
  * @module http/csrf
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/csrf.js
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, cookie, csrf} from 'ergo';
+ * import {compose, cookie, csrf} from '@centralping/ergo';
  *
  * const csrfMiddleware = csrf({secret: process.env.CSRF_SECRET});
  *

package/http/handler.js

@@ -13,11 +13,10 @@
  * compose middleware directly without the router.
  *
  * @module http/handler
- * @version 0.2.0
  * @since 0.1.0
  *
  * @example
- * import {handler, compose, send, logger, authorization, body} from 'ergo';
+ * import {handler, compose, logger, authorization, body} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [logger(), 'log'],

package/http/index.js

@@ -1,13 +1,46 @@
 /**
- * @fileoverview Entry point for the @centralping/ergo package.
+ * @fileoverview Fast Fail REST API toolkit for Node.js.
  *
- * Re-exports the main module for ESM consumers:
- * `import { handler, send } from '@centralping/ergo'`
+ * Composable middleware organized into four ordered pipeline stages — a failure
+ * at any stage immediately returns a standards-compliant error response so no
+ * downstream work is wasted:
+ *
+ * | Stage | Middleware | Purpose |
+ * | --- | --- | --- |
+ * | **Negotiation** | {@link logger}, {@link cors}, {@link accepts}, {@link cookie}, {@link url} | Parse/inspect request headers and URL |
+ * | **Authorization** | {@link authorization}, {@link csrf} | Authenticate and verify request integrity |
+ * | **Validation** | {@link body}, {@link jsonApiQuery}, {@link validate} | Parse and validate the request body |
+ * | **Execution** | {@link timeout}, {@link compress}, {@link handler}, {@link send} | Run the handler and serialize the response |
+ *
+ * Cross-cutting middleware available at any stage:
+ * {@link cacheControl}, {@link prefer}, {@link precondition},
+ * {@link rateLimit}, {@link securityHeaders}
+ *
+ * **Composition utilities:** {@link compose}, {@link createResponseAcc},
+ * {@link mergeResponse}, {@link httpErrors}, {@link fromConnect}
  *
  * @module @centralping/ergo
- * @version 0.1.0-beta.1
  * @since 0.1.0
  * @requires ./main.js
+ *
+ * @example
+ * import {compose, handler, logger, cors, accepts, authorization,
+ *         body, send} from '@centralping/ergo';
+ *
+ * const pipeline = compose(
+ *   [logger(), 'log'],
+ *   [cors(), 'cors'],
+ *   [accepts({types: ['application/json']}), 'accepts'],
+ *   [authorization({strategies: [...]}), 'auth'],
+ *   [body(), 'body'],
+ *   (req, res, acc) => ({response: {body: acc.body.parsed}}),
+ * );
+ *
+ * const server = http.createServer(handler(pipeline));
+ *
+ * @see {@link https://centralping.github.io/concepts/fast-fail/ Fast Fail Pipeline}
+ * @see {@link https://centralping.github.io/concepts/security/ Security}
+ * @see {@link https://centralping.github.io/concepts/standards/ Standards Compliance}
  */
 
 export * from './main.js';

package/http/json-api-query.js

@@ -11,13 +11,12 @@
  * Must be placed after `url()` in the pipeline so that `acc.url` is populated.
  *
  * @module http/json-api-query
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/json-api-query/index.js
  * @requires ../utils/http-errors.js
  *
  * @example
- * import {compose, url, jsonApiQuery} from 'ergo';
+ * import {compose, url, jsonApiQuery} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [url(), 'url'],

package/http/logger.js

@@ -23,13 +23,12 @@
  * accidental secret leakage.
  *
  * @module http/logger
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:os
  * @requires node:crypto
  *
  * @example
- * import {compose, logger} from 'ergo';
+ * import {compose, logger} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [logger(), 'log'],

package/http/main.js

@@ -14,8 +14,7 @@
  * accumulated under named keys in `domainAcc`; response properties merge
  * into `responseAcc`. `send()` is called post-pipeline by `handler()`.
  *
- * @module ergo
- * @version 0.1.0
+ * @module @centralping/ergo
  * @since 0.1.0
  * @requires ./handler.js
  * @requires ./accepts.js
@@ -42,7 +41,7 @@
  *
  * @example
  * import {compose, handler, logger, cors, authorization, accepts,
- *         cookie, url, body} from 'ergo';
+ *         cookie, url, body} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   // Stage 1: Negotiation

package/http/precondition.js

@@ -10,11 +10,10 @@
  * inspection that short-circuits before authorization, body parsing, or execution.
  *
  * @module http/precondition
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import {compose, precondition} from 'ergo';
+ * import {compose, precondition} from '@centralping/ergo';
  *
  * // Enforce on all requests (method scoping handled by pipeline builder)
  * const pipeline = compose(

package/http/prefer.js

@@ -8,12 +8,11 @@
  * Placed in Stage 1 (Negotiation) — cheap header parse with no I/O.
  *
  * @module http/prefer
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/prefer.js
  *
  * @example
- * import {compose, prefer} from 'ergo';
+ * import {compose, prefer} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [prefer(), 'prefer'],

package/http/rate-limit.js

@@ -10,12 +10,11 @@
  * or execution.
  *
  * @module http/rate-limit
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/rate-limit.js
  *
  * @example
- * import {compose, rateLimit} from 'ergo';
+ * import {compose, rateLimit} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [rateLimit({max: 100, windowMs: 60000}), 'rateLimit'],

package/http/security-headers.js

@@ -8,12 +8,11 @@
  * Delegates tuple construction to `lib/security-headers.js` (the shared primitive).
  *
  * @module http/security-headers
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/security-headers.js
  *
  * @example
- * import {compose, securityHeaders} from 'ergo';
+ * import {compose, securityHeaders} from '@centralping/ergo';
  *
  * // Use defaults
  * const pipeline = compose(

package/http/send.js

@@ -29,7 +29,6 @@
  * - Optional response envelope for 2xx Object bodies
  *
  * @module http/send
- * @version 0.2.0
  * @since 0.1.0
  * @requires node:stream
  * @requires node:http
@@ -38,7 +37,7 @@
  * @requires ../lib/vary.js
  *
  * @example
- * import {send, createResponseAcc} from 'ergo';
+ * import {send, createResponseAcc} from '@centralping/ergo';
  *
  * const writer = send({etag: true});
  * // After pipeline completes:

package/http/timeout.js

@@ -12,11 +12,10 @@
  * can be GC'd.
  *
  * @module http/timeout
- * @version 0.2.0
  * @since 0.1.0
  *
  * @example
- * import {compose, timeout} from 'ergo';
+ * import {compose, timeout} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [timeout({ms: 10000, statusCode: 504}), 'timeout'],

package/http/url.js

@@ -11,12 +11,11 @@
  * - `search` is the raw query string including the `?` prefix, or `undefined`
  *
  * @module http/url
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/query.js
  *
  * @example
- * import {compose, url} from 'ergo';
+ * import {compose, url} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [url(), 'url'],

package/http/validate.js

@@ -9,12 +9,11 @@
  * are populated before validation runs.
  *
  * @module http/validate
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../lib/validate.js
  *
  * @example
- * import {compose, body, url, validate} from 'ergo';
+ * import {compose, body, url, validate} from '@centralping/ergo';
  *
  * const pipeline = compose(
  *   [body(), 'body'],

package/lib/accepts.js

@@ -6,13 +6,12 @@
  * as the pure-logic backing implementation.
  *
  * @module lib/accepts
- * @version 0.1.0
  * @since 0.1.0
  * @requires negotiator
  * @requires ../utils/flat-array.js
  *
  * @example
- * import accepts from 'ergo/lib/accepts';
+ * import accepts from '@centralping/ergo/lib/accepts';
  *
  * const negotiate = accepts({types: ['application/json', 'text/html']});
  * const result = negotiate({'accept': 'text/html,application/json;q=0.9'});

package/lib/attach-instance.js

@@ -5,7 +5,6 @@
  * `x-request-id` header, formatted as a `urn:uuid:` URI.
  *
  * @module lib/attach-instance
- * @version 0.1.0
  * @since 0.1.0
  */
 

package/lib/authorization.js

@@ -11,11 +11,10 @@
  * 401 for known schemes (with a `WWW-Authenticate` challenge) or 403 for unrecognized schemes.
  *
  * @module lib/authorization
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import authorize from 'ergo/lib/authorization';
+ * import authorize from '@centralping/ergo/lib/authorization';
  *
  * const authorizer = authorize([{
  *   type: 'Bearer',

package/lib/body/multiparse.js

@@ -12,7 +12,6 @@
  * `Content-Disposition`, `Content-Type`, `Content-Transfer-Encoding`.
  *
  * @module lib/body/multiparse
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./multipart/headers.js
  * @requires ../../utils/iterables/buffer-split.js
@@ -21,7 +20,7 @@
  * @see {@link https://www.rfc-editor.org/rfc/rfc7578}
  *
  * @example
- * import multiparse from 'ergo/lib/body/multiparse';
+ * import multiparse from '@centralping/ergo/lib/body/multiparse';
  *
  * const parts = multiparse(rawBodyBuffer, 'boundary-string');
  * // parts => [{headers: {...}, name: 'file', filename: 'upload.txt', body: Buffer}]

package/lib/body/multipart/headers.js

@@ -11,14 +11,13 @@
  * - `content-transfer-encoding` (deprecated but present in legacy clients)
  *
  * @module lib/body/multipart/headers
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../../../utils/iterables/exec-all.js
  *
  * @see {@link https://www.rfc-editor.org/rfc/rfc7578 RFC 7578 - Returning Values from Forms: multipart/form-data}
  *
  * @example
- * import parseHeaders from 'ergo/lib/body/multipart/headers';
+ * import parseHeaders from '@centralping/ergo/lib/body/multipart/headers';
  *
  * parseHeaders(['Content-Disposition: form-data; name="field1"']);
  * // => {'content-disposition': {type: 'form-data', parameters: {name: 'field1'}}}

package/lib/body/writer.js

@@ -8,13 +8,12 @@
  * `pipeline(req, meter, decompressor, writer())`
  *
  * @module lib/body/writer
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:stream
  *
  * @example
  * import {pipeline} from 'node:stream';
- * import writer from 'ergo/lib/body/writer';
+ * import writer from '@centralping/ergo/lib/body/writer';
  *
  * const w = writer();
  * pipeline(readable, w, err => {

package/lib/cookie/cookie.js

@@ -9,11 +9,10 @@
  * immediately by defaulting `maxAge` to 0.
  *
  * @module lib/cookie/cookie
- * @version 0.1.0
  * @since 0.1.0
  *
  * @example
- * import bake from 'ergo/lib/cookie/cookie';
+ * import bake from '@centralping/ergo/lib/cookie/cookie';
  *
  * const c = bake('session', 'abc123', {maxAge: 3600, sameSite: 'Lax'});
  * c.toHeader(); // 'session=abc123; Path=/; Max-Age=3600; SameSite=Lax; Secure; HttpOnly'

package/lib/cookie/index.js

@@ -5,7 +5,6 @@
  * and `jar` for creating a cookie jar instance that manages cookie state for a request.
  *
  * @module lib/cookie
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./parse.js
  * @requires ./jar.js

package/lib/cookie/jar.js

@@ -4,7 +4,7 @@
  * Creates a cookie jar with dual-storage semantics for per-request cookie management.
  *
  * **Incoming cookies** (from the `Cookie` header) are parsed as raw `name: value` strings
- * and stored as own properties via `Object.assign()`. Per RFC 6265 §5.4, the browser sends
+ * and stored as own properties. Per RFC 6265 §5.4, the browser sends
  * only `name=value` pairs — no directives. Access them directly: `jar.session`.
  *
  * **Outgoing cookies** (created via `set()`) are full cookie objects with directives,
@@ -19,14 +19,13 @@
  * - `toHeader()` — serializes outgoing cookies to `Set-Cookie` header strings
  *
  * @module lib/cookie/jar
- * @version 0.1.0
  * @since 0.1.0
  * @requires ./cookie.js
  * @requires ../../utils/iterables/index.js
  *
  * @example
- * import jar from 'ergo/lib/cookie/jar';
- * import parse from 'ergo/lib/cookie/parse';
+ * import jar from '@centralping/ergo/lib/cookie/jar';
+ * import parse from '@centralping/ergo/lib/cookie/parse';
  *
  * const cookies = jar(parse('session=abc123; lang=en'));
  * cookies.session;     // => 'abc123' (incoming, own property)
@@ -91,16 +90,21 @@ const clay = Object.create(
 /**
  * Creates a cookie jar pre-populated from a parsed cookie object.
  *
+ * Incoming cookie names that collide with jar prototype methods or own properties
+ * (`set`, `get`, `clear`, `toHeader`, `isJar`, `size`, `jar`) are silently dropped
+ * to prevent `TypeError` from strict-mode assignment to non-writable properties.
+ *
  * @param {object} [cookies={}] - Initial cookie values (from `parse()`)
  * @returns {object} - Cookie jar with `get`, `set`, `clear`, `toHeader`, `size` members
  */
 function jar(cookies = {}) {
-  return Object.assign(
-    Object.create(clay, {
-      jar: {
-        value: new Map()
-      }
-    }),
-    cookies
-  );
+  const instance = Object.create(clay, {jar: {value: new Map()}});
+
+  for (const key of Object.keys(cookies)) {
+    if (!(key in instance)) {
+      instance[key] = cookies[key];
+    }
+  }
+
+  return instance;
 }

package/lib/cookie/parse.js

@@ -10,7 +10,6 @@
  * to protect against header-stuffing attacks.
  *
  * @module lib/cookie/parse
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../../utils/iterables/index.js
  *
@@ -18,7 +17,7 @@
  * @see {@link https://www.rfc-editor.org/rfc/rfc2109 RFC 2109 - HTTP State Management Mechanism (obsoleted)}
  *
  * @example
- * import parse from 'ergo/lib/cookie/parse';
+ * import parse from '@centralping/ergo/lib/cookie/parse';
  *
  * parse('session=abc123; user=alice');
  * // => {session: 'abc123', user: 'alice'}

package/lib/cors.js

@@ -15,13 +15,12 @@
  * @see {@link https://www.w3.org/TR/2014/REC-cors-20140116/}
  *
  * @module lib/cors
- * @version 0.1.0
  * @since 0.1.0
  * @requires ../utils/type.js
  * @requires ../utils/flat-array.js
  *
  * @example
- * import cors from 'ergo/lib/cors';
+ * import cors from '@centralping/ergo/lib/cors';
  *
  * const corsValidator = cors({
  *   origins: ['https://app.example.com'],

package/lib/csrf.js

@@ -9,13 +9,12 @@
  * can be reissued without changing the UUID.
  *
  * @module lib/csrf
- * @version 0.1.0
  * @since 0.1.0
  * @requires node:crypto
  * @requires ../utils/type.js
  *
  * @example
- * import {issue, verify} from 'ergo/lib/csrf';
+ * import {issue, verify} from '@centralping/ergo/lib/csrf';
  *
  * const {token, uuid} = issue('my-secret');
  * // token => 'base64-encoded-hmac'