diff --git a/packages/adapter/addon/index.js b/packages/adapter/addon/index.js index c7f1824eb5f..042f53daaec 100644 --- a/packages/adapter/addon/index.js +++ b/packages/adapter/addon/index.js @@ -1,4 +1,6 @@ /** + * + * @module @ember-data/adapter @main @ember-data/adapter */ @@ -56,6 +58,7 @@ import EmberObject from '@ember/object'; For an example of the implementation, see `RESTAdapter`, the included REST adapter. + @module @ember-data/adapter @class Adapter @extends EmberObject */ @@ -77,6 +80,7 @@ export default EmberObject.extend({ }); ``` + @deprecated @property defaultSerializer @type {String} */ diff --git a/packages/serializer/addon/index.js b/packages/serializer/addon/index.js index f2ef4d0e95c..a6138cc0961 100644 --- a/packages/serializer/addon/index.js +++ b/packages/serializer/addon/index.js @@ -1,6 +1,5 @@ /** @module @ember-data/serializer - @main @ember-data/serializer */ import EmberObject from '@ember/object'; diff --git a/packages/store/addon/-private/ts-interfaces/minimum-serializer-interface.ts b/packages/store/addon/-private/ts-interfaces/minimum-serializer-interface.ts index f6819d9c2d7..fd5a8cd6bb6 100644 --- a/packages/store/addon/-private/ts-interfaces/minimum-serializer-interface.ts +++ b/packages/store/addon/-private/ts-interfaces/minimum-serializer-interface.ts @@ -1,26 +1,26 @@ /** ## Overview - In order to properly manage and present your data, `EmberData` + In order to properly manage and present your data, EmberData needs to understand the structure of data it receives. `Serializers` convert data between the server's API format and - the format `EmberData` understands. + the format EmberData understands. - Data received from an API response is `"normalized"` into + Data received from an API response is **normalized** into [JSON:API](https://jsonapi.org/) (the format used internally - by `EmberData`), while data sent to an API is `"serialized"` + by EmberData), while data sent to an API is **serialized** into the format the API expects. ### Implementing a Serializer There are only two required serializer methods, one for - normalizing data from the server API format into `JSON:API`, and - another for serializing records via `Snapshot`s into the expected + normalizing data from the server API format into JSON:API, and + another for serializing records via `Snapshots` into the expected server API format. To implement a serializer, export a class that conforms to the structure - described by the [MinimumSerializerInterface](MinimumSerializerInterface) + described by the [MinimumSerializerInterface](/ember-data/release/classes/MinimumSerializerInterface) from the `app/serializers/` directory. An example is below. ```ts @@ -44,10 +44,10 @@ ``` - #### Serializer Resolution + ### Serializer Resolution `store.serializerFor(name)` will lookup serializers defined in - `app/serializers` and return an instance. If no serializer is found, an + `app/serializers/` and return an instance. If no serializer is found, an error will be thrown. `serializerFor` first attempts to find a serializer with an exact match on `name`, @@ -61,9 +61,9 @@ // app/serializers/application.js ``` - Most requests in `ember-data` are made with respect to a particular `type` (or `modelName`) + Most requests in EmberData are made with respect to a particular `type` (or `modelName`) (e.g., "get me the full collection of **books**" or "get me the **employee** whose id is 37"). We - refer to this as the *"primary"* resource `type`. + refer to this as the **primary** resource `type`. Typically `serializerFor` will be used to find a serializer with a name matching that of the primary resource `type` for the request, falling back to the `application` serializer for those types that @@ -80,11 +80,11 @@ ### Using a Serializer - Any serializer in `app/serializers` can be looked up by `name` using `store.serializerFor(name)`. + Any serializer in `app/serializers/` can be looked up by `name` using `store.serializerFor(name)`. ### Default Serializers - For applications whose APIs are *very close to* or *exactly* the `REST` or `JSON:API` + For applications whose APIs are *very close to* or *exactly* the **REST** format or **JSON:API** format the `@ember-data/serializer` package contains implementations these applications can extend. It also contains a simple `JSONSerializer` for serializing to/from very basic JSON objects. @@ -97,7 +97,6 @@ @module @ember-data/serializer @main @ember-data/serializer - @class MinimumSerializerInterface @public */ @@ -110,6 +109,17 @@ import { Dict } from './utils'; type OptionsHash = Dict; +/** + The following documentation describes the methods an application + serializer should implement with descriptions around when an + application might expect these methods to be called. + + Methods that are not required are marked as **optional**. + + @module @ember-data/serializer + @class MinimumSerializerInterface + @public +*/ interface Serializer { /** * This method is responsible for normalizing the value resolved from the promise returned @@ -128,18 +138,18 @@ interface Serializer { * * @method normalizeResponse * @public - * @param {Store} store - the store service that initiated the request being normalized - * @param {ShimModelClass} schema - An object with methods for accessing information about + * @param {Store} store The store service that initiated the request being normalized + * @param {ShimModelClass} schema An object with methods for accessing information about * the type, attributes and relationships of the primary type associated with the request. - * @param {JSONObject} rawPayload - The raw JSON response data returned from an API request. + * @param {JSONObject} rawPayload The raw JSON response data returned from an API request. * This correlates to the value the promise returned by the adapter method that performed * the request resolved to. - * @param {string|null} id - For a `findRecord` request, this is the `id` initially provided - * in the call to `store.findRecord`. Else this value is `null`. - * @param {'findRecord' | 'queryRecord' | 'findAll' | 'findBelongsTo' | 'findHasMany' | 'findMany' | 'query' | 'createRecord' | 'deleteRecord' | 'updateRecord'} requestType - The + * @param {string|null} id For a findRecord request, this is the id initially provided + * in the call to store.findRecord. Else this value is null. + * @param {'findRecord' | 'queryRecord' | 'findAll' | 'findBelongsTo' | 'findHasMany' | 'findMany' | 'query' | 'createRecord' | 'deleteRecord' | 'updateRecord'} requestType The * type of request the Adapter had been asked to perform. * - * @returns {JsonApiDocument} - a document following the structure of a [JSON:API Document](https://jsonapi.org/format/#document-structure). + * @returns {JsonApiDocument} a document following the structure of a JSON:API Document. */ normalizeResponse( store: Store, @@ -173,7 +183,7 @@ interface Serializer { * * @method serialize * @public - * @param {Snapshot} snapshot - A Snapshot for the record to serialize + * @param {Snapshot} snapshot A Snapshot for the record to serialize * @param {object} [options] */ serialize(snapshot: Snapshot, options?: OptionsHash): JSONObject; @@ -182,7 +192,7 @@ interface Serializer { * This method is intended to normalize data into a [JSON:API Document](https://jsonapi.org/format/#document-structure) * with a data member containing a single [Resource](https://jsonapi.org/format/#document-resource-objects). * - * - `type` should be formatted in the `singular` `dasherized` `lowercase` form + * - `type` should be formatted in the singular, dasherized and lowercase form * - `members` (the property names of attributes and relationships) should be formatted * to match their definition in the corresponding `Model` definition. Typically this * will be `camelCase`. @@ -196,7 +206,7 @@ interface Serializer { * * This method may be called when also using the `RESTSerializer` * when `serializer.pushPayload` is called by `store.pushPayload`. - * It is recommended to use `store.push` over `store.pushPayload` after normalizing + * However, it is recommended to use `store.push` over `store.pushPayload` after normalizing * the payload directly. * * Example: @@ -223,21 +233,22 @@ interface Serializer { * @method normalize [OPTIONAL] * @public * @optional - * @param {ShimModelClass} schema - An object with methods for accessing information about + * @param {ShimModelClass} schema An object with methods for accessing information about * the type, attributes and relationships of the primary type associated with the request. - * @param {JSONObject} rawPayload - Some raw JSON data to be normalized into a [JSON:API Resource](https://jsonapi.org/format/#document-resource-objects). - * @param {string} [prop] - When called by the `EmbeddedRecordsMixin` this param will be the + * @param {JSONObject} rawPayload Some raw JSON data to be normalized into a JSON:API Resource. + * @param {string} [prop] When called by the EmbeddedRecordsMixin this param will be the * property at which the object provided as rawPayload was found. - * @returns {SingleResourceDocument} - A [JSON:API Document](https://jsonapi.org/format/#document-structure) - * containing a single [JSON:API Resource](https://jsonapi.org/format/#document-resource-objects) + * @returns {SingleResourceDocument} A JSON:API Document + * containing a single JSON:API Resource * as its primary data. */ normalize?(schema: ShimModelClass, rawPayload: JSONObject, prop?: string): SingleResourceDocument; /** * When using `JSONAPIAdapter` or `RESTAdapter` this method is called - * by `adapter.updateRecord` and `adapter.createRecord` if `Serializer.serializeIntoHash` - * is not implemented. + * by `adapter.updateRecord` and `adapter.createRecord` if `serializer.serializeIntoHash` + * is implemented. If this method is not implemented, `serializer.serialize` + * will be called in this case. * * You can use this method to customize the root keys serialized into the payload. * The hash property should be modified by reference. @@ -265,11 +276,11 @@ interface Serializer { * @method serializeIntoHash [OPTIONAL] * @public * @optional - * @param hash - a top most object of the request payload onto + * @param hash A top most object of the request payload onto * which to append the serialized record - * @param {ShimModelClass} schema - An object with methods for accessing information about + * @param {ShimModelClass} schema An object with methods for accessing information about * the type, attributes and relationships of the primary type associated with the request. - * @param {Snapshot} snapshot - A Snapshot for the record to serialize + * @param {Snapshot} snapshot A Snapshot for the record to serialize * @param [options] * @returns {void} */ @@ -279,10 +290,14 @@ interface Serializer { * This method allows for normalization of data when `store.pushPayload` is called * and should be implemented if you want to use that method. * - * The output should be a [JSON:API Document](https://jsonapi.org/format/#document-structure) + * The method is responsible for pushing new data to the store using `store.push` + * once any necessary normalization has occurred, and no data in the store will be + * updated unless it does so. + * + * The normalized form pushed to the store should be a [JSON:API Document](https://jsonapi.org/format/#document-structure) * with the following additional restrictions: * - * - `type` should be formatted in the `singular` `dasherized` `lowercase` form + * - `type` should be formatted in the singular, dasherized and lowercase form * - `members` (the property names of attributes and relationships) should be formatted * to match their definition in the corresponding `Model` definition. Typically this * will be `camelCase`. @@ -308,12 +323,12 @@ interface Serializer { * @method pushPayload [OPTIONAL] * @public * @optional - * @param {Store} store - the store service that initiated the request being normalized - * @param {JSONObject} rawPayload - The raw JSON response data returned from an API request. + * @param {Store} store The store service that initiated the request being normalized + * @param {JSONObject} rawPayload The raw JSON response data returned from an API request. * This JSON should be in the API format expected by the serializer. - * @returns {JsonApiDocument} - a document following the structure of a [JSON:API Document](https://jsonapi.org/format/#document-structure) + * @returns {void} */ - pushPayload?(store: Store, rawPayload: JSONObject): JsonApiDocument; + pushPayload?(store: Store, rawPayload: JSONObject): void; } export default Serializer;