@ember-data-mirror/serializer 4.13.0-alpha.1

package/unstable-preview-types/json-api.d.ts

@@ -0,0 +1,527 @@
+declare module '@ember-data-mirror/serializer/json-api' {
+  export default JSONAPISerializer;
+  /**
+   * <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 adapter, 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 EmberData a Serializer is used to serialize and deserialize
+    records when they are transferred in and out of an external source.
+    This process involves normalizing property names, transforming
+    attribute values and serializing relationships.
+  
+    `JSONAPISerializer` supports the http://jsonapi.org/ spec and is the
+    serializer recommended by Ember Data.
+  
+    This serializer normalizes a JSON API payload that looks like:
+  
+    ```app/models/player.js
+    import Model, { attr, belongsTo } from '@ember-data-mirror/model';
+  
+    export default class Player extends Model {
+      @attr('string') name;
+      @attr('string') skill;
+      @attr('number') gamesPlayed;
+      @belongsTo('club') club;
+    }
+    ```
+  
+    ```app/models/club.js
+    import Model, { attr, hasMany } from '@ember-data-mirror/model';
+  
+    export default class Club extends Model {
+      @attr('string') name;
+      @attr('string') location;
+      @hasMany('player') players;
+    }
+    ```
+  
+    ```js
+      {
+        "data": [
+          {
+            "attributes": {
+              "name": "Benfica",
+              "location": "Portugal"
+            },
+            "id": "1",
+            "relationships": {
+              "players": {
+                "data": [
+                  {
+                    "id": "3",
+                    "type": "players"
+                  }
+                ]
+              }
+            },
+            "type": "clubs"
+          }
+        ],
+        "included": [
+          {
+            "attributes": {
+              "name": "Eusebio Silva Ferreira",
+              "skill": "Rocket shot",
+              "games-played": 431
+            },
+            "id": "3",
+            "relationships": {
+              "club": {
+                "data": {
+                  "id": "1",
+                  "type": "clubs"
+                }
+              }
+            },
+            "type": "players"
+          }
+        ]
+      }
+    ```
+  
+    to the format that the Ember Data store expects.
+  
+    ### Customizing meta
+  
+    Since a JSON API Document can have meta defined in multiple locations you can
+    use the specific serializer hooks if you need to customize the meta.
+  
+    One scenario would be to camelCase the meta keys of your payload. The example
+    below shows how this could be done using `normalizeArrayResponse` and
+    `extractRelationship`.
+  
+    ```app/serializers/application.js
+    import JSONAPISerializer from '@ember-data-mirror/serializer/json-api';
+  
+    export default class ApplicationSerializer extends JSONAPISerializer {
+      normalizeArrayResponse(store, primaryModelClass, payload, id, requestType) {
+        let normalizedDocument = super.normalizeArrayResponse(...arguments);
+  
+        // Customize document meta
+        normalizedDocument.meta = camelCaseKeys(normalizedDocument.meta);
+  
+        return normalizedDocument;
+      }
+  
+      extractRelationship(relationshipHash) {
+        let normalizedRelationship = super.extractRelationship(...arguments);
+  
+        // Customize relationship meta
+        normalizedRelationship.meta = camelCaseKeys(normalizedRelationship.meta);
+  
+        return normalizedRelationship;
+      }
+    }
+    ```
+  
+    @main @ember-data-mirror/serializer/json-api
+    @since 1.13.0
+    @class JSONAPISerializer
+    @public
+    @extends JSONSerializer
+  */
+  const JSONAPISerializer: Readonly<Readonly<typeof import("@ember-data-mirror/serializer").default> & (new (owner?: import("@ember/-internals/owner").default) => import(".").default) & {
+      primaryKey: string;
+      mergedProperties: Object;
+      applyTransforms(typeClass: Model, data: Object): Object;
+      normalizeResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeFindRecordResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeQueryRecordResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeFindAllResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeFindBelongsToResponse(store: Store, primaryModelClass: 
+      /**
+        Dasherizes and singularizes the model name in the payload to match
+        the format Ember Data uses internally for the model name.
+    
+        For example the key `posts` would be converted to `post` and the
+        key `studentAssesments` would be converted to `student-assesment`.
+    
+        @method modelNameFromPayloadKey
+        @public
+        @param {String} key
+        @return {String} the model's modelName
+      */
+      Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeFindHasManyResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeFindManyResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeQueryResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeCreateRecordResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeDeleteRecordResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeUpdateRecordResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeSaveResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, ...args: any[]): Object;
+      normalizeSingleResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string): Object;
+      normalizeArrayResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string): Object;
+      _normalizeResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, isSingle: boolean): Object;
+      normalize(modelClass: any, resourceHash: any): Object;
+      extractId(modelClass: Object, resourceHash: Object): string;
+      extractAttributes(modelClass: Object, resourceHash: Object): Object;
+      extractRelationship(relationshipModelName: Object, relationshipHash: Object): Object;
+      extractPolymorphicRelationship(relationshipModelName: Object, relationshipHash: Object, relationshipOptions: Object): Object;
+      extractRelationships(modelClass: Object, resourceHash: Object): Object;
+      modelNameFromPayloadKey(key: string): string;
+      normalizeRelationships(typeClass: any, hash: any): void;
+      normalizeUsingDeclaredMapping(modelClass: any, hash: any): void;
+      _getMappedKey(key: string, modelClass: any): string;
+      _canSerialize(key: string): boolean;
+      _mustSerialize(key: string): boolean;
+      shouldSerializeHasMany(snapshot: Snapshot, key: string, relationship: RelationshipSchema): boolean;
+      serialize(snapshot: Snapshot, options: Object): Object;
+      serializeIntoHash(hash: Object, typeClass: Model, snapshot: Snapshot, options: Object): void;
+      serializeAttribute(snapshot: Snapshot, json: Object, key: string, attribute: Object): void;
+      serializeBelongsTo(snapshot: Snapshot, json: Object, relationship: Object): void;
+      serializeHasMany(snapshot: Snapshot, json: Object, relationship: Object): void;
+      serializePolymorphicType(): void;
+      extractMeta(store: Store, modelClass: Model, payload: Object): any;
+      extractErrors(store: Store, typeClass: Model, payload: Object, id: (string | number)): Object;
+      keyForAttribute(key: string, method: string): string;
+      keyForRelationship(key: string, typeClass: string, method: string): string;
+      keyForLink(key: string, kind: string): string;
+      transformFor(attributeType: string, skipAssertion: boolean): Transform;
+  }> & (new (owner?: import("@ember-data-mirror/serializer/@ember/-internals/owner").default) => import(".").default) & {
+      /**
+        @method _normalizeDocumentHelper
+        @param {Object} documentHash
+        @return {Object}
+        @private
+      */
+      _normalizeDocumentHelper(documentHash: Object): Object;
+      /**
+        @method _normalizeRelationshipDataHelper
+        @param {Object} relationshipDataHash
+        @return {Object}
+        @private
+      */
+      _normalizeRelationshipDataHelper(relationshipDataHash: Object): Object;
+      /**
+        @method _normalizeResourceHelper
+        @param {Object} resourceHash
+        @return {Object}
+        @private
+      */
+      _normalizeResourceHelper(resourceHash: Object): Object;
+      /**
+        Normalize some data and push it into the store.
+    
+        @method pushPayload
+        @public
+        @param {Store} store
+        @param {Object} payload
+      */
+      pushPayload(store: Store, payload: Object): void;
+      /**
+        @method _normalizeResponse
+        @param {Store} store
+        @param {Model} primaryModelClass
+        @param {Object} payload
+        @param {String|Number} id
+        @param {String} requestType
+        @param {Boolean} isSingle
+        @return {Object} JSON-API Document
+        @private
+      */
+      _normalizeResponse(store: Store, primaryModelClass: Model, payload: Object, id: string | number, requestType: string, isSingle: boolean): Object;
+      normalizeQueryRecordResponse(...args: any[]): any;
+      extractAttributes(modelClass: any, resourceHash: any): {};
+      /**
+         Returns a relationship formatted as a JSON-API "relationship object".
+    
+         http://jsonapi.org/format/#document-resource-object-relationships
+    
+         @method extractRelationship
+        @public
+         @param {Object} relationshipHash
+         @return {Object}
+      */
+      extractRelationship(relationshipHash: Object): Object;
+      /**
+         Returns the resource's relationships formatted as a JSON-API "relationships object".
+    
+         http://jsonapi.org/format/#document-resource-object-relationships
+    
+         @method extractRelationships
+        @public
+         @param {Object} modelClass
+         @param {Object} resourceHash
+         @return {Object}
+      */
+      extractRelationships(modelClass: Object, resourceHash: Object): Object;
+      /**
+        @method _extractType
+        @param {Model} modelClass
+        @param {Object} resourceHash
+        @return {String}
+        @private
+      */
+      _extractType(modelClass: Model, resourceHash: Object): string;
+      /**
+        Dasherizes and singularizes the model name in the payload to match
+        the format Ember Data uses internally for the model name.
+    
+        For example the key `posts` would be converted to `post` and the
+        key `studentAssesments` would be converted to `student-assesment`.
+    
+        @method modelNameFromPayloadKey
+        @public
+        @param {String} key
+        @return {String} the model's modelName
+      */
+      modelNameFromPayloadKey(key: string): string;
+      /**
+        Converts the model name to a pluralized version of the model name.
+    
+        For example `post` would be converted to `posts` and
+        `student-assesment` would be converted to `student-assesments`.
+    
+        @method payloadKeyFromModelName
+        @public
+        @param {String} modelName
+        @return {String}
+      */
+      payloadKeyFromModelName(modelName: string): string;
+      normalize(modelClass: any, resourceHash: any): {
+          data: {
+              id: any;
+              type: string;
+              attributes: {};
+              relationships: Object;
+          };
+      };
+      /**
+        `keyForAttribute` can be used to define rules for how to convert an
+        attribute name in your model to a key in your JSON.
+        By default `JSONAPISerializer` follows the format used on the examples of
+        http://jsonapi.org/format and uses dashes as the word separator in the JSON
+        attribute keys.
+    
+        This behaviour can be easily customized by extending this method.
+    
+        Example
+    
+        ```app/serializers/application.js
+        import JSONAPISerializer from '@ember-data-mirror/serializer/json-api';
+        import { dasherize } from '<app-name>/utils/string-utils';
+    
+        export default class ApplicationSerializer extends JSONAPISerializer {
+          keyForAttribute(attr, method) {
+            return dasherize(attr).toUpperCase();
+          }
+        }
+        ```
+    
+        @method keyForAttribute
+        @public
+        @param {String} key
+        @param {String} method
+        @return {String} normalized key
+      */
+      keyForAttribute(key: string, method: string): string;
+      /**
+       `keyForRelationship` can be used to define a custom key when
+       serializing and deserializing relationship properties.
+       By default `JSONAPISerializer` follows the format used on the examples of
+       http://jsonapi.org/format and uses dashes as word separators in
+       relationship properties.
+    
+       This behaviour can be easily customized by extending this method.
+    
+       Example
+    
+        ```app/serializers/post.js
+        import JSONAPISerializer from '@ember-data-mirror/serializer/json-api';
+        import { underscore } from '<app-name>/utils/string-utils';
+    
+        export default class ApplicationSerializer extends JSONAPISerializer {
+          keyForRelationship(key, relationship, method) {
+            return underscore(key);
+          }
+        }
+        ```
+       @method keyForRelationship
+        @public
+       @param {String} key
+       @param {String} typeClass
+       @param {String} method
+       @return {String} normalized key
+      */
+      keyForRelationship(key: string, typeClass: string, method: string): string;
+      /**
+        Called when a record is saved in order to convert the
+        record into JSON.
+    
+        For example, consider this model:
+    
+        ```app/models/comment.js
+        import Model, { attr, belongsTo } from '@ember-data-mirror/model';
+    
+        export default class CommentModel extends Model {
+          @attr title;
+          @attr body;
+    
+          @belongsTo('user', { async: false, inverse: null })
+          author;
+        }
+        ```
+    
+        The default serialization would create a JSON-API resource object like:
+    
+        ```javascript
+        {
+          "data": {
+            "type": "comments",
+            "attributes": {
+              "title": "Rails is unagi",
+              "body": "Rails? Omakase? O_O",
+            },
+            "relationships": {
+              "author": {
+                "data": {
+                  "id": "12",
+                  "type": "users"
+                }
+              }
+            }
+          }
+        }
+        ```
+    
+        By default, attributes are passed through as-is, unless
+        you specified an attribute type (`attr('date')`). If
+        you specify a transform, the JavaScript value will be
+        serialized when inserted into the attributes hash.
+    
+        Belongs-to relationships are converted into JSON-API
+        resource identifier objects.
+    
+        ## IDs
+    
+        `serialize` takes an options hash with a single option:
+        `includeId`. If this option is `true`, `serialize` will,
+        by default include the ID in the JSON object it builds.
+    
+        The JSONAPIAdapter passes in `includeId: true` when serializing a record
+        for `createRecord` or `updateRecord`.
+    
+        ## Customization
+    
+        Your server may expect data in a different format than the
+        built-in serialization format.
+    
+        In that case, you can implement `serialize` yourself and
+        return data formatted to match your API's expectations, or override
+        the invoked adapter method and do the serialization in the adapter directly
+        by using the provided snapshot.
+    
+        If your API's format differs greatly from the JSON:API spec, you should
+        consider authoring your own adapter and serializer instead of extending
+        this class.
+    
+        ```app/serializers/post.js
+        import JSONAPISerializer from '@ember-data-mirror/serializer/json-api';
+    
+        export default class PostSerializer extends JSONAPISerializer {
+          serialize(snapshot, options) {
+            let json = {
+              POST_TTL: snapshot.attr('title'),
+              POST_BDY: snapshot.attr('body'),
+              POST_CMS: snapshot.hasMany('comments', { ids: true })
+            };
+    
+            if (options.includeId) {
+              json.POST_ID_ = snapshot.id;
+            }
+    
+            return json;
+          }
+        }
+        ```
+    
+        ## Customizing an App-Wide Serializer
+    
+        If you want to define a serializer for your entire
+        application, you'll probably want to use `eachAttribute`
+        and `eachRelationship` on the record.
+    
+        ```app/serializers/application.js
+        import JSONAPISerializer from '@ember-data-mirror/serializer/json-api';
+        import { underscore, singularize } from '<app-name>/utils/string-utils';
+    
+        export default class ApplicationSerializer extends JSONAPISerializer {
+          serialize(snapshot, options) {
+            let json = {};
+    
+            snapshot.eachAttribute((name) => {
+              json[serverAttributeName(name)] = snapshot.attr(name);
+            });
+    
+            snapshot.eachRelationship((name, relationship) => {
+              if (relationship.kind === 'hasMany') {
+                json[serverHasManyName(name)] = snapshot.hasMany(name, { ids: true });
+              }
+            });
+    
+            if (options.includeId) {
+              json.ID_ = snapshot.id;
+            }
+    
+            return json;
+          }
+        }
+    
+        function serverAttributeName(attribute) {
+          return underscore(attribute).toUpperCase();
+        }
+    
+        function serverHasManyName(name) {
+          return serverAttributeName(singularize(name)) + '_IDS';
+        }
+        ```
+    
+        This serializer will generate JSON that looks like this:
+    
+        ```javascript
+        {
+          "TITLE": "Rails is omakase",
+          "BODY": "Yep. Omakase.",
+          "COMMENT_IDS": [ "1", "2", "3" ]
+        }
+        ```
+    
+        ## Tweaking the Default Formatting
+    
+        If you just want to do some small tweaks on the default JSON:API formatted response,
+        you can call `super.serialize` first and make the tweaks
+        on the returned object.
+    
+        ```app/serializers/post.js
+        import JSONAPISerializer from '@ember-data-mirror/serializer/json-api';
+    
+        export default class PostSerializer extends JSONAPISerializer {
+          serialize(snapshot, options) {
+            let json = super.serialize(...arguments);
+    
+            json.data.attributes.subject = json.data.attributes.title;
+            delete json.data.attributes.title;
+    
+            return json;
+          }
+        }
+        ```
+    
+        @method serialize
+        @public
+        @param {Snapshot} snapshot
+        @param {Object} options
+        @return {Object} json
+      */
+      serialize(snapshot: Snapshot, options: Object, ...args: any[]): Object;
+      serializeAttribute(snapshot: any, json: any, key: any, attribute: any): void;
+      serializeBelongsTo(snapshot: any, json: any, relationship: any): void;
+      serializeHasMany(snapshot: any, json: any, relationship: any): void;
+  };
+}
+//# sourceMappingURL=json-api.d.ts.map

