@warp-drive/legacy 5.7.0 → 5.8.0-alpha.10

package/declarations/model/-private/model.d.ts

@@ -28,9 +28,6 @@ export type FactoryCache = Record<string, ModelFactory>;
 export type ModelStore = Store & {
 	_modelFactoryCache: FactoryCache;
 };
-/**
-* @noInheritDoc
-*/
 interface Model {
 	/**
 	* The store service instance which created this record instance
@@ -89,8 +86,8 @@ interface Model {
 	```
 	
 	@public
-	@param {Object} options
-	@return {Promise} a promise that will be resolved when the adapter returns
+	@param options
+	@return a promise that will be resolved when the adapter returns
 	successfully or rejected if the adapter returns with an error.
 	*/
 	destroyRecord<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<this>;
@@ -204,9 +201,9 @@ interface Model {
 	}
 	```
 	
+	@deprecated use {@link Store.request} instead
 	@public
-	@param {Object} options
-	@return {Promise} a promise that will be resolved when the adapter returns
+	@return a promise that will be resolved when the adapter returns
 	successfully or rejected if the adapter returns with an error.
 	*/
 	save<T extends MinimalLegacyRecord>(this: T, options?: Record<string, unknown>): Promise<this>;
@@ -414,7 +411,10 @@ interface Model {
 * the class to use as the reactive object for data of resource
 * of that type.
 *
+* @public
 * @noInheritDoc
+* @hideconstructor
+* @legacy
 */
 declare class Model extends EmberObject implements MinimalLegacyRecord {
 	/** @private */
@@ -797,7 +797,7 @@ declare class Model extends EmberObject implements MinimalLegacyRecord {
 	Represents the model's class name as a string. This can be used to look up the model's class name through
 	`Store`'s modelFor method.
 	
-	`modelName` is generated for you by EmberData. It will be a lowercased, dasherized string.
+	`modelName` is generated for you by WarpDrive. It will be a lowercased, dasherized string.
 	For example:
 	
 	```javascript

package/declarations/model/-private/record-state.d.ts

@@ -1,6 +1,6 @@
 import type { MinimalLegacyRecord } from "./model-methods.js";
 /**
-Historically EmberData managed a state machine
+Historically WarpDrive managed a state machine
 for each record, the localState for which
 was reflected onto Model.
 

package/declarations/model/-private/references/belongs-to.d.ts

@@ -241,7 +241,7 @@ export default class BelongsToReference<
 	*/
 	remoteType(): "link" | "id";
 	/**
-	`push` can be used to update the data in the relationship and EmberData
+	`push` can be used to update the data in the relationship and WarpDrive
 	will treat the new data as the canonical value of this relationship on
 	the backend. A value of `null` (e.g. `{ data: null }`) can be passed to
 	clear the relationship.

package/declarations/model/-private/references/has-many.d.ts

@@ -243,7 +243,7 @@ export default class HasManyReference<
 	*/
 	meta(): Meta | null;
 	/**
-	`push` can be used to update the data in the relationship and EmberData
+	`push` can be used to update the data in the relationship and WarpDrive
 	will treat the new data as the canonical value of this relationship on
 	the backend. An empty array will signify the canonical value should be
 	empty.

package/declarations/model/migration-support.d.ts

@@ -207,8 +207,6 @@ export interface DelegatingSchemaService {
 	doesTypeExist?(type: string): boolean;
 }
 export declare class DelegatingSchemaService implements SchemaService {
-	_preferred: SchemaService;
-	_secondary: SchemaService;
 	constructor(store: Store, schema: SchemaService);
 	isDelegated(resource: ResourceKey | {
 		type: string;
@@ -252,4 +250,8 @@ export declare class DelegatingSchemaService implements SchemaService {
 	CAUTION_MEGA_DANGER_ZONE_objectExtensions(field: ExtensibleField, resolvedType: string | null): null | ProcessedExtension["features"];
 	CAUTION_MEGA_DANGER_ZONE_arrayExtensions(field: ExtensibleField): null | ProcessedExtension["features"];
 }
+export interface PrivateDelegatingSchemaService extends DelegatingSchemaService {
+	_preferred: SchemaService;
+	_secondary: SchemaService;
+}
 export {};

package/declarations/serializer/-private/embedded-records-mixin.d.ts

@@ -85,11 +85,6 @@ instances must have an `id` property to be used with Ember Data.
 are. Please read the docs for the methods this mixin provides, in case you need
 to modify it to fit your specific needs.**
 
-For example, review the docs for each method of this mixin:
-* [normalize](/ember-data/release/classes/EmbeddedRecordsMixin/methods/normalize?anchor=normalize)
-* [serializeBelongsTo](/ember-data/release/classes/EmbeddedRecordsMixin/methods/serializeBelongsTo?anchor=serializeBelongsTo)
-* [serializeHasMany](/ember-data/release/classes/EmbeddedRecordsMixin/methods/serializeHasMany?anchor=serializeHasMany)
-
 @class EmbeddedRecordsMixin
 @public
 */

package/declarations/serializer/-private/transforms/boolean.d.ts

@@ -5,8 +5,8 @@ export interface BooleanTransform {
 /**
 The `BooleanTransform` class is used to serialize and deserialize
 boolean attributes on Ember Data record objects. This transform is
-used when `boolean` is passed as the type parameter to the
-[attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function.
+used when `'boolean'` is passed as the type parameter to the
+{@link attr}function.
 
 Usage
 

package/declarations/serializer/-private/transforms/date.d.ts

@@ -5,8 +5,8 @@ export interface DateTransform {
 /**
 The `DateTransform` class is used to serialize and deserialize
 date attributes on Ember Data record objects. This transform is used
-when `date` is passed as the type parameter to the
-[attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function. It uses the [`ISO 8601`](https://en.wikipedia.org/wiki/ISO_8601)
+when `'date'` is passed as the type parameter to the
+{@link attr} function. It uses the [`ISO 8601`](https://en.wikipedia.org/wiki/ISO_8601)
 standard.
 
 ```js [app/models/score.js]

package/declarations/serializer/-private/transforms/number.d.ts

@@ -6,7 +6,7 @@ export interface NumberTransform {
 The `NumberTransform` class is used to serialize and deserialize
 numeric attributes on Ember Data record objects. This transform is
 used when `number` is passed as the type parameter to the
-[attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function.
+{@link attr} function.
 
 Usage
 

package/declarations/serializer/-private/transforms/string.d.ts

@@ -6,7 +6,7 @@ export interface StringTransform {
 The `StringTransform` class is used to serialize and deserialize
 string attributes on Ember Data record objects. This transform is
 used when `string` is passed as the type parameter to the
-[attr](/ember-data/release/functions/@ember-data%2Fmodel/attr) function.
+{@link attr} function.
 
 Usage
 

package/declarations/serializer/json-api.d.ts

@@ -1,13 +1,11 @@
 /**
-* <blockquote style="margin: 1em; padding: .1em 1em .1em 1em; border-left: solid 1em #E34C32; background: #e0e0e0;">
-<p>
+* :::danger
 ⚠️ <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>
+{@link Handler} instead to be used with the {@link RequestManager}
+:::
 
-In EmberData a Serializer is used to serialize and deserialize
+In WarpDrive 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.

package/declarations/serializer/json.d.ts

@@ -1,18 +1,16 @@
 /**
-* <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.
+* :::danger
+⚠️ **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 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>
+{@link Handler} instead to be used with the {@link RequestManager}
+:::
 
-In EmberData a Serializer is used to serialize and deserialize
+In WarpDrive 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.
 
-By default, EmberData uses and recommends the `JSONAPISerializer`.
+By default, WarpDrive uses and recommends the `JSONAPISerializer`.
 
 `JSONSerializer` is useful for simpler or legacy backends that may
 not support the http://jsonapi.org/ spec.

package/declarations/serializer/rest.d.ts

@@ -1,11 +1,9 @@
 /**
-* <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.
+* :::danger
+⚠️ **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 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>
+{@link Handler} instead to be used with the {@link RequestManager}
+:::
 
 Normally, applications will use the `RESTSerializer` by implementing
 the `normalize` method.

package/declarations/serializer.d.ts

@@ -1,13 +1,11 @@
 /**
 ## 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.
+:::danger
+⚠️ **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
-<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>
+{@link Handler} instead to be used with the {@link RequestManager}
+:::
 
 In order to properly manage and present your data, WarpDrive
 needs to understand the structure of data it receives.
@@ -16,14 +14,14 @@ needs to understand the structure of data it receives.
 the format WarpDrive understands.
 
 Data received from an API response is **normalized** into
-[JSON:API](https://jsonapi.org/) (the format used internally
+[{json:api}](https://jsonapi.org/) (the format used internally
 by WarpDrive), 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
+normalizing data from the server API format into {json:api}, and
 another for serializing records via `Snapshots` into the expected
 server API format.
 
@@ -69,7 +67,7 @@ store.serializerFor('author');
 //   app/serializers/application.js
 ```
 
-Most requests in @warp-drive/legacy are made with respect to a particular `type` (or `modelName`)
+Most requests in `@warp-drive/legacy` 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`.
 
@@ -124,8 +122,7 @@ And you can optionally override the following methods:
 
 * `normalize()`
 
-For an example implementation, see
-[JSONSerializer](JSONSerializer), the included JSON serializer.
+For an example implementation, see the included {@link JSONSerializer}.
 
 @class Serializer
 @public

package/dist/{-private-8UmnAf9J.js → -private-B1pSSN52.js}

@@ -1202,7 +1202,7 @@ function _flushPendingSave(store, pending) {
 
 /**
  * Utilities - often temporary - for maintaining backwards compatibility with
- * older parts of EmberData.
+ * older parts of WarpDrive.
  *
   @module
 */

package/dist/adapter/-private.js

@@ -1 +1 @@
-export { d as determineBodyPromise, g as fetch, p as parseResponseHeaders, b as serializeIntoHash, s as serializeQueryParams, a as setupFastboot } from "../serialize-into-hash-CS0MIv4F.js";
+export { d as determineBodyPromise, g as fetch, p as parseResponseHeaders, b as serializeIntoHash, s as serializeQueryParams, a as setupFastboot } from "../serialize-into-hash-BnYvPex3.js";

package/dist/adapter/error.js

@@ -3,17 +3,16 @@ import { macroCondition, getGlobalConfig } from '@embroider/macros';
 
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 
 /**
   ## 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.
+  :::danger
+    ⚠️ **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 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>
+    {@link Handler} instead to be used with the {@link RequestManager}
+  :::
 
   An `AdapterError` is used by an adapter to signal that an error occurred
   during a request to an external API. It indicates a generic error, and

package/dist/adapter/json-api.js

@@ -1,8 +1,11 @@
 import { dasherize, pluralize } from '@warp-drive/utilities/string';
 import '@ember/debug';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
-import { b as serializeIntoHash } from "../serialize-into-hash-CS0MIv4F.js";
+import { b as serializeIntoHash } from "../serialize-into-hash-BnYvPex3.js";
 import { RESTAdapter } from './rest.js';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
 class JSONAPIAdapter extends RESTAdapter {
   _defaultContentType = 'application/vnd.api+json';
 

package/dist/adapter/rest.js

@@ -2,7 +2,7 @@ import { getOwner } from '@ember/application';
 import { warn } from '@ember/debug';
 import { computed } from '@ember/object';
 import { Adapter, BuildURLMixin } from '../adapter.js';
-import { b as serializeIntoHash, d as determineBodyPromise, g as getFetchFunction, s as serializeQueryParams, p as parseResponseHeaders } from "../serialize-into-hash-CS0MIv4F.js";
+import { b as serializeIntoHash, d as determineBodyPromise, g as getFetchFunction, s as serializeQueryParams, p as parseResponseHeaders } from "../serialize-into-hash-BnYvPex3.js";
 import { InvalidError, ServerError, ConflictError, NotFoundError, ForbiddenError, UnauthorizedError, AdapterError, TimeoutError, AbortError } from './error.js';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 import { d as decorateMethodV2 } from "../runtime-BPCpkOf1-BKOwiRJp.js";
@@ -14,13 +14,11 @@ import { d as decorateMethodV2 } from "../runtime-BPCpkOf1-BKOwiRJp.js";
 const AdapterWithBuildURLMixin = Adapter.extend(BuildURLMixin);
 
 /**
- * <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.
+ * :::danger
+    ⚠️ **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 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>
+    {@link Handler} instead to be used with the {@link RequestManager}
+  :::
 
   The REST adapter allows your store to communicate with an HTTP server by
   transmitting JSON via XHR.
@@ -392,8 +390,7 @@ class RESTAdapter extends AdapterWithBuildURLMixin {
     Some APIs require HTTP headers, e.g. to provide an API
     key. Arbitrary headers can be set as key/value pairs on the
     `RESTAdapter`'s `headers` object and Ember Data will send them
-    along with each ajax request. For dynamic headers see [headers
-    customization](/ember-data/release/classes/RESTAdapter).
+    along with each ajax request..
      ```js [app/adapters/application.js]
     import { RESTAdapter } from '@warp-drive/legacy/adapter/rest';
      export default class ApplicationAdapter extends RESTAdapter {

package/dist/adapter.js

@@ -496,13 +496,11 @@ const BuildURLMixin = Mixin.create(mixinProps);
 /**
  * ## 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.
+ * :::danger
+ *   ⚠️ **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 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>
+ *   {@link Handler} instead to be used with the {@link RequestManager}
+ * ::::
  *
  * In order to properly fetch and update data, @warp-drive/legacy
  * needs to understand how to connect to your API.

package/dist/compat/-private.js

@@ -1 +1 @@
-export { F as FetchManager, S as SaveOp, c as Snapshot, b as SnapshotRecordArray, u as upgradeStore } from "../-private-8UmnAf9J.js";
+export { F as FetchManager, S as SaveOp, c as Snapshot, b as SnapshotRecordArray, u as upgradeStore } from "../-private-B1pSSN52.js";

package/dist/compat/utils.js

@@ -33,7 +33,7 @@ let NormalizedType = str => {
  * changes during normalization. This is useful for instrumenting
  * to discover places where usage in the app is not consistent.
  *
- * @param method a function which takes a mismatch-type ('formatted-id' | 'formatted-type'), actual, and expected value
+ * @param fn - a function which takes a mismatch-type ('formatted-id' | 'formatted-type'), actual, and expected value
  * @public
  */
 function configureMismatchReporter(fn) {
@@ -45,7 +45,7 @@ function configureMismatchReporter(fn) {
  * fails validation. This is useful for instrumenting
  * to discover places where usage in the app is not consistent.
  *
- * @param method a function which takes a message and a condition
+ * @param fn - a function which takes a message and a condition
  * @public
  */
 function configureAssertFn(fn) {
@@ -62,7 +62,7 @@ function configureAssertFn(fn) {
  * the configured mismatch reporter and assert functions will
  * be called.
  *
- * @param method a function which takes a string and returns a string
+ * @param fn - a function which takes a string and returns a string
  * @public
  */
 function configureTypeNormalization(fn) {
@@ -72,7 +72,7 @@ const NORMALIZED_TYPES = new Map();
 
 /**
  * Converts a potentially unnormalized type into the format expected
- * by our EmberData Cache. Currently this is singular-dasherized.
+ * by our WarpDrive Cache. Currently this is singular-dasherized.
  *
  * you should not rely on this function to give you an exact format
  * for display purposes. Formatting for display should be handled
@@ -95,8 +95,8 @@ const NORMALIZED_TYPES = new Map();
  * formattedType('PostComment'); // => 'post-comment'
  * ```
  *
- * @param {String} type the potentially un-normalized type
- * @return {String} the normalized type
+ * @param type the potentially un-normalized type
+ * @return the normalized type
  * @public
  */
 function formattedType(type) {
@@ -116,7 +116,7 @@ function formattedType(type) {
 }
 
 /**
- * Format an id to the format expected by the EmberData Cache.
+ * Format an id to the format expected by the WarpDrive Cache.
  * Currently this means that id should be `string | null`.
  *
  * Asserts invalid IDs (undefined, '', 0, '0') in dev.
@@ -131,8 +131,8 @@ function formattedType(type) {
  * formattedId(null); // => null
  *	```
  *
- * @param {String | Number | null} id the potentially un-normalized id
- * @return {String | null} the normalized id
+ * @param id the potentially un-normalized id
+ * @return the normalized id
  * @public
  */
 
@@ -154,7 +154,7 @@ function expectId(id) {
 
 /**
  * Compares two types for strict equality, converting them to
- * the format expected by the EmberData Cache to ensure
+ * the format expected by the WarpDrive Cache to ensure
  * differences in format are accounted for in the comparison.
  *
  * Asserts when expected or actual are invalid types in dev.
@@ -172,9 +172,9 @@ function expectId(id) {
  * isEquivType('posts', null); // false
  * ```
  *
- * @param {String} expected a potentially unnormalized type to match against
- * @param {String} actual a potentially unnormalized type to match against
- * @return {Boolean} true if the types are equivalent
+ * @param expected a potentially unnormalized type to match against
+ * @param actual a potentially unnormalized type to match against
+ * @return true if the types are equivalent
  * @public
  */
 function isEquivType(expected, actual) {
@@ -191,7 +191,7 @@ function isEquivType(expected, actual) {
 
 /**
  * Compares two IDs for strict equality, converting them to
- * the format expected by the EmberData Cache to ensure
+ * the format expected by the WarpDrive Cache to ensure
  * differences in format are accounted for in the comparison.
  *
  * Asserts when expected or actual are invalid IDs in dev.
@@ -205,9 +205,9 @@ function isEquivType(expected, actual) {
  * isEquivId(1, null); // false
  * ```
  *
- * @param {string | number} expected a potentially un-normalized id to match against
- * @param {string | number} actual a potentially un-normalized id to match against
- * @return {Boolean} true if the ids are equivalent
+ * @param expected a potentially un-normalized id to match against
+ * @param actual a potentially un-normalized id to match against
+ * @return true if the ids are equivalent
  * @public
  */
 function isEquivId(expected, actual) {

package/dist/compat.js

@@ -2,7 +2,7 @@ import { getOwner } from '@ember/application';
 import { recordIdentifierFor } from '@warp-drive/core';
 import { assertPrivateStore, waitFor, _deprecatingNormalize } from '@warp-drive/core/store/-private';
 import '@warp-drive/core/reactive/-private';
-import { p as payloadIsNotBlank, n as normalizeResponseHelper, i as iterateData, F as FetchManager, S as SaveOp, a as assertIdentifierHasId, b as SnapshotRecordArray } from "./-private-8UmnAf9J.js";
+import { p as payloadIsNotBlank, n as normalizeResponseHelper, i as iterateData, F as FetchManager, S as SaveOp, a as assertIdentifierHasId, b as SnapshotRecordArray } from "./-private-B1pSSN52.js";
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 function _findHasMany(adapter, store, identifier, link, relationship, options) {
   const promise = Promise.resolve().then(() => {
@@ -737,18 +737,30 @@ function queryRecord(context) {
 }
 
 /**
-    Returns an instance of the adapter for a given type. For
-    example, `adapterFor('person')` will return an instance of
-    the adapter located at `app/adapters/person.js`
+ * Extends the signature of {@link Store} with additional
+ * methods available when using the legacy network layer.
+ *
+ * @public
+ * @noInheritDoc
+ * @legacy
+ */
 
-    If no `person` adapter is found, this method will look
-    for an `application` adapter (the default adapter for
-    your entire application).
+/**
+ * @deprecated - use {@link LegacyStoreCompat} instead
+ */
 
-    @public
-    @param {String} modelName
-    @return {Adapter}
-  */
+/**
+  Returns an instance of the adapter for a given type. For
+  example, `adapterFor('person')` will return an instance of
+  the adapter located at `app/adapters/person.js`
+
+  If no `person` adapter is found, this method will look
+  for an `application` adapter (the default adapter for
+  your entire application).
+
+  @public
+  @param modelName
+*/
 
 function adapterFor(modelName, _allowMissing) {
   macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
@@ -799,20 +811,19 @@ function adapterFor(modelName, _allowMissing) {
 }
 
 /**
-    Returns an instance of the serializer for a given type. For
-    example, `serializerFor('person')` will return an instance of
-    `App.PersonSerializer`.
+  Returns an instance of the serializer for a given type. For
+  example, `serializerFor('person')` will return an instance of
+  `App.PersonSerializer`.
 
-    If no `App.PersonSerializer` is found, this method will look
-    for an `App.ApplicationSerializer` (the default serializer for
-    your entire application).
+  If no `App.PersonSerializer` is found, this method will look
+  for an `App.ApplicationSerializer` (the default serializer for
+  your entire application).
 
-    If a serializer cannot be found on the adapter, it will fall back
-    to an instance of `JSONSerializer`.
+  If a serializer cannot be found on the adapter, it will fall back
+  to an instance of `JSONSerializer`.
 
-    @public
-    @param {String} modelName the record to serialize
-    @return {Serializer}
+  @public
+  @param modelName the record to serialize
   */
 function serializerFor(modelName) {
   macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
@@ -859,23 +870,29 @@ function serializerFor(modelName) {
 }
 
 /**
-    `normalize` converts a json payload into the normalized form that
-    [push](../methods/push?anchor=push) expects.
+  `normalize` converts a json payload into the normalized form expected by
+  {@link Store.push | push} using the serializer specified by `modelName`
 
-    Example
+  :::warning
+  Generally it would be better to invoke the serializer yourself directly,
+  or write a more specialized normalization utility.
+  :::
 
-    ```js
-    socket.on('message', function(message) {
-      let modelName = message.model;
-      let data = message.data;
-      store.push(store.normalize(modelName, data));
-    });
-    ```
+  Example
 
-    @public
-    @param modelName The name of the model type for this payload
-    @return The normalized payload
-  */
+  ```js
+  socket.on('message', function(message) {
+    let modelName = message.model;
+    let data = message.data;
+    store.push(store.normalize(modelName, data));
+  });
+  ```
+
+  @legacy
+  @public
+  @param modelName The name of the model type for this payload
+  @return The normalized payload
+*/
 // TODO @runspired @deprecate users should call normalize on the associated serializer directly
 function normalize(modelName, payload) {
   macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
@@ -956,8 +973,8 @@ function normalize(modelName, payload) {
     ```
 
     @public
-    @param {String} modelName Optionally, a model type used to determine which serializer will be used
-    @param {Object} inputPayload
+    @param modelName Optionally, a model type used to determine which serializer will be used
+    @param inputPayload
   */
 // TODO @runspired @deprecate pushPayload in favor of looking up the serializer
 function pushPayload(modelName, inputPayload) {