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

package/LICENSE.md

@@ -0,0 +1,11 @@
+The MIT License (MIT)
+
+Copyright (C) 2017-2023 Ember.js contributors
+Portions Copyright (C) 2011-2017 Tilde, Inc. and contributors.
+Portions Copyright (C) 2011 LivingSocial Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+<p align="center">
+  <img
+    class="project-logo"
+    src="./ember-data-logo-dark.svg#gh-dark-mode-only"
+    alt="EmberData Serializer"
+    width="240px"
+    title="EmberData Serializer"
+    />
+  <img
+    class="project-logo"
+    src="./ember-data-logo-light.svg#gh-light-mode-only"
+    alt="EmberData Serializer"
+    width="240px"
+    title="EmberData Serializer"
+    />
+</p>
+
+<p align="center">Provides JSON, REST and JSON:API Implementations of the legacy <a href="https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Serializer">Serializer Interface</a></p>
+
+> **Caution** ⚠️ **This is LEGACY documentation** 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 [Handler](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Handler)
+> instead to be used with the [RequestManager](https://github.com/emberjs/data/tree/main/packages/request#readme)
+
+## Installation
+
+This package is currently installed when installing `ember-data`.
+
+If installing `@ember-data/` packages individually install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/)
+
+```no-highlight
+pnpm add @ember-data-mirror/serializer
+```
+
+**Tagged Releases**
+
+- ![NPM Canary Version](https://img.shields.io/npm/v/%40ember-data/serializer/canary?label=%40canary&color=FFBF00)
+- ![NPM Beta Version](https://img.shields.io/npm/v/%40ember-data/serializer/beta?label=%40beta&color=ff00ff)
+- ![NPM Stable Version](https://img.shields.io/npm/v/%40ember-data/serializer/latest?label=%40latest&color=90EE90)
+- ![NPM LTS Version](https://img.shields.io/npm/v/%40ember-data/serializer/lts?label=%40lts&color=0096FF)
+- ![NPM LTS 4.12 Version](https://img.shields.io/npm/v/%40ember-data/serializer/lts-4-12?label=%40lts-4-12&color=bbbbbb)
+
+
+## 🚀 Setup
+
+If using `ember-data` no additional setup is necesssary.
+
+> **Note**
+> When using [ember-data](https://github.com/emberjs/data/blob/main/packages/-ember-data) the below
+> configuration is handled for you automatically.
+
+To use legacy serializers you will need to have installed and configured the LegacyNetworkHandler from [@ember-data-mirror/legacy-compat](https://github.com/emberjs/data/blob/main/packages/-ember-data)
+
+```no-highlight
+pnpm add @ember-data-mirror/legacy-compat
+```
+
+```ts
+import Store, { CacheHandler } from '@ember-data-mirror/store';
+import RequestManager from '@ember-data-mirror/request';
+import { LegacyNetworkHandler } from '@ember-data-mirror/legacy-compat';
+
+export default class extends Store {
+  requestManager = new RequestManager();
+
+  constructor(args) {
+    super(args);
+    this.requestManager.use([LegacyNetworkHandler]);
+    this.requestManager.useCache(CacheHandler);
+  }
+}
+```
+
+
+## Usage
+
+To use as either a per-type or application serializer, export one of the
+implementations within the `serializers/` directory of your app as appropriate.
+
+For instance, to configure an application serializer to use `JSON:API`
+
+
+*app/serializers/application.ts*
+```ts
+export { default } from '@ember-data-mirror/serializer/json-api';
+```
+
+By default serializers are resolved by looking for a serializer with the same name in the `serializers/` folder as the `type` given to `store.serializerFor(<type>)`, falling back to looking for a serializer named `application`.
+
+**Overriding Resolution**
+
+If you would like to avoid using resolver semantics and your application has only one or a few serializers, you may ovveride the `serializerFor` hook on the store.
+
+```ts
+import Store from '@ember-data-mirror/store';
+import Serializer from '@ember-data-mirror/serializer/json-api';
+
+class extends Store {
+  #serializer = new Serializer();
+
+  serializerFor() {
+    return this.#serializer;
+  }
+}
+```
+
+
+For the full list of APIs available read the code documentation for [@ember-data-mirror/serializer](https://api.emberjs.com/ember-data/release/modules/@ember-data%2Fserializer). You may also be interested in learning more about *Ember***Data**'s [Serializer Interface](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Serializer).

package/addon-main.cjs

@@ -0,0 +1,5 @@
+'use strict';
+
+const { addonShim } = require('@warp-drive-mirror/build-config/addon-shim.cjs');
+
+module.exports = addonShim(__dirname);

package/blueprints/serializer/files/__root__/__path__/__name__.js

@@ -0,0 +1,4 @@
+<%= importStatement %>
+
+export default <%= baseClass %>.extend({
+});

package/blueprints/serializer/index.js

@@ -0,0 +1,80 @@
+const path = require('path');
+const fs = require('fs');
+
+const stringUtil = require('ember-cli-string-utils');
+const pathUtil = require('ember-cli-path-utils');
+
+const { has } = require('@ember/edition-utils');
+
+module.exports = {
+  description: 'Generates an ember-data Serializer.',
+
+  availableOptions: [{ name: 'base-class', type: String }],
+
+  root: __dirname,
+
+  filesPath() {
+    let hasOctane = has('octane');
+    if (hasOctane && process.env.EMBER_EDITION === 'classic') {
+      hasOctane = false; //forcible override
+    }
+    let rootPath = hasOctane ? 'native-files' : 'files';
+    return path.join(__dirname, rootPath);
+  },
+
+  locals(options) {
+    return extendFromApplicationEntity('serializer', 'JSONAPISerializer', options);
+  },
+};
+
+function extendFromApplicationEntity(type, baseClass, options) {
+  let isAddon = options.inRepoAddon || options.project.isEmberCLIAddon();
+
+  let entityName = options.entity.name;
+  let relativePath = pathUtil.getRelativePath(options.entity.name);
+
+  if (options.pod && options.podPath) {
+    relativePath = pathUtil.getRelativePath(options.podPath + options.entity.name);
+  }
+
+  let applicationEntityPath = path.join(options.project.root, 'app', `${type}s`, 'application.js');
+
+  let hasApplicationEntity = fs.existsSync(applicationEntityPath);
+  if (!isAddon && !options.baseClass && entityName !== 'application' && hasApplicationEntity) {
+    options.baseClass = 'application';
+  }
+
+  if (options.baseClass === entityName) {
+    throw new Error(
+      stringUtil.classify(type) +
+        's cannot extend from themself. To resolve this, remove the `--base-class` option or change to a different base-class.'
+    );
+  }
+
+  let importStatement;
+
+  if (options.baseClass) {
+    let baseClassPath = options.baseClass;
+    baseClass = stringUtil.classify(baseClassPath.replace('/', '-'));
+    baseClass = baseClass + stringUtil.classify(type);
+
+    importStatement = `import ${baseClass} from '${relativePath}${baseClassPath}';`;
+  } else {
+    let baseClassPath = `@ember-data/${type}`;
+
+    if (baseClass.startsWith('JSONAPI')) {
+      baseClassPath += '/json-api';
+    }
+
+    if (baseClass.startsWith('REST')) {
+      baseClassPath += '/rest';
+    }
+
+    importStatement = `import ${baseClass} from '${baseClassPath}';`;
+  }
+
+  return {
+    importStatement,
+    baseClass,
+  };
+}

package/blueprints/serializer/native-files/__root__/__path__/__name__.js

@@ -0,0 +1,4 @@
+<%= importStatement %>
+
+export default class <%= classifiedModuleName %>Serializer extends <%= baseClass %> {
+}

package/blueprints/serializer-test/index.js

@@ -0,0 +1,35 @@
+const path = require('path');
+
+const testInfo = require('ember-cli-test-info');
+const { dasherize } = require('ember-cli-string-utils');
+
+module.exports = {
+  description: 'Generates an EmberData Serializer unit test',
+  supportsAddon() { return false; },
+
+  root: __dirname,
+
+  fileMapTokens() {
+    return {
+      __root__() {
+        return 'tests';
+      },
+      __path__() {
+        return path.join('unit', 'serializers');
+      },
+    };
+  },
+
+  locals(options) {
+    const modulePrefix = dasherize(options.project.config().modulePrefix);
+    return {
+      friendlyTestDescription: testInfo.description(options.entity.name, 'Unit', 'Serializer'),
+      modulePrefix,
+    };
+  },
+
+  filesPath() {
+    return path.join(__dirname, 'qunit-files')
+  }
+};
+

package/blueprints/serializer-test/qunit-files/__root__/__path__/__test__.js

@@ -0,0 +1,23 @@
+import { setupTest } from '<%= modulePrefix %>/tests/helpers';
+import { module, test } from 'qunit';
+
+module('<%= friendlyTestDescription %>', function (hooks) {
+  setupTest(hooks);
+
+  // Replace this with your real tests.
+  test('it exists', function (assert) {
+    const store = this.owner.lookup('service:store');
+    const serializer = store.serializerFor('<%= dasherizedModuleName %>');
+
+    assert.ok(serializer, 'serializer exists');
+  });
+
+  test('it serializes records', function (assert) {
+    const store = this.owner.lookup('service:store');
+    const record = store.createRecord('<%= dasherizedModuleName %>', {});
+
+    const serializedRecord = record.serialize();
+
+    assert.ok(serializedRecord, 'it serializes records');
+  });
+});

package/blueprints/transform/files/__root__/__path__/__name__.js

@@ -0,0 +1,13 @@
+export default class <%= classifiedModuleName %>Transform {
+  deserialize(serialized) {
+    return serialized;
+  }
+
+  serialize(deserialized) {
+    return deserialized;
+  }
+
+  static create() {
+    return new this();
+  }
+}

package/blueprints/transform/index.js

@@ -0,0 +1,17 @@
+const path = require('path');
+
+const { has } = require('@ember/edition-utils');
+
+module.exports = {
+  description: 'Generates an ember-data Transform.',
+  root: __dirname,
+
+  filesPath() {
+    let hasOctane = has('octane');
+    if (hasOctane && process.env.EMBER_EDITION === 'classic') {
+      hasOctane = false; //forcible override
+    }
+    let rootPath = hasOctane ? 'native-files' : 'files';
+    return path.join(__dirname, rootPath);
+  },
+};

package/blueprints/transform/native-files/__root__/__path__/__name__.js

@@ -0,0 +1,13 @@
+export default class <%= classifiedModuleName %>Transform {
+  deserialize(serialized) {
+    return serialized;
+  }
+
+  serialize(deserialized) {
+    return deserialized;
+  }
+
+  static create() {
+    return new this();
+  }
+}

package/blueprints/transform-test/index.js

@@ -0,0 +1,35 @@
+const path = require('path');
+
+const testInfo = require('ember-cli-test-info');
+const { dasherize } = require('ember-cli-string-utils');
+
+module.exports = {
+  description: 'Generates an EmberData Transform unit test',
+  supportsAddon() { return false; },
+
+  root: __dirname,
+
+  fileMapTokens() {
+    return {
+      __root__() {
+        return 'tests';
+      },
+      __path__() {
+        return path.join('unit', 'transforms');
+      },
+    };
+  },
+
+  locals(options) {
+    const modulePrefix = dasherize(options.project.config().modulePrefix);
+    return {
+      friendlyTestDescription: testInfo.description(options.entity.name, 'Unit', 'Transform'),
+      modulePrefix,
+    };
+  },
+
+  filesPath() {
+    return path.join(__dirname, 'qunit-files')
+  }
+};
+

package/blueprints/transform-test/qunit-files/__root__/__path__/__test__.js

@@ -0,0 +1,12 @@
+import { setupTest } from '<%= modulePrefix %>/tests/helpers';
+import { module, test } from 'qunit';
+
+module('<%= friendlyTestDescription %>', function (hooks) {
+  setupTest(hooks);
+
+  // Replace this with your real tests.
+  test('it exists', function (assert) {
+    const transform = this.owner.lookup('transform:<%= dasherizedModuleName %>');
+    assert.ok(transform, 'transform exists');
+  });
+});

package/dist/index.js

@@ -0,0 +1,304 @@
+import EmberObject from '@ember/object';
+import { inject } from '@ember/service';
+const deferred = /* @__PURE__ */new WeakMap();
+function deferDecorator(proto, prop, desc) {
+  let map = deferred.get(proto);
+  if (!map) {
+    map = /* @__PURE__ */new Map();
+    deferred.set(proto, map);
+  }
+  map.set(prop, desc);
+}
+function findDeferredDecorator(target, prop) {
+  var _a;
+  let cursor = target.prototype;
+  while (cursor) {
+    let desc = (_a = deferred.get(cursor)) == null ? void 0 : _a.get(prop);
+    if (desc) {
+      return desc;
+    }
+    cursor = cursor.prototype;
+  }
+}
+function decorateFieldV2(prototype, prop, decorators, initializer) {
+  let desc = {
+    configurable: true,
+    enumerable: true,
+    writable: true,
+    initializer: null
+  };
+  if (initializer) {
+    desc.initializer = initializer;
+  }
+  for (let decorator of decorators) {
+    desc = decorator(prototype, prop, desc) || desc;
+  }
+  if (desc.initializer === void 0) {
+    Object.defineProperty(prototype, prop, desc);
+  } else {
+    deferDecorator(prototype, prop, desc);
+  }
+}
+function initializeDeferredDecorator(target, prop) {
+  let desc = findDeferredDecorator(target.constructor, prop);
+  if (desc) {
+    Object.defineProperty(target, prop, {
+      enumerable: desc.enumerable,
+      configurable: desc.configurable,
+      writable: desc.writable,
+      value: desc.initializer ? desc.initializer.call(target) : void 0
+    });
+  }
+}
+
+/**
+  ## 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>
+
+  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.
+
+  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
+
+  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.
+
+  ```ts
+  import EmberObject from '@ember/object';
+
+  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()
+      };
+
+      return serializedResource;
+    }
+  }
+ ```
+
+
+  ### 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.
+
+  `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');
+
+  // 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`.
+
+  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.
+
+  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
+
+  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** 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.
+
+  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
+*/
+
+/**
+  > ⚠️ 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:
+
+    * `normalize()`
+
+  For an example implementation, see
+  [JSONSerializer](JSONSerializer), the included JSON serializer.
+
+  @class Serializer
+  @public
+  @extends Ember.EmberObject
+*/
+
+class Serializer extends EmberObject {
+  static {
+    decorateFieldV2(this.prototype, "store", [inject]);
+  }
+  #store = (initializeDeferredDecorator(this, "store"), void 0);
+  /**
+    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, hash) {
+    return hash;
+  }
+}
+export { Serializer as default };