lumen-framework 3.0.2 → 3.1.0

package/dist/types/errors/namespaced-serializer-missing-error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Thrown at boot when a namespace that opted out of serializer fallback
+ * (`serializerFallback = false` on its ApplicationController) can reach a type
+ * that has no Serializer in that namespace.
+ *
+ * @private
+ */
+declare class NamespacedSerializerMissingError extends ReferenceError {
+    /**
+     * @param missing - Each missing serializer key (`admin/comments`) with an
+     * example of how it is reached (`admin/posts?include=comments`).
+     */
+    constructor(missing: Map<string, string>);
+}
+export default NamespacedSerializerMissingError;

package/dist/types/packages/application/utils/validate-namespaced-serializers.d.ts

@@ -0,0 +1,15 @@
+import type Controller from '../../controller';
+import type Serializer from '../../serializer';
+import type { Model } from '../../database';
+import type { Bundle$Namespace } from '../../loader';
+/**
+ * Enforce `serializerFallback = false`: for every namespace whose
+ * ApplicationController sets it, each type its controllers can serialize — the
+ * resource itself, and everything reachable through `include` (and so
+ * `fields`) down to the controller's `maxIncludeDepth` — must have a
+ * Serializer in exactly that namespace. Throws listing every gap, so a missing
+ * serializer fails the boot instead of silently falling back to the root one.
+ *
+ * @private
+ */
+export default function validateNamespacedSerializers(controllers: Bundle$Namespace<Controller> | Map<string, Controller>, serializers: Bundle$Namespace<Serializer<Model>> | Map<string, Serializer<Model>>): void;

package/dist/types/packages/controller/errors/index.d.ts

@@ -0,0 +1 @@
+export { default as RelatedRecordNotFoundError } from './related-record-not-found-error';

package/dist/types/packages/controller/errors/related-record-not-found-error.d.ts

@@ -0,0 +1,14 @@
+import type { ModelClass } from '../../database';
+import type { Server$ErrorSource } from '../../server';
+/**
+ * JSON:API 1.0: "A server MUST return 404 Not Found when processing a request
+ * that references a related resource that does not exist."
+ *
+ * @private
+ */
+declare class RelatedRecordNotFoundError extends Error {
+    source: Server$ErrorSource;
+    constructor({ name, primaryKey }: ModelClass, primaryKeyValue: unknown, path: string);
+}
+declare const _default: new (...args: Array<any>) => RelatedRecordNotFoundError & import("../../server/interfaces").Server$Error;
+export default _default;

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

