@centralping/ergo 0.1.0-beta.3 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Fixed
+
+- **BREAKING (types only)**: All middleware factory `.d.ts` declarations now emit inferred
+  function signatures instead of `Function`. `compose()`/`composeWith()` return
+  `(...args) => Promise<object>` instead of `Function`. `csrf()` and `logger()` emit
+  full object types instead of `object`. No runtime behavior changes. (#75)
+
+### Added
+
+- TypeScript usage example alongside the JavaScript Quick Start in `README.md`. (#74)
+
+## [0.1.0-beta.4] - 2026-05-29
+
+### Added
+
+- JSON Schema `format` keyword support via `ajv-formats`. Standard formats (`email`, `uri`,
+  `date-time`, `uuid`, etc.) are validated by default. Opt out with `formats: false` or select
+  specific formats with an array (e.g. `formats: ['email', 'uri']`). (#58)
+
+### Fixed
+
+- **BREAKING**: `accepts()` now defaults `throwIfFail` to `true`, enforcing 406 responses for unsatisfied content negotiation per the Fast Fail pipeline contract. Set `throwIfFail: false` to restore the previous informational-only behavior. (#55)
+- `body()` default types now include `application/merge-patch+json` (RFC 7386) and `application/json-patch+json` (RFC 6902), resolving 415 rejections for valid PATCH content types that ergo-router's `strictPatch` allows. (#56)
+- `validate()` params validation now checks `acc.route.params` (ergo-router convention) with fallback to `acc.params` (standalone), fixing silent no-op validation when used with ergo-router. (#57)
+
 ## [0.1.0-beta.1] - 2026-05-20
 
 ### Changed

package/README.md

@@ -72,6 +72,40 @@ const pipeline = compose(
 createServer(handler(pipeline)).listen(3000);
 ```
 
+<details>
+<summary>TypeScript</summary>
+
+```ts
+import {createServer, type IncomingMessage, type ServerResponse} from 'node:http';
+import {compose, handler, logger, cors, authorization, body} from '@centralping/ergo';
+
+interface AuthResult {
+  authorized: boolean;
+  info?: {uid: number};
+}
+
+const pipeline = compose(
+  [logger(), 'log'],
+  [cors(), 'cors'],
+  [authorization({strategies: [{
+    type: 'Bearer' as const,
+    authorizer: (_: Record<string, string>, token: string): AuthResult =>
+      token === 'my-token' ? {authorized: true, info: {uid: 1}} : {authorized: false}
+  }]}), 'auth'],
+  [body(), 'body'],
+  (req: IncomingMessage, res: ServerResponse, acc: {auth: AuthResult['info']; body: {parsed: unknown}}) =>
+    ({response: {body: {user: acc.auth, data: acc.body.parsed}}})
+);
+
+createServer(handler(pipeline)).listen(3000);
+```
+
+> **Note:** The type annotations above represent the expected types for the accumulator
+> properties. As ergo's `.d.ts` type declarations improve, these types will be inferred
+> automatically — removing the need for explicit annotations.
+
+</details>
+
 ## Middleware Overview
 
 | Middleware | Description | Standard |
@@ -135,4 +169,4 @@ npm run format      # Prettier
 
 ## License
 
-[MIT](LICENSE) &copy; 2019-present Jason Cust
+[MIT](https://github.com/CentralPing/ergo/blob/main/LICENSE) &copy; 2019-present Jason Cust

package/http/accepts.js

@@ -5,9 +5,9 @@
  * `Accept-Charset`, and `Accept-Encoding` request headers and determine the best
  * matching content type, language, charset, and encoding for the response.
  *
- * When `throwIfFail` is true, returns `{response: {statusCode: 406, detail}}` for any
- * header that cannot be satisfied, enforcing strict content negotiation in the
- * Fast Fail pipeline.
+ * By default, returns `{response: {statusCode: 406, detail}}` for any header
+ * that cannot be satisfied, enforcing strict content negotiation in the Fast
+ * Fail pipeline. Set `throwIfFail: false` for informational-only negotiation.
  *
  * @module http/accepts
  * @since 0.1.0
@@ -37,14 +37,13 @@ const headerMap = {
  * Creates a content negotiation middleware.
  *
  * @param {object} [options] - Negotiation configuration
- * @param {boolean} [options.throwIfFail=false] - Return `{response: {statusCode: 406, detail}}` if any negotiation key is undefined
+ * @param {boolean} [options.throwIfFail=true] - Return `{response: {statusCode: 406, detail}}` if any negotiation key is undefined
  * @param {string[]} [options.types] - Acceptable media types
  * @param {string[]} [options.languages] - Acceptable languages
  * @param {string[]} [options.charsets] - Acceptable character sets
  * @param {string[]} [options.encodings] - Acceptable content encodings
- * @returns {function} - Middleware `(req) => {type, language, charset, encoding}` on success, or `{response: {statusCode: 406, detail: string}}` when `throwIfFail` is true and any negotiation value is undefined
  */
-export default ({throwIfFail = false, ...options} = {}) => {
+export default ({throwIfFail = true, ...options} = {}) => {
   const acceptor = accepts(options);
 
   return ({headers = {}} = {}) => {

package/http/authorization.js

@@ -44,7 +44,6 @@ import authorize from '../lib/authorization.js';
  *
  * @param {object} [options] - Authorization configuration
  * @param {Array<{type: string, attributes?: object, authorizer: function}>} [options.strategies=[]] - Authentication strategy definitions
- * @returns {function} - Async middleware `(req) => info` on success; on failure `{response: {statusCode: 401|403, headers?}}` with optional `WWW-Authenticate` header tuples from `authenticate`
  */
 export default ({strategies = []} = {}) => {
   const authorizer = authorize(strategies);

package/http/body.js

@@ -2,7 +2,8 @@
  * @fileoverview HTTP middleware factory for request body parsing.
  *
  * Reads and parses the request body according to the declared `Content-Type`. Supports:
- * - `application/json` and `application/vnd.api+json` — parsed via `JSON.parse`
+ * - `application/json`, `application/vnd.api+json`, `application/merge-patch+json`
+ *   (RFC 7386), and `application/json-patch+json` (RFC 6902) — parsed via `JSON.parse`
  * - `application/x-www-form-urlencoded` — parsed via the query string parser
  * - `multipart/form-data` — parsed via the RFC 7578 streaming multipart parser
  *
@@ -117,7 +118,6 @@ const decompressors = new Proxy(
  * @param {number} [options.decompressedLimit] - Maximum decompressed body size (default 10 * limit, capped at MAX_DECOMPRESSED)
  * @param {string[]} [options.types] - Allowed Content-Type MIME types
  * @param {string} [options.charset='utf-8'] - Default character encoding
- * @returns {function} - Async middleware `(req) => {type, charset, encoding, length, received, boundary, raw, parsed}` on success; on error `{response: {statusCode: 400|411|413|415, detail: string}}`. Errors without `statusCode` are rethrown.
  */
 const DEFAULT_LIMIT = 1 << 20; // 1 MiB
 const MAX_DECOMPRESSED = 10 * DEFAULT_LIMIT; // 10 MiB hard cap
@@ -128,6 +128,8 @@ export default ({
     types = [
       'application/vnd.api+json',
       'application/json',
+      'application/merge-patch+json',
+      'application/json-patch+json',
       'application/x-www-form-urlencoded',
       'multipart/form-data'
     ],

package/http/cache-control.js

@@ -43,7 +43,6 @@
  * @param {number} [options.sMaxAge] - `s-maxage` value in seconds
  * @param {number} [options.staleWhileRevalidate] - `stale-while-revalidate` value in seconds
  * @param {number} [options.staleIfError] - `stale-if-error` value in seconds
- * @returns {function} - Ergo middleware `() => Array<[string, string]>`
  */
 export default ({
   directives,

package/http/compress.js

@@ -40,7 +40,6 @@ const COMPRESSIBLE_RE = /^(text\/|application\/(json|javascript|xml|x-www-form-u
  * @param {object} [options] - Compression configuration
  * @param {number} [options.threshold=1024] - Minimum byte size before compression is applied
  * @param {string[]} [options.encodings=['br','gzip','deflate']] - Supported encodings in priority order
- * @returns {function} - Ergo middleware `(req, res) => void` that wraps `res.write`/`res.end`
  */
 export default ({threshold = 1024, encodings = ['br', 'gzip', 'deflate']} = {}) => {
   return (req, res) => {

package/http/cookie.js

@@ -31,7 +31,6 @@ import {parse, jar} from '../lib/cookie/index.js';
  * Creates a cookie parsing middleware.
  *
  * @param {object} [options] - Options forwarded to the RFC 6265 cookie parser
- * @returns {function} - Ergo middleware `({headers}) => CookieJar`
  */
 export default options =>
   ({headers: {cookie} = {}} = {}) =>

package/http/cors.js

@@ -39,8 +39,6 @@ import cors from '../lib/cors.js';
  * @param {string|string[]} [options.exposeHeaders] - Headers to expose to the client
  * @param {boolean} [options.allowCredentials=false] - Whether to allow credentials
  * @param {number} [options.maxAge] - Preflight cache duration in seconds
- * @returns {function} - Ergo middleware that returns `undefined` for non-CORS requests,
- *   `{response: {headers}}` when allowed, or `{response: {statusCode: 403}}` when denied
  */
 export default options => {
   const corsValidator = cors(options);

package/http/csrf.js

@@ -46,8 +46,6 @@ import {issue, verify} from '../lib/csrf.js';
  * @param {string} options.secret - HMAC secret for token signing
  * @param {string} [options.encoding] - Token encoding (default: base64)
  * @param {object} [options.cookieOptions={}] - Cookie directives passed to the cookie factory
- * @returns {object} - Object with `issue(req, res, ...rest)` and `verify(req, res, ...rest)` methods;
- *   `verify` returns `{response: {statusCode: 403}}` when CSRF token verification fails
  */
 export default ({
   cookieTokenName = 'CSRF-TOKEN',

package/http/handler.js

@@ -37,7 +37,6 @@ import createSend from './send.js';
  *
  * @param {function} pipeline - Composed middleware pipeline
  * @param {object} [sendOptions] - Options forwarded to `send()`
- * @returns {function} - Async handler `(req, res) => void` for `http.createServer()`
  */
 export default (pipeline, sendOptions = {}) => {
   const send = createSend(sendOptions);

package/http/idempotency.js

@@ -40,7 +40,6 @@ const DEFAULT_METHODS = new Set(['POST', 'PATCH']);
  *   on applicable methods
  * @param {Set<string>|string[]} [options.methods] - HTTP methods to apply idempotency to
  *   (default: POST, PATCH)
- * @returns {function} - Middleware `(req, res, domainAcc) => {value?, response?}`
  */
 export default function idempotency({store, ttlMs, required = false, methods} = {}) {
   const _store = store ?? new IdempotencyStore(ttlMs ? {ttlMs} : undefined);

package/http/json-api-query.js

@@ -30,8 +30,6 @@ import {validate} from '../lib/json-api-query/index.js';
  * Creates a JSON:API query validation middleware.
  *
  * @param {...*} options - Options forwarded to the underlying JSON:API validator
- * @returns {function} - Ergo middleware `(req, res, acc) => void`; returns
- *   `{response: {statusCode: 400}}` when JSON:API query parameters fail validation
  */
 export default (...options) => {
   const validator = validate(...options);

package/http/logger.js

@@ -73,7 +73,6 @@ const host = Object.freeze({
  * @param {string} [options.headerRequestIpName] - Client IP header name (default: 'x-real-ip')
  * @param {Set<string>} [options.redactHeaders] - Header names to replace with '[REDACTED]' in logs
  *   (default: authorization, proxy-authorization, cookie, set-cookie)
- * @returns {object} - Log entry with request metadata and host info (statusCode/duration added on finish)
  */
 export default ({
     /* eslint-disable-next-line no-console */

package/http/precondition.js

@@ -37,7 +37,6 @@
  * @param {string[]|Set<string>} [options.methods] - HTTP methods to enforce on.
  *   When omitted, enforces unconditionally (the pipeline builder handles method scoping).
  *   When provided, only activates for the specified methods.
- * @returns {function} - Middleware `(req) => void` that returns `{response: {statusCode: 428}}` if no conditional header is present
  */
 export default function precondition({methods} = {}) {
   const methodSet = methods ? (methods instanceof Set ? methods : new Set(methods)) : undefined;

package/http/prefer.js

@@ -28,7 +28,6 @@ import parsePrefer from '../lib/prefer.js';
 /**
  * Creates a Prefer header parsing middleware.
  *
- * @returns {function} - Middleware `(req) => object` returning parsed preferences
  */
 export default () => {
   return req => parsePrefer(req.headers?.prefer);

package/http/rate-limit.js

@@ -33,8 +33,6 @@ import {MemoryStore, checkRateLimit, defaultKeyGenerator} from '../lib/rate-limi
  * @param {number} [options.windowMs=60000] - Window size in milliseconds (default: 1 minute)
  * @param {object} [options.store] - Pluggable store (must implement `hit(key, windowMs)`)
  * @param {function} [options.keyGenerator] - `(req) => string` client identifier (default: remote IP)
- * @returns {function} - Middleware `(req) => {response}` that returns rate-limit header tuples on allowed
- *   requests and `{response: {statusCode: 429, retryAfter}}` when the limit is exceeded
  */
 export default function rateLimit({max = 100, windowMs = 60000, store, keyGenerator} = {}) {
   const _store = store ?? new MemoryStore();

package/http/security-headers.js

@@ -52,7 +52,6 @@ import buildSecurityHeaderTuples from '../lib/security-headers.js';
  * @param {string|false} [options.referrerPolicy='no-referrer'] - Referrer-Policy header
  * @param {string|false} [options.xXssProtection='0'] - X-XSS-Protection header (0 disables the browser filter)
  * @param {string} [options.permissionsPolicy] - Permissions-Policy header (omitted by default)
- * @returns {function} - Ergo middleware `() => Array<[string, string]>`
  */
 export default (options = {}) => {
   const headerTuples = buildSecurityHeaderTuples(options);

package/http/send.js

@@ -108,7 +108,6 @@ function bodyType(body) {
  * @param {boolean|function} [options.envelope=false] - Wrap 2xx Object bodies in a response
  *   envelope. `false` (default) — no envelope. `true` — built-in format `{id, status, data,
  *   count?}`. `function(body, ctx)` — custom envelope.
- * @returns {function} - `(req, res, responseAcc, domainAcc) => void`
  */
 export default ({
   prettify = false,

package/http/timeout.js

@@ -29,7 +29,6 @@
  * @param {object} [options] - Timeout configuration
  * @param {number} [options.ms=30000] - Timeout in milliseconds
  * @param {number} [options.statusCode=408] - HTTP status code on timeout (408 or 504)
- * @returns {function} - Ergo middleware `(req, res, domainAcc, responseAcc) => void`
  */
 export default ({ms = 30000, statusCode = 408} = {}) => {
   return (req, res, domainAcc, responseAcc) => {

package/http/url.js

@@ -26,8 +26,6 @@ import queryParse from '../lib/query.js';
 
 /**
  * Creates a URL parsing middleware.
- *
- * @returns {function} - Ergo middleware `({url}) => {query, pathname, search}`
  */
 export default () =>
   ({url} = {}) => {

package/http/validate.js

@@ -1,8 +1,10 @@
 /**
  * @fileoverview HTTP middleware factory for JSON Schema validation.
  *
- * Validates properties from the accumulator (body, url, params) against provided JSON
- * Schemas using AJV. Schemas are compiled once at middleware creation time for performance.
+ * Validates properties from the accumulator (body, url, route params) against provided
+ * JSON Schemas using AJV. Schemas are compiled once at middleware creation time for
+ * performance. Route params are resolved from `acc.route.params` (ergo-router) with
+ * fallback to `acc.params` (standalone).
  *
  * Returns `{response: {statusCode: 422, detail: ...}}` with structured error details on validation failure.
  * Must be placed after `body()` and/or `url()` in the pipeline so accumulator values
@@ -39,10 +41,10 @@ import createValidator from '../lib/validate.js';
  * @param {object} [schemas] - Schema map; each key corresponds to an accumulator property
  * @param {object} [schemas.body] - JSON Schema for the parsed request body
  * @param {object} [schemas.query] - JSON Schema for parsed query parameters
- * @param {object} [schemas.params] - JSON Schema for route path parameters
+ * @param {object} [schemas.params] - JSON Schema for route path parameters (reads `acc.route.params` or `acc.params`)
  * @param {object} [options] - AJV options forwarded to each compiled validator
- * @returns {function} - Ergo middleware `(req, res, acc) => void` that returns `{response: {statusCode: 422}}`
- *   (with `detail` and `details` from AJV) on validation failure
+ * @param {boolean|Array<string>|object} [options.formats] - Format keyword support via
+ *   `ajv-formats`; forwarded to `createValidator`. Defaults to all standard formats enabled
  */
 export default (schemas = {}, options = {}) => {
   const validators = {};
@@ -67,8 +69,8 @@ export default (schemas = {}, options = {}) => {
         validators.query(acc.url.query);
       }
 
-      if (validators.params && acc.params) {
-        validators.params(acc.params);
+      if (validators.params && (acc.route?.params ?? acc.params)) {
+        validators.params(acc.route?.params ?? acc.params);
       }
     } catch (err) {
       return {

package/lib/accepts.js

@@ -31,7 +31,6 @@ import flatArray from '../utils/flat-array.js';
  * @param {string|string[]} [options.languages] - Acceptable languages
  * @param {string|string[]} [options.charsets] - Acceptable charsets
  * @param {string|string[]} [options.encodings] - Acceptable encodings
- * @returns {function} - `(headers) => {type, language, charset, encoding}`
  */
 export default ({types, languages, charsets, encodings} = {}) =>
   (headers = {}) => {

package/lib/authorization.js

@@ -38,7 +38,6 @@ import sanitizeQuotedString from './sanitize-quoted-string.js';
  * Creates an authorization dispatcher for the given strategy list.
  *
  * @param {Array<{type: string, attributes?: object, authorizer: function}>} strategies - Authentication strategy definitions
- * @returns {function} - Async `(authorization) => {authorized, info}`
  */
 export default (strategies = []) => {
   const dispatcher = createDispatcher(strategies);

package/lib/cors.js

@@ -56,7 +56,6 @@ const defaultMethods = ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PU
  * @param {string|RegExp|function|Array} [options.allowHeaders='*'] - Allowed request headers
  * @param {string|string[]} [options.exposeHeaders] - Headers to expose to the client
  * @param {number} [options.maxAge] - Pre-flight cache duration in seconds
- * @returns {function} - `({origin, method, requestMethod, requestHeaders}) => {allowed, info}`
  */
 export default ({
   origins = '*', // '*', 'foo.com', /foo/, ['foo', /bar/]
@@ -131,7 +130,6 @@ export default ({
  *
  * @param {string|RegExp|function|Array<string|RegExp>} valid - Origin policy
  * @param {boolean} [allowCreds] - If true, wildcard reflects the request origin
- * @returns {function} - `(origin: string) => string|false` — returns the allowed origin or false
  */
 function configOriginValidator(valid, allowCreds) {
   if (valid === '*') {
@@ -151,7 +149,6 @@ function configOriginValidator(valid, allowCreds) {
  * Builds a request header validator function from an allowed-headers policy.
  *
  * @param {string|RegExp|function|Array<string|RegExp>} allowed - Header policy
- * @returns {function} - `(headers: string[]) => string[]` — returns filtered allowed headers
  */
 function configHeaderValidator(allowed) {
   if (allowed === '*') {

package/lib/from-connect.js

@@ -42,7 +42,6 @@
  * Wrap a Connect/Express-style middleware for use in an ergo pipeline.
  *
  * @param {function} middleware - Connect middleware `(req, res, next) => void`
- * @returns {function} - Ergo-compatible middleware `(req, res) => Promise<undefined>`
  */
 export default function fromConnect(middleware) {
   return (req, res) =>

package/lib/json-api-query/validate.js

@@ -39,7 +39,6 @@ import defaultSchema from './schema.json' with {type: 'json'};
  * @param {boolean|string} [options.coerceTypes='array'] - Coerce validated values to specified types.
  * @param {boolean} [options.ownProperties=true] - Restrict validation to own properties of data object.
  * @param {object} [schema] - JSON Schema 2020-12. Defaults to the included schema.
- * @returns {function} - The configured validator function.
  */
 export default (
   {coerceTypes = 'array', ownProperties = true, ...ajvOptions} = {},

package/lib/validate.js

@@ -10,6 +10,7 @@
  * @module lib/validate
  * @since 0.1.0
  * @requires ajv
+ * @requires ajv-formats
  * @requires ../utils/http-errors.js
  *
  * @example
@@ -25,6 +26,7 @@
  * validate({});                    // throws 422 with details
  */
 import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
 import httpErrors from '../utils/http-errors.js';
 
 /**
@@ -34,8 +36,12 @@ import httpErrors from '../utils/http-errors.js';
  * @param {object} [options] - Validator options
  * @param {boolean} [options.allErrors=true] - Report all errors instead of stopping at the first
  * @param {boolean} [options.coerceTypes=false] - Coerce input values to match schema types
+ * @param {boolean|Array<string>|object} [options.formats] - Format keyword support via
+ *   `ajv-formats`. `undefined` or `true` enables all standard formats; `false` disables (AJV
+ *   strict mode rejects unknown formats); an array enables selective formats
+ *   (e.g. `['email', 'uri']`); an object is passed as the full plugin config
+ *   (e.g. `{mode: 'fast'}`)
  * @param {object} [options.ajv] - Additional AJV constructor options
- * @returns {function} - `validateData(data)` — returns `data` on success, throws 422 on failure
  * @throws {Error} 422 with `details` array if schema validation fails
  */
 export default function createValidator(schema, options = {}) {
@@ -45,6 +51,13 @@ export default function createValidator(schema, options = {}) {
     ...options.ajv
   });
 
+  if (options.formats !== false) {
+    addFormats(
+      ajv,
+      options.formats === true || options.formats === undefined ? undefined : options.formats
+    );
+  }
+
   const validate = ajv.compile(schema);
 
   return function validateData(data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centralping/ergo",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0",
   "description": "A Fast Fail REST API toolkit for Node.js -- composable middleware with structured Negotiation, Authorization, Validation, and Execution stages.",
   "main": "http/index.js",
   "type": "module",
@@ -116,6 +116,7 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "content-type": "^2.0.0",
     "etag": "^1.8.1",
     "negotiator": "^1.0.0"

package/types/http/accepts.d.ts

@@ -4,5 +4,17 @@ declare function _default({ throwIfFail, ...options }?: {
     languages?: string[] | undefined;
     charsets?: string[] | undefined;
     encodings?: string[] | undefined;
-}): Function;
+}): ({ headers }?: {
+    headers?: {} | undefined;
+}) => {
+    type: any;
+    language: any;
+    charset: any;
+    encoding: any;
+} | {
+    response: {
+        statusCode: number;
+        detail: string;
+    };
+};
 export default _default;

package/types/http/authorization.d.ts

@@ -4,5 +4,9 @@ declare function _default({ strategies }?: {
         attributes?: object;
         authorizer: Function;
     }[] | undefined;
-}): Function;
+}): ({ headers: { authorization } }?: {
+    headers?: {
+        authorization?: string | undefined;
+    } | undefined;
+}) => Promise<any>;
 export default _default;

package/types/http/cache-control.d.ts

@@ -12,5 +12,9 @@ declare function _default({ directives, public: isPublic, private: isPrivate, no
     sMaxAge?: number | undefined;
     staleWhileRevalidate?: number | undefined;
     staleIfError?: number | undefined;
-}): Function;
+}): () => {
+    response: {
+        headers: string[][];
+    };
+};
 export default _default;

package/types/http/compress.d.ts

@@ -1,5 +1,5 @@
 declare function _default({ threshold, encodings }?: {
     threshold?: number | undefined;
     encodings?: string[] | undefined;
-}): Function;
+}): (req: any, res: any) => void;
 export default _default;

package/types/http/cookie.d.ts

@@ -1,2 +1,4 @@
-declare function _default(options?: object): Function;
+declare function _default(options?: object): ({ headers: { cookie } }?: {
+    headers?: {} | undefined;
+}) => object;
 export default _default;

package/types/http/cors.d.ts

@@ -5,5 +5,17 @@ declare function _default(options?: {
     exposeHeaders?: string | string[] | undefined;
     allowCredentials?: boolean | undefined;
     maxAge?: number | undefined;
-}): Function;
+}): ({ headers: { origin, "access-control-request-method": requestMethod, "access-control-request-headers": requestHeadersRaw }, method }?: {
+    headers?: {} | undefined;
+}) => {
+    response: {
+        statusCode: number;
+        headers?: undefined;
+    };
+} | {
+    response: {
+        headers: any[][];
+        statusCode?: undefined;
+    };
+} | undefined;
 export default _default;

package/types/http/csrf.d.ts

@@ -5,5 +5,15 @@ declare function _default({ cookieTokenName, headerTokenName, cookieUuidName, se
     secret: string;
     encoding?: string | undefined;
     cookieOptions?: object | undefined;
-}): object;
+}): {
+    issue(req: any, res: any, acc: any): void;
+    verify({ headers: { [headerTokenName.toLowerCase()]: headerToken } }: {
+        headers?: {} | undefined;
+    } | undefined, res: any, acc: any): {
+        response: {
+            statusCode: number;
+            detail: string;
+        };
+    } | undefined;
+};
 export default _default;

package/types/http/handler.d.ts

@@ -1,2 +1,2 @@
-declare function _default(pipeline: Function, sendOptions?: object): Function;
+declare function _default(pipeline: Function, sendOptions?: object): (req: any, res: any) => Promise<void>;
 export default _default;

package/types/http/idempotency.d.ts

@@ -10,11 +10,37 @@
  *   on applicable methods
  * @param {Set<string>|string[]} [options.methods] - HTTP methods to apply idempotency to
  *   (default: POST, PATCH)
- * @returns {function} - Middleware `(req, res, domainAcc) => {value?, response?}`
  */
 export default function idempotency({ store, ttlMs, required, methods }?: {
     store?: object | undefined;
     ttlMs?: number | undefined;
     required?: boolean | undefined;
     methods?: string[] | Set<string> | undefined;
-}): Function;
+}): (req: any, _res: any, domainAcc: any) => {
+    response?: undefined;
+    value?: undefined;
+} | {
+    response: {
+        statusCode: number;
+        detail: string;
+    };
+    value?: undefined;
+} | {
+    value: {
+        replayed: boolean;
+        key?: undefined;
+        fingerprint?: undefined;
+        complete?: undefined;
+        discard?: undefined;
+    };
+    response: any;
+} | {
+    value: {
+        key: string;
+        fingerprint: string;
+        complete: (response: any) => any;
+        discard: () => any;
+        replayed?: undefined;
+    };
+    response?: undefined;
+};

package/types/http/json-api-query.d.ts

@@ -1,2 +1,7 @@
-declare function _default(...options: any[]): Function;
+declare function _default(...options: any[]): (req: any, res: any, acc: any) => {
+    response: {
+        statusCode: number;
+        detail: string;
+    };
+} | undefined;
 export default _default;

package/types/http/logger.d.ts

@@ -5,5 +5,24 @@ declare function _default({ log, error: logError, uuid, headerRequestIdName, hea
     headerRequestIdName?: string | undefined;
     headerRequestIpName?: string | undefined;
     redactHeaders?: Set<string> | undefined;
-}): object;
+}): (req: any, res: any) => {
+    requestId: any;
+    timestamp: number;
+    ip: any;
+    method: any;
+    url: any;
+    httpVersion: any;
+    host: Readonly<{
+        hostname: any;
+        arch: any;
+        platform: any;
+        pid: any;
+    }>;
+    request: {
+        headers: object;
+        encrypted: any;
+        remoteAddress: any;
+        remotePort: any;
+    };
+};
 export default _default;

package/types/http/main.d.ts

@@ -1,23 +1,39 @@
 declare const _default: {
     compose: {
-        (...ops: (Function | any[])[]): Function;
-        all(...ops: (Function | any[])[]): Function;
+        (...ops: (Function | any[])[]): (...args: any[]) => Promise<object>;
+        all(...ops: (Function | any[])[]): (...args: any[]) => Promise<object>;
     };
-    handler: (pipeline: Function, sendOptions?: object) => Function;
+    handler: (pipeline: Function, sendOptions?: object) => (req: any, res: any) => Promise<void>;
     accepts: ({ throwIfFail, ...options }?: {
         throwIfFail?: boolean | undefined;
         types?: string[] | undefined;
         languages?: string[] | undefined;
         charsets?: string[] | undefined;
         encodings?: string[] | undefined;
-    }) => Function;
+    }) => ({ headers }?: {
+        headers?: {} | undefined;
+    }) => {
+        type: any;
+        language: any;
+        charset: any;
+        encoding: any;
+    } | {
+        response: {
+            statusCode: number;
+            detail: string;
+        };
+    };
     authorization: ({ strategies }?: {
         strategies?: {
             type: string;
             attributes?: object;
             authorizer: Function;
         }[] | undefined;
-    }) => Function;
+    }) => ({ headers: { authorization } }?: {
+        headers?: {
+            authorization?: string | undefined;
+        } | undefined;
+    }) => Promise<any>;
     body: ({ limit, decompressedLimit, types, charset }?: {
         limit?: number | undefined;
         decompressedLimit?: number | undefined;
@@ -51,12 +67,18 @@ declare const _default: {
         sMaxAge?: number | undefined;
         staleWhileRevalidate?: number | undefined;
         staleIfError?: number | undefined;
-    }) => Function;
+    }) => () => {
+        response: {
+            headers: string[][];
+        };
+    };
     compress: ({ threshold, encodings }?: {
         threshold?: number | undefined;
         encodings?: string[] | undefined;
-    }) => Function;
-    cookie: (options?: object) => Function;
+    }) => (req: any, res: any) => void;
+    cookie: (options?: object) => ({ headers: { cookie } }?: {
+        headers?: {} | undefined;
+    }) => object;
     cors: (options?: {
         origins?: string | Function | RegExp | string[] | undefined;
         allowMethods?: string[] | undefined;
@@ -64,7 +86,19 @@ declare const _default: {
         exposeHeaders?: string | string[] | undefined;
         allowCredentials?: boolean | undefined;
         maxAge?: number | undefined;
-    }) => Function;
+    }) => ({ headers: { origin, "access-control-request-method": requestMethod, "access-control-request-headers": requestHeadersRaw }, method }?: {
+        headers?: {} | undefined;
+    }) => {
+        response: {
+            statusCode: number;
+            headers?: undefined;
+        };
+    } | {
+        response: {
+            headers: any[][];
+            statusCode?: undefined;
+        };
+    } | undefined;
     csrf: ({ cookieTokenName, headerTokenName, cookieUuidName, secret, encoding, cookieOptions }?: {
         cookieTokenName?: string | undefined;
         headerTokenName?: string | undefined;
@@ -72,11 +106,26 @@ declare const _default: {
         secret: string;
         encoding?: string | undefined;
         cookieOptions?: object | undefined;
-    }) => object;
+    }) => {
+        issue(req: any, res: any, acc: any): void;
+        verify({ headers: { [headerTokenName.toLowerCase()]: headerToken } }: {
+            headers?: {} | undefined;
+        } | undefined, res: any, acc: any): {
+            response: {
+                statusCode: number;
+                detail: string;
+            };
+        } | undefined;
+    };
     fromConnect: typeof fromConnect;
     httpErrors: typeof httpErrors;
     idempotency: typeof idempotency;
-    jsonApiQuery: (...options: any[]) => Function;
+    jsonApiQuery: (...options: any[]) => (req: any, res: any, acc: any) => {
+        response: {
+            statusCode: number;
+            detail: string;
+        };
+    } | undefined;
     logger: ({ log, error: logError, uuid, headerRequestIdName, headerRequestIpName, redactHeaders }?: {
         log?: Function | undefined;
         error?: Function | undefined;
@@ -84,8 +133,27 @@ declare const _default: {
         headerRequestIdName?: string | undefined;
         headerRequestIpName?: string | undefined;
         redactHeaders?: Set<string> | undefined;
-    }) => object;
-    prefer: () => Function;
+    }) => (req: any, res: any) => {
+        requestId: any;
+        timestamp: number;
+        ip: any;
+        method: any;
+        url: any;
+        httpVersion: any;
+        host: Readonly<{
+            hostname: any;
+            arch: any;
+            platform: any;
+            pid: any;
+        }>;
+        request: {
+            headers: object;
+            encrypted: any;
+            remoteAddress: any;
+            remotePort: any;
+        };
+    };
+    prefer: () => (req: any) => object;
     precondition: typeof precondition;
     rateLimit: typeof rateLimit;
     securityHeaders: (options?: {
@@ -96,24 +164,44 @@ declare const _default: {
         referrerPolicy?: string | false | undefined;
         xXssProtection?: string | false | undefined;
         permissionsPolicy?: string | undefined;
-    }) => Function;
-    url: () => Function;
+    }) => () => {
+        response: {
+            headers: [string, string][];
+        };
+    };
+    url: () => ({ url }?: {}) => {
+        query: any;
+        pathname: any;
+        search: undefined;
+    } | {
+        query: object;
+        pathname: any;
+        search: any;
+    };
     send: ({ prettify, vary, etag, prefer, envelope }?: {
         prettify?: boolean | undefined;
         vary?: string[] | undefined;
         etag?: boolean | undefined;
         prefer?: boolean | undefined;
         envelope?: boolean | Function | undefined;
-    }) => Function;
+    }) => (req: any, res: any, responseAcc: any, domainAcc?: {}) => void;
     timeout: ({ ms, statusCode }?: {
         ms?: number | undefined;
         statusCode?: number | undefined;
-    }) => Function;
+    }) => (req: any, res: any, domainAcc: any, responseAcc: any) => void;
     validate: (schemas?: {
         body?: object | undefined;
         query?: object | undefined;
         params?: object | undefined;
-    }, options?: object) => Function;
+    }, options?: {
+        formats?: boolean | object | string[] | undefined;
+    }) => (req: any, res: any, acc: any) => {
+        response: {
+            statusCode: any;
+            detail: any;
+            details: any;
+        };
+    } | undefined;
 };
 export default _default;
 import compose from '../utils/compose-with.js';

package/types/http/precondition.d.ts

@@ -36,8 +36,11 @@
  * @param {string[]|Set<string>} [options.methods] - HTTP methods to enforce on.
  *   When omitted, enforces unconditionally (the pipeline builder handles method scoping).
  *   When provided, only activates for the specified methods.
- * @returns {function} - Middleware `(req) => void` that returns `{response: {statusCode: 428}}` if no conditional header is present
  */
 export default function precondition({ methods }?: {
     methods?: string[] | Set<string> | undefined;
-}): Function;
+}): (req: any) => {
+    response: {
+        statusCode: number;
+    };
+} | undefined;

package/types/http/prefer.d.ts

@@ -1,2 +1,2 @@
-declare function _default(): Function;
+declare function _default(): (req: any) => object;
 export default _default;

package/types/http/rate-limit.d.ts

@@ -6,12 +6,22 @@
  * @param {number} [options.windowMs=60000] - Window size in milliseconds (default: 1 minute)
  * @param {object} [options.store] - Pluggable store (must implement `hit(key, windowMs)`)
  * @param {function} [options.keyGenerator] - `(req) => string` client identifier (default: remote IP)
- * @returns {function} - Middleware `(req) => {response}` that returns rate-limit header tuples on allowed
- *   requests and `{response: {statusCode: 429, retryAfter}}` when the limit is exceeded
  */
 export default function rateLimit({ max, windowMs, store, keyGenerator }?: {
     max?: number | undefined;
     windowMs?: number | undefined;
     store?: object | undefined;
     keyGenerator?: Function | undefined;
-}): Function;
+}): (req: any) => {
+    response: {
+        statusCode: number;
+        retryAfter: number | undefined;
+        headers?: undefined;
+    };
+} | {
+    response: {
+        headers: string[][];
+        statusCode?: undefined;
+        retryAfter?: undefined;
+    };
+};

package/types/http/security-headers.d.ts

@@ -6,5 +6,9 @@ declare function _default(options?: {
     referrerPolicy?: string | false | undefined;
     xXssProtection?: string | false | undefined;
     permissionsPolicy?: string | undefined;
-}): Function;
+}): () => {
+    response: {
+        headers: [string, string][];
+    };
+};
 export default _default;

package/types/http/send.d.ts

@@ -4,5 +4,5 @@ declare function _default({ prettify, vary, etag, prefer, envelope }?: {
     etag?: boolean | undefined;
     prefer?: boolean | undefined;
     envelope?: boolean | Function | undefined;
-}): Function;
+}): (req: any, res: any, responseAcc: any, domainAcc?: {}) => void;
 export default _default;

package/types/http/timeout.d.ts

@@ -1,5 +1,5 @@
 declare function _default({ ms, statusCode }?: {
     ms?: number | undefined;
     statusCode?: number | undefined;
-}): Function;
+}): (req: any, res: any, domainAcc: any, responseAcc: any) => void;
 export default _default;

package/types/http/url.d.ts

@@ -1,2 +1,10 @@
-declare function _default(): Function;
+declare function _default(): ({ url }?: {}) => {
+    query: any;
+    pathname: any;
+    search: undefined;
+} | {
+    query: object;
+    pathname: any;
+    search: any;
+};
 export default _default;

package/types/http/validate.d.ts

@@ -2,5 +2,13 @@ declare function _default(schemas?: {
     body?: object | undefined;
     query?: object | undefined;
     params?: object | undefined;
-}, options?: object): Function;
+}, options?: {
+    formats?: boolean | object | string[] | undefined;
+}): (req: any, res: any, acc: any) => {
+    response: {
+        statusCode: any;
+        detail: any;
+        details: any;
+    };
+} | undefined;
 export default _default;

package/types/lib/accepts.d.ts

@@ -3,5 +3,10 @@ declare function _default({ types, languages, charsets, encodings }?: {
     languages?: string | string[] | undefined;
     charsets?: string | string[] | undefined;
     encodings?: string | string[] | undefined;
-}): Function;
+}): (headers?: {}) => {
+    type: any;
+    language: any;
+    charset: any;
+    encoding: any;
+};
 export default _default;

package/types/lib/authorization.d.ts

@@ -2,5 +2,5 @@ declare function _default(strategies?: Array<{
     type: string;
     attributes?: object;
     authorizer: Function;
-}>): Function;
+}>): (authorization?: string) => Promise<any>;
 export default _default;

package/types/lib/cors.d.ts

@@ -5,5 +5,29 @@ declare function _default({ origins, allowMethods, allowCredentials, allowHeader
     allowHeaders?: string | Function | RegExp | any[] | undefined;
     exposeHeaders?: string | string[] | undefined;
     maxAge?: number | undefined;
-}): Function;
+}): ({ origin, method, requestMethod, requestHeaders }?: {}) => {
+    allowed: boolean;
+    info: {
+        type: string;
+        origin: any;
+        method?: undefined;
+        headers?: undefined;
+    };
+} | {
+    allowed: boolean;
+    info: {
+        type: string;
+        origin: any;
+        method: any;
+        headers?: undefined;
+    };
+} | {
+    allowed: boolean;
+    info: {
+        origin: any;
+        headers: any[];
+        type?: undefined;
+        method?: undefined;
+    };
+};
 export default _default;

package/types/lib/from-connect.d.ts

@@ -41,6 +41,5 @@
  * Wrap a Connect/Express-style middleware for use in an ergo pipeline.
  *
  * @param {function} middleware - Connect middleware `(req, res, next) => void`
- * @returns {function} - Ergo-compatible middleware `(req, res) => Promise<undefined>`
  */
-export default function fromConnect(middleware: Function): Function;
+export default function fromConnect(middleware: Function): (req: any, res: any) => Promise<any>;

package/types/lib/json-api-query/validate.d.ts

@@ -1,5 +1,5 @@
 declare function _default({ coerceTypes, ownProperties, ...ajvOptions }?: {
     coerceTypes?: string | boolean | undefined;
     ownProperties?: boolean | undefined;
-}, schema?: object): Function;
+}, schema?: object): any;
 export default _default;

package/types/lib/validate.d.ts

@@ -5,12 +5,17 @@
  * @param {object} [options] - Validator options
  * @param {boolean} [options.allErrors=true] - Report all errors instead of stopping at the first
  * @param {boolean} [options.coerceTypes=false] - Coerce input values to match schema types
+ * @param {boolean|Array<string>|object} [options.formats] - Format keyword support via
+ *   `ajv-formats`. `undefined` or `true` enables all standard formats; `false` disables (AJV
+ *   strict mode rejects unknown formats); an array enables selective formats
+ *   (e.g. `['email', 'uri']`); an object is passed as the full plugin config
+ *   (e.g. `{mode: 'fast'}`)
  * @param {object} [options.ajv] - Additional AJV constructor options
- * @returns {function} - `validateData(data)` — returns `data` on success, throws 422 on failure
  * @throws {Error} 422 with `details` array if schema validation fails
  */
 export default function createValidator(schema: object, options?: {
     allErrors?: boolean | undefined;
     coerceTypes?: boolean | undefined;
+    formats?: boolean | object | string[] | undefined;
     ajv?: object | undefined;
-}): Function;
+}): (data: any) => any;

package/types/utils/attempt.d.ts

@@ -1,2 +1,2 @@
-declare function _default(fn: Function, fail: Function): Function;
+declare function _default(fn: Function, fail: Function): (...args: any[]) => Promise<any>;
 export default _default;

package/types/utils/compose-with.d.ts

@@ -26,15 +26,13 @@ export default composeWith;
  * If either is absent, a fresh one is created.
  *
  * @param {...(function|Array)} ops - Operation specs; each is a function or `[fn, setPath]`
- * @returns {function} - Async composed pipeline
  */
-declare function composeWith(...ops: (Function | any[])[]): Function;
+declare function composeWith(...ops: (Function | any[])[]): (...args: any[]) => Promise<object>;
 declare namespace composeWith {
     /**
      * Concurrent variant of composeWith.
      *
      * @param {...(function|Array)} ops - Operation specs
-     * @returns {function} - Async composed pipeline
      */
-    function all(...ops: (Function | any[])[]): Function;
+    function all(...ops: (Function | any[])[]): (...args: any[]) => Promise<object>;
 }

package/types/utils/compose.d.ts

@@ -45,20 +45,18 @@ export default compose;
  * Composes middleware functions into an async pipeline with result accumulation.
  *
  * @param {...function} fns - Middleware functions to compose
- * @returns {function} - Async composed pipeline
  */
-declare function compose(...fns: Function[]): Function;
+declare function compose(...fns: Function[]): (...args: any[]) => Promise<any>;
 declare namespace compose {
-    function all(...fns: any[]): Function;
+    function all(...fns: any[]): (...args: any[]) => Promise<any>;
     namespace all {
         /**
          * Creates a concurrent pipeline with configuration options.
          *
          * @param {object} options - Pipeline options
          * @param {...function} fns - Middleware functions to compose
-         * @returns {function} - Async composed pipeline
          */
-        function withOptions(options: object, ...fns: Function[]): Function;
+        function withOptions(options: object, ...fns: Function[]): (...args: any[]) => Promise<any>;
     }
     /**
      * Creates a sequential pipeline with configuration options.
@@ -67,11 +65,10 @@ declare namespace compose {
      * @param {function} [options.breakWhen] - Predicate `(acc) => boolean`; when truthy,
      *   serial iteration stops after the current step's result is merged
      * @param {...function} fns - Middleware functions to compose
-     * @returns {function} - Async composed pipeline
      */
     function withOptions(options: {
         breakWhen?: Function | undefined;
-    }, ...fns: Function[]): Function;
+    }, ...fns: Function[]): (...args: any[]) => Promise<any>;
 }
 /**
  * Creates a null-prototype accumulator object.

package/utils/attempt.js

@@ -23,7 +23,6 @@
 /**
  * @param {function} fn - Primary async function to execute
  * @param {function} fail - Error handler called with (...originalArgs, error)
- * @returns {function} - Wrapped async function with try/catch behavior
  */
 export default (fn, fail) => {
   return async (...args) => {

package/utils/compose-with.js

@@ -198,7 +198,6 @@ async function concurrent(descriptors, args, domainAcc, responseAcc) {
  * If either is absent, a fresh one is created.
  *
  * @param {...(function|Array)} ops - Operation specs; each is a function or `[fn, setPath]`
- * @returns {function} - Async composed pipeline
  */
 const composeWith = (...ops) => {
   const descriptors = ops.map(normalizeOp);
@@ -215,7 +214,6 @@ const composeWith = (...ops) => {
  * Concurrent variant of composeWith.
  *
  * @param {...(function|Array)} ops - Operation specs
- * @returns {function} - Async composed pipeline
  */
 composeWith.all = (...ops) => {
   const descriptors = ops.map(normalizeOp);

package/utils/compose.js

@@ -44,7 +44,6 @@
  * Composes middleware functions into an async pipeline with result accumulation.
  *
  * @param {...function} fns - Middleware functions to compose
- * @returns {function} - Async composed pipeline
  */
 const compose = (...fns) => setup(serial, fns);
 compose.all = (...fns) => setup(concurrent, fns);
@@ -56,7 +55,6 @@ compose.all = (...fns) => setup(concurrent, fns);
  * @param {function} [options.breakWhen] - Predicate `(acc) => boolean`; when truthy,
  *   serial iteration stops after the current step's result is merged
  * @param {...function} fns - Middleware functions to compose
- * @returns {function} - Async composed pipeline
  */
 compose.withOptions = (options, ...fns) => setup(serial, fns, options);
 
@@ -65,7 +63,6 @@ compose.withOptions = (options, ...fns) => setup(serial, fns, options);
  *
  * @param {object} options - Pipeline options
  * @param {...function} fns - Middleware functions to compose
- * @returns {function} - Async composed pipeline
  */
 compose.all.withOptions = (options, ...fns) => setup(concurrent, fns, options);
 
@@ -132,7 +129,6 @@ async function concurrent(fns, args, acc, _options) {
  * @param {function} processor - `serial` or `concurrent`
  * @param {function[]} fns - Middleware functions
  * @param {object} [options] - Pipeline options forwarded to the processor
- * @returns {function} - Async composed function `(...args) => Accumulator`
  */
 function setup(processor, fns, options = {}) {
   return async (...args) => {