lumen-framework 3.1.1 → 4.0.0

package/dist/types/packages/serializer/interfaces.d.ts

@@ -1,7 +1,25 @@
 import type Serializer from './index';
 import type { Model, ModelClass } from '../database';
-export type Serializer$opts<T extends Model> = {
+/**
+ * What Lumen constructs a serializer with when the app boots. Apps don't
+ * construct serializers themselves.
+ */
+export type SerializerOptions<T extends Model> = {
+    /** The model of the serializer's type. */
     model: ModelClass<T>;
+    /** The namespace's `application` serializer, if there is one. */
     parent: Serializer<Model> | null;
+    /** The serializer's namespace (`admin`), or `''` for the root. */
     namespace: string;
 };
+/**
+ * The request's sparse fieldsets: field (attribute and relationship) names
+ * keyed by resource type (`fields[users]=name,posts` →
+ * `{ users: ['name', 'posts'] }`). An empty list selects no fields.
+ */
+export type SerializerFields = Record<string, Array<string>>;
+/**
+ * Whether the application serves `GET` at a route key path
+ * (`/posts/:dynamic/relationships/user`).
+ */
+export type SerializerRouted = (path: string) => boolean;

package/dist/types/packages/serializer/utils/include-tree.d.ts

@@ -4,7 +4,7 @@ import type Serializer from '../index';
  * A parsed `include` parameter: each relationship name maps to the tree of
  * relationships to include from the records it points to.
  *
- * @private
+ * @internal
  */
 export type IncludeTree = Map<string, IncludeTree>;
 /**
@@ -13,7 +13,7 @@ export type IncludeTree = Map<string, IncludeTree>;
  * requires the intermediate resources of a multi-part path to be included
  * along with its leaves (`comments.user` includes the comments too).
  *
- * @private
+ * @internal
  */
 export declare function createIncludeTree(paths?: Array<string>): IncludeTree;
 /**
@@ -24,6 +24,15 @@ export declare function createIncludeTree(paths?: Array<string>): IncludeTree;
  * fallback to the root). Used to build the allowed values of the `include`
  * parameter.
  *
- * @private
+ * @internal
  */
 export declare function enumerateIncludePaths(model: ModelClass, names: Array<string>, depth: number, serializerFor?: (model: ModelClass) => Serializer<Model> | undefined): Array<string>;
+/**
+ * Every resource type a response can contain, with the Serializer each is
+ * serialized by: `model` itself (`serializer`), and every type reachable
+ * through `include` from it down to `depth` levels — direct relationships
+ * always, as with `include`. Used to build the allowed `fields[TYPE]`.
+ *
+ * @internal
+ */
+export declare function enumerateIncludeTypes(model: ModelClass, serializer: Serializer<Model>, depth: number, serializerFor?: (model: ModelClass) => Serializer<Model> | undefined): Map<string, Serializer<Model>>;

package/dist/types/packages/serializer/utils/load-linkage.d.ts

@@ -1,10 +1,11 @@
+import { Scope } from '../../controller/visibility';
 import type { Model, ModelClass } from '../../database';
 /**
  * The resource linkage of one record: the primary key(s) of the records each
  * named relationship points to — an array for has-many, otherwise a single id
  * or `null`.
  *
- * @private
+ * @internal
  */
 export type Linkage = Record<string, Array<string> | string | null>;
 /**
@@ -17,6 +18,11 @@ export type Linkage = Record<string, Array<string> | string | null>;
  * many records there are. The queries mirror the lazy relationship getters in
  * `database/relationship/utils/getters.ts`, which remain the source of truth.
  *
- * @private
+ * `scope` hides related records from the linkage: has-one and has-many queries
+ * are narrowed by it directly; belongs-to and has-many-through linkage — read
+ * from foreign keys, not from the related table — is checked against it
+ * afterwards (`dropHidden()`).
+ *
+ * @internal
  */
-export default function loadLinkage(model: ModelClass, records: Array<Model>, names: Array<string>): Promise<Map<string, Linkage>>;
+export default function loadLinkage(model: ModelClass, records: Array<Model>, names: Array<string>, scope?: Scope): Promise<Map<string, Linkage>>;

package/dist/types/packages/server/errors/error-list.d.ts

@@ -0,0 +1,25 @@
+import type { ServerError } from '../interfaces';
+/**
+ * Several problems with one request, reported together: each becomes its own
+ * error object in the response's `errors`.
+ *
+ * @internal
+ */
+declare class ErrorList extends Error implements ServerError {
+    errors: Array<ServerError>;
+    statusCode: number;
+    constructor(errors: Array<ServerError>);
+    /**
+     * The error to throw for `errors`: the only one, or a list of them.
+     */
+    static from(errors: Array<ServerError>): ServerError;
+}
+/**
+ * Run each of `steps`, collecting the server errors (those with a
+ * `statusCode`) they throw instead of stopping at the first; anything else
+ * is a bug and is rethrown at once. Throws the collected errors, if any.
+ *
+ * @internal
+ */
+export declare function collectErrors(steps: Array<() => void>, errors?: Array<ServerError>): void;
+export default ErrorList;

package/dist/types/packages/server/errors/method-not-allowed-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A request whose path exists, but not for its method. The responder's
+ * caller sets the `Allow` header listing the methods that are.
+ *
+ * @internal
+ */
+declare class MethodNotAllowedError extends Error {
+    constructor(method: string, allowed: Array<string>);
+}
+declare const _default: new (...args: Array<any>) => MethodNotAllowedError & import("..").ServerError;
+export default _default;

package/dist/types/packages/server/index.d.ts

@@ -4,25 +4,25 @@ import type Logger from '../logger';
 import type Router from '../router';
 import type { Request } from './request/interfaces';
 import type { Response } from './response/interfaces';
-import type { Server$opts, Server$cors } from './interfaces';
-/**
- * @private
- */
+import type { ServerOptions, CorsConfig } from './interfaces';
+/** @internal */
 declare class Server {
     logger: Logger;
     router: Router;
-    cors: Server$cors;
+    cors: CorsConfig;
+    trustProxy: boolean;
     instance: HTTPServer;
-    constructor({ logger, router, cors }: Server$opts);
+    constructor({ logger, router, cors, trustProxy }: ServerOptions);
     listen(port: number): void;
     initializeRequest(req: IncomingMessage, res: Writable): [Request, Response];
-    validateRequest({ method, headers }: Request): true;
+    validateRequest({ method, headers, route }: Request): true;
     receiveRequest: (req: IncomingMessage, res: Writable) => void;
 }
 export default Server;
 export { REQUEST_METHODS, getDomain } from './request';
 export { default as createServerError } from './utils/create-server-error';
 export { default as sourceFor } from './utils/source-for';
-export type { Server$config, Server$ErrorSource } from './interfaces';
-export type { Request, Request$params, Request$method } from './request/interfaces';
+export { default as ErrorList } from './errors/error-list';
+export type { CorsConfig, ServerConfig, ServerError, ServerErrorSource } from './interfaces';
+export type { Request, RequestParams, RequestMethod } from './request/interfaces';
 export type { Response } from './response/interfaces';

package/dist/types/packages/server/interfaces.d.ts

@@ -1,23 +1,75 @@
 import type Logger from '../logger';
 import type Router from '../router';
-export type Server$cors = {
+/**
+ * CORS headers for every response, so browsers on another origin may call
+ * the API:
+ *
+ * ```javascript
+ * cors: {
+ *   enabled: true,
+ *   origin: 'https://app.example.com',
+ *   headers: ['Accept', 'Content-Type', 'Authorization'],
+ *   methods: ['GET', 'POST', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']
+ * }
+ * ```
+ */
+export type CorsConfig = {
+    /** Whether to send the headers at all. Off by default. */
     enabled: boolean;
+    /** `Access-Control-Allow-Origin`: the origin allowed, or `*`. */
     origin?: string;
+    /** `Access-Control-Allow-Headers`: the request headers allowed. */
     headers?: Array<string>;
+    /** `Access-Control-Allow-Methods`: the methods allowed. */
     methods?: Array<string>;
 };
-export type Server$config = {
-    cors: Server$cors;
+/**
+ * The `server` section of `config/environments/<environment>.js`.
+ */
+export type ServerConfig = {
+    /** CORS headers; off by default. */
+    cors: CorsConfig;
+    /**
+     * Whether one proxy sits in front of the app (Heroku's router, a load
+     * balancer) whose `X-Forwarded-For` entry is the client's address. Only
+     * enable it behind such a proxy: without one, clients can set the header to
+     * anything.
+     */
+    trustProxy?: boolean;
+    /**
+     * How long, in milliseconds, `lumen serve` lets a worker finish the
+     * requests in flight when it stops (`SIGTERM`, `SIGINT`) before killing
+     * it. Defaults to `8000`: within Docker's 10 s grace period, and Heroku's
+     * and Kubernetes' 30 s.
+     */
+    shutdownTimeout?: number;
 };
-export type Server$opts = Server$config & {
+export type ServerOptions = ServerConfig & {
     logger: Logger;
     router: Router;
 };
-export type Server$ErrorSource = {
+export type ServerErrorSource = {
     pointer?: string;
     parameter?: string;
 };
-export interface Server$Error extends Error {
+/**
+ * An error a request is answered with. Besides `statusCode`, it may carry the
+ * members of its JSON:API error object: `source` points into the request;
+ * `id`, `code`, `title`, `meta` and `links.about` are passed through as set.
+ * (`detail` is the message, exposed only in development, when it starts
+ * with `[public]`, or for the framework's own client errors, which set
+ * `isPublic`.)
+ */
+export interface ServerError extends Error {
     statusCode: number;
-    source?: Server$ErrorSource;
+    source?: ServerErrorSource;
+    id?: string;
+    code?: string;
+    title?: string;
+    meta?: Record<string, unknown>;
+    links?: {
+        about: string;
+    };
+    /** @internal */
+    isPublic?: boolean;
 }

package/dist/types/packages/server/request/constants.d.ts

@@ -1,2 +1,2 @@
-import type { Request$method } from './interfaces';
-export declare const REQUEST_METHODS: Array<Request$method>;
+import type { RequestMethod } from './interfaces';
+export declare const REQUEST_METHODS: Array<RequestMethod>;

package/dist/types/packages/server/request/index.d.ts

@@ -1,8 +1,6 @@
-import type { Request, Request$opts } from './interfaces';
-/**
- * @private
- */
-export declare function createRequest(req: any, { logger, router }: Request$opts): Request;
+import type { Request, RequestOptions } from './interfaces';
+/** @internal */
+export declare function createRequest(req: any, { logger, router }: RequestOptions): Request;
 export { REQUEST_METHODS } from './constants';
 export { parseRequest } from './parser';
 export { default as getDomain } from './utils/get-domain';

package/dist/types/packages/server/request/interfaces.d.ts

@@ -4,11 +4,11 @@ import type Logger from '../../logger';
 import type Router from '../../router';
 import type { Route } from '../../router';
 import type Controller from '../../controller';
-export type Request$opts = {
+export type RequestOptions = {
     logger: Logger;
     router: Router;
 };
-type Request$url = {
+type RequestUrl = {
     protocol?: string;
     slashes?: boolean;
     auth?: string;
@@ -23,41 +23,105 @@ type Request$url = {
     path: string;
     href: string;
 };
-export type Request$method = 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'DELETE';
-export type Request$params = {
+/** An HTTP method Lumen routes. */
+export type RequestMethod = 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'DELETE';
+/**
+ * A request's parameters, parsed and validated: `request.params`. Member
+ * names are camelCase whatever the client sent. Only what the request
+ * carries is present; query parameters a controller lists in
+ * {@link Controller.query} appear under their own names.
+ */
+export type RequestParams = {
+    /** The route's `:id`: a number for an integer primary key. */
     id: number | string | Buffer;
+    /** `?sort=`: an attribute, `-` first for descending. */
     sort: string;
+    /** `?filter[…]=`, by attribute; a comma-separated value is a list. */
     filter: Record<string, unknown>;
+    /** `?fields[…]=`: the fields to serialize, by resource type. */
     fields: Record<string, unknown>;
+    /** `?include=`: relationship paths (`comments.user`). */
     include: Array<string>;
+    /** `?page[…]=`. */
     page: {
+        /** `page[size]`. */
         size?: number;
+        /** `page[number]`, counting from 1. */
         number?: number;
     };
+    /** The body's primary data, on `POST` and `PATCH`. */
     data: {
+        /** The resource's id (`PATCH`). */
         id: number | string | Buffer;
+        /** The resource type. */
         type: string;
+        /** The attributes the controller accepts. */
         attributes?: Record<string, unknown>;
+        /** The relationships, each as `{ data }` linkage. */
         relationships?: Record<string, unknown>;
     };
 };
+/**
+ * The request an action or hook receives: Node's incoming message, with
+ * Lumen's parsed parameters and routing.
+ */
 export interface Request extends Readable {
+    /**
+     * Identifies the request in the logs and the `X-Request-Id` response
+     * header: the client's own `X-Request-Id` when it is well-formed, otherwise
+     * a fresh UUID.
+     */
+    id: string;
+    /**
+     * The client's address: the connection's, or — with `server.trustProxy` —
+     * the one the proxy in front added to `X-Forwarded-For`.
+     */
+    ip?: string;
+    /**
+     * The headers, by lowercase name, as a `Map`:
+     * `request.headers.get('authorization')`.
+     */
     headers: Map<string, string>;
+    /** The HTTP version, `'1.1'`. */
     httpVersion: string;
-    method: Request$method;
+    /** The method, or an `X-HTTP-Method-Override` header's. */
+    method: RequestMethod;
+    /** Node's request trailers. */
     trailers: Record<string, unknown>;
+    /** The connection's socket. */
     socket: Socket;
+    /** The application's logger. */
     logger: Logger;
-    params: Request$params;
-    defaultParams: Request$params;
+    /** @internal */
+    router: Router;
+    /** The parsed, validated parameters. */
+    params: RequestParams;
+    /**
+     * The parsed JSON body of a `POST` or `PATCH`, as the client sent it. On a
+     * plain route (neither `member` nor `collection`) it is any JSON, and is
+     * not validated: read it here, not in `params`. `undefined` without a body.
+     */
+    body?: unknown;
+    /** @internal */
+    defaultParams: RequestParams;
+    /**
+     * The matched route. `route.type` is `'relationship'` or `'related'` on a
+     * relationship or related endpoint, and `route.relationship` names the
+     * relationship there.
+     */
     route: Route;
+    /** The name of the action handling the request (`'index'`). */
     action: string;
+    /** The controller handling the request. */
     controller: Controller;
-    url: Request$url;
+    /** The parsed URL: `pathname`, `query` and the rest. */
+    url: RequestUrl;
+    /** @internal */
     connection: {
         encrypted: boolean;
         remoteAddress: string;
     };
+    /** Node's `setTimeout` for the request. */
     setTimeout(msecs: number, callback: () => void): void;
 }
 export {};

package/dist/types/packages/server/request/parser/errors/malformed-request-error.d.ts

@@ -1,8 +1,6 @@
-/**
- * @private
- */
+/** @internal */
 declare class MalformedRequestError extends SyntaxError {
-    constructor();
+    constructor(expected?: string);
 }
-declare const _default: new (...args: Array<any>) => MalformedRequestError & import("../../../interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => MalformedRequestError & import("../../..").ServerError;
 export default _default;

package/dist/types/packages/server/request/parser/index.d.ts

@@ -1,5 +1,10 @@
 import type { Request } from '../interfaces';
 /**
- * @private
+ * The request's parameters: the query string's, and on `POST` and `PATCH`
+ * the body's. A plain route's body is any JSON, kept as `request.body` and
+ * not validated; a resource route's is a JSON:API document, normalized into
+ * the parameters (`data`) and also kept as `request.body`.
+ *
+ * @internal
  */
 export declare function parseRequest(req: Request): Promise<Record<string, unknown>>;

package/dist/types/packages/server/request/parser/utils/format.d.ts

@@ -1,17 +1,19 @@
-import type { Request$method } from '../../interfaces';
-/**
- * @private
- */
+/** @internal */
 export declare function formatSort(sort: string): string;
+/** @internal */
+export declare function formatFields(fields: Record<string, unknown>): Record<string, Array<string>>;
 /**
- * @private
- */
-export declare function formatFields(fields: Record<string, unknown>): Record<string, unknown>;
-/**
- * @private
+ * Relationship paths, with each member name camelized
+ * (`comments.blog-author` -> `comments.blogAuthor`).
+ *
+ * @internal
  */
 export declare function formatInclude(include: string | Array<string>): Array<string>;
 /**
- * @private
+ * Format query parameters: keys are camelized (they are member names, e.g.
+ * `filter[is-public]`), values are coerced (`123`, `true`, `null`, ISO dates)
+ * and split on commas, but otherwise left as written.
+ *
+ * @internal
  */
-export default function format(params: Record<string, unknown>, method: Request$method): Record<string, unknown>;
+export default function format(params: Record<string, unknown>): Record<string, unknown>;

package/dist/types/packages/server/request/parser/utils/normalize-document.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bring a request document's member names into their internal form: the
+ * names of `data.attributes` and `data.relationships` are camelized
+ * (`is-public` -> `isPublic`). Nothing else is touched — in particular no
+ * value: attribute values (and keys inside them) are data, and ids and dates
+ * are typed by parameter validation, from the columns they are written to.
+ *
+ * Anything that is not a resource document is passed through for parameter
+ * validation to reject.
+ *
+ * @internal
+ */
+export default function normalizeDocument(document: unknown): unknown;

package/dist/types/packages/server/request/parser/utils/parse-nested-object.d.ts

@@ -1,4 +1,2 @@
-/**
- * @private
- */
+/** @internal */
 export default function parseNestedObject(source: Record<string, unknown>): Record<string, unknown>;

package/dist/types/packages/server/request/parser/utils/parse-read.d.ts

@@ -1,5 +1,3 @@
 import type { Request } from '../../interfaces';
-/**
- * @private
- */
-export default function parseRead({ method, url: { query } }: Request): Record<string, unknown>;
+/** @internal */
+export default function parseRead({ url: { query } }: Request): Record<string, unknown>;

package/dist/types/packages/server/request/parser/utils/parse-write.d.ts

@@ -1,5 +1,21 @@
 import type { Request } from '../../interfaces';
 /**
- * @private
+ * The request body, read to the end as text.
+ *
+ * @internal
+ */
+export declare function readBody(req: Request): Promise<string>;
+/**
+ * A plain route's body: any JSON, as sent, or `undefined` when there is
+ * none. Nothing in it is validated or renamed.
+ *
+ * @internal
+ */
+export declare function parseJSON(req: Request): Promise<unknown>;
+/**
+ * A JSON:API document's members, normalized into the request's parameters.
+ * The document as sent is also `request.body`.
+ *
+ * @internal
  */
 export default function parseWrite(req: Request): Promise<Record<string, unknown>>;

package/dist/types/packages/server/request/utils/get-domain.d.ts

@@ -1,5 +1,3 @@
 import type { Request } from '../interfaces';
-/**
- * @private
- */
+/** @internal */
 export default function getDomain({ headers, connection: { encrypted } }: Request): string;

package/dist/types/packages/server/responder/index.d.ts

@@ -1,5 +1,3 @@
 import type { Request, Response } from '../index';
-/**
- * @private
- */
+/** @internal */
 export declare function createResponder(req: Request, res: Response): (data?: unknown) => void;

package/dist/types/packages/server/responder/utils/content-type-for.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `Content-Type` of a response body, before it is serialized: the
+ * JSON:API media type for a JSON:API document, `application/json` for any
+ * other object or array, plain text for a string, and none for an empty body.
+ *
+ * @internal
+ */
+export default function contentTypeFor(body: unknown): string | undefined;

package/dist/types/packages/server/responder/utils/data-for.d.ts

@@ -1,5 +1,3 @@
-import type { JSONAPI$Document } from '../../../jsonapi';
-/**
- * @private
- */
-export default function dataFor(status: number, err?: Error): string | JSONAPI$Document;
+import type { JsonApiDocument } from '../../../jsonapi';
+/** @internal */
+export default function dataFor(status: number, err?: Error): string | JsonApiDocument;

package/dist/types/packages/server/responder/utils/normalize.d.ts

@@ -1,7 +1,6 @@
-/**
- * @private
- */
+/** @internal */
 export default function normalize(data?: unknown): {
     statusCode: number | undefined;
+    body: unknown;
     data: string;
 };

package/dist/types/packages/server/response/index.d.ts

@@ -1,5 +1,3 @@
-import type { Response, Response$opts } from './interfaces';
-/**
- * @private
- */
-export declare function createResponse(res: any, opts: Response$opts): Response;
+import type { Response, ResponseOptions } from './interfaces';
+/** @internal */
+export declare function createResponse(res: any, opts: ResponseOptions): Response;

package/dist/types/packages/server/response/interfaces.d.ts

@@ -1,22 +1,33 @@
 import type { Writable } from 'stream';
 import type Logger from '../../logger';
-type Response$stat = {
+type ResponseStat = {
     type: string;
     name: string;
     duration: number;
     controller: string;
 };
-export type Response$opts = {
+export type ResponseOptions = {
     logger: Logger;
 };
+/**
+ * The response an action or hook receives: Node's server response. Use it
+ * for headers, or for a status the action's return value doesn't decide.
+ */
 export interface Response extends Writable {
     [key: string]: unknown;
-    stats: Array<Response$stat>;
+    /** @internal */
+    stats: Array<ResponseStat>;
+    /** The application's logger. */
     logger: Logger;
+    /** The status code to send. */
     statusCode: number;
+    /** The status message to send; defaults to the code's standard one. */
     statusMessage: string;
+    /** A header set so far. */
     getHeader(name: string): string | void;
+    /** Set a header. */
     setHeader(name: string, value: string): void;
+    /** Remove a header set earlier. */
     removeHeader(name: string): void;
 }
 export {};

package/dist/types/packages/server/utils/client-ip-for.d.ts

@@ -0,0 +1,10 @@
+import type { Request } from '../request/interfaces';
+/**
+ * The client's address. Behind a trusted proxy that is the *last*
+ * `X-Forwarded-For` entry — the one the proxy appended; anything before it
+ * came from the client and could be forged. Otherwise it is the connection's
+ * own address.
+ *
+ * @internal
+ */
+export default function clientIpFor({ headers, socket }: Request, trustProxy?: boolean): string | undefined;

package/dist/types/packages/server/utils/create-server-error.d.ts

@@ -1,7 +1,15 @@
-import type { Server$Error } from '../interfaces';
+import type { ServerError } from '../interfaces';
 type Constructor<T> = new (...args: Array<any>) => T;
 /**
- * @private
+ * `Target`, answered with `statusCode`. `isPublic` marks a client error whose
+ * message only describes the request — echoed input and declared names, never
+ * stored data, SQL or internals — so it is the error's `detail` in every
+ * environment. Leave it off for anything that passes on another message (a
+ * database driver's, say).
+ *
+ * @internal
  */
-export default function createServerError<T extends object>(Target: Constructor<T>, statusCode: number): Constructor<T & Server$Error>;
+export default function createServerError<T extends object>(Target: Constructor<T>, statusCode: number, { isPublic }?: {
+    isPublic?: boolean;
+}): Constructor<T & ServerError>;
 export {};

package/dist/types/packages/server/utils/request-id-for.d.ts

@@ -0,0 +1,9 @@
+import type { Request } from '../request/interfaces';
+/**
+ * The id a request is logged and answered with: the client's (or a proxy's)
+ * own `X-Request-Id` when it is well-formed, so a request can be traced
+ * across services, otherwise a fresh UUID.
+ *
+ * @internal
+ */
+export default function requestIdFor({ headers }: Request): string;

package/dist/types/packages/server/utils/set-cors-headers.d.ts

@@ -1,3 +1,3 @@
 import type { Response } from '../index';
-import type { Server$cors } from '../interfaces';
-export default function setCORSHeaders(res: Response, { origin, methods, headers, enabled }: Server$cors): void;
+import type { CorsConfig } from '../interfaces';
+export default function setCORSHeaders(res: Response, { origin, methods, headers, enabled }: CorsConfig): void;