ember-data-model-fragments 7.0.3 → 8.0.2

package/addon/serializers/utils.js

@@ -0,0 +1,253 @@
+import { assert } from '@ember/debug';
+import { getOwner } from '@ember/application';
+import JSONAPISerializer from '@ember-data/serializer/json-api';
+import RESTSerializer from '@ember-data/serializer/rest';
+
+/**
+ * Helper function to implement fragment transform lookup.
+ * Used by FragmentSerializer, FragmentRESTSerializer, and FragmentJSONAPISerializer.
+ *
+ * @param {Serializer} serializer - The serializer instance
+ * @param {String} attributeType - The attribute type to get the transform for
+ * @param {Function} superTransformFor - The parent class's transformFor method
+ * @return {Transform}
+ * @private
+ */
+export function fragmentTransformFor(
+  serializer,
+  attributeType,
+  superTransformFor,
+) {
+  if (attributeType.indexOf('-mf-') !== 0) {
+    return superTransformFor.call(serializer, attributeType);
+  }
+
+  const owner = getOwner(serializer);
+  const containerKey = `transform:${attributeType}`;
+
+  if (!owner.hasRegistration(containerKey)) {
+    const match = attributeType.match(
+      /^-mf-(fragment|fragment-array|array)(?:\$([^$]+))?(?:\$(.+))?$/,
+    );
+    assert(
+      `Failed parsing ember-data-model-fragments attribute type ${attributeType}`,
+      match != null,
+    );
+    const transformName = match[1];
+    const type = match[2];
+    const polymorphicTypeProp = match[3];
+    let transformClass = owner.factoryFor(`transform:${transformName}`);
+    transformClass = transformClass && transformClass.class;
+    transformClass = transformClass.extend({
+      type,
+      polymorphicTypeProp,
+      store: serializer.store,
+    });
+    owner.register(containerKey, transformClass);
+  }
+  return owner.lookup(containerKey);
+}
+
+/**
+ * Helper function to implement fragment-aware applyTransforms.
+ * Used by FragmentSerializer, FragmentRESTSerializer, and FragmentJSONAPISerializer.
+ *
+ * @param {Serializer} serializer - The serializer instance
+ * @param {Class} typeClass - The model class
+ * @param {Object} data - The data to apply transforms to
+ * @return {Object} The transformed data
+ * @private
+ */
+export function fragmentApplyTransforms(serializer, typeClass, data) {
+  const attributes = typeClass.attributes;
+
+  // Handle regular @attr transforms
+  typeClass.eachTransformedAttribute((key, attrType) => {
+    if (data[key] === undefined) {
+      return;
+    }
+
+    const transform = serializer.transformFor(attrType);
+    const transformMeta = attributes.get(key);
+    data[key] = transform.deserialize(data[key], transformMeta.options, data);
+  });
+
+  // Also handle @array computed properties with transforms
+  // These are not in eachTransformedAttribute because they're computed properties,
+  // not regular @attr attributes
+  typeClass.eachComputedProperty((key, meta) => {
+    if (data[key] === undefined) {
+      return;
+    }
+
+    // Only handle @array attributes that have a transform type (arrayTransform)
+    // meta.arrayTransform is the child transform type (e.g., 'string')
+    // meta.type is the full transform type string (e.g., '-mf-array$string')
+    if (meta?.isFragment && meta.kind === 'array' && meta.arrayTransform) {
+      // Use the full transform type string from meta.type
+      const transform = serializer.transformFor(meta.type);
+      data[key] = transform.deserialize(data[key], meta.options, data);
+    }
+  });
+
+  return data;
+}
+
+function isFragmentAttribute(meta) {
+  return (
+    meta &&
+    meta.isFragment &&
+    (meta.kind === 'fragment' ||
+      meta.kind === 'fragment-array' ||
+      meta.kind === 'array')
+  );
+}
+
+function serializedAttributesHash(serializer, snapshot, payload) {
+  // JSON:API: fragment attributes belong inside payload.data.attributes.
+  // If the model has no regular @attr fields, JSONAPISerializer#serialize
+  // omits `attributes` entirely, so we create it here. We dispatch by
+  // serializer type rather than payload shape, because a model could
+  // legitimately declare an @attr named `data` under RESTSerializer /
+  // JSONSerializer and we must not clobber it.
+  if (serializer instanceof JSONAPISerializer) {
+    if (payload?.data && typeof payload.data === 'object') {
+      payload.data.attributes ??= {};
+      return payload.data.attributes;
+    }
+    return payload;
+  }
+
+  // RESTSerializer: payload is keyed by the model's payload key, e.g.
+  // `{ person: { ...attrs } }`.
+  if (serializer instanceof RESTSerializer) {
+    const rootKey = serializer.payloadKeyFromModelName?.(snapshot.modelName);
+    if (rootKey && payload?.[rootKey] && typeof payload[rootKey] === 'object') {
+      return payload[rootKey];
+    }
+    return payload;
+  }
+
+  // JSONSerializer (default): flat hash keyed by attribute names.
+  return payload;
+}
+
+/**
+ * Helper function to serialize computed fragment attributes that newer
+ * ember-data versions no longer include via eachAttribute.
+ *
+ * @param {Serializer} serializer
+ * @param {Snapshot} snapshot
+ * @param {Object} payload
+ * @return {Object}
+ * @private
+ */
+export function fragmentSerialize(serializer, snapshot, payload) {
+  const attributes = serializedAttributesHash(serializer, snapshot, payload);
+  const modelClass = serializer.store.modelFor(snapshot.modelName);
+
+  modelClass.eachComputedProperty((key, meta) => {
+    if (!isFragmentAttribute(meta)) {
+      return;
+    }
+
+    const value = snapshot.attr(key);
+
+    if (value === undefined) {
+      return;
+    }
+
+    const attributeKey = serializer.keyForAttribute(key, 'serialize');
+    const transform = serializer.transformFor(meta.type);
+
+    attributes[attributeKey] = transform.serialize(
+      value,
+      meta.options,
+      snapshot,
+    );
+  });
+
+  return payload;
+}
+
+/**
+ * Helper function to extract attributes including fragment attributes.
+ * The default extractAttributes only iterates modelClass.eachAttribute which
+ * doesn't include fragment attributes (they're computed properties).
+ *
+ * Used by FragmentSerializer and FragmentRESTSerializer.
+ *
+ * @param {Serializer} serializer - The serializer instance
+ * @param {Class} modelClass - The model class
+ * @param {Object} resourceHash - The raw resource data from the server
+ * @param {Function} superExtractAttributes - The parent's extractAttributes method
+ * @return {Object} The extracted attributes
+ * @private
+ */
+export function fragmentExtractAttributes(
+  serializer,
+  modelClass,
+  resourceHash,
+  superExtractAttributes,
+) {
+  // First, call parent to get regular attributes
+  const attributes = superExtractAttributes.call(
+    serializer,
+    modelClass,
+    resourceHash,
+  );
+
+  // Then, add fragment attributes
+  modelClass.eachComputedProperty((key, meta) => {
+    if (isFragmentAttribute(meta)) {
+      const attributeKey = serializer.keyForAttribute(key, 'deserialize');
+      if (resourceHash[attributeKey] !== undefined) {
+        attributes[key] = resourceHash[attributeKey];
+      }
+    }
+  });
+
+  return attributes;
+}
+
+/**
+ * Helper function to extract attributes including fragment attributes for JSON:API.
+ * JSON:API serializers have attributes nested under resourceHash.attributes.
+ *
+ * Used by FragmentJSONAPISerializer.
+ *
+ * @param {Serializer} serializer - The serializer instance
+ * @param {Class} modelClass - The model class
+ * @param {Object} resourceHash - The raw resource data from the server
+ * @param {Function} superExtractAttributes - The parent's extractAttributes method
+ * @return {Object} The extracted attributes
+ * @private
+ */
+export function fragmentExtractAttributesJSONAPI(
+  serializer,
+  modelClass,
+  resourceHash,
+  superExtractAttributes,
+) {
+  // First, call parent to get regular attributes
+  const attributes = superExtractAttributes.call(
+    serializer,
+    modelClass,
+    resourceHash,
+  );
+
+  // For JSON:API serializers, attributes are nested under resourceHash.attributes
+  const attrHash = resourceHash.attributes || resourceHash;
+
+  // Then, add fragment attributes
+  modelClass.eachComputedProperty((key, meta) => {
+    if (isFragmentAttribute(meta)) {
+      const attributeKey = serializer.keyForAttribute(key, 'deserialize');
+      if (attrHash[attributeKey] !== undefined) {
+        attributes[key] = attrHash[attributeKey];
+      }
+    }
+  });
+
+  return attributes;
+}

