lumen-framework 3.1.1 → 4.0.0

package/dist/types/packages/router/definitions/context/utils/create-definition.d.ts

@@ -1,10 +1,15 @@
-import type { Request$method } from '../../../../server';
-import type { Router$Namespace, Route$type } from '../../../index';
+import type { RequestMethod } from '../../../../server';
+import type { RouterNamespace, RouteOptions, RouteType } from '../../../index';
 /**
- * @private
+ * Add the route `opts` describes to `namespace`, along with a `HEAD` route
+ * for a `GET` and an `OPTIONS` route for its path.
+ *
+ * @internal
  */
+export declare function addRoute(namespace: RouterNamespace, opts: RouteOptions): void;
+/** @internal */
 export default function createDefinition({ type, method, namespace }: {
-    type: Route$type;
-    method: Request$method;
-    namespace: Router$Namespace;
+    type: RouteType;
+    method: RequestMethod;
+    namespace: RouterNamespace;
 }): (name: string, action?: string) => void;

package/dist/types/packages/router/definitions/context/utils/normalize-resource-args.d.ts

@@ -1,12 +1,11 @@
-import { type Controller$builtIn } from '../../../../controller';
-/**
- * @private
- */
+import { type BuiltInAction } from '../../../../controller';
+/** @internal */
 export default function normalizeResourceArgs(args: Array<any>): [
     {
         name: string;
         path: string;
-        only: Array<Controller$builtIn>;
+        only: Array<BuiltInAction>;
+        relationships?: boolean | Array<string>;
     },
     () => void
 ];

package/dist/types/packages/router/definitions/index.d.ts

@@ -1,10 +1,6 @@
 import type Router from '../index';
-import type { Router$Namespace } from '../index';
-/**
- * @private
- */
-export declare function build<T extends Router$Namespace>(builder: (() => void) | undefined, namespace: T): T;
-/**
- * @private
- */
-export declare function define<T extends Router$Namespace>(router: Router, parent: T): void;
+import type { RouterNamespace } from '../index';
+/** @internal */
+export declare function build<T extends RouterNamespace>(builder: (() => void) | undefined, namespace: T): T;
+/** @internal */
+export declare function define<T extends RouterNamespace>(router: Router, parent: T): void;

package/dist/types/packages/router/definitions/interfaces.d.ts