@@ -442,6 +442,71 @@ declare class Controller {
      * @public
      */
     defaultPerPage: number;
+    /**
+     * How many relationships deep an `?include` path may go on this
+     * controller's routes. `comments.reactions.user` is 3 levels deep; with `1`
+     * only direct relationships (`comments`) can be included. Paths deeper than
+     * this are rejected with `400 Bad Request`.
+     *
+     * Set it on `ApplicationController` to change it for the whole app, or on a
+     * single controller to override it there.
+     *
+     * ```javascript
+     * class ApplicationController extends Controller {
+     *   maxIncludeDepth = 2;
+     * }
+     * ```
+     *
+     * Every allowed path is enumerated up front from the serializers'
+     * relationships, and each nested level costs its own queries per request, so
+     * keep this small.
+     *
+     * @property maxIncludeDepth
+     * @type {Number}
+     * @default 3
+     * @public
+     */
+    maxIncludeDepth: number;
+    /**
+     * Whether a namespace may fall back to the root Serializer of a type it has
+     * no Serializer for. Read from a namespace's `ApplicationController` and
+     * applies to the whole namespace.
+     *
+     * By default `app/controllers/admin/comments.js` without an
+     * `app/serializers/admin/comments.js` — or an included type without one —
+     * is serialized by the root Serializer, with every attribute and
+     * relationship it declares. For a namespace that must only expose what it
+     * declares itself, turn the fallback off:
+     *
+     * ```javascript
+     * // app/controllers/admin/application.js
+     * class AdminApplicationController extends ApplicationController {
+     *   serializerFallback = false;
+     * }
+     * ```
+     *
+     * The application then refuses to boot while any type the namespace can
+     * serialize or `include` (down to each controller's `maxIncludeDepth`) has
+     * no Serializer in that namespace, listing each missing one.
+     *
+     * @property serializerFallback
+     * @type {Boolean}
+     * @default true
+     * @public
+     */
+    serializerFallback: boolean;
+    /**
+     * The Serializer to serialize (and validate, and load) related resources of
+     * this Controller's responses with: the related model's Serializer in this
+     * Controller's namespace, falling back to the root one.
+     *
+     * Always this Controller's namespace — not its Serializer's, which is the
+     * root one when the namespace has no Serializer for this resource.
+     *
+     * @method serializerFor
+     * @private
+     */
+    serializerFor(model: ModelClass): Serializer<Model>;
     /**
      * The resolved Model for a Controller instance.
      *

package/dist/types/packages/controller/utils/find-many.d.ts

@@ -1,6 +1,7 @@
 import type { Model, ModelClass, Query } from '../../database';
+import type Serializer from '../../serializer';
 import type { Request } from '../../server';
 /**
  * @private
  */
-export default function findMany<T extends Model>(model: ModelClass<T>, req: Request): Query<Array<Model>>;
+export default function findMany<T extends Model>(model: ModelClass<T>, req: Request, serializerFor?: (model: ModelClass) => Serializer<Model>): Query<Array<Model>>;

package/dist/types/packages/controller/utils/find-one.d.ts

@@ -1,6 +1,7 @@
 import type { Model, ModelClass, Query } from '../../database';
+import type Serializer from '../../serializer';
 import type { Request } from '../../server';
 /**
  * @private
  */
-export default function findOne<T extends Model>(model: ModelClass<T>, req: Request): Query<T>;
+export default function findOne<T extends Model>(model: ModelClass<T>, req: Request, serializerFor?: (model: ModelClass) => Serializer<Model>): Query<T>;

package/dist/types/packages/controller/utils/params-to-query.d.ts

@@ -1,4 +1,5 @@
-import type { ModelClass } from '../../database';
+import type { Model, ModelClass } from '../../database';
+import type Serializer from '../../serializer';
 import type { Request$params } from '../../server';
 type Controller$query = {
     id?: number | string | Buffer;
@@ -10,7 +11,11 @@ type Controller$query = {
     include: Record<string, Array<string>>;
 };
 /**
+ * `serializerFor` resolves the Serializer an included resource is serialized
+ * with — in the request's namespace (`Controller#serializerFor()`) — so its
+ * attributes are the ones loaded. Defaults to the related model's root one.
+ *
  * @private
  */
-export default function paramsToQuery(model: ModelClass, { id, page, sort, filter, fields, include }: Request$params): Controller$query;
+export default function paramsToQuery(model: ModelClass, { id, page, sort, filter, fields, include }: Request$params, serializerFor?: (related: ModelClass) => Serializer<Model>): Controller$query;
 export {};

package/dist/types/packages/controller/utils/validate-relationships.d.ts

@@ -0,0 +1,8 @@
+import type { Model, ModelClass } from '../../database';
+/**
+ * Check that every resource referenced from `data.relationships` exists, so a
+ * write cannot leave dangling linkage. One query per relationship.
+ *
+ * @private
+ */
+export default function validateRelationships<T extends Model>(model: ModelClass<T>, relationships?: Record<string, unknown>): Promise<void>;

package/dist/types/packages/database/constants.d.ts

@@ -1,3 +1,4 @@
+export declare const UNIQUE_CONSTRAINT_CODES: Set<string>;
 export declare const UNIQUE_CONSTRAINT: RegExp;
 export declare const VALID_DRIVERS: string[];
 export declare const TYPE_ALIASES: Map<string, string>;

package/dist/types/packages/database/model/index.d.ts

@@ -78,6 +78,17 @@ declare class Model {
      * @private
      */
     prevAssociations: Set<Model>;
+    /**
+     * Names of `hasOne` relationships that were eager-loaded (joined) and found
+     * to have no related record. Lets the relationship getter answer `null`
+     * without a per-record query. Kept outside of the change sets so it never
+     * counts as a change to the record.
+     *
+     * @property absentRelationships
+     * @type {Set}
+     * @private
+     */
+    absentRelationships: Set<string>;
     /**
      * @property changeSets
      * @type {Array}

package/dist/types/packages/database/model/utils/process-write-error.d.ts

@@ -1,4 +1,12 @@
 /**
+ * Map a database write error to the server error it should surface as.
+ *
  * @private
  */
-export default function resolveWriteError(err: Error): Error;
+export default function processWriteError(err: unknown): unknown;
+/**
+ * `.catch()` handler for a write: rethrows the mapped error.
+ *
+ * @private
+ */
+export declare function rethrowWriteError(err: unknown): never;

package/dist/types/packages/database/validation/errors/validation-error.d.ts

@@ -1,7 +1,16 @@
+import type { Server$ErrorSource } from '../../../server';
 /**
+ * A model validator (`static validates`) rejected an attribute. Answered with
+ * 422 and a pointer to the attribute, which clients such as ember-data map to
+ * field errors. The rejected value is deliberately not in the message: it
+ * ends up in logs and may be a secret (e.g. a password).
+ *
  * @private
  */
 declare class ValidationError extends Error {
-    constructor(key: string, value: string);
+    key: string;
+    source: Server$ErrorSource;
+    constructor(key: string);
 }
-export default ValidationError;
+declare const _default: new (...args: Array<any>) => ValidationError & import("../../../server/interfaces").Server$Error;
+export default _default;

package/dist/types/packages/jsonapi/errors/not-acceptable-error.d.ts

@@ -2,7 +2,7 @@
  * @private
  */
 declare class NotAcceptableError extends TypeError {
-    constructor(contentType: string);
+    constructor(accept: string);
 }
 declare const _default: new (...args: Array<any>) => NotAcceptableError & import("../../server/interfaces").Server$Error;
 export default _default;

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

@@ -1,5 +1,7 @@
 export * from './constants';
 export * from './errors';
 export { default as isJSONAPI } from './utils/is-jsonapi';
-export { default as hasMediaType } from './utils/has-media-type';
+export { default as hasMediaTypeParams } from './utils/has-media-type-params';
+export { parseAccept, parseMediaType } from './utils/media-type';
+export type { MediaType } from './utils/media-type';
 export type { JSONAPI$versions, JSONAPI$Document, JSONAPI$ErrorObject, JSONAPI$DocumentLinks, JSONAPI$ResourceObject, JSONAPI$IdentifierObject, JSONAPI$RelationshipObject } from './interfaces';

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

@@ -28,7 +28,7 @@ export interface JSONAPI$ResourceObject {
     };
 }
 export interface JSONAPI$RelationshipObject {
-    data: JSONAPI$IdentifierObject;
+    data: JSONAPI$IdentifierObject | Array<JSONAPI$IdentifierObject> | null;
     meta?: JSONAPI$BaseObject;
     links?: JSONAPI$ResourceLinksObject;
 }

package/dist/types/packages/jsonapi/utils/has-media-type-params.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a media type (e.g. a `Content-Type` value) carries parameters.
+ *
+ * @private
+ */
+export default function hasMediaTypeParams(value: string): boolean;

package/dist/types/packages/jsonapi/utils/is-jsonapi.d.ts

@@ -1,4 +1,6 @@
 /**
+ * Whether a media type is the JSON:API media type, ignoring parameters.
+ *
  * @private
  */
 export default function isJSONAPI(value: string): boolean;

package/dist/types/packages/jsonapi/utils/media-type.d.ts

@@ -0,0 +1,19 @@
+export type MediaType = {
+    type: string;
+    params: Array<string>;
+};
+/**
+ * Parse a single media type, e.g. a `Content-Type` header value.
+ *
+ * @private
+ */
+export declare function parseMediaType(value: string): MediaType;
+/**
+ * Parse an `Accept` header into its media ranges.
+ *
+ * Per RFC 7231 §5.3.2 the `q` weight (and any accept-extension after it) is
+ * not a media type parameter, so it is not reported in `params`.
+ *
+ * @private
+ */
+export declare function parseAccept(value: string): Array<MediaType>;

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

@@ -0,0 +1,13 @@
+import type { Server$ErrorSource } 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
+ */
+declare class ClientGeneratedIdError extends TypeError {
+    source: Server$ErrorSource;
+    constructor();
+}
+declare const _default: new (...args: Array<any>) => ClientGeneratedIdError & import("../../../../server/interfaces").Server$Error;
+export default _default;

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

@@ -0,0 +1,14 @@
+import type { Server$ErrorSource } 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
+ */
+declare class ForbiddenParameterError extends TypeError {
+    source: Server$ErrorSource;
+    constructor(path: string);
+}
+declare const _default: new (...args: Array<any>) => ForbiddenParameterError & import("../../../../server/interfaces").Server$Error;
+export default _default;

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

@@ -3,3 +3,5 @@ export { default as ParameterValueError } from './parameter-value-error';
 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 ForbiddenParameterError } from './forbidden-parameter-error';

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -12,6 +12,7 @@ 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 { default as Parameter } from './parameter';

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

@@ -0,0 +1,12 @@
+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
+ */
+declare class ForbiddenParameter extends Parameter {
+    constructor(path: string);
+    validate<V>(): V;
+}
+export default ForbiddenParameter;

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

@@ -8,6 +8,14 @@ declare class Parameter extends FreezeableSet<unknown> {
     type: string;
     required: boolean;
     sanitize: boolean;
+    /**
+     * Whether the parameter only accepts the given `values`. A parameter built
+     * without `values` accepts any value of its type; one built with `values`
+     * accepts only those — so an empty list accepts nothing. (Both used to look
+     * alike as an empty set, which let e.g. `?include=anything` through on a
+     * serializer without relationships, where JSON:API requires a 400.)
+     */
+    restricted: boolean;
     constructor({ path, type, values, required, sanitize }: Parameter$opts);
     validate<V>(value: V): V;
 }

package/dist/types/packages/router/route/params/utils/validate-client-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reject `data.id` on a create request before the parameter tree runs, so it
+ * is answered with 403 (unsupported client-generated ID) rather than the 400
+ * an unknown member gets.
+ *
+ * @private
+ */
+export default function validateClientId(params: Record<string, unknown>): boolean;