Serializers section

Author: Baltazore

app/routes/application.js

@@ -76,6 +76,16 @@ export default class ApplicationRoute extends Route {
           },
         ],
       },
+      {
+        id: 'serializers',
+        subsections: [
+          {
+            id: 'general',
+            classicFiles: ['old.js'],
+            octaneFiles: ['utils.js', 'app-code.js', 'handler.js'],
+          },
+        ],
+      },
     ];
   }
 }

snippets/serializers/general/app-code.js

@@ -0,0 +1,23 @@
+// File: my-app/components/my-component.js
+
+import { serializeResource } from "my-app/utils/serialization";
+import { recordIdentifierFor } from '@ember-data/store';
+import { createRecord } from "@ember-data/json-api/request"
+
+// ...
+let record = store.createRecord('blog-post', {
+  title: "My first blog post",
+  body: "This is the body of my blog post",
+  createdAt: new Date(),
+  user: currentUser,
+});
+
+const request = createRecord(record);
+request.body = JSON.stringify(
+  serializeResource(
+    store.cache,
+    recordIdentifierFor(record)
+  )
+);
+
+await this.store.request(request);

snippets/serializers/general/handler.js

@@ -0,0 +1,13 @@
+// File: my-app/utils/my-custom-rest-handler.js
+
+import { normalizeResource } from 'my-app/utils/serialization';
+
+const MyCustomRESTHandler = {
+  async request(context, next) {
+    const { content, request } = await next(context.request);
+    // convert to JSON:API, because EmberData expect it by default (using the JSON:API Cache)
+    return normalizeResource(content, request.store.schema);
+  },
+};
+
+export default MyCustomRESTHandler;

snippets/serializers/general/old.js

@@ -0,0 +1,36 @@
+import JSONAPISerializer from '@ember-data/serializer/json-api';
+
+export default class ApplicationSerializer extends JSONAPISerializer {
+  primaryKey = '_id';
+
+  keyForAttribute(attr) {
+    return attr.replace(/_/g, '-'); // blog_post_comment becomes blog-post-comment
+  }
+
+  keyForRelationship(key, relationship) {
+    return key + 'Ids';
+  }
+
+  serialize(snapshot, options) {
+    let json = super.serialize(...arguments);
+
+    json.data.attributes.cost = {
+      amount: json.data.attributes.amount,
+      currency: json.data.attributes.currency,
+    };
+
+    delete json.data.attributes.amount;
+    delete json.data.attributes.currency;
+
+    return json;
+  }
+
+  normalizeResponse(store, primaryModelClass, payload, id, requestType) {
+    payload.data.attributes.amount = payload.data.attributes.cost.amount;
+    payload.data.attributes.currency = payload.data.attributes.cost.currency;
+
+    delete payload.data.attributes.cost;
+
+    return super.normalizeResponse(...arguments);
+  }
+}

snippets/serializers/general/utils.js

@@ -0,0 +1,69 @@
+// File: my-app/utils/serialization.js
+
+const keyForAttribute = (attr) => {
+  return attr.replace(/_/g, '-'); // blog_post_comment becomes blog-post-comment
+}
+
+const keyForRelationship = (relationship) => {
+  return relationship + 'Ids';
+}
+
+const serializeResource = (cache, identifier) => {
+  const body = { _id: identifier.id, type: identifier.type };
+
+  if (cache.hasChangedAttrs(identifier)) {
+    const attrsChanges = cache.changedAttrs(identifier);
+
+    Object.keys(attrsChanges).forEach((attr) => {
+      const change = attrsChanges[attr][1];
+      body[keyForAttribute(attr)] = change === undefined ? null : change;
+    });
+  }
+
+  if (cache.hasChangedRelationships(identifier)) {
+    const relationshipsChanged = cache.changedRelationships(identifier);
+    if (relationshipsChanged.size) {
+      relationshipsChanged.forEach((diff, key) => {
+        body[keyForRelationship(key)] = diff.localState.id;
+      });
+    }
+  }
+
+  return body;
+};
+
+const normalizeResource = (item, schema) => {
+  // destructuring and renaming primaryKey from _id to id
+  const { _id: id, type } = item;
+
+  const attributesDefined = schema.attributesDefinitionFor({ type });
+  const relationshipsDefined = schema.relationshipsDefinitionFor({ type });
+
+  const data = { id, type, attributes: {} };
+
+  for (const attr of Object.values(attributesDefined)) {
+    data.attributes[attr.name] = item[attr.name];
+  }
+
+  data.attributes.amount = item.data.attributes.cost.amount;
+  data.attributes.currency = item.data.attributes.cost.currency;
+
+  for (const rel of Object.values(relationshipsDefined)) {
+    if (Object.hasOwnProperty.call(item, rel.name)) {
+      data.relationships ??= {};
+      data.relationships[rel.name] = {
+        data: {
+          id: item[rel.name],
+          type: rel.type,
+        },
+      };
+    }
+  }
+
+  return data;
+};
+
+export {
+  normalizeResource,
+  serializeResource,
+}

translations/serializers/en-us.yaml

@@ -0,0 +1 @@
+title: Serializers

translations/serializers/general/en-us.yaml

@@ -0,0 +1,15 @@
+title: Serializers in general
+description: |
+  In order to provide migration support for Adapters and Serializers, a '<code>'LegacyNetworkHandler'</code>' is provided. This handler takes a request and converts it into the older form, calling the appropriate Adapter and Serializer methods. If no serializer exists for the type (including no application serializer), this handler calls '<code>'next'</code>'. In this manner an app can incrementally migrate request-handling to this new paradigm on a per-type basis as desired.
+  <br />
+  The package '<code>'ember-data'</code>' automatically configures this handler. If not using the '<code>'ember-data'</code>' package, this configuration needs to be done explicitly.
+  <br />
+  We intend to support this handler through at least the 5.x series -- not deprecating its usage before 6.0.
+  <br />
+  Similarly, the methods '<code>'adapterFor'</code>' and '<code>'serializerFor'</code>' will not be deprecated until at least 6.0; however, it should no longer be assumed that an application has an adapter or serializer at all.
+  <br />
+  Serializers previously was used to accomplish two main things: serialization and normalization.
+  <br />
+  Normalization is now done in handlers, before returning the response.
+  <br />
+  Serialization can be done in handler, but we encourage application developers to do it in request builder.