package/unstable-preview-types/json-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-api.d.ts","sourceRoot":"","sources":["../src/json-api.js"],"names":[],"mappings":";AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4HE;AACF;;;+BAoF+B,KAC9B;6BAyC4J,KAAK,qBAAqB,KAAI;uCA2CxK,KAAK,qBACd,KACP;wCAW6C,KAAK,qBAAoB,KAAK;oCASyH,KAAK,qBAAqB,KAAI;0CAmB7L,KAAK;IAG3C;;;;;;;;;;;MAWE;IACF,KAZE;wCAiBW,KAAK,qBAAoB,KAAK;qCAiBzC,KAAA,qBAEa,KAAK;kCAeI,KAAK,qBAAoB,KAEnD;yCAe6B,KAAI,qBAAoB,KAAK;yCAqBtB,KAAI,qBAAoB,KAC3D;yCAakB,KAAK,qBAAoB,KAAK;iCAuB5B,KAAK,qBACR,KAAI;mCAoBd,KACN,qBAAoB,KACtB;kCAqBqD,KAAK,qBACxC,KAAK;8BAWoB,KAAK,qBACzC,KAAK;;;;;;;;;;;;;qCA0OwwK,QAAQ,6BAA+C,kBAAkB;wBAA24I,QAAQ;+CAA2tD,KAAK,YAAwB,QAAQ;iCAAq1B,QAAQ;iCAAi6C,QAAQ;+BAAq9C,QAAQ;;uBAAm7E,KAAK,cAAoB,KAAK;yBAAk8E,KAAK,aAAoB,KAAK;;;;iEAAuhH,SAAS;;IArnBlqvB;;;;;MAKE;2CAHQ,MAAM,GACL,MAAM;IAkCjB;;;;;MAKE;2DAHQ,MAAM,GACL,MAAM;IASjB;;;;;MAKE;2CAHQ,MAAM,GACL,MAAM;IAqBjB;;;;;;;MAOE;uBAFQ,KAAK,WACL,MAAM;IAOhB;;;;;;;;;;MAUE;8BARQ,KAAK,qBACL,KAAK,WACL,MAAM,MACN,eAAa,2CAGZ,MAAM;;;IA0CjB;;;;;;;;;MASE;0CAFS,MAAM,GACL,MAAM;IAmBlB;;;;;;;;;;MAUE;qCAHS,MAAM,gBACN,MAAM,GACL,MAAM;IA6BlB;;;;;;MAME;6BAJQ,KAAK,gBACL,MAAM;IAQhB;;;;;;;;;;;MAWE;;IAKF;;;;;;;;;;MAUE;;;;;;;;;;IA8BF;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2BE;;IAKF;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2BE;;IAKF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAwKE;wBAHQ,QAAQ,WACR,MAAM,mBACL,MAAM;;;;EA+FhB"}