ember-data-model-fragments 7.0.3 → 8.0.2

package/addon/attributes/fragment.js

@@ -7,6 +7,7 @@ import {
   isFragment,
   setFragmentOwner,
 } from '../fragment';
+import fragmentCacheFor from '../util/fragment-cache';
 import metaTypeFor from '../util/meta-type-for';
 import isInstanceOfType from '../util/instance-of-type';
 
@@ -60,57 +61,68 @@ export default function fragment(type, options) {
     options,
   };
 
-  // eslint-disable-next-line ember/require-computed-property-dependencies -- isDestroying/isDestroyed are guards, not dependencies
-  return computed('store.{_instanceCache,cache}', {
-    get(key) {
-      if (this.isDestroying || this.isDestroyed) {
-        return null;
-      }
-      const identifier = recordIdentifierFor(this);
-      const cache = this.store.cache;
-      const fragmentIdentifier = cache.getFragment(identifier, key);
-      if (fragmentIdentifier === null) {
-        return null;
-      }
-      // Get the fragment record from the identifier
-      return this.store._instanceCache.getRecord(fragmentIdentifier);
-    },
-    set(key, value) {
-      assert(
-        'You must pass a fragment or null to set a fragment',
-        value === null || isFragment(value) || typeOf(value) === 'object',
-      );
-      const identifier = recordIdentifierFor(this);
-      const cache = this.store.cache;
-      if (value === null) {
-        cache.setDirtyFragment(identifier, key, null);
-        return null;
-      }
-      if (isFragment(value)) {
+  // Use computed with a dependency on hasDirtyAttributes which changes on rollback
+  // This ensures the computed property is re-evaluated when dirty state changes
+  const cp = computed(
+    'currentState',
+    'hasDirtyAttributes',
+    'isDestroyed',
+    'isDestroying',
+    'store.{_instanceCache,cache}',
+    {
+      get(key) {
+        if (this.isDestroying || this.isDestroyed) {
+          return null;
+        }
+        const identifier = recordIdentifierFor(this);
+        const cache = fragmentCacheFor(this.store);
+        const fragmentIdentifier = cache.getFragment(identifier, key);
+        if (fragmentIdentifier === null) {
+          return null;
+        }
+        // Get the fragment record from the identifier
+        return this.store._instanceCache.getRecord(fragmentIdentifier);
+      },
+      set(key, value) {
         assert(
-          `You can only set '${type}' fragments to this property`,
-          isInstanceOfType(this.store.modelFor(type), value),
+          'You must pass a fragment or null to set a fragment',
+          value === null || isFragment(value) || typeOf(value) === 'object',
         );
-        const fragmentIdentifier = recordIdentifierFor(value);
-        setFragmentOwner(value, identifier, key);
-        cache.setDirtyFragment(identifier, key, fragmentIdentifier);
-        return value;
-      }
-      // Value is a plain object - update existing fragment or create new one
-      const fragmentIdentifier = cache.getFragment(identifier, key);
-      const actualType = getActualFragmentType(type, options, value, this);
-      if (fragmentIdentifier?.type !== actualType) {
-        // Create a new fragment
-        const fragment = this.store.createFragment(actualType, value);
-        const newFragmentIdentifier = recordIdentifierFor(fragment);
-        setFragmentOwner(fragment, identifier, key);
-        cache.setDirtyFragment(identifier, key, newFragmentIdentifier);
+        const identifier = recordIdentifierFor(this);
+        const cache = fragmentCacheFor(this.store);
+        if (value === null) {
+          cache.setDirtyFragment(identifier, key, null);
+          return null;
+        }
+        if (isFragment(value)) {
+          assert(
+            `You can only set '${type}' fragments to this property`,
+            isInstanceOfType(this.store.modelFor(type), value),
+          );
+          const fragmentIdentifier = recordIdentifierFor(value);
+          setFragmentOwner(value, identifier, key);
+          cache.setDirtyFragment(identifier, key, fragmentIdentifier);
+          return value;
+        }
+        // Value is a plain object - update existing fragment or create new one
+        const fragmentIdentifier = cache.getFragment(identifier, key);
+        const actualType = getActualFragmentType(type, options, value, this);
+        if (fragmentIdentifier?.type !== actualType) {
+          // Create a new fragment
+          const fragment = this.store.createFragment(actualType, value);
+          const newFragmentIdentifier = recordIdentifierFor(fragment);
+          setFragmentOwner(fragment, identifier, key);
+          cache.setDirtyFragment(identifier, key, newFragmentIdentifier);
+          return fragment;
+        }
+        // Update existing fragment
+        const fragment =
+          this.store._instanceCache.getRecord(fragmentIdentifier);
+        fragment.setProperties(value);
         return fragment;
-      }
-      // Update existing fragment
-      const fragment = this.store._instanceCache.getRecord(fragmentIdentifier);
-      fragment.setProperties(value);
-      return fragment;
+      },
     },
-  }).meta(meta);
+  ).meta(meta);
+
+  return cp;
 }

