@warp-drive/legacy 5.9.0-alpha.2 → 5.9.0-alpha.21

package/dist/unpkg/dev-deprecated/index.js

@@ -7,11 +7,11 @@ import '@ember/object';
 import '@warp-drive/core/types/symbols';
 import '@warp-drive/utilities/string';
 import '@warp-drive/core/store/-private';
-import "./errors-Spt6ubMd.js";
-import "./schema-provider-BP6_8N-V.js";
-import { i as instantiateRecord, t as teardownRecord, m as modelFor } from "./hooks-DOXegvhL.js";
+import "./errors-Bzidntpi.js";
+import "./schema-provider-ZwO5_fZw.js";
+import { i as instantiateRecord, t as teardownRecord, m as modelFor } from "./hooks-DVXhMW14.js";
 import { registerDerivations as registerDerivations$1, DelegatingSchemaService } from './model/migration-support.js';
-import { F as FragmentExtension, a as FragmentArrayExtension, f as fragmentsModelFor } from "./model-for-CqXsIKws.js";
+import { F as FragmentExtension, a as FragmentArrayExtension, f as fragmentsModelFor } from "./model-for-CXkJw59V.js";
 import { restoreDeprecatedStoreBehaviors } from './store.js';
 
 /**
@@ -19,10 +19,153 @@ import { restoreDeprecatedStoreBehaviors } from './store.js';
  * @mergeModuleWith <project>
  */
 
+/**
+ * Setup options for a legacy store configured to use `Model` with `linksMode`
+ * enabled, meaning no legacy adapter/serializer request infrastructure is required.
+ *
+ * @public
+ */
+
+/**
+ * Setup options for a legacy store configured to use `Model` along with the
+ * legacy adapter/serializer network layer, but without the deprecated
+ * `store.findRecord`/`findAll`/`query`/etc. request methods.
+ *
+ * @public
+ */
+
+/**
+ * Setup options for a legacy store configured to use `Model` along with the
+ * legacy adapter/serializer network layer and the deprecated
+ * `store.findRecord`/`findAll`/`query`/etc. request methods.
+ *
+ * @public
+ */
+
 //export type ConfiguredStore<T = unknown> = typeof Store;
 
