lumen-framework 3.1.0 → 4.0.0

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

@@ -1,418 +1,147 @@
-import type { Bundle$Namespace } from '../loader';
+import type { BundleNamespace } 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 { JsonApiDocument, JsonApiDocumentLinks, JsonApiResourceObject, JsonApiRelationshipObject, JsonApiRelationshipDocument } from '../jsonapi';
+import type { SerializerFields, SerializerOptions, SerializerRouted } from './interfaces';
+import { Scope } from '../controller/visibility';
 import type { Linkage } from './utils/load-linkage';
 import type { IncludeTree } from './utils/include-tree';
 /**
- * ## Overview
- *
- * The Serializer class is used to describe which attributes and relationships
- * to include for a particular resource.
- *
- * The attributes and relationships you declare in a Serializer will determine
- * the attributes and relationships that will be included in the response from
- * the resource that the Serializer represents.
- *
- * #### Attributes
- *
- * You can add attributes to your serializer using an array assigned to the
- * class property `attributes` like the example below.
- *
- * ```javascript
- * class UsersSerializer extends Serializer {
- *   attributes = [
- *     'name',
- *     'email',
- *     'username',
- *     'createdAt',
- *     'updatedAt'
- *   ];
- * }
- * ```
- *
- * Since the attributes required for a resource are declared ahead of time in a
- * Serializer, Lumen will optimize SQL queries for the resource to only include
- * what the Serializer needs to build the response.
- *
- * ```javascript
- * import { Serializer } from 'lumen-framework';
- *
- * class PostsSerializer extends Serializer {
- *   attributes = [
- *     'body',
- *     'title',
- *     'createdAt'
- *   ];
- * }
- *
- * export default PostsSerializer;
- * ```
- *
- * The Serializer above would result in resources returned from the `/posts`
- * endpoint to only include the `body`, `title`, and `createdAt` attributes. If
- * we wanted include an additional attribute such as `isPublic`, we would have
- * to add `'isPublic'` to the `attributes` property.
- *
- * ```javascript
- * import { Serializer } from 'lumen-framework';
- *
- * class PostsSerializer extends Serializer {
- *   attributes = [
- *     'body',
- *     'title',
- *     'isPublic',
- *     'createdAt'
- *   ];
- * }
- *
- * export default PostsSerializer;
- * ```
- *
- * #### Associations
- *
- * Similar to `attributes` you can declare associations by adding relationship
- * names to either the `hasOne` or `hasMany` property arrays on a Serializer.
- *
- * Serializers are not concerned with ownership when it comes to associations,
- * so both `hasOne` and `belongsTo` associations can be specified in the
- * `hasOne` array property.
- *
- * ```javascript
- * import { Model } from 'lumen-framework';
- *
- * class Post extends Model {
- *  static hasOne = {
- *    image: {
- *      inverse: 'post'
- *    }
- *  };
- *
- *  static hasMany = {
- *    tags: {
- *      inverse: 'posts',
- *      through: 'categorization'
- *    },
- *
- *    comments: {
- *      inverse: 'post'
- *    }
- *  };
- *
- *  static belongsTo = {
- *    user: {
- *      inverse: 'posts'
- *    }
- *  };
- * }
- *
- * export default Post;
- * ```
- *
- * To include the `user` and `image` associations in the response returned from
- * the `/posts` endpoint, we must specify both associations in the `hasOne`
- * property array of the Serializer.
- *
- * ```javascript
- * import { Serializer } from 'lumen-framework';
- *
- * class PostsSerializer extends Serializer {
- *  hasOne = [
- *    'user',
- *    'image'
- *  ];
- * }
- *
- * export default PostsSerializer;
- * ```
- *
- * If we wanted to also include the `tags` and `comments` in the response, we
- * have to add a `hasMany` array property containing `'tags'` and `'comments'`.
- *
- * ```javascript
- * import { Serializer } from 'lumen-framework';
- *
- * class PostsSerializer extends Serializer {
- *  hasOne = [
- *    'user',
- *    'image'
- *  ];
- *
- *  hasMany = [
- *    'tags',
- *    'comments'
- *  ];
- * }
- *
- * export default PostsSerializer;
- * ```
- *
- * You no longer need to specify that `tags` is a many to many relationship
- * using the `Categorization` model as a join table.
- *
- * #### Including Related Resources
- *
- * When requesting related resources for an endpoint, the included resource will
- * follow the serialization rules defined by the included resources Serializer.
- *
- * 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
- *
- * When a request specifies the fields that it would like included in the
- * response, the fields **MUST** be declared in the `attributes` property array
- * of the resources Serializer, or they will be ignored.
- *
- * #### Namespaces
- *
- * When using namespaces, you are not required to have a Serializer for each
- * resource as long as a Serializer for the given resource can be resolved
- * upstream.
- *
- * For example, if you have a `posts` resource and you decide to implement an
- * admin namespace, you only need to export an `AdminPostsSerializer` from
- * `app/serializers/admin/posts.js` if you want to specify different attributes
- * or relationships than the `PostsSerializer` exported from
- * `app/serializers/posts.js`.
- *
- * In the event that you do want to specify different attributes or
- * relationships that the `PostsSerializer` exported from
- * `app/serializers/posts.js`, you are not required to extend `PostsSerializer`.
- *
- * ```javascript
- * import { Serializer } from 'lumen-framework';
- *
- * class PostsSerializer extends Serializer {
- *   attributes = [
- *     'body',
- *     'title',
- *     'createdAt'
- *   ];
- *
- *   hasOne = [
- *     'user',
- *     'image'
- *   ];
- *
- *   hasMany = [
- *     'tags',
- *     'comments'
- *   ];
- * }
- *
- * export default PostsSerializer;
- * ```
- *
- * To add the `isPublic` attribute to the response payload of requests to a
- * `/admin/posts` endpoint we can do either of the following examples:
- *
- * ```javascript
- * // app/serializers/admin/posts.js
- * import PostsSerializer from 'app/serializers/posts';
- *
- * class AdminPostsSerializer extends PostsSerializer {
- *   attributes = [
- *     'body',
- *     'title',
- *     'isPublic',
- *     'createdAt'
- *   ];
- * }
- *
- * export default AdminPostsSerializer;
- * ```
- *
- * OR
- *
- * ```javascript
- * // app/serializers/admin/posts.js
- * import { Serializer } from 'lumen-framework';
- *
- * class AdminPostsSerializer extends Serializer {
- *   attributes = [
- *     'body',
- *     'title',
- *     'isPublic',
- *     'createdAt'
- *   ];
- *
- *   hasOne = [
- *     'user',
- *     'image'
- *   ];
- *
- *   hasMany = [
- *     'tags',
- *     'comments'
- *   ];
- * }
- *
- * export default AdminPostsSerializer;
- * ```
- *
- * Even with inheritance, the examples above are a tad repetitive. We can
- * improve this code by exporting constants from `app/serializers/posts.js`.
+ * The base class of an app's serializers. A serializer lists what a
+ * resource looks like in a JSON:API document: its `attributes`, and its
+ * relationships in `hasOne` (to-one, whether the model's relationship is
+ * `hasOne` or `belongsTo`) and `hasMany`.
  *
  * ```javascript
+ * // app/serializers/posts.js
  * import { Serializer } from 'lumen-framework';
  *
- * export const HAS_ONE = [
- *   'user',
- *   'image'
- * ];
- *
- * export const HAS_MANY = [
- *   'tags',
- *   'comments'
- * ];
- *
- * export const ATTRIBUTES = [
- *   'body',
- *   'title',
- *   'createdAt'
- * ];
- *
  * class PostsSerializer extends Serializer {
- *   hasOne = HAS_ONE;
- *   hasMany = HAS_MANY;
- *   attributes = ATTRIBUTES;
+ *   attributes = ['title', 'body', 'createdAt'];
+ *   hasOne = ['user'];
+ *   hasMany = ['comments', 'tags'];
  * }
  *
  * export default PostsSerializer;
  * ```
  *
- * If we choose to use inheritance, our code can look like this:
- *
- * ```javascript
- * // app/serializers/admin/posts.js
- * import PostsSerializer, { ATTRIBUTES } from 'app/serializers/posts';
- *
- * class AdminPostsSerializer extends PostsSerializer {
- *   attributes = [
- *     ...ATTRIBUTES,
- *     'isPublic'
- *   ];
- * }
- *
- * export default AdminPostsSerializer;
- * ```
- *
- * If we choose not use inheritance, our code can look like this:
- *
- * ```javascript
- * // app/serializers/admin/posts.js
- * import { Serializer } from 'lumen-framework';
- * import { HAS_ONE, HAS_MANY, ATTRIBUTES } from 'app/serializers/posts';
- *
- * class AdminPostsSerializer extends PostsSerializer {
- *   hasOne = HAS_ONE;
- *   hasMany = HAS_MANY;
- *
- *   attributes = [
- *     ...ATTRIBUTES,
- *     'isPublic'
- *   ];
- * }
- *
- * export default AdminPostsSerializer;
- * ```
- *
- * @class Serializer
- * @public
+ * Lumen loads only the columns a serializer needs. The lists are also what
+ * clients may ask for: `sort` and `filter` default to the attributes,
+ * `include` accepts the relationships (nested up to the controller's
+ * `maxIncludeDepth`), and `fields[posts]` may name any of them. Each included
+ * resource is formatted by its own type's serializer.
+ *
+ * A namespace may have its own serializer for a type
+ * (`app/serializers/admin/posts.js`), used for that type everywhere in the
+ * namespace, included resources too; without one, the root serializer is used,
+ * unless the namespace's `ApplicationController` sets `serializerFallback =
+ * false`. See the
+ * [serializers guide](https://github.com/nickschot/lux/blob/main/docs/guides/serializers.md).
  */
 declare class Serializer<T extends Model> {
     /**
-     * An Array of the `hasOne` or `belongsTo` relationships on a Serializer
-     * instance's Model to include in the
-     * `relationships` resource object of a serialized payload.
+     * The to-one relationships to serialize — the model's `hasOne` and
+     * `belongsTo` relationships alike.
      *
      * ```javascript
      * class PostsSerializer extends Serializer {
-     *   hasOne = [
-     *     'user'
-     *   ];
+     *   hasOne = ['user', 'image'];
      * }
      * ```
-     *
-     * @property hasOne
-     * @type {Array}
-     * @default []
-     * @public
      */
     hasOne: Array<string>;
     /**
-     * An Array of the `hasMany` relationships on a Serializer instance's Model to
-     * include in the `relationships` resource object of a serialized payload.
+     * The to-many relationships to serialize.
      *
-     * ```javscript
+     * ```javascript
      * class PostsSerializer extends Serializer {
-     *   hasMany = [
-     *     'comments'
-     *   ];
+     *   hasMany = ['comments', 'tags'];
      * }
      * ```
-     *
-     * @property hasMany
-     * @type {Array}
-     * @default []
-     * @public
      */
     hasMany: Array<string>;
     /**
-     * An array of the `attributes` on a Serializer instance's Model to include in
-     * the `attributes` resource object of a serialized payload.
+     * The model attributes to serialize, camelCase as on the model; documents
+     * dasherize them (`createdAt` → `created-at`). Each must be a column of the
+     * model's table: the app refuses to boot when one isn't (a getter, say).
      *
-     * ```javscript
+     * ```javascript
      * class PostsSerializer extends Serializer {
-     *   attributes = [
-     *     'body',
-     *     'title'
-     *   ];
+     *   attributes = ['title', 'body', 'createdAt'];
      * }
      * ```
-     *
-     * @property attributes
-     * @type {Array}
-     * @default []
-     * @public
      */
     attributes: Array<string>;
+    /**
+     * The `hasMany` relationships to serialize as links only: without resource
+     * linkage (`data`), so a resource with many related records stays small and
+     * their ids are not loaded. Clients load them from the relationship's
+     * `related` link when needed (ember-data does so for an async `hasMany`).
+     *
+     * ```javascript
+     * class PostsSerializer extends Serializer {
+     *   hasMany = ['comments', 'tags'];
+     *
+     *   linksOnly = ['comments'];
+     * }
+     * ```
+     *
+     * ```json
+     * "comments": {
+     *   "links": {
+     *     "self": "https://api.example.com/posts/1/relationships/comments",
+     *     "related": "https://api.example.com/posts/1/comments"
+     *   }
+     * }
+     * ```
+     *
+     * A relationship a request includes (`?include=comments`) keeps its `data`,
+     * since JSON:API requires every included resource to be linked from the
+     * document. So does one without a related endpoint where it is serialized
+     * (a namespace without a resource for the type), which would otherwise be
+     * left with nothing to load it from.
+     *
+     * Each name must be in `hasMany`, and have a related endpoint in at least
+     * one namespace that formats this type with this Serializer (the related
+     * type's resource routing `index`, this type's routing `show`), or the
+     * application refuses to boot.
+     */
+    linksOnly: Array<string>;
+    /**
+     * Allow `attributes`, `hasOne` or `hasMany` to name `type` or `id`.
+     *
+     * JSON:API forbids a field with either name: they share a namespace with
+     * the resource's own `type` and `id`. By default the application refuses
+     * to boot when a serializer lists one. Set this for a serializer whose
+     * clients already rely on such a field; the application then boots with a
+     * warning, and the field is sent as before:
+     *
+     * ```javascript
+     * class ReactionsSerializer extends Serializer {
+     *   attributes = ['type', 'createdAt'];
+     *
+     *   // `type` breaks JSON:API, but our clients read it.
+     *   allowReservedNames = true;
+     * }
+     * ```
+     */
+    allowReservedNames: boolean;
     /**
      * The resolved Model that a Serializer instance represents.
      *
-     * @property model
-     * @type {Model}
-     * @private
+     * @internal
      */
     model: ModelClass<T>;
     /**
      * A reference to the root Serializer for the namespace that a Serializer
      * instance is a member of.
      *
-     * @property parent
-     * @type {?Serializer}
-     * @private
+     * @internal
      */
     parent: Serializer<Model> | null;
     /**
      * The namespace that a Serializer instance is a member of.
      *
-     * @property namespace
-     * @type {String}
-     * @private
+     * @internal
      */
     namespace: string;
     /**
@@ -421,138 +150,182 @@ declare class Serializer<T extends Model> {
      * `serializerFor()` to serialize related resources in this Serializer's
      * namespace.
      *
-     * @property serializers
-     * @type {Map}
-     * @private
+     * @internal
      */
-    serializers?: Bundle$Namespace<Serializer<Model>>;
-    constructor({ model, parent, namespace }: Serializer$opts<T>);
+    serializers?: BundleNamespace<Serializer<Model>>;
+    constructor({ model, parent, namespace }: SerializerOptions<T>);
     /**
      * Transform an array of Model instances or a single Model instance into a
      * [JSON API](http://jsonapi.org) document object.
      *
-     * @method format
      *
-     * @param {Object} options - An options object used for building the
+     * @param options - An options object used for building the
      * returned [JSON API](http://jsonapi.org) document object.
      *
-     * @param {Model|Array} options.data - The Model instance or array of
+     * @param options.data - The Model instance or array of
      * Model instances to transform into the returned [JSON API](
      * http://jsonapi.org) document object.
      *
-     * @param {Object} options.links - An object containing links to include in
+     * @param options.links - An object containing links to include in
      * the top level links object of the returned [JSON API](http://jsonapi.org)
      * document object.
      *
-     * @param {String} options.domain - A string used to build links included in
+     * @param options.domain - A string used to build links included in
      * the resource and relationship objects in the returned [JSON API](
      * http://jsonapi.org) document object.
      *
-     * @param {Array} options.include - An array of relationship paths (e.g.
+     * @param 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
+     * @param options.fields - The request's sparse fieldsets, keyed by
+     * type. Each narrows the attributes and relationships of every resource of
+     * its type in the document; primary data was already loaded with its own.
+     *
+     * @param options.scope - The visibility rules of the request. Every
+     * related record loaded for the document — its linkage and `included` — is
+     * narrowed by them; primary data was already loaded through them.
+     *
+     * @param options.meta - Top level meta information of the returned
+     * document (`{ total }` for a page of a collection), if any.
+     *
+     * @param 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
+     * @param options.routed - Whether the application serves a path
+     * (`/posts/:dynamic/relationships/user`). A relationship is only given the
+     * links of the endpoints it is served by, since JSON:API requires every
+     * relationship `self` link to be served. Without it, none are.
+     *
+     * @returns Resolves with a [JSON API](http://jsonapi.org) document
      * object.
      *
-     * @private
+     * @internal
      */
-    format({ data, links, domain, include, namespace }: {
+    format({ data, meta, links, domain, include, fields, scope, namespace, routed }: {
         data: T | Array<T>;
-        links: JSONAPI$DocumentLinks;
+        meta?: JsonApiDocument['meta'];
+        links: JsonApiDocumentLinks;
         domain: string;
         include: Array<string>;
+        fields?: SerializerFields;
+        scope?: Scope;
         namespace?: string;
-    }): Promise<JSONAPI$Document>;
+        routed?: SerializerRouted;
+    }): Promise<JsonApiDocument>;
     /**
      * Transform a single Model instance into a [JSON API](http://jsonapi.org)
-     * resource object.
+     * resource object. Its attributes are the ones loaded on `item`, declared by
+     * this Serializer and kept by the request's fieldset for its type; its
+     * relationships, those declared and kept, are built from `linkage`,
+     * batch-loaded by `loadLinkage()`, without touching the database.
      *
-     * 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
+     * @param options - An options object used for building the returned
      * [JSON API](http://jsonapi.org) resource object.
      *
-     * @param {Model} options.item - The Model instance to transform into the
+     * @param options.item - The Model instance to transform into the
      * returned [JSON API](http://jsonapi.org) resource object.
      *
-     * @param {Object} options.links - An object containing links to include in
+     * @param options.links - An object containing links to include in
      * the top level links object of the returned [JSON API](http://jsonapi.org)
      * resource object.
      *
-     * @param {String} options.domain - A string used to build links included in
+     * @param options.domain - A string used to build links included in
      * 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 the relationship keys whose
-     * related records should be collected into `options.related`.
-     *
-     * @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 options.linkage - The resource linkage (related primary
+     * keys per relationship key) to serialize relationships from.
      *
-     * @param {Object} options.linkage - Pre-loaded resource linkage (related
-     * primary keys per relationship key) to serialize relationships from.
+     * @param options.fields - The request's sparse fieldsets, keyed by
+     * type. Only the one for this resource's type applies.
      *
-     * @param {String} options.namespace - The namespace to build links in.
+     * @param 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
+     * @param options.routed - Whether the application serves a path;
+     * see `format()`.
+     *
+     * @param options.linksOnly - The relationships to serialize without
+     * resource linkage; see `linksOnlyFor()`.
+     *
+     * @returns Resolves with a [JSON API](http://jsonapi.org) resource
      * object.
      *
-     * @private
+     * @internal
      */
-    formatOne({ item, links, domain, include, related, linkage, namespace }: {
+    formatOne({ item, links, domain, linkage, fields, namespace, routed, linksOnly }: {
         item: T;
         links?: boolean;
         domain: string;
-        include?: Array<string>;
-        related?: Map<string, Array<Model>>;
         linkage?: Linkage;
+        fields?: SerializerFields;
         namespace?: string;
-    }): Promise<JSONAPI$ResourceObject>;
+        routed?: SerializerRouted;
+        linksOnly?: Set<string>;
+    }): Promise<JsonApiResourceObject>;
     /**
-     * Transform a single Model instance into a [JSON API](http://jsonapi.org)
-     * relationship object.
-     *
-     * @method formatRelationship
-     *
-     * @param {Model} item - The Model instance to transform into the returned
-     * [JSON API](http://jsonapi.org) relationship object.
-     *
-     * @param {String} domain - A string used to build links included in the
-     * returned [JSON API](http://jsonapi.org) relationship object.
+     * The document a relationship endpoint (`/posts/1/relationships/user`)
+     * responds with: the relationship of `item` named `name` as resource
+     * linkage, narrowed by `scope` like any other linkage, and its links.
      *
-     * @return {Object} A [JSON API](http://jsonapi.org) relationship object.
+     * @internal
+     */
+    formatRelationship({ item, name, domain, scope, namespace, routed }: {
+        item: T;
+        name: string;
+        domain: string;
+        scope?: Scope;
+        namespace?: string;
+        routed?: SerializerRouted;
+    }): Promise<JsonApiRelationshipDocument>;
+    /**
+     * The relationships of `linksOnly` to serialize without resource linkage at
+     * one level of a document, whose include tree is `tree`: those not included
+     * there (an included resource must be linked from the document) and with a
+     * related endpoint in `namespace` to load them from.
      *
-     * @private
+     * @internal
      */
-    formatRelationship(item: Model, domain: string, namespace?: string): JSONAPI$RelationshipObject;
+    linksOnlyFor(tree: IncludeTree, namespace: string, routed: SerializerRouted): Set<string>;
+    /**
+     * The `links` of the relationship `name` of the resource `type`/`id`: a
+     * `self` link to its relationship endpoint (`/posts/1/relationships/user`)
+     * and a `related` link to its related endpoint (`/posts/1/user`), each when
+     * the application serves it in `namespace` (JSON:API requires every
+     * relationship `self` link to be served). Without either the relationship
+     * has no links.
+     *
+     * A related resource's own URL (`/users/2`) is never a relationship's
+     * `related` link: that link must not change when the relationship's content
+     * does.
+     *
+     * @internal
+     */
+    relationshipLinksFor({ id, type, name, domain, routed, namespace }: {
+        id: string;
+        type: string;
+        name: string;
+        domain: string;
+        routed: SerializerRouted;
+        namespace: string;
+    }): Pick<JsonApiRelationshipObject, 'links'>;
     /**
      * 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 }`.
+     * linkage: `{ data }`, where `data` is an identifier (or `null`) for a
+     * to-one relationship and an array of them for a to-many one. Its links
+     * come from `relationshipLinksFor()`.
      *
-     * @method formatLinkage
-     * @private
+     * @internal
      */
-    formatLinkage(domain: string, type: string | undefined, linkage: Array<string> | string | null | undefined, namespace?: string): JSONAPI$RelationshipObject;
+    formatLinkage(type: string | undefined, linkage: Array<string> | string | null | undefined): JsonApiRelationshipObject;
     /**
      * Add `records` (instances of `model`) to `included` as resource objects,
      * then recurse into the relationships named in `tree`. Each is serialized by
@@ -561,17 +334,49 @@ declare class Serializer<T extends Model> {
      * 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
+     * @internal
      */
-    addIncluded({ model, records, tree, domain, included, namespace }: {
+    addIncluded({ model, records, tree, scope, domain, fields, routed, included, namespace }: {
         model: ModelClass;
         records: Array<Model>;
         tree: IncludeTree;
+        scope: Scope;
+        domain: string;
+        fields: SerializerFields;
+        routed: SerializerRouted;
+        included: Map<string, JsonApiResourceObject>;
+        namespace: string;
+    }): Promise<void>;
+    /**
+     * Load the records `linkage` points to through each relationship named in
+     * `tree` — one query per relationship, selecting the attributes their
+     * Serializer (narrowed by the request's `fields[type]`) will serialize —
+     * and add them to `included` with `addIncluded()`. Only the relationships in
+     * `names`, those the parent's Serializer exposes, are followed. The tree is
+     * walked in request order, so `included` is deterministic.
+     *
+     * @internal
+     */
+    includeRelated({ model, names, linkage, tree, scope, domain, fields, routed, included, namespace }: {
+        model: ModelClass;
+        names: Array<string>;
+        linkage: Map<string, Linkage>;
+        tree: IncludeTree;
+        scope: Scope;
         domain: string;
-        included: Map<string, JSONAPI$ResourceObject>;
+        fields: SerializerFields;
+        routed: SerializerRouted;
+        included: Map<string, JsonApiResourceObject>;
         namespace: string;
     }): Promise<void>;
+    /**
+     * The attributes to load for included resources of `model`: those its
+     * Serializer in `namespace` declares, narrowed to the request's
+     * `fields[type]` when there is one — possibly to none.
+     *
+     * @internal
+     */
+    attributesFor(model: ModelClass, namespace: string, fields: SerializerFields): Array<string>;
     /**
      * Resolve the Serializer for `model` in `namespace` (this Serializer's by
      * default), the way a namespaced Controller resolves its own:
@@ -584,13 +389,17 @@ declare class Serializer<T extends Model> {
      * namespace is the root one whenever it is a namespaced Controller's
      * fallback.
      *
-     * @method serializerFor
-     * @private
+     * @internal
      */
     serializerFor(model: ModelClass, namespace?: string): Serializer<Model>;
+    /** @internal */
+    linkFor(domain: string, type: string, id: string, namespace?: string): string;
     /**
-     * @private
+     * The path of the resource `type`/`id` in `namespace`.
+     *
+     * @internal
      */
-    linkFor(domain: string, type: string, id: string, namespace?: string): string;
+    pathFor(type: string, id: string, namespace?: string): string;
 }
 export default Serializer;
+export type { SerializerOptions } from './interfaces';