package/addon/cache/fragment-cache.js

@@ -1,3 +1,4 @@
+import { assert } from '@ember/debug';
 import JSONAPICache from '@ember-data/json-api';
 import FragmentStateManager from './fragment-state-manager';
 import FragmentRecordDataProxy from './fragment-record-data-proxy';
@@ -17,12 +18,40 @@ export default class FragmentCache {
     this.__innerCache = new JSONAPICache(storeWrapper);
     this.__fragmentState = new FragmentStateManager(storeWrapper);
     this.__recordDataProxies = new Map();
+    this.__storeValidated = false;
   }
 
   get store() {
     return this.__storeWrapper._store;
   }
 
+  /**
+   * Validates that the store service extends FragmentStore
+   * This validation is lazy - only checked when fragment functionality is first needed
+   */
+  _validateStore() {
+    if (this.__storeValidated) {
+      return;
+    }
+    this.__storeValidated = true;
+
+    const store = this.store;
+
+    // Check if the store has the required fragment methods
+    const hasFragmentMethods =
+      typeof store.createFragment === 'function' &&
+      typeof store.isFragment === 'function';
+
+    assert(
+      `ember-data-model-fragments requires your store service to extend FragmentStore.\n\n` +
+        `Create app/services/store.js with the following:\n\n` +
+        `import FragmentStore from 'ember-data-model-fragments/store';\n` +
+        `export default class extends FragmentStore {}\n\n` +
+        `See the ember-data-model-fragments documentation for more information.`,
+      hasFragmentMethods,
+    );
+  }
+
   /**
    * Get or create a FragmentRecordDataProxy for the given identifier.
    * This provides backwards compatibility with code expecting per-resource RecordData API.
@@ -41,6 +70,7 @@ export default class FragmentCache {
   // ==================
 
   getFragment(identifier, key) {
+    this._validateStore();
     return this.__fragmentState.getFragment(identifier, key);
   }
 
@@ -109,10 +139,136 @@ export default class FragmentCache {
   // ==================
 
   /**
-   * Cache the response to a request
+   * Cache the response to a request.
+   *
+   * In ember-data 4.13+, this is the primary entry point for caching data.
+   * We intercept to extract fragment attributes before passing to the inner cache.
+   *
+   * The document structure is:
+   * {
+   *   request: {...},
+   *   response: {...},
+   *   content: {
+   *     data: { type, id, attributes, relationships } | [...],
+   *     included: [...],
+   *     meta: {...}
+   *   }
+   * }
    */
   put(doc) {
-    return this.__innerCache.put(doc);
+    // Normalize id to string to ensure consistent comparison
+    if (doc?.content?.data) {
+      if (Array.isArray(doc.content.data)) {
+        doc.content.data.forEach((resource) => {
+          if (resource.id != null && typeof resource.id !== 'string') {
+            resource.id = String(resource.id);
+          }
+        });
+      } else if (
+        doc.content.data.id != null &&
+        typeof doc.content.data.id !== 'string'
+      ) {
+        doc.content.data.id = String(doc.content.data.id);
+      }
+    }
+
+    // NEW APPROACH: Store fragment data separately, push to inner cache first, then process fragments
+    // This is needed because polymorphic fragment type resolution may require accessing owner attributes,
+    // which requires the owner record to exist in the cache first.
+
+    // Step 1: Extract fragment data from resources WITHOUT creating fragment identifiers
+    const fragmentDataByIdentifier = new Map();
+    if (doc && doc.content && doc.content.data) {
+      this._collectFragmentsFromDocument(doc.content, fragmentDataByIdentifier);
+    }
+
+    // Step 2: Push to inner cache (this creates the owner records)
+    const result = this.__innerCache.put(doc);
+
+    // Step 3: Now that owner records exist, push fragment data to create fragment identifiers
+    for (const [identifier, data] of fragmentDataByIdentifier) {
+      this.__fragmentState.pushFragmentData(identifier, data, false);
+    }
+
+    return result;
+  }
+
+  /**
+   * Collect fragment attributes from a JSON:API document WITHOUT creating fragment identifiers.
+   * This just stores the raw fragment data and removes fragment attributes from resources.
+   * Fragment identifiers will be created later after owner records are in the cache.
+   *
+   * @private
+   */
+  _collectFragmentsFromDocument(jsonApiDoc, fragmentDataByIdentifier) {
+    const { data, included } = jsonApiDoc;
+
+    // Handle single resource
+    if (data && !Array.isArray(data)) {
+      this._collectFragmentsFromResource(data, fragmentDataByIdentifier);
+    }
+
+    // Handle array of resources
+    if (Array.isArray(data)) {
+      for (const resource of data) {
+        this._collectFragmentsFromResource(resource, fragmentDataByIdentifier);
+      }
+    }
+
+    // Handle included resources
+    if (included) {
+      for (const resource of included) {
+        this._collectFragmentsFromResource(resource, fragmentDataByIdentifier);
+      }
+    }
+  }
+
+  /**
+   * Collect fragment attributes from a single resource WITHOUT creating fragment identifiers.
+   *
+   * @private
+   */
+  _collectFragmentsFromResource(resource, fragmentDataByIdentifier) {
+    if (!resource || !resource.attributes || !resource.type) {
+      return;
+    }
+
+    // Get or create identifier for this resource
+    const identifier =
+      this.__storeWrapper.identifierCache.getOrCreateRecordIdentifier({
+        type: resource.type,
+        id: resource.id,
+      });
+
+    const definitions = this.__storeWrapper
+      .getSchemaDefinitionService()
+      .attributesDefinitionFor(identifier);
+
+    const fragmentData = {};
+    const fragmentKeys = [];
+
+    for (const [key, definition] of Object.entries(definitions)) {
+      const isFragment =
+        definition.isFragment || definition.options?.isFragment;
+
+      if (isFragment && resource.attributes[key] !== undefined) {
+        fragmentData[key] = resource.attributes[key];
+        fragmentKeys.push(key);
+      }
+    }
+
+    // Store fragment data for later processing (AFTER inner cache put)
+    if (fragmentKeys.length > 0) {
+      fragmentDataByIdentifier.set(identifier, { attributes: fragmentData });
+
+      // Clone attributes and remove fragment keys to avoid mutating original data
+      // This is necessary because resource.attributes may reference user-provided data
+      const cleanedAttributes = { ...resource.attributes };
+      for (const key of fragmentKeys) {
+        delete cleanedAttributes[key];
+      }
+      resource.attributes = cleanedAttributes;
+    }
   }
 
   /**
@@ -136,6 +292,10 @@ export default class FragmentCache {
     return this.__innerCache.peek(identifier);
   }
 
+  peekRemoteState(identifier) {
+    return this.__innerCache.peekRemoteState?.(identifier);
+  }
+
   /**
    * Peek the Cache for existing request data
    */