+/**
+ * The available options when setting up the legacy store,
+ * one of:
+ *
+ * - {@link LegacyModelStoreSetupOptions}
+ * - {@link LegacyModelAndNetworkStoreSetupOptions}
+ * - {@link LegacyModelAndNetworkAndRequestStoreSetupOptions}
+ */
+
 /**
  * Use the legacy store with the given options.
+ *
+ * See {@link LegacyStoreSetupOptions} for details on the available options.
+ *
+ * ```ts
+ * import { useLegacyStore } from '@warp-drive/legacy';
+ * import { JSONAPICache } from '@warp-drive/json-api';
+ *
+ * export default useLegacyStore({
+ *   linksMode: false,
+ *   legacyRequests: true,
+ *   cache: JSONAPICache,
+ *   schemas: [],
+ * });
+ * ```
+ *
+ * ### Adding Stateful Handlers
+ *
+ * A request {@link Handler} is sometimes more than a plain object or class
+ * with a `request` method — it may need access to a stateful dependency such
+ * as an Ember service (an auth token, a feature-flags service, an i18n
+ * helper, etc.).
+ *
+ * A plain class handler that only relies on Ember's `@service` decorator will
+ * not work here on its own: the handler is never instantiated *through*
+ * Ember's container (it's just `new`'d up), so it has no owner and its
+ * `@service` injections would fail to resolve.
+ *
+ * Instead, give `handlers` a function. It receives the {@link Store} instance
+ * being configured, which by the time the function runs already has an owner
+ * assigned. Use `getOwner`/`setOwner` from `@ember/owner` to transfer that
+ * owner onto your handler instance before returning it, exactly as you would
+ * when constructing any other DI-aware object outside of the container:
+ *
+ * ```ts
+ * import { getOwner, setOwner } from '@ember/owner';
+ * import { service } from '@ember/service';
+ * import { useLegacyStore } from '@warp-drive/legacy';
+ * import type { NextFn } from '@warp-drive/core/request';
+ * import type { RequestContext } from '@warp-drive/core/types/request';
+ * import { JSONAPICache } from '@warp-drive/json-api';
+ *
+ * class AuthHandler {
+ *   @service session;
+ *
+ *   request<T>(context: RequestContext, next: NextFn<T>) {
+ *     const headers = new Headers(context.request.headers);
+ *     headers.append('Authorization', `Bearer ${this.session.accessToken}`);
+ *     return next(Object.assign({}, context.request, { headers }));
+ *   }
+ * }
+ *
+ * export default useLegacyStore({
+ *   linksMode: false,
+ *   legacyRequests: true,
+ *   cache: JSONAPICache,
+ *   handlers: (store) => {
+ *     const authHandler = new AuthHandler();
+ *     setOwner(authHandler, getOwner(store)!);
+ *     return [authHandler];
+ *   },
+ * });
+ * ```
+ *
+ * The `handlers` function is invoked lazily and only once per store instance,
+ * the first time `store.requestManager` is accessed, so it is safe to do
+ * owner-dependent setup like this inside of it.
+ *
+ * ### Accessing the Store from a Handler's Context
+ *
+ * If a handler only needs to read something *off of the store itself*
+ * (its cache, or a property/service you've attached to a custom store
+ * subclass) rather than an unrelated Ember service, there is a second,
+ * simpler option that requires no DI/`setOwner` wiring at all.
+ *
+ * Every request issued via {@link Store.request | store.request(...)}
+ * automatically carries the originating store along as
+ * {@link RequestInfo.store | context.request.store}. Any handler — a plain
+ * object, a function-built handler, or a class — can read it directly,
+ * without needing the `handlers` callback form shown above:
+ *
+ * ```ts
+ * import { useLegacyStore } from '@warp-drive/legacy';
+ * import type { NextFn } from '@warp-drive/core/request';
+ * import type { RequestContext } from '@warp-drive/core/types/request';
+ * import { JSONAPICache } from '@warp-drive/json-api';
+ *
+ * const LoggingHandler = {
+ *   request<T>(context: RequestContext, next: NextFn<T>) {
+ *     // only present when the request was made via `store.request(...)`
+ *     const store = context.request.store;
+ *     if (store) {
+ *       console.log(`[${store.constructor.name}] ${context.request.url ?? ''}`);
+ *     }
+ *     return next(context.request);
+ *   },
+ * };
+ *
+ * export default useLegacyStore({
+ *   linksMode: false,
+ *   legacyRequests: true,
+ *   cache: JSONAPICache,
+ *   handlers: [LoggingHandler],
+ * });
+ * ```
+ *
+ * The trade-off versus the `getOwner`/`setOwner` pattern above is that
+ * `context.request.store` is only populated for requests issued via
+ * `store.request(...)`; a request made directly against a
+ * {@link RequestManager} won't have it set unless the caller supplies it
+ * explicitly, so a handler relying on it should treat it as optional (as
+ * `LoggingHandler` does above).
  */
 
 function useLegacyStore(options, StoreKlass = Store) {
@@ -34,7 +177,30 @@ function useLegacyStore(options, StoreKlass = Store) {
   // we extend the store to ensure we don't leak our prototype overrides to other stores below.
   class BaseKlass extends StoreKlass {}
   class LegacyConfiguredStore extends BaseKlass {
-    requestManager = new RequestManager().use([options.linksMode ? null : LegacyNetworkHandler, ...(options.handlers ?? []), Fetch].filter(Boolean)).useCache(CacheHandler);
+    constructor(createArgs) {
+      super(createArgs);
+      // installed via defineProperty (rather than a class field/accessor) so that
+      // this lazy override of the inherited `requestManager` field does not
+      // conflict with the documented pattern of assigning it directly on
+      // consumer-authored Store subclasses. The setter preserves the ability
+      // to replace `requestManager` outright after construction.
+      let requestManager;
+      Object.defineProperty(this, 'requestManager', {
+        configurable: true,
+        enumerable: true,
+        get: () => {
+          if (!requestManager) {
+            const handlersOption = options.handlers;
+            const handlers = typeof handlersOption === 'function' ? handlersOption(this) : handlersOption ?? [];
+            requestManager = new RequestManager().use([options.linksMode ? null : LegacyNetworkHandler, ...handlers, Fetch].filter(Boolean)).useCache(CacheHandler);
+          }
+          return requestManager;
+        },
+        set: value => {
+          requestManager = value;
+        }
+      });
+    }
     lifetimes = options.policy ?? new DefaultCachePolicy({
       apiCacheHardExpires: 15 * 60 * 1000,
       // 15 minutes
@@ -114,14 +280,6 @@ function useLegacyStore(options, StoreKlass = Store) {
     }
     modelFor(type) {
       assertType(this.schema, type);
-      // TODO I'm not sure this is right
-      (test => {
-        if (!test) {
-          throw new Error(`modelFor should only be used to lookup legacy models when in linksMode: false`);
-        }
-      })(!options.linksMode || !this.schema.isDelegated({
-        type
-      }));
       const klass =
       // prefer real models if present
       modelFor.call(this, type) || (

package/dist/unpkg/{prod-deprecated/json-BWrZ5546.js → dev-deprecated/json-K2Y9z6MN.js}

@@ -13,6 +13,78 @@ function coerceId(id) {
   }
 }
 
+/**
+  Given the name of a relationship on a resource `type`, determines the
+  inverse relationship field (if any) using only the schema service.
+
+  Unlike `Model.inverseFor`, this does not require `type` to be backed by
+  a `Model` class, so it works for both `Model`-based and schema-only
+  (e.g. `withDefaults` migration-support) resources.
+
+  @private
+*/
+function inverseForRelationship(store, type, name) {
+  const relationship = store.schema.fields({
+    type
+  }).get(name);
+  (test => {
+    if (!test) {
+      throw new Error(`No relationship named '${name}' on '${type}' exists.`);
+    }
+  })(relationship);
+  const {
+    options
+  } = relationship;
+  (test => {
+    if (!test) {
+      throw new Error(`Expected the relationship ${name} on ${type} to define an inverse.`);
+    }
+  })(options.inverse === null || typeof options.inverse === 'string' && options.inverse.length > 0);
+  if (options.inverse === null) {
+    return null;
+  }
+  const schemaExists = store.schema.hasResource(relationship);
+  (test => {
+    if (!test) {
+      throw new Error(`No associated schema found for '${relationship.type}' while calculating the inverse of ${name} on ${type}`);
+    }
+  })(schemaExists);
+  if (!schemaExists) {
+    return null;
+  }
+  const inverseField = store.schema.fields(relationship).get(options.inverse);
+  (test => {
+    if (!test) {
+      throw new Error(`No inverse relationship found for '${name}' on '${type}'`);
+    }
+  })(inverseField && (inverseField.kind === 'belongsTo' || inverseField.kind === 'hasMany'));
+  return inverseField ?? null;
+}
+
+/**
+  Given a relationship field on a resource `type`, determines the
+  cardinality of the relationship using only the schema service.
+
+  Unlike `Model.determineRelationshipType`, this does not require `type`
+  to be backed by a `Model` class, so it works for both `Model`-based and
+  schema-only (e.g. `withDefaults` migration-support) resources.
+
+  @private
+*/
+function determineRelationshipType(store, type, knownSide) {
+  const knownKind = knownSide.kind;
+  const inverse = inverseForRelationship(store, type, knownSide.name);
+  if (!inverse) {
+    return knownKind === 'belongsTo' ? 'oneToNone' : 'manyToNone';
+  }
+  const otherKind = inverse.kind;
+  if (otherKind === 'belongsTo') {
+    return knownKind === 'belongsTo' ? 'oneToOne' : 'manyToOne';
+  } else {
+    return knownKind === 'belongsTo' ? 'oneToMany' : 'manyToMany';
+  }
+}
+
 /* eslint-disable @typescript-eslint/no-unsafe-argument */
 /* eslint-disable @typescript-eslint/no-unsafe-call */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
@@ -381,6 +453,11 @@ const JSONSerializer = Serializer.extend({
     };
     const meta = this.extractMeta(store, primaryModelClass, payload);
     if (meta) {
+      (test => {
+        if (!test) {
+          throw new Error('The `meta` returned from `extractMeta` has to be an object, not "' + typeof meta + '".');
+        }
+      })(typeof meta === 'object');
       // @ts-expect-error untyped
       documentHash.meta = meta;
     }
@@ -686,6 +763,9 @@ const JSONSerializer = Serializer.extend({
      @private
   */
   _getMappedKey(key, modelClass) {
+    console.warn('There is no attribute or relationship with the name `' + key + '` on `' + modelClass.modelName + '`. Check your serializers attrs hash.', modelClass.attributes.has(key) || modelClass.relationshipsByName.has(key), {
+      id: 'ds.serializer.no-mapped-attrs-key'
+    }); // @ts-expect-error attrs is dynamically injected
     const attrs = this.attrs;
     let mappedKey;
     if (attrs && attrs[key]) {
@@ -733,9 +813,7 @@ const JSONSerializer = Serializer.extend({
   */
   shouldSerializeHasMany(snapshot, key, relationship) {
     // @ts-expect-error store is dynamically injected
-    const schema = this.store.modelFor(snapshot.modelName);
-    // @ts-expect-error store is dynamically injected
-    const relationshipType = schema.determineRelationshipType(relationship, this.store);
+    const relationshipType = determineRelationshipType(this.store, snapshot.modelName, relationship);
     if (this._mustSerialize(key)) {
       return true;
     }
@@ -774,8 +852,15 @@ const JSONSerializer = Serializer.extend({
      `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 adapter passes in `includeId: true` when serializing
-    a record for `createRecord`, but not for `updateRecord`.
+     Whether `includeId` is `true` or `false` depends on the
+    adapter and the operation being performed, since it is the
+    adapter that invokes `serialize` and decides which options
+    to pass. For instance, `RESTAdapter` passes `includeId: true`
+    when serializing a record for `createRecord`, but not for
+    `updateRecord`, while `JSONAPIAdapter` passes `includeId: true`
+    for both `createRecord` and `updateRecord`. Refer to the
+    documentation for the adapter and serializer pairing you are
+    using for specifics.
      ## Customization
      Your server may expect a different JSON format than the
     built-in serialization format.
@@ -1237,7 +1322,12 @@ const JSONSerializer = Serializer.extend({
   */
   transformFor(attributeType, skipAssertion) {
     const transform = getOwner(this).lookup(`transform:${attributeType}`);
+    (test => {
+      if (!test) {
+        throw new Error(`Unable to find the transform for \`attr('${attributeType}')\``);
+      }
+    })(skipAssertion || !!transform);
     return transform;
   }
 });
-export { JSONSerializer as J, coerceId as c };
+export { JSONSerializer as J, coerceId as c, inverseForRelationship as i };

package/dist/unpkg/dev-deprecated/model/-private.js

@@ -1 +1 @@
-export { E as Errors, L as LEGACY_SUPPORT, P as PromiseBelongsTo, a as PromiseManyArray, l as lookupLegacySupport } from "../errors-Spt6ubMd.js";
+export { E as Errors, L as LEGACY_SUPPORT, P as PromiseBelongsTo, a as PromiseManyArray, l as lookupLegacySupport } from "../errors-Bzidntpi.js";

package/dist/unpkg/dev-deprecated/model/migration-support.js

@@ -4,8 +4,8 @@ import { notifyInternalSignal } from '@warp-drive/core/signals/-leaked';
 import { assertPrivateStore } from '@warp-drive/core/store/-private';
 import { getOrSetGlobal } from '@warp-drive/core/types/-private';
 import { Type } from '@warp-drive/core/types/symbols';
-import { l as lookupLegacySupport, E as Errors } from "../errors-Spt6ubMd.js";
-import { b as buildSchema, u as unloadRecord, s as serialize, _ as _save, a as save, r as rollbackAttributes, c as _reload, d as reload, h as hasMany, e as _destroyRecord, f as destroyRecord, i as deleteRecord, R as RecordState, j as changedAttributes, k as belongsTo, l as createSnapshot } from "../schema-provider-BP6_8N-V.js";
+import { l as lookupLegacySupport, E as Errors } from "../errors-Bzidntpi.js";
+import { b as buildSchema, u as unloadRecord, s as serialize, _ as _save, a as save, r as rollbackAttributes, c as _reload, d as reload, h as hasMany, e as _destroyRecord, f as destroyRecord, i as deleteRecord, R as RecordState, j as changedAttributes, k as belongsTo, l as createSnapshot } from "../schema-provider-ZwO5_fZw.js";
 
 /**
  * This module provides support for migrating away from @warp-drive/legacy/model
@@ -27,6 +27,12 @@ import { b as buildSchema, u as unloadRecord, s as serialize, _ as _save, a as s
  * @module
  */
 
+/**
+ * Adds the `Model`-style `belongsTo`/`hasMany` reference methods to a
+ * {@link TypedRecordInstance}, for use when migrating a resource from
+ * `Model` to a schema-based record while preserving these APIs.
+ */
+
 // 'isDestroying', 'isDestroyed'
 const LegacyFields = ['_createSnapshot', 'adapterError', 'belongsTo', 'changedAttributes', 'constructor', 'currentState', 'deleteRecord', 'destroyRecord', 'dirtyType', 'errors', 'hasDirtyAttributes', 'hasMany', 'isDeleted', 'isEmpty', 'isError', 'isLoaded', 'isLoading', 'isNew', 'isSaving', 'isValid', 'reload', 'rollbackAttributes', 'save', 'serialize', 'unloadRecord'];
 
@@ -423,6 +429,9 @@ function registerDerivations(schema) {
  * @public
  */
 
+/**
+ * See the {@link DelegatingSchemaService | class documentation above} for usage.
+ */
 class DelegatingSchemaService {
   /** @internal */
   _preferred;
@@ -432,6 +441,11 @@ class DelegatingSchemaService {
     this._preferred = schema;
     this._secondary = buildSchema(store);
   }
+
+  /**
+   * Whether the given resource's schema is being served by the fallback
+   * (legacy Model-derived) schema service rather than the primary one.
+   */
   isDelegated(resource) {
     return !this._preferred.hasResource(resource) && this._secondary.hasResource(resource);
   }

package/dist/unpkg/{dev/model-for-CqXsIKws.js → dev-deprecated/model-for-CXkJw59V.js}

@@ -1,6 +1,11 @@
 import { tracked, cached } from '@glimmer/tracking';
 import { Context } from '@warp-drive/core/reactive/-private';
 import { a as decorateFieldV2, i as initializeDeferredDecorator, d as decorateMethodV2 } from "./runtime-BPCpkOf1-BKOwiRJp.js";
+
+/**
+ * The features added to an object resource by {@link FragmentExtension}, providing
+ * a subset of the legacy `ModelFragments` fragment API for migrated resources.
+ */
 class Fragment {
   static {
     decorateFieldV2(this.prototype, "isDestroying", [tracked], function () {
@@ -8,12 +13,21 @@ class Fragment {
     });
   }
   #isDestroying = (initializeDeferredDecorator(this, "isDestroying"), void 0); // We might want to check the parent values once we move this code to warp-drive.
+  /**
+   * Whether this fragment is in the process of being destroyed.
+   */
   static {
     decorateFieldV2(this.prototype, "isDestroyed", [tracked], function () {
       return false;
     });
   }
   #isDestroyed = (initializeDeferredDecorator(this, "isDestroyed"), void 0);
+  /**
+   * Whether this fragment has been destroyed.
+   */
+  /**
+   * Whether this fragment (or the attribute it is rooted at) has uncommitted changes.
+   */
   get hasDirtyAttributes() {
     const {
       path,
@@ -27,18 +41,30 @@ class Fragment {
     }
     return false;
   }
+
+  /**
+   * Always `true`. Used to distinguish fragments from other resources.
+   */
   static {
     decorateMethodV2(this.prototype, "hasDirtyAttributes", [cached]);
   }
   get isFragment() {
     return true;
   }
+
+  /**
+   * The resource type of this fragment, if known.
+   */
   get $type() {
     const {
       field
     } = this[Context];
     return field?.type;
   }
+
+  /**
+   * Reverts this fragment's attribute back to its last known remote value.
+   */
   rollbackAttributes() {
     const {
       path,
@@ -51,11 +77,21 @@ class Fragment {
     }
   }
 }
+
+/**
+ * A schema extension that adds the {@link Fragment} API to migrated
+ * `ModelFragments` object resources.
+ */
 const FragmentExtension = {
   kind: 'object',
   name: 'fragment',
   features: Fragment
 };
+
+/**
+ * The features added to an array resource by {@link FragmentArrayExtension}, providing
+ * a subset of the legacy `ModelFragments` fragment-array API for migrated resources.
+ */
 class FragmentArray {
   static {
     decorateFieldV2(this.prototype, "isDestroying", [tracked], function () {
@@ -63,18 +99,29 @@ class FragmentArray {
     });
   }
   #isDestroying = (initializeDeferredDecorator(this, "isDestroying"), void 0); // We might want to check the parent values once we move this code to warp-drive.
+  /**
+   * Whether this fragment array is in the process of being destroyed.
+   */
   static {
     decorateFieldV2(this.prototype, "isDestroyed", [tracked], function () {
       return false;
     });
   }
   #isDestroyed = (initializeDeferredDecorator(this, "isDestroyed"), void 0);
+  /**
+   * Whether this fragment array has been destroyed.
+   */
+  /**
+   * Whether this fragment array (or any of its members) has uncommitted changes.
+   */
   get hasDirtyAttributes() {
+    const array = this;
+    const context = array[Context];
     const {
       path,
       resourceKey,
       store
-    } = this[Context];
+    } = context;
     const record = store.peekRecord(resourceKey);
     if (record.hasDirtyAttributes && path) {
       const root = path.at(0);
@@ -82,6 +129,10 @@ class FragmentArray {
     }
     return false;
   }
+
+  /**
+   * Adds an existing fragment to this array, if one was given.
+   */
   static {
     decorateMethodV2(this.prototype, "hasDirtyAttributes", [cached]);
   }
@@ -91,12 +142,20 @@ class FragmentArray {
     }
     return this.addObject(fragment);
   }
+
+  /**
+   * Appends a new fragment to the end of this array, if one was given.
+   */
   createFragment(fragment) {
     if (!fragment) {
       return;
     }
     return this.pushObject(fragment);
   }
+
+  /**
+   * Removes the given fragment from this array, if present.
+   */
   removeFragment(fragment) {
     if (!fragment) {
       return;
@@ -106,6 +165,10 @@ class FragmentArray {
       this.splice(index, 1);
     }
   }
+
+  /**
+   * Reverts each member fragment's attribute back to its last known remote value.
+   */
   rollbackAttributes() {
     for (const fragment of this) {
       // @ts-expect-error TODO: fix these types
@@ -113,6 +176,11 @@ class FragmentArray {
     }
   }
 }
+
+/**
+ * A schema extension that adds the {@link FragmentArray} API to migrated
+ * `ModelFragments` array resources.
+ */
 const FragmentArrayExtension = {
   kind: 'array',
   name: 'fragment-array',
@@ -217,5 +285,13 @@ class ShimModelClass {
 function fragmentsModelFor(modelName) {
   return getShimClass(this, modelName);
 }
+
+/**
+ * The `modelFor` fallback used to construct a `ShimModelClass` schema for a
+ * type when ModelFragments support is enabled and no real `Model` subclass
+ * is registered for that type.
+ *
+ * @public
+ */
 const modelFor = fragmentsModelFor;
 export { FragmentExtension as F, FragmentArrayExtension as a, FragmentArray as b, Fragment as c, fragmentsModelFor as f, modelFor as m };

package/dist/unpkg/dev-deprecated/model-fragments.js

@@ -1,7 +1,7 @@
 import { pluralize, singularize } from '@warp-drive/utilities/string';
 import { withDefaults } from './model/migration-support.js';
-import { F as FragmentExtension, a as FragmentArrayExtension } from "./model-for-CqXsIKws.js";
-export { c as Fragment, b as FragmentArray, m as modelFor } from "./model-for-CqXsIKws.js";
+import { F as FragmentExtension, a as FragmentArrayExtension } from "./model-for-CXkJw59V.js";
+export { c as Fragment, b as FragmentArray, m as modelFor } from "./model-for-CXkJw59V.js";
 
 /**
  * Used as a helper to setup the relevant parts of an array
@@ -62,6 +62,15 @@ function withFragmentArrayDefaults(fragmentArrayType, fragmentArrayName) {
     }
   };
 }
+
+/**
+ * Used as a helper to setup the relevant parts of a legacy resource schema
+ * migrated from `Model`, applying the `ember-object` and `fragment` object
+ * extensions and a default `@id` identity field.
+ *
+ * @param schema the partial legacy resource schema to complete
+ * @returns the completed resource schema
+ */
 function withLegacy(schema) {
   return withDefaults({
     ...schema,
@@ -72,6 +81,13 @@ function withLegacy(schema) {
     objectExtensions: ['ember-object', 'fragment']
   });
 }
+
+/**
+ * Registers the {@link FragmentExtension}/{@link FragmentArrayExtension} schema
+ * extensions on the given `SchemaService`, enabling ModelFragments migration support.
+ *
+ * @public
+ */
 function registerFragmentExtensions(schema) {
   schema.CAUTION_MEGA_DANGER_ZONE_registerExtension?.(FragmentExtension);
   schema.CAUTION_MEGA_DANGER_ZONE_registerExtension?.(FragmentArrayExtension);