@@ -1,7 +1,7 @@
-import type { Router$Namespace, Resource$opts } from '../index';
-export type Router$DefinitionBuilder<T extends Router$Namespace> = (builder: (() => void) | undefined, namespace: T) => T;
-export type Router$resourceArgs = [
+import type { RouterNamespace, ResourceOptions } from '../index';
+export type RouterDefinitionBuilder<T extends RouterNamespace> = (builder: (() => void) | undefined, namespace: T) => T;
+export type RouterResourceArgs = [
     string,
-    (Resource$opts | null | undefined)?,
+    (ResourceOptions | null | undefined)?,
     ((() => void) | null | undefined)?
 ];

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

@@ -1,18 +1,30 @@
 import { FreezeableMap } from '../freezeable';
-import type { Request } from '../server';
+import type { Request, RequestMethod } from '../server';
 import Route, { DYNAMIC_PATTERN } from './route';
-import type { Router$opts } from './interfaces';
-/**
- * @private
- */
+import type { Replacer } from './utils/create-replacer';
+import type { RouterOptions } from './interfaces';
+/** @internal */
 declare class Router extends FreezeableMap<string, Route> {
-    replacer: RegExp;
-    constructor({ routes, controller, controllers }: Router$opts);
+    replacer: Replacer;
+    constructor({ routes, controller, controllers }: RouterOptions);
+    /**
+     * The route key path of `pathname` and the ids in it. A path some route
+     * defines as is (`/users/login`) is static, so it is never read as an id.
+     */
+    resolve(pathname: string): {
+        staticPath: string;
+        params: Array<string>;
+    };
     match({ method, url }: Request): void | Route;
+    /**
+     * The methods some route accepts at the request's path — empty when no
+     * route has the path at all.
+     */
+    methodsFor({ url }: Request): Array<RequestMethod>;
 }
 export default Router;
 export { Route, DYNAMIC_PATTERN };
-export type { Router$Namespace } from './interfaces';
-export type { Resource$opts } from './resource';
-export type { Namespace$opts } from './namespace';
-export type { Action, Route$opts, Route$type } from './route';
+export type { RouterNamespace } from './interfaces';
+export type { ResourceOptions } from './resource';
+export type { NamespaceOptions } from './namespace';
+export type { Action, RouteOptions, RouteType } from './route';

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

@@ -1,17 +1,17 @@
 import type Route from './route';
 import type Controller from '../controller';
 import type { FreezeableSet } from '../freezeable';
-export type Router$opts = {
+export type RouterOptions = {
     controller: Controller;
     controllers: Map<string, Controller>;
     routes(): void;
 };
-type Router$NS$content = Route | Router$Namespace;
-export interface Router$Namespace extends FreezeableSet<Router$NS$content> {
+type RouterNamespaceEntry = Route | RouterNamespace;
+export interface RouterNamespace extends FreezeableSet<RouterNamespaceEntry> {
     name: string;
     path: string;
     isRoot: boolean;
-    namespace: Router$Namespace;
+    namespace: RouterNamespace;
     controller: Controller;
     controllers: Map<string, Controller>;
 }

package/dist/types/packages/router/namespace/index.d.ts

@@ -1,20 +1,18 @@
 import { FreezeableSet } from '../../freezeable';
 import type Controller from '../../controller';
-import type { Route, Router$Namespace } from '../index';
-import type { Namespace$opts } from './interfaces';
-/**
- * @private
- */
-declare class Namespace extends FreezeableSet<Route | Router$Namespace> {
+import type { Route, RouterNamespace } from '../index';
+import type { NamespaceOptions } from './interfaces';
+/** @internal */
+declare class Namespace extends FreezeableSet<Route | RouterNamespace> {
     name: string;
     path: string;
     isRoot: boolean;
-    namespace: Router$Namespace;
+    namespace: RouterNamespace;
     controller: Controller;
     controllers: Map<string, Controller>;
-    constructor({ name, path, namespace, controller, controllers }: Namespace$opts);
+    constructor({ name, path, namespace, controller, controllers }: NamespaceOptions);
 }
 export default Namespace;
 export { default as normalizeName } from './utils/normalize-name';
 export { default as normalizePath } from './utils/normalize-path';
-export type { Namespace$opts } from './interfaces';
+export type { NamespaceOptions } from './interfaces';

package/dist/types/packages/router/namespace/interfaces.d.ts

@@ -1,9 +1,9 @@
 import type Controller from '../../controller';
-import type { Router$Namespace } from '../index';
-export type Namespace$opts = {
+import type { RouterNamespace } from '../index';
+export type NamespaceOptions = {
     name: string;
     path: string;
-    namespace?: Router$Namespace;
+    namespace?: RouterNamespace;
     controller: Controller;
     controllers: Map<string, Controller>;
 };

package/dist/types/packages/router/namespace/utils/normalize-name.d.ts

@@ -1,4 +1,2 @@
-/**
- * @private
- */
+/** @internal */
 export default function normalizeName(str: string): string;

package/dist/types/packages/router/namespace/utils/normalize-path.d.ts

@@ -1,4 +1,2 @@
-/**
- * @private
- */
+/** @internal */
 export default function normalizePath(str: string): string;

package/dist/types/packages/router/resource/index.d.ts

@@ -1,13 +1,12 @@
 import Namespace from '../namespace';
 import { FreezeableSet } from '../../freezeable';
-import type { Controller$builtIn } from '../../controller';
-import type { Resource$opts } from './interfaces';
-/**
- * @private
- */
+import type { BuiltInAction } from '../../controller';
+import type { ResourceOptions, ResourceRelationships } from './interfaces';
+/** @internal */
 declare class Resource extends Namespace {
-    only: FreezeableSet<Controller$builtIn>;
-    constructor({ only, ...opts }: Resource$opts);
+    only: FreezeableSet<BuiltInAction>;
+    relationships: ResourceRelationships | undefined;
+    constructor({ only, relationships, ...opts }: ResourceOptions);
 }
 export default Resource;
-export type { Resource$opts } from './interfaces';
+export type { ResourceOptions, ResourceRelationships } from './interfaces';

package/dist/types/packages/router/resource/interfaces.d.ts

@@ -1,5 +1,13 @@
-import type { Controller$builtIn } from '../../controller';
-import type { Namespace$opts } from '../namespace';
-export type Resource$opts = Namespace$opts & {
-    only: Array<Controller$builtIn>;
+import type { BuiltInAction } from '../../controller';
+import type { NamespaceOptions } from '../namespace';
+/**
+ * Which relationships of a resource get relationship and related endpoints:
+ * all its Serializer exposes (`true`), none (`false`), or those named. The
+ * default is `true` in a namespace with visibility rules, `false` in one
+ * without.
+ */
+export type ResourceRelationships = boolean | Array<string>;
+export type ResourceOptions = NamespaceOptions & {
+    only: Array<BuiltInAction>;
+    relationships?: ResourceRelationships;
 };

package/dist/types/packages/router/resource/utils/normalize-only.d.ts

@@ -1,5 +1,3 @@
-import { type Controller$builtIn } from '../../../controller';
-/**
- * @private
- */
-export default function normalizeOnly(only: Array<Controller$builtIn>): Array<Controller$builtIn>;
+import { type BuiltInAction } from '../../../controller';
+/** @internal */
+export default function normalizeOnly(only: Array<BuiltInAction>): Array<BuiltInAction>;

package/dist/types/packages/router/route/action/enhancers/resource.d.ts

@@ -1,5 +1,3 @@
 import type { Action } from '../interfaces';
-/**
- * @private
- */
+/** @internal */
 export default function resource(action: Action<unknown>): Action<unknown>;

package/dist/types/packages/router/route/action/enhancers/track-perf.d.ts

@@ -1,5 +1,3 @@
 import type { Action } from '../interfaces';
-/**
- * @private
- */
+/** @internal */
 export default function trackPerf<T, U extends Action<T>>(action: U): Action<T>;

package/dist/types/packages/router/route/action/index.d.ts

@@ -1,9 +1,14 @@
 import type Controller from '../../../controller';
 import type { Action } from './interfaces';
 /**
- * @private
+ * The handlers of an action: `controller`'s `beforeAction` hooks, the action,
+ * then its `afterAction` hooks. A related route (`/posts/1/comments`) also
+ * serves the related type, so `related`'s `beforeAction` hooks run too, after
+ * the owner's, each hook once (both usually inherit the same ones).
+ *
+ * @internal
  */
-export declare function createAction(type: string, action: Action<unknown>, controller: Controller): Array<Action<unknown>>;
+export declare function createAction(type: string, action: Action<unknown>, controller: Controller, related?: Controller): Array<Action<unknown>>;
 export { FINAL_HANDLER } from './constants';
 export { default as createPageLinks } from './utils/create-page-links';
 export type { Action } from './interfaces';

package/dist/types/packages/router/route/action/interfaces.d.ts

@@ -1,2 +1,6 @@
 import type { Request, Response } from '../../../server';
+/**
+ * A function called with a request and its response, as an action or hook
+ * is: what {@link lumenify} returns.
+ */
 export type Action<T> = (req: Request, res: Response, data?: unknown) => Promise<T>;

package/dist/types/packages/router/route/action/utils/create-page-links.d.ts

@@ -1,12 +1,28 @@
-import type { Request$params } from '../../../../server';
-import type { JSONAPI$DocumentLinks } from '../../../../jsonapi';
+import type { RequestParams } from '../../../../server';
+import type { JsonApiDocumentLinks } from '../../../../jsonapi';
 /**
- * @private
+ * The link to the request itself: its path and its query as the client wrote
+ * it (member names, order, values), encoded like page links.
+ *
+ * @internal
+ */
+export declare function createSelfLink({ search, domain, pathname }: {
+    search: string;
+    domain: string;
+    pathname: string;
+}): string;
+/**
+ * The top level `links` of a paginated collection. `self` is always the page
+ * requested — even past the last one, where `prev`/`next` are `null` — and
+ * every link keeps the rest of the request's query string as is.
+ *
+ * @internal
  */
 export default function createPageLinks(opts: {
     total: number;
-    params: Request$params;
+    params: RequestParams;
+    search: string;
     domain: string;
     pathname: string;
     defaultPerPage: number;
-}): JSONAPI$DocumentLinks;
+}): JsonApiDocumentLinks;

package/dist/types/packages/router/route/action/utils/get-action-name.d.ts

@@ -1,5 +1,3 @@
 import type { Request } from '../../../../server';
-/**
- * @private
- */
+/** @internal */
 export default function getActionName({ route: { action } }: Request): string;

package/dist/types/packages/router/route/action/utils/get-controller-name.d.ts

@@ -1,5 +1,3 @@
 import type { Request } from '../../../../server';
-/**
- * @private
- */
+/** @internal */
 export default function getControllerName({ route: { controller: { constructor: { name } } } }: Request): string;

package/dist/types/packages/router/route/index.d.ts

@@ -1,28 +1,32 @@
 import { FreezeableSet } from '../../freezeable';
 import type Controller from '../../controller';
-import type { Request, Response, Request$method } from '../../server';
+import type { Request, Response, RequestMethod } from '../../server';
 import type { Action } from './action';
 import type { ParameterGroup } from './params';
-import type { Route$opts } from './interfaces';
-/**
- * @private
- */
+import type { RouteOptions } from './interfaces';
+/** @internal */
 declare class Route extends FreezeableSet<Action<unknown>> {
     type: string;
     path: string;
     action: string;
     params: ParameterGroup;
-    method: Request$method;
+    method: RequestMethod;
     controller: Controller;
+    relationship: string | undefined;
+    related: Controller | undefined;
     staticPath: string;
     defaultParams: Record<string, unknown>;
     dynamicSegments: Array<string>;
-    constructor({ type, path, action, method, controller }: Route$opts);
-    parseParams(params: Array<string>): Record<string, number>;
+    constructor({ type, path, action, method, controller, relationship, related }: RouteOptions);
+    /**
+     * The ids in the request path, keyed by their dynamic segment: a number for
+     * a numeric primary key (or a model-less controller), else as written.
+     */
+    parseParams(params: Array<string>): Record<string, number | string>;
     execHandlers(req: Request, res: Response): Promise<unknown>;
     visit(req: Request, res: Response): Promise<unknown>;
 }
 export default Route;
 export { DYNAMIC_PATTERN } from './constants';
 export type { Action } from './action';
-export type { Route$opts, Route$type } from './interfaces';
+export type { RouteOptions, RouteType } from './interfaces';

package/dist/types/packages/router/route/interfaces.d.ts

@@ -1,10 +1,12 @@
 import type Controller from '../../controller';
-import type { Request$method } from '../../server';
-export type Route$type = 'custom' | 'member' | 'collection';
-export type Route$opts = {
-    type: Route$type;
+import type { RequestMethod } from '../../server';
+export type RouteType = 'custom' | 'member' | 'collection' | 'relationship' | 'related';
+export type RouteOptions = {
+    type: RouteType;
     path: string;
     action: string;
-    method: Request$method;
+    method: RequestMethod;
     controller: Controller;
+    relationship?: string;
+    related?: Controller;
 };

package/dist/types/packages/router/route/params/errors/client-generated-id-error.d.ts

@@ -1,13 +1,13 @@
-import type { Server$ErrorSource } from '../../../../server';
+import type { ServerErrorSource } from '../../../../server';
 /**
  * JSON:API 1.0: "A server MUST return 403 Forbidden in response to an
  * unsupported request to create a resource with a client-generated ID."
  *
- * @private
+ * @internal
  */
 declare class ClientGeneratedIdError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor();
 }
-declare const _default: new (...args: Array<any>) => ClientGeneratedIdError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => ClientGeneratedIdError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/errors/forbidden-parameter-error.d.ts

@@ -1,14 +1,14 @@
-import type { Server$ErrorSource } from '../../../../server';
+import type { ServerErrorSource } from '../../../../server';
 /**
  * JSON:API 1.0: "A server MUST return 403 Forbidden in response to an
  * unsupported request to update a resource or relationship." Used for members
  * the model knows about but the controller does not accept (`params`).
  *
- * @private
+ * @internal
  */
 declare class ForbiddenParameterError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor(path: string);
 }
-declare const _default: new (...args: Array<any>) => ForbiddenParameterError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => ForbiddenParameterError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/errors/index.d.ts

@@ -4,4 +4,5 @@ export { default as InvalidParameterError } from './invalid-parameter-error';
 export { default as ResourceMismatchError } from './resource-mismatch-error';
 export { default as ParameterRequiredError } from './parameter-required-error';
 export { default as ClientGeneratedIdError } from './client-generated-id-error';
+export { default as ParameterRangeError } from './parameter-range-error';
 export { default as ForbiddenParameterError } from './forbidden-parameter-error';

package/dist/types/packages/router/route/params/errors/invalid-parameter-error.d.ts

@@ -1,10 +1,8 @@
-import type { Server$ErrorSource } from '../../../../server';
-/**
- * @private
- */
+import type { ServerErrorSource } from '../../../../server';
+/** @internal */
 declare class InvalidParameterError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor(path: string);
 }
-declare const _default: new (...args: Array<any>) => InvalidParameterError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => InvalidParameterError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/errors/parameter-not-nullable-error.d.ts

@@ -1,11 +1,9 @@
-import type { Server$ErrorSource } from '../../../../server';
+import type { ServerErrorSource } from '../../../../server';
 import type { ParameterLike } from '../index';
-/**
- * @private
- */
+/** @internal */
 declare class ParameterNotNullableError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor({ path }: ParameterLike);
 }
-declare const _default: new (...args: Array<any>) => ParameterNotNullableError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => ParameterNotNullableError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/errors/parameter-range-error.d.ts

@@ -0,0 +1,9 @@
+import type { ServerErrorSource } from '../../../../server';
+import type Parameter from '../parameter';
+/** @internal */
+declare class ParameterRangeError extends RangeError {
+    source: ServerErrorSource;
+    constructor({ path, min, max }: Parameter, actual: number);
+}
+declare const _default: new (...args: Array<any>) => ParameterRangeError & import("../../../../server").ServerError;
+export default _default;

package/dist/types/packages/router/route/params/errors/parameter-required-error.d.ts

@@ -1,10 +1,8 @@
-import type { Server$ErrorSource } from '../../../../server';
-/**
- * @private
- */
+import type { ServerErrorSource } from '../../../../server';
+/** @internal */
 declare class ParameterRequiredError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor(path: string);
 }