@@ -146,8 +306,13 @@ export default class FragmentCache {
   /**
    * Push resource data from a remote source into the cache.
    * Intercepts to handle fragment attributes.
+   *
+   * In ember-data 4.13+, the signature is:
+   *   upsert(identifier, resource, hasRecord) where resource is the JSON:API resource object
+   * In ember-data 4.12, the signature was:
+   *   upsert(identifier, data, calculateChanges) where data = { attributes: {...} }
    */
-  upsert(identifier, data, calculateChanges) {
+  upsert(identifier, data, hasRecordOrCalculateChanges) {
     // Normalize the id to string to match identifier.id (which is always coerced to string)
     // This ensures cached.id matches identifier.id type when didCommit compares them
     if (data.id != null && typeof data.id !== 'string') {
@@ -164,7 +329,9 @@ export default class FragmentCache {
         .attributesDefinitionFor(identifier);
 
       for (const [key, definition] of Object.entries(definitions)) {
-        if (definition.isFragment && data.attributes[key] !== undefined) {
+        const isFragment =
+          definition.isFragment || definition.options?.isFragment;
+        if (isFragment && data.attributes[key] !== undefined) {
           fragmentData[key] = data.attributes[key];
           fragmentAttributeKeys.push(key);
         }
@@ -187,7 +354,7 @@ export default class FragmentCache {
     const changedKeys = this.__innerCache.upsert(
       identifier,
       data,
-      calculateChanges,
+      hasRecordOrCalculateChanges,
     );
 
     // Handle fragment attributes
@@ -195,9 +362,9 @@ export default class FragmentCache {
       const changedFragmentKeys = this.__fragmentState.pushFragmentData(
         identifier,
         { attributes: fragmentData },
-        calculateChanges,
+        hasRecordOrCalculateChanges,
       );
-      if (calculateChanges && changedFragmentKeys?.length) {
+      if (hasRecordOrCalculateChanges && changedFragmentKeys?.length) {
         return [...(changedKeys || []), ...changedFragmentKeys];
       }
     }
@@ -209,6 +376,91 @@ export default class FragmentCache {
    * Signal to the cache that a new record has been instantiated on the client
    */
   clientDidCreate(identifier, options) {
+    // Extract fragment attributes from options before passing to inner cache
+    if (options) {
+      const definitions = this.__storeWrapper
+        .getSchemaDefinitionService()
+        .attributesDefinitionFor(identifier);
+
+      // Raw fragment data (plain objects / arrays of plain objects) flows
+      // through pushFragmentData -> behavior.pushData which only accepts raw
+      // canonical data. Fragment-instance values must be adopted directly
+      // (mirroring behavior.getDefaultValue's handling of fragment defaults)
+      // so that consumers can pass `store.createFragment(...)` results into
+      // `store.createRecord(type, { fragmentKey: fragment })` without hitting
+      // "Fragment canonical value must be an object or null".
+      const fragmentData = {};
+      const fragmentInstanceData = {};
+      const regularOptions = {};
+      let hasFragmentData = false;
+      let hasFragmentInstanceData = false;
+
+      for (const [key, value] of Object.entries(options)) {
+        const definition = definitions[key];
+        const isFragmentAttr =
+          definition?.isFragment || definition?.options?.isFragment;
+
+        if (isFragmentAttr && value !== undefined) {
+          if (this.__fragmentState.valueContainsFragmentInstance(value)) {
+            fragmentInstanceData[key] = value;
+            hasFragmentInstanceData = true;
+          } else {
+            fragmentData[key] = value;
+            hasFragmentData = true;
+          }
+        } else {
+          regularOptions[key] = value;
+        }
+      }
+
+      // IMPORTANT: Create the inner cache entry first, so the owner's attributes
+      // are available when fragment typeKey functions try to access them
+      const result = this.__innerCache.clientDidCreate(
+        identifier,
+        regularOptions,
+      );
+
+      // Adopt fragment-instance values directly into the canonical fragment
+      // data map. This sets up ownership on each adopted fragment and avoids
+      // the raw-object-only pushData assertion path.
+      if (hasFragmentInstanceData) {
+        for (const [key, value] of Object.entries(fragmentInstanceData)) {
+          const adopted = this.__fragmentState.adoptFragmentForKey(
+            identifier,
+            key,
+            value,
+          );
+          if (adopted !== undefined) {
+            this.__fragmentState.setCanonicalFragmentValue(
+              identifier,
+              key,
+              adopted,
+            );
+          } else {
+            // Defensive fallback: shouldn't happen because
+            // _valueContainsFragmentInstance only flagged values that
+            // adoptFragmentForKey can handle, but if it ever does, route
+            // through the raw-object path as a last resort.
+            fragmentData[key] = value;
+            hasFragmentData = true;
+          }
+        }
+      }
+
+      // Push remaining raw fragment data (plain objects) through the normal
+      // canonical-data path.
+      if (hasFragmentData) {
+        this.__fragmentState.pushFragmentData(
+          identifier,
+          { attributes: fragmentData },
+          false,
+          false,
+        );
+      }
+
+      return result;
+    }
+
     return this.__innerCache.clientDidCreate(identifier, options);
   }
 
@@ -263,7 +515,9 @@ export default class FragmentCache {
       fragmentData = { attributes: {} };
 
       for (const [key, definition] of Object.entries(definitions)) {
-        if (definition.isFragment && attributes[key] !== undefined) {
+        const isFragment =
+          definition.isFragment || definition.options?.isFragment;
+        if (isFragment && attributes[key] !== undefined) {
           fragmentData.attributes[key] = attributes[key];
         }
       }
@@ -315,7 +569,13 @@ export default class FragmentCache {
       .attributesDefinitionFor(identifier);
     const definition = definitions[attr];
 
-    if (definition?.isFragment) {
+    // Check for fragment attribute - support both metadata formats:
+    // - Direct: definition.isFragment (ember-data 4.12 or original metadata)
+    // - Transformed: definition.options?.isFragment (from FragmentSchemaService in 4.13)
+    const isFragmentAttr =
+      definition?.isFragment || definition?.options?.isFragment;
+
+    if (isFragmentAttr) {
       // Fragment attributes are handled by fragment state manager
       // getFragment returns identifier(s), we need to convert to Fragment instance(s)
       const fragmentValue = this.__fragmentState.getFragment(identifier, attr);
@@ -324,29 +584,45 @@ export default class FragmentCache {
         return fragmentValue;
       }
 
+      // Get the fragment kind from the appropriate location:
+      // - Direct: definition.kind (original metadata)
+      // - Transformed: definition.options?.fragmentKind (from FragmentSchemaService)
+      const fragmentKind = definition.options?.fragmentKind || definition.kind;
+
       // For single fragments, convert identifier to Fragment instance
-      if (definition.kind === 'fragment') {
+      if (fragmentKind === 'fragment') {
         if (fragmentValue.lid) {
           // It's an identifier, get the record instance
-          return this.store._instanceCache.getRecord(fragmentValue);
+          const record = this.store._instanceCache.getRecord(fragmentValue);
+          return record;
         }
         return fragmentValue;
       }
 
-      // For fragment arrays, convert array of identifiers to Fragment instances
-      if (
-        definition.kind === 'fragment-array' &&
-        Array.isArray(fragmentValue)
-      ) {
-        return fragmentValue.map((item) => {
-          if (item?.lid) {
-            return this.store._instanceCache.getRecord(item);
-          }
-          return item;
-        });
+      // For fragment arrays and primitive arrays, return the wrapper object
+      // This is needed for Snapshot._attributes which expects objects with _createSnapshot
+      if (fragmentKind === 'fragment-array' || fragmentKind === 'array') {
+        // Get the cached wrapper if it exists
+        let arrayWrapper = this.getFragmentArrayCache(identifier, attr);
+        if (arrayWrapper) {
+          return arrayWrapper;
+        }
+        // If no wrapper exists yet, convert identifiers to Fragment instances
+        // so ext.js patch can call _createSnapshot on each fragment
+        if (fragmentKind === 'fragment-array' && Array.isArray(fragmentValue)) {
+          const fragments = fragmentValue.map((item) => {
+            if (item?.lid) {
+              return this.store._instanceCache.getRecord(item);
+            }
+            return item;
+          });
+          return fragments;
+        }
+        // For primitive arrays, return as-is
+        return fragmentValue;
       }
 
-      // For primitive arrays, return as-is
+      // For single fragment type that fell through, return as-is
       return fragmentValue;
     }
 
@@ -362,7 +638,10 @@ export default class FragmentCache {
       .attributesDefinitionFor(identifier);
     const definition = definitions[attr];
 
-    if (definition?.isFragment) {
+    const isFragmentAttr =
+      definition?.isFragment || definition?.options?.isFragment;
+
+    if (isFragmentAttr) {
       return this.__fragmentState.setDirtyFragment(identifier, attr, value);
     }
 
@@ -431,6 +710,22 @@ export default class FragmentCache {
     return this.__innerCache.getRelationship(identifier, field);
   }
 
+  getRemoteRelationship(identifier, field) {
+    return this.__innerCache.getRemoteRelationship?.(identifier, field);
+  }
+
+  changedRelationships(identifier) {
+    return this.__innerCache.changedRelationships?.(identifier);
+  }
+
+  hasChangedRelationships(identifier) {
+    return this.__innerCache.hasChangedRelationships?.(identifier) || false;
+  }
+
+  rollbackRelationships(identifier) {
+    return this.__innerCache.rollbackRelationships?.(identifier);
+  }
+
   /**
    * Update the cache state for the given resource to be marked as locally deleted
    */
@@ -445,6 +740,10 @@ export default class FragmentCache {
     return this.__innerCache.getErrors(identifier);
   }
 
+  getRemoteAttr(identifier, attr) {
+    return this.__innerCache.getRemoteAttr?.(identifier, attr);
+  }
+
   /**
    * Query the cache for whether a given resource has any available data
    */

package/addon/cache/fragment-record-data-proxy.js

@@ -125,7 +125,9 @@ export default class FragmentRecordDataProxy {
       .getSchemaDefinitionService()
       .attributesDefinitionFor(this.identifier);
     for (const [key, definition] of Object.entries(definitions)) {
-      if (!definition.isFragment) {
+      const isFragmentAttr =
+        definition.isFragment || definition.options?.isFragment;
+      if (!isFragmentAttr) {
         regularState[key] = this.__cache.getAttr(this.identifier, key);
       }
     }