lumen-framework 3.0.2 → 3.1.0

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

@@ -1,6 +1,9 @@
+import type { Bundle$Namespace } from '../loader';
 import type { Model, ModelClass } from '../database';
 import type { JSONAPI$Document, JSONAPI$DocumentLinks, JSONAPI$ResourceObject, JSONAPI$RelationshipObject } from '../jsonapi';
 import type { Serializer$opts } from './interfaces';
+import type { Linkage } from './utils/load-linkage';
+import type { IncludeTree } from './utils/include-tree';
 /**
  * ## Overview
  *
@@ -155,6 +158,17 @@ import type { Serializer$opts } from './interfaces';
  * If we request that the `posts` association is included from the `/users`
  * endpoint, we will only get the `attributes` that the `PostsSerializer` has
  * defined even though the response is processed by the `UsersSerializer`.
+ * The same goes for relationships: each included resource carries the
+ * `relationships` its own Serializer declares in `hasOne` and `hasMany`.
+ *
+ * Included resources follow the request's namespace: from `/admin/posts`,
+ * included comments are serialized by `AdminCommentsSerializer` when it
+ * exists and by `CommentsSerializer` otherwise (the same fallback a
+ * namespaced Controller uses), and their links point into `/admin`.
+ *
+ * Relationship paths may be nested, e.g. `/posts?include=comments.user`, up
+ * to the controller's `maxIncludeDepth` (3 by default). The intermediate
+ * resources (the comments) are included along with the leaves (their users).
  *
  * #### Sparse Fieldsets
  *
@@ -401,6 +415,17 @@ declare class Serializer<T extends Model> {
      * @private
      */
     namespace: string;
+    /**
+     * Every Serializer of the application, keyed by namespaced path (`posts`,
+     * `admin/posts`). Attached once all of them are built, and used by
+     * `serializerFor()` to serialize related resources in this Serializer's
+     * namespace.
+     *
+     * @property serializers
+     * @type {Map}
+     * @private
+     */
+    serializers?: Bundle$Namespace<Serializer<Model>>;
     constructor({ model, parent, namespace }: Serializer$opts<T>);
     /**
      * Transform an array of Model instances or a single Model instance into a
@@ -423,25 +448,40 @@ declare class Serializer<T extends Model> {
      * the resource and relationship objects in the returned [JSON API](
      * http://jsonapi.org) document object.
      *
-     * @param {Array} options.include - An array of strings containing the
-     * relationship keys that should be added to the top level included object of
-     * the returned [JSON API](http://jsonapi.org) document object.
+     * @param {Array} options.include - An array of relationship paths (e.g.
+     * `'comments'` or `'comments.user'`) whose resources should be added to the
+     * top level included object of the returned [JSON API](http://jsonapi.org)
+     * document object. Intermediate resources of a nested path are included too.
+     *
+     * @param {String} options.namespace - The namespace of the request, i.e. of
+     * the Controller handling it. Every link in the document is built in it, and
+     * included resources are serialized by their Serializer in it (falling back
+     * to the root). Defaults to this Serializer's namespace — which is the root
+     * one when a namespaced Controller has no Serializer of its own, so the
+     * Controller passes its namespace explicitly.
      *
      * @return {Promise} Resolves with a [JSON API](http://jsonapi.org) document
      * object.
      *
      * @private
      */