-declare const _default: new (...args: Array<any>) => ParameterRequiredError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => ParameterRequiredError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/errors/parameter-type-error.d.ts

@@ -1,11 +1,9 @@
-import type { Server$ErrorSource } from '../../../../server';
+import type { ServerErrorSource } from '../../../../server';
 import type { ParameterLike } from '../index';
-/**
- * @private
- */
+/** @internal */
 declare class ParameterTypeError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor(param: ParameterLike, actual: string);
 }
-declare const _default: new (...args: Array<any>) => ParameterTypeError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => ParameterTypeError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/errors/parameter-value-error.d.ts

@@ -1,11 +1,9 @@
-import type { Server$ErrorSource } from '../../../../server';
+import type { ServerErrorSource } from '../../../../server';
 import type { ParameterLike } from '../index';
-/**
- * @private
- */
+/** @internal */
 declare class ParameterValueError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor(param: ParameterLike, actual: unknown);
 }
-declare const _default: new (...args: Array<any>) => ParameterValueError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => ParameterValueError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/errors/resource-mismatch-error.d.ts

@@ -1,10 +1,8 @@
-import type { Server$ErrorSource } from '../../../../server';
-/**
- * @private
- */
+import type { ServerErrorSource } from '../../../../server';
+/** @internal */
 declare class ResourceMismatchError extends TypeError {
-    source: Server$ErrorSource;
+    source: ServerErrorSource;
     constructor(path: string, expected: unknown, actual: unknown);
 }