package/addon/store.js

@@ -0,0 +1,301 @@
+import { assert } from '@ember/debug';
+import { getOwner } from '@ember/application';
+import Store from 'ember-data/store';
+import {
+  macroCondition,
+  dependencySatisfies,
+  importSync,
+} from '@embroider/macros';
+import FragmentCache from './cache/fragment-cache';
+import { default as Fragment } from './fragment';
+import { installCacheManagerCompat } from './util/fragment-cache';
+
+// Import side-effects to ensure monkey-patches are applied
+// These must be imported before any store instances are created
+import './ext'; // Applies Snapshot monkey-patch for fragment serialization
+
+/**
+  FragmentStore is the base store class for ember-data-model-fragments.
+  
+  To use this addon, you must create an application store service that extends FragmentStore:
+  
+  ```js
+  // app/services/store.js
+  import FragmentStore from 'ember-data-model-fragments/store';
+  
+  export default class extends FragmentStore {}
+  ```
+
+  Your application serializer should also extend one of the fragment-aware serializers:
+
+  ```js
+  // app/serializers/application.js
+  import FragmentSerializer from 'ember-data-model-fragments/serializer';
+  
+  export default class extends FragmentSerializer {}
+  ```
+
+  @class FragmentStore
+  @extends Store
+  @public
+*/
+export default class FragmentStore extends Store {
+  get cache() {
+    return installCacheManagerCompat(this, super.cache);
+  }
+
+  /**
+   * Override createCache to return our FragmentCache
+   * This is the V2 Cache hook introduced in ember-data 4.7+
+   *
+   * @method createCache
+   * @param {Object} storeWrapper
+   * @return {FragmentCache}
+   * @public
+   */
+  createCache(storeWrapper) {
+    return new FragmentCache(storeWrapper);
+  }
+
+  /**
+   * Override createSchemaService to provide fragment-aware schema for ember-data 4.13+
+   *
+   * In ember-data 4.13, a new schema service architecture was introduced that only
+   * recognizes attributes with `kind: 'attribute'`. Fragment attributes use different
+   * kinds ('fragment', 'fragment-array', 'array'), so they need special handling.
+   *
+   * This method is only called in ember-data 4.13+. For ember-data 4.12, this method
+   * doesn't exist in the Store class, so it's never invoked.
+   *
+   * The `macroCondition` ensures build-time optimization:
+   * - For 4.12 builds: This code is completely removed (tree-shaking)
+   * - For 4.13 builds: Only the FragmentSchemaService path remains
+   *
+   * @method createSchemaService
+   * @return {FragmentSchemaService|undefined}
+   * @public
+   */
+  createSchemaService() {
+    if (macroCondition(dependencySatisfies('ember-data', '>=4.13.0-alpha.0'))) {
+      const { buildSchema } = importSync('@ember-data/model/hooks');
+
+      const FragmentSchemaService = importSync('./schema-service').default;
+
+      return new FragmentSchemaService(this, buildSchema(this));
+    }
+    // For ember-data 4.12, this method is never called (doesn't exist in Store base class)
+    return undefined;
+  }
+
+  /**
+   * Override teardownRecord to handle fragments in a disconnected state.
+   * In ember-data 4.12+, fragments can end up disconnected during unload,
+   * and the default teardownRecord fails when trying to destroy them.
+   *
+   * @method teardownRecord
+   * @param {Model} record
+   * @public
+   */
+  teardownRecord(record) {
+    // Check if record is a fragment (by checking if it has no id or by model type)
+    // We need to handle the case where the fragment's store is disconnected
+    if (record.isDestroyed || record.isDestroying) {
+      return;
+    }
+    try {
+      record.destroy();
+    } catch (e) {
+      // If the error is about disconnected state, just let it go
+      // The fragment will be cleaned up by ember's garbage collection
+      if (
+        e?.message?.includes?.('disconnected state') ||
+        e?.message?.includes?.('cannot utilize the store')
+      ) {
+        return;
+      }
+      throw e;
+    }
+  }
+
+  /**
+    Create a new fragment that does not yet have an owner record.
+    The properties passed to this method are set on the newly created
+    fragment.
+
+    To create a new instance of the `name` fragment:
+
+    ```js
+    store.createFragment('name', {
+      first: 'Alex',
+      last: 'Routé'
+    });
+    ```
+
+    @method createFragment
+    @param {String} modelName - The type of fragment to create
+    @param {Object} props - A hash of properties to set on the newly created fragment
+    @return {Fragment} fragment
+    @public
+  */
+  createFragment(modelName, props) {
+    assert(
+      `The '${modelName}' model must be a subclass of MF.Fragment`,
+      this.isFragment(modelName),
+    );
+    // Create a new identifier for the fragment
+    const identifier = this.identifierCache.createIdentifierForNewRecord({
+      type: modelName,
+    });
+    // Signal to cache that this is a new record
+    this.cache.clientDidCreate(identifier, props || {});
+    if (macroCondition(dependencySatisfies('ember-data', '>=5.8.0'))) {
+      const record = this._instanceCache.getRecord(identifier);
+
+      if (props) {
+        const definitions =
+          this.getSchemaDefinitionService().fields(identifier);
+
+        for (const [key, value] of Object.entries(props)) {
+          if (!definitions.has(key)) {
+            record.set(key, value);
+          }
+        }
+      }
+
+      return record;
+    }
+
+    // Get the record instance
+    return this._instanceCache.getRecord(identifier, props);
+  }
+
+  /**
+    Override `serializerFor` so fragment models never fall back to
+    `serializer:application`.
+
+    Why: a typical app's `serializer:application` is a REST or JSON:API
+    serializer that does not know how to normalize a raw fragment hash. In
+    particular, a JSON:API application serializer would trip the assert in
+    `FragmentTransform.deserializeSingle` and break fragment deserialization
+    on ember-data 4.12 (and any other path that runs the fragment transform
+    pipeline).
+
+    Resolution order for fragment model names:
+      1. `serializer:{modelName}` (if the app registered a per-fragment serializer)
+      2. `serializer:-fragment` (consumer-overridable global fragment serializer)
+      3. `serializer:-mf-fragment` (lazily-registered default `FragmentSerializer`,
+         which extends `JSONSerializer` and is what the fragment pipeline expects)
+
+    Non-fragment lookups defer to the parent `serializerFor`, preserving normal
+    app behavior (including `serializer:application` fallback).
+
+    Implementation note: in ember-data 5.x, `serializerFor` is defined on the
+    parent `Store` as a class-field arrow function, which is assigned per
+    instance during the parent constructor and would shadow any prototype-level
+    override declared on this subclass. To handle both shapes (class field on
+    5.x, prototype method on 4.12) we install the override in the constructor,
+    which runs after the parent constructor and therefore wins in either case.
+    The original `serializerFor` is captured and used for non-fragment lookups.
+
+    This restores the pre-4.13 behavior that was lost when the previous
+    `Store.reopen({ serializerFor })` from `addon/ext.js` was removed.
+
+    @method serializerFor
+    @param {String} modelName
+    @return {Serializer}
+    @public
+  */
+  constructor(...args) {
+    super(...args);
+
+    const parentSerializerFor =
+      typeof this.serializerFor === 'function'
+        ? this.serializerFor.bind(this)
+        : null;
+
+    this.serializerFor = (modelName) => {
+      if (typeof modelName === 'string' && this._isFragmentSafe(modelName)) {
+        return this._fragmentSerializerFor(modelName);
+      }
+      if (parentSerializerFor) {
+        return parentSerializerFor(modelName);
+      }
+      return null;
+    };
+  }
+
+  /**
+    Resolve a serializer for a fragment model name.
+
+    @private
+  */
+  _fragmentSerializerFor(modelName) {
+    const owner = getOwner(this);
+
+    // 1. Per-fragment-type serializer (e.g. app/serializers/name.js).
+    //    `owner.lookup('serializer:<name>')` returns `undefined` when no
+    //    registration / app file exists, so a non-undefined result means a
+    //    consumer actually provided one.
+    const perTypeKey = `serializer:${modelName}`;
+    let serializer = owner.lookup(perTypeKey);
+    if (serializer !== undefined) {
+      return serializer;
+    }
+
+    // 2. Consumer-provided global fragment serializer.
+    serializer = owner.lookup('serializer:-fragment');
+    if (serializer !== undefined) {
+      return serializer;
+    }
+
+    // 3. Lazily register and return our default FragmentSerializer.
+    //    This is JSON-based (not REST/JSON:API), which is what the fragment
+    //    pipeline expects.
+    const FALLBACK_KEY = 'serializer:-mf-fragment';
+    if (!owner.hasRegistration(FALLBACK_KEY)) {
+      const FragmentSerializer = importSync('./serializers/fragment').default;
+      owner.register(FALLBACK_KEY, FragmentSerializer);
+    }
+    return owner.lookup(FALLBACK_KEY);
+  }
+
+  /**
+    Like `isFragment`, but never throws for unknown model names. `serializerFor`
+    is called with synthetic names (e.g. `-default`, `application`, transform
+    types, etc.) so we can't let `modelFor` blow up.
+
+    @private
+  */
+  _isFragmentSafe(modelName) {
+    if (
+      !modelName ||
+      modelName === 'application' ||
+      modelName === '-default' ||
+      modelName.charAt(0) === '-'
+    ) {
+      return false;
+    }
+    try {
+      return this.isFragment(modelName);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+    Returns true if the modelName is a fragment, false if not
+
+    @method isFragment
+    @param {String} modelName - The modelName to check if a fragment
+    @return {Boolean}
+    @public
+  */
+  isFragment(modelName) {
+    if (modelName === 'application' || modelName === '-default') {
+      return false;
+    }
+
+    const type = this.modelFor(modelName);
+    return Fragment.detect(type);
+  }
+}

package/addon/transforms/fragment.js

@@ -1,6 +1,4 @@
-import { assert } from '@ember/debug';
 import Transform from '@ember-data/serializer/transform';
-import JSONAPISerializer from '@ember-data/serializer/json-api';
 import { service } from '@ember/service';
 import { recordIdentifierFor } from '@ember-data/store';
 
@@ -80,13 +78,11 @@ const FragmentTransform = Transform.extend({
   deserializeSingle(data, options, parentData) {
     const store = this.store;
     const modelName = this.modelNameFor(data, options, parentData);
+    // `FragmentStore#serializerFor` guarantees a JSON-based serializer
+    // (FragmentSerializer / JSONSerializer) for fragment model names, so we
+    // do not need to defend against REST/JSON:API serializers here.
     const serializer = store.serializerFor(modelName);
 
-    assert(
-      'The `JSONAPISerializer` is not suitable for model fragments, please use `JSONSerializer`',
-      !(serializer instanceof JSONAPISerializer),
-    );
-
     const typeClass = store.modelFor(modelName);
     const serialized = serializer.normalize(typeClass, data);
 

package/addon/util/fragment-cache.js

@@ -0,0 +1,59 @@
+const CACHE_METHODS = [
+  'createFragmentRecordData',
+  'getFragment',
+  'hasFragment',
+  'setDirtyFragment',
+  'isFragmentDirty',
+  'getFragmentOwner',
+  'setFragmentOwner',
+  'newFragmentIdentifierForKey',
+  'getFragmentArrayCache',
+  'setFragmentArrayCache',
+  'rollbackFragment',
+  'hasChangedFragments',
+  'changedFragments',
+  'getFragmentCanonicalState',
+  'getFragmentCurrentState',
+];
+
+function installCacheManagerCompat(store, rawCache = store.cache) {
+  const cacheManager = rawCache;
+  const cache = cacheManager?.___cache;
+
+  if (!cacheManager || !cache || cacheManager.__mfCompatInstalled) {
+    return cache || cacheManager;
+  }
+
+  Object.defineProperty(cacheManager, '__mfCompatInstalled', {
+    value: true,
+    configurable: true,
+  });
+
+  Object.defineProperty(cacheManager, '__innerCache', {
+    get() {
+      return cache.__innerCache;
+    },
+    configurable: true,
+  });
+
+  CACHE_METHODS.forEach((methodName) => {
+    if (typeof cacheManager[methodName] === 'function') {
+      return;
+    }
+
+    Object.defineProperty(cacheManager, methodName, {
+      value(...args) {
+        return cache[methodName](...args);
+      },
+      configurable: true,
+    });
+  });
+
+  return cache;
+}
+
+export { installCacheManagerCompat };
+
+export default function fragmentCacheFor(store) {
+  return installCacheManagerCompat(store);
+}