-    format({ data, links, domain, include }: {
+    format({ data, links, domain, include, namespace }: {
         data: T | Array<T>;
         links: JSONAPI$DocumentLinks;
         domain: string;
         include: Array<string>;
+        namespace?: string;
     }): Promise<JSONAPI$Document>;
     /**
      * Transform a single Model instance into a [JSON API](http://jsonapi.org)
      * resource object.
      *
+     * Relationships are serialized in one of two ways. By default each one is
+     * read from the Model instance (for primary data the query has already
+     * loaded them). When `linkage` is given — as it is for included resources,
+     * whose relationships are batch-loaded by `addIncluded()` — the resource
+     * linkage is built from it instead, without touching the database.
+     *
      * @method formatOne
      *
      * @param {Object} options - An options object used for building the returned
@@ -458,30 +498,33 @@ declare class Serializer<T extends Model> {
      * the top level links object or relationship links objects in the returned
      * [JSON API](http://jsonapi.org) resource object.
      *
-     * @param {Array} options.include - An array of strings containing the
-     * relationship keys that should be added to the top level included object of
-     * a [JSON API](http://jsonapi.org) document object.
+     * @param {Array} options.include - An array of the relationship keys whose
+     * related records should be collected into `options.related`.
      *
-     * @param {Array} options.included - An array of [JSON API](
-     * http://jsonapi.org) resource objects that will be added to the top level
-     * included array of a [JSON API](http://jsonapi.org) document object.
+     * @param {Map} options.related - Collects, per relationship key in
+     * `options.include`, the related Model instances that belong in the top
+     * level included object of a [JSON API](http://jsonapi.org) document object.
      *
-     * @param {Boolean} options.formatRelationships - Wether or not
-     * relationships should be formatted and included in the returned
-     * [JSON API](http://jsonapi.org) resource object.
+     * @param {Object} options.linkage - Pre-loaded resource linkage (related
+     * primary keys per relationship key) to serialize relationships from.
+     *
+     * @param {String} options.namespace - The namespace to build links in.
+     * Defaults to this Serializer's; included resources pass the namespace of
+     * the request, so every link in a document points into the same namespace.
      *
      * @return {Promise} Resolves with a [JSON API](http://jsonapi.org) resource
      * object.
      *
      * @private
      */
-    formatOne({ item, links, domain, include, included, formatRelationships }: {
+    formatOne({ item, links, domain, include, related, linkage, namespace }: {
         item: T;
         links?: boolean;
         domain: string;
-        include: Array<string>;
-        included: Array<JSONAPI$ResourceObject>;
-        formatRelationships?: boolean;
+        include?: Array<string>;
+        related?: Map<string, Array<Model>>;
+        linkage?: Linkage;
+        namespace?: string;
     }): Promise<JSONAPI$ResourceObject>;
     /**
      * Transform a single Model instance into a [JSON API](http://jsonapi.org)
@@ -489,33 +532,65 @@ declare class Serializer<T extends Model> {
      *
      * @method formatRelationship
      *
-     * @param {Object} options - An options object used for building the returned
+     * @param {Model} item - The Model instance to transform into the returned
      * [JSON API](http://jsonapi.org) relationship object.
      *
-     * @param {Model} options.item - The Model instance to transform into the
+     * @param {String} domain - A string used to build links included in the
      * returned [JSON API](http://jsonapi.org) relationship object.
      *
-     * @param {String} options.domain - A string used to build links included in
-     * the returned [JSON API](http://jsonapi.org) relationship object.
-     *
-     * @param {Array} options.include - An array of strings containing the
-     * relationship keys that should be added to the top level included object of
-     * a [JSON API](http://jsonapi.org) document object.
+     * @return {Object} A [JSON API](http://jsonapi.org) relationship object.
      *
-     * @param {Array} options.included - An array of [JSON API](
-     * http://jsonapi.org) resource objects that will be added to the top level
-     * included array of a [JSON API](http://jsonapi.org) document object.
-     *
-     * @return {Promise} Resolves with a [JSON API](http://jsonapi.org)
-     * relationship object.
+     * @private
+     */
+    formatRelationship(item: Model, domain: string, namespace?: string): JSONAPI$RelationshipObject;
+    /**
+     * Build a [JSON API](http://jsonapi.org) relationship object from resource
+     * linkage, in the same shape `formatRelationship()` produces from Model
+     * instances: to-one relationships carry a `links` object, to-many ones only
+     * `data`, and a missing to-one relationship is `{ data: null }`.
      *
+     * @method formatLinkage
+     * @private
+     */
+    formatLinkage(domain: string, type: string | undefined, linkage: Array<string> | string | null | undefined, namespace?: string): JSONAPI$RelationshipObject;
+    /**
+     * Add `records` (instances of `model`) to `included` as resource objects,
+     * then recurse into the relationships named in `tree`. Each is serialized by
+     * `model`'s Serializer in this Serializer's namespace (`serializerFor()`), so
+     * `/admin/posts?include=comments` uses `AdminCommentsSerializer` when there
+     * is one and `CommentsSerializer` otherwise. The relationships of every level
+     * are batch-loaded with one query per relationship, not one per record.
+     *
+     * @method addIncluded
      * @private
      */
-    formatRelationship({ item, domain, include, included }: {
-        item: Model;
+    addIncluded({ model, records, tree, domain, included, namespace }: {
+        model: ModelClass;
+        records: Array<Model>;
+        tree: IncludeTree;
         domain: string;
-        include: boolean;
-        included: Array<JSONAPI$ResourceObject>;
-    }): Promise<JSONAPI$RelationshipObject>;
+        included: Map<string, JSONAPI$ResourceObject>;
+        namespace: string;
+    }): Promise<void>;
+    /**
+     * Resolve the Serializer for `model` in `namespace` (this Serializer's by
+     * default), the way a namespaced Controller resolves its own:
+     * `admin/comments` if it exists, otherwise the closest ancestor namespace's,
+     * down to the root `comments` Serializer. Falls back to `model.serializer`
+     * when this Serializer was not created by an application (e.g. in
+     * isolation).
+     *
+     * Pass the request's namespace when there is one: a Serializer's own
+     * namespace is the root one whenever it is a namespaced Controller's
+     * fallback.
+     *
+     * @method serializerFor
+     * @private
+     */
+    serializerFor(model: ModelClass, namespace?: string): Serializer<Model>;
+    /**
+     * @private
+     */
+    linkFor(domain: string, type: string, id: string, namespace?: string): string;
 }
 export default Serializer;

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

@@ -0,0 +1,29 @@
+import type { Model, ModelClass } from '../../database';
+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
+ */
+export type IncludeTree = Map<string, IncludeTree>;
+/**
+ * Parse relationship paths (`['comments', 'comments.user', 'user']`) into an
+ * include tree. Every prefix of a path is part of the tree, because JSON:API
+ * requires the intermediate resources of a multi-part path to be included
+ * along with its leaves (`comments.user` includes the comments too).
+ *
+ * @private
+ */
+export declare function createIncludeTree(paths?: Array<string>): IncludeTree;
+/**
+ * Enumerate every include path available from `names` (relationships of
+ * `model`), down to `depth` levels. Each level continues with the relationships
+ * declared by the related model's serializer as `serializerFor` resolves it —
+ * the same one its included resources are serialized with (namespaced, with a
+ * fallback to the root). Used to build the allowed values of the `include`
+ * parameter.
+ *
+ * @private
+ */
+export declare function enumerateIncludePaths(model: ModelClass, names: Array<string>, depth: number, serializerFor?: (model: ModelClass) => Serializer<Model> | undefined): Array<string>;

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

@@ -0,0 +1,22 @@
+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
+ */
+export type Linkage = Record<string, Array<string> | string | null>;
+/**
+ * Batch-load the resource linkage of the relationships `names` for every one of
+ * `records` (all instances of `model`), keyed by each record's primary key.
+ *
+ * This is what lets included resources carry `relationships` without an N+1:
+ * it issues at most one query per relationship — and a single query for all
+ * belongs-to relationships, whose foreign keys live on `model` itself — however
+ * many records there are. The queries mirror the lazy relationship getters in
+ * `database/relationship/utils/getters.ts`, which remain the source of truth.
+ *
+ * @private
+ */
+export default function loadLinkage(model: ModelClass, records: Array<Model>, names: Array<string>): Promise<Map<string, Linkage>>;

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

@@ -22,6 +22,7 @@ declare class Server {
 export default Server;
 export { REQUEST_METHODS, getDomain } from './request';
 export { default as createServerError } from './utils/create-server-error';
-export type { Server$config } from './interfaces';
+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 type { Response } from './response/interfaces';

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

@@ -13,6 +13,11 @@ export type Server$opts = Server$config & {
     logger: Logger;
     router: Router;
 };
+export type Server$ErrorSource = {
+    pointer?: string;
+    parameter?: string;
+};
 export interface Server$Error extends Error {
     statusCode: number;
+    source?: Server$ErrorSource;
 }

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

@@ -0,0 +1,10 @@
+import type { Server$ErrorSource } from '../interfaces';
+/**
+ * Map an internal parameter path to a JSON:API error `source`. Paths under
+ * `data` are request document members and become a JSON Pointer
+ * (`data.attributes.isPublic` -> `/data/attributes/is-public`); anything else
+ * is a query parameter (`page.size` -> `page[size]`).
+ *
+ * @private
+ */
+export default function sourceFor(path: string): Server$ErrorSource;

package/dist/types/packages/server/utils/validate-accept.d.ts

@@ -1,4 +1,8 @@
 /**
+ * JSON:API 1.0: respond 406 if the Accept header contains the JSON:API media
+ * type and *all* instances of it are modified with media type parameters.
+ * An Accept header without the JSON:API media type is left alone.
+ *
  * @private
  */
-export default function validateAccept(contentType?: string): true;
+export default function validateAccept(accept?: string): true;

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

@@ -1,4 +1,8 @@
 /**
+ * JSON:API 1.0: respond 415 if the Content-Type is the JSON:API media type
+ * with any media type parameters. A missing or different Content-Type is
+ * also answered with 415, since that is the only type the server accepts.
+ *
  * @private
  */
 export default function validateContentType(contentType?: string): true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumen-framework",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Build scalable, Node.js-powered REST APIs with almost no code.",
   "keywords": [
     "mvc",

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

@@ -1,4 +0,0 @@
-/**
- * @private
- */
-export default function hasMediaType(value: string): boolean;