-declare const _default: new (...args: Array<any>) => ResourceMismatchError & import("../../../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => ResourceMismatchError & import("../../../../server").ServerError;
 export default _default;

package/dist/types/packages/router/route/params/index.d.ts

@@ -1,19 +1,15 @@
 import type Controller from '../../../controller';
 import ParameterGroup from './parameter-group';
-import type { Params$opts } from './interfaces';
-/**
- * @private
- */
-export declare function paramsFor({ type, method, controller, dynamicSegments }: Params$opts): ParameterGroup;
-/**
- * @private
- */
+import type { ParamsOptions } from './interfaces';
+/** @internal */
+export declare function paramsFor({ type, method, controller, dynamicSegments }: ParamsOptions): ParameterGroup;
+/** @internal */
 export declare function defaultParamsFor({ type, controller }: {
     type: string;
     controller: Controller;
 }): Record<string, unknown>;
 export { default as validateClientId } from './utils/validate-client-id';
 export { default as validateResourceId } from './utils/validate-resource-id';
-export type { ParameterLike, ParameterLike$opts } from './interfaces';
+export type { ParameterLike, ParameterLikeOptions } from './interfaces';
 export type { default as Parameter } from './parameter';
 export type { default as ParameterGroup } from './parameter-group';

package/dist/types/packages/router/route/params/interfaces.d.ts

@@ -1,21 +1,25 @@
 import type Controller from '../../../controller';
-import type { Route$type } from '../index';
-import type { Request$method } from '../../../server';
-import type { Lumen$Collection } from '../../../../interfaces';
-export type Params$opts = {
-    type: Route$type;
-    method: Request$method;
+import type { RouteType } from '../index';
+import type { RequestMethod } from '../../../server';
+import type { LumenCollection } from '../../../../interfaces';
+export type ParamsOptions = {
+    type: RouteType;
+    method: RequestMethod;
     controller: Controller;
     dynamicSegments: Array<string>;
 };
-export type ParameterLike$opts = {
+export type ParameterLikeOptions = {
     path: string;
     type?: string;
     values?: Array<unknown>;
+    min?: number;
+    max?: number;
+    parse?: (value: unknown) => unknown;
+    items?: (path: string) => ParameterLike;
     required?: boolean;
     sanitize?: boolean;
 };
-export interface ParameterLike extends Lumen$Collection<unknown> {
+export interface ParameterLike extends LumenCollection<unknown> {
     path: string;
     type: string;
     required: boolean;

package/dist/types/packages/router/route/params/parameter/forbidden-parameter.d.ts

@@ -3,7 +3,7 @@ import Parameter from './index';
  * A member the resource has but the controller does not accept. Any value for
  * it is rejected with 403 rather than the 400 an unknown member gets.
  *
- * @private
+ * @internal
  */
 declare class ForbiddenParameter extends Parameter {
     constructor(path: string);