@ember-data-mirror/serializer 5.6.0-beta.0 → 5.6.0-beta.1

package/unstable-preview-types/index.d.ts

@@ -1,277 +1,115 @@
+/// <reference path="./json.d.ts" />
+/// <reference path="./transform.d.ts" />
 /// <reference path="./json-api.d.ts" />
 /// <reference path="./rest.d.ts" />
-/// <reference path="./transform.d.ts" />
-/// <reference path="./json.d.ts" />
-/// <reference path="./-private/utils.d.ts" />
-/// <reference path="./-private/embedded-records-mixin.d.ts" />
-/// <reference path="./-private/transforms/number.d.ts" />
-/// <reference path="./-private/transforms/boolean.d.ts" />
-/// <reference path="./-private/transforms/boolean.type-test.d.ts" />
-/// <reference path="./-private/transforms/date.d.ts" />
-/// <reference path="./-private/transforms/string.d.ts" />
-/// <reference path="./-private/transforms/transform.d.ts" />
 declare module '@ember-data-mirror/serializer' {
   /**
-    ## Overview
+  ## Overview
   
-    <blockquote style="margin: 1em; padding: .1em 1em .1em 1em; border-left: solid 1em #E34C32; background: #e0e0e0;">
-    <p>
-      ⚠️ <strong>This is LEGACY documentation</strong> for a feature that is no longer encouraged to be used.
-      If starting a new app or thinking of implementing a new serializer, consider writing a
-      <a href="/ember-data/release/classes/%3CInterface%3E%20Handler">Handler</a> instead to be used with the <a href="https://github.com/emberjs/data/tree/main/packages/request#readme">RequestManager</a>
-    </p>
-    </blockquote>
+  <blockquote style="margin: 1em; padding: .1em 1em .1em 1em; border-left: solid 1em #E34C32; background: #e0e0e0;">
+  <p>
+  ⚠️ <strong>This is LEGACY documentation</strong> for a feature that is no longer encouraged to be used.
+  If starting a new app or thinking of implementing a new serializer, consider writing a
+  <a href="/ember-data/release/classes/%3CInterface%3E%20Handler">Handler</a> instead to be used with the <a href="https://github.com/emberjs/data/tree/main/packages/request#readme">RequestManager</a>
+  </p>
+  </blockquote>
   
-    In order to properly manage and present your data, EmberData
-    needs to understand the structure of data it receives.
+  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.
+  `Serializers` convert data between the server's API format and
+  the format EmberData understands.
   
-    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**
-    into the format the API expects.
+  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**
+  into the format the API expects.
   
-    ### Implementing a Serializer
+  ### 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 `Snapshots` into the expected
-    server API format.
+  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 `Snapshots` into the expected
+  server API format.
   
-    To implement a serializer, export a class that conforms to the structure
-    described by [<Interface> Serializer](/ember-data/release/classes/%3CInterface%3E%20Serializer)
-    from the `app/serializers/` directory. An example is below.
+  To implement a serializer, export a class that conforms to the structure
+  described by {@link MinimumSerializerInterface}
+  from the `app/serializers/` directory. An example is below.
   
-    ```ts
-    import EmberObject from '@ember/object';
+  ```ts
+  import EmberObject from '@ember/object';
   
-    export default class ApplicationSerializer extends EmberObject {
-      normalizeResponse(store, schema, rawPayload) {
-        return rawPayload;
-      }
+  export default class ApplicationSerializer extends EmberObject {
+  normalizeResponse(store, schema, rawPayload) {
+  return rawPayload;
+  }
   
-      serialize(snapshot, options) {
-        const serializedResource = {
-          id: snapshot.id,
-          type: snapshot.modelName,
-          attributes: snapshot.attributes()
-        };
+  serialize(snapshot, options) {
+  const serializedResource = {
+  id: snapshot.id,
+  type: snapshot.modelName,
+  attributes: snapshot.attributes()
+  };
   
-        return serializedResource;
-      }
-    }
-   ```
+  return serializedResource;
+  }
+  }
+  ```
   
   
-    ### Serializer Resolution
+  ### Serializer Resolution
   
-    `store.serializerFor(name)` will lookup serializers defined in
-    `app/serializers/` and return an instance. If no serializer is found, an
-    error will be thrown.
+  `store.serializerFor(name)` will lookup serializers defined in
+  `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`,
-    then falls back to checking for the presence of a serializer named `application`.
+  `serializerFor` first attempts to find a serializer with an exact match on `name`,
+  then falls back to checking for the presence of a serializer named `application`.
   
-    ```ts
-    store.serializerFor('author');
+  ```ts
+  store.serializerFor('author');
   
-    // lookup paths (in order) =>
-    //   app/serializers/author.js
-    //   app/serializers/application.js
-    ```
+  // lookup paths (in order) =>
+  //   app/serializers/author.js
+  //   app/serializers/application.js
+  ```
   
-    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`.
+  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`.
   
-    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
-    do not have a defined serializer. This is often described as a `per-model` or `per-type` strategy
-    for defining serializers. However, because APIs rarely format payloads per-type but rather
-    per-API-version, this may not be a desired strategy.
+  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
+  do not have a defined serializer. This is often described as a `per-model` or `per-type` strategy
+  for defining serializers. However, because APIs rarely format payloads per-type but rather
+  per-API-version, this may not be a desired strategy.
   
-    It is recommended that applications define only a single `application` adapter and serializer
-    where possible.
+  It is recommended that applications define only a single `application` adapter and serializer
+  where possible.
   
-    If you have multiple API formats and the per-type strategy is not viable, one strategy is to
-    write an `application` adapter and serializer that make use of `options` to specify the desired
-    format when making a request.
+  If you have multiple API formats and the per-type strategy is not viable, one strategy is to
+  write an `application` adapter and serializer that make use of `options` to specify the desired
+  format when making a request.
   
-    ### Using a Serializer
+  ### 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
+  ### Default Serializers
   
-    For applications whose APIs are *very close to* or *exactly* the **REST** format or **JSON:API**
-    format the `@ember-data-mirror/serializer` package contains implementations these applications can
-    extend. It also contains a simple `JSONSerializer` for serializing to/from very basic JSON objects.
+  For applications whose APIs are *very close to* or *exactly* the **REST** format or **JSON:API**
+  format the `@ember-data-mirror/serializer` package contains implementations these applications can
+  extend. It also contains a simple `JSONSerializer` for serializing to/from very basic JSON objects.
   
-    Many applications will find writing their own serializer to be more performant and less
-    complex than extending these classes even when their API format is very close to that expected
-    by these serializers.
+  Many applications will find writing their own serializer to be more performant and less
+  complex than extending these classes even when their API format is very close to that expected
+  by these serializers.
   
-    It is recommended that apps write their own serializer to best suit the needs of their API and
-    application.
+  It is recommended that apps write their own serializer to best suit the needs of their API and
+  application.
   
-    @module @ember-data-mirror/serializer
-    @main @ember-data-mirror/serializer
+  @module
   */
-  import EmberObject from '@ember/object';
-  import type Store from '@ember-data-mirror/store';
-  import type { ModelSchema } from '@ember-data-mirror/store/types';
-  import type { EmptyResourceDocument, SingleResourceDocument } from '@warp-drive-mirror/core-types/spec/json-api-raw';
-  /**
-    > ⚠️ CAUTION you likely want the docs for [<Interface> Serializer](/ember-data/release/classes/%3CInterface%3E%20Serializer)
-    > as extending this abstract class is unnecessary.
-  
-    `Serializer` is an abstract base class that you may override in your
-    application to customize it for your backend. The minimum set of methods
-    that you should implement is:
-  
-      * `normalizeResponse()`
-      * `serialize()`
-  
-    And you can optionally override the following methods:
+  export { Serializer as default } from "@warp-drive-mirror/legacy/serializer";
   
-      * `normalize()`
-  
-    For an example implementation, see
-    [JSONSerializer](JSONSerializer), the included JSON serializer.
-  
-    @class Serializer
-    @public
-    @extends Ember.EmberObject
-  */
-  export default class extends EmberObject {
-      store: Store;
-      /**
-        The `store` property is the application's `store` that contains
-        all records. It can be used to look up serializers for other model
-        types that may be nested inside the payload response.
-    
-        Example:
-    
-        ```js
-        Serializer.extend({
-          extractRelationship(relationshipModelName, relationshipHash) {
-            let modelClass = this.store.modelFor(relationshipModelName);
-            let relationshipSerializer = this.store.serializerFor(relationshipModelName);
-            return relationshipSerializer.normalize(modelClass, relationshipHash);
-          }
-        });
-        ```
-    
-        @property store
-        @type {Store}
-        @public
-      */
-      /**
-        The `normalizeResponse` method is used to normalize a payload from the
-        server to a JSON-API Document.
-    
-        http://jsonapi.org/format/#document-structure
-    
-        Example:
-    
-        ```js
-        Serializer.extend({
-          normalizeResponse(store, primaryModelClass, payload, id, requestType) {
-            if (requestType === 'findRecord') {
-              return this.normalize(primaryModelClass, payload);
-            } else {
-              return payload.reduce(function(documentHash, item) {
-                let { data, included } = this.normalize(primaryModelClass, item);
-                documentHash.included.push(...included);
-                documentHash.data.push(data);
-                return documentHash;
-              }, { data: [], included: [] })
-            }
-          }
-        });
-        ```
-    
-        @since 1.13.0
-        @method normalizeResponse
-        @public
-        @param {Store} store
-        @param {Model} primaryModelClass
-        @param {Object} payload
-        @param {String|Number} id
-        @param {String} requestType
-        @return {Object} JSON-API Document
-      */
-      /**
-        The `serialize` method is used when a record is saved in order to convert
-        the record into the form that your external data source expects.
-    
-        `serialize` takes an optional `options` hash with a single option:
-    
-        - `includeId`: If this is `true`, `serialize` should include the ID
-          in the serialized object it builds.
-    
-        Example:
-    
-        ```js
-        Serializer.extend({
-          serialize(snapshot, options) {
-            let json = {
-              id: snapshot.id
-            };
-    
-            snapshot.eachAttribute((key, attribute) => {
-              json[key] = snapshot.attr(key);
-            });
-    
-            snapshot.eachRelationship((key, relationship) => {
-              if (relationship.kind === 'belongsTo') {
-                json[key] = snapshot.belongsTo(key, { id: true });
-              } else if (relationship.kind === 'hasMany') {
-                json[key] = snapshot.hasMany(key, { ids: true });
-              }
-            });
-    
-            return json;
-          },
-        });
-        ```
-    
-        @method serialize
-        @public
-        @param {Snapshot} snapshot
-        @param {Object} [options]
-        @return {Object}
-      */
-      /**
-        The `normalize` method is used to convert a payload received from your
-        external data source into the normalized form `store.push()` expects. You
-        should override this method, munge the hash and return the normalized
-        payload.
-    
-        Example:
-    
-        ```js
-        Serializer.extend({
-          normalize(modelClass, resourceHash) {
-            let data = {
-              id:            resourceHash.id,
-              type:          modelClass.modelName,
-              attributes:    resourceHash
-            };
-            return { data: data };
-          }
-        })
-        ```
-    
-        @method normalize
-        @public
-        @param {Model} typeClass
-        @param {Object} hash
-        @return {Object}
-      */
-      normalize(_typeClass: ModelSchema, hash: Record<string, unknown>): SingleResourceDocument | EmptyResourceDocument;
-  }
-}
-//# sourceMappingURL=index.d.ts.map
+}