feat: improve lifetime handling of ad-hoc createRecord requests

Author: runspired

packages/core-types/src/request.ts

@@ -45,7 +45,12 @@ export type CacheOptions = {
    * provided by `@ember-data/request-utils` for an example.
    *
    * It is recommended to only use this for query/queryRecord requests where
-   * new records created later would affect the results.
+   * new records created later would affect the results, though using it for
+   * findRecord requests is also supported if desired where it may be useful
+   * when a create may affect the result of a sideloaded relationship.
+   *
+   * Generally it is better to patch the cache directly for relationship updates
+   * than to invalidate findRecord requests for one.
    *
    * @typedoc
    */

packages/request-utils/src/index.ts

@@ -654,14 +654,25 @@ export type LifetimesConfig = { apiCacheSoftExpires: number; apiCacheHardExpires
  * Invalidates any request for which `cacheOptions.types` was provided when a createRecord
  * request for that type is successful.
  *
+ * For this to work, the `createRecord` request must include the `cacheOptions.types` array
+ * with the types that should be invalidated, or its request should specify the identifiers
+ * of the records that are being created via `records`. Providing both is valid.
+ *
+ * > [!NOTE]
+ * > only requests that had specified `cacheOptions.types` and occurred prior to the
+ * > createRecord request will be invalidated. This means that a given request should always
+ * > specify the types that would invalidate it to opt into this behavior. Abstracting this
+ * > behavior via builders is recommended to ensure consistency.
+ *
  * This allows the Store's CacheHandler to determine if a request is expired and
  * should be refetched upon next request.
  *
  * The `Fetch` handler provided by `@ember-data/request/fetch` will automatically
  * add the `date` header to responses if it is not present.
  *
- * Note: Date headers do not have millisecond precision, so expiration times should
- * generally be larger than 1000ms.
+ * > [!NOTE]
+ * > Date headers do not have millisecond precision, so expiration times should
+ * > generally be larger than 1000ms.
  *
  * Usage:
  *
@@ -804,6 +815,11 @@ export class LifetimesService {
       const statusNumber = response?.status ?? 0;
       if (statusNumber >= 200 && statusNumber < 400) {
         const types = new Set(request.records?.map((r) => r.type));
+        const additionalTypes = request.cacheOptions?.types;
+        additionalTypes?.forEach((type) => {
+          types.add(type);
+        });
+
         types.forEach((type) => {
           this.invalidateRequestsForType(type, store);
         });

packages/store/src/-private/cache-handler.ts

@@ -411,6 +411,47 @@ function cloneError(error: Error & { error: string | object }) {
   return cloned;
 }
 
+/**
+ * A CacheHandler that adds support for using an EmberData Cache with a RequestManager.
+ *
+ * This handler will only run when a request has supplied a `store` instance. Requests
+ * issued by the store via `store.request()` will automatically have the `store` instance
+ * attached to the request.
+ *
+ * ```ts
+ * requestManager.request({
+ *   store: store,
+ *   url: '/api/posts',
+ *   method: 'GET'
+ * });
+ * ```
+ *
+ * When this handler elects to handle a request, it will return the raw `StructuredDocument`
+ * unless the request has `[EnableHydration]` set to `true`. In this case, the handler will
+ * return a `Document` instance that will automatically update the UI when the cache is updated
+ * in the future and will hydrate any identifiers in the StructuredDocument into Record instances.
+ *
+ * When issuing a request via the store, [EnableHydration] is automatically set to `true`. This
+ * means that if desired you can issue requests that utilize the cache without needing to also
+ * utilize Record instances if desired.
+ *
+ * Said differently, you could elect to issue all requests via a RequestManager, without ever using
+ * the store directly, by setting [EnableHydration] to `true` and providing a store instance. Not
+ * necessarily the most useful thing, but the decoupled nature of the RequestManager and incremental-feature
+ * approach of EmberData allows for this flexibility.
+ *
+ * ```ts
+ * import { EnableHydration } from '@warp-drive/core-types/request';
+ *
+ * requestManager.request({
+ *   store: store,
+ *   url: '/api/posts',
+ *   method: 'GET',
+ *   [EnableHydration]: true
+ * });
+ *
+ * @typedoc
+ */
 export const CacheHandler: CacheHandlerType = {
   request<T>(context: StoreRequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> | T {
     // if we have no cache or no cache-key skip cache handling

tests/main/tests/integration/cache-handler/lifetimes-test.ts

@@ -300,7 +300,7 @@ module('Store | CacheHandler + Lifetimes', function (hooks) {
 
     assert.verifySteps(['isHardExpired: false', 'isSoftExpired: false'], 'we resolve from cache still');
 
-    const record = store.createRecord('test', {}) as { identifier: StableRecordIdentifier };
+    const record = store.createRecord('test', {});
 
     await store.request({
       url: '/test',
@@ -477,7 +477,7 @@ module('Store | CacheHandler + Lifetimes', function (hooks) {
 
     assert.verifySteps(['isHardExpired: false', 'isSoftExpired: false'], 'we resolve from cache still');
 
-    const record = store.createRecord('test', {}) as { identifier: StableRecordIdentifier };
+    const record = store.createRecord('test', {});
     await store.saveRecord(record);
 
     assert.verifySteps(['adapter:createRecord', 'didRequest'], 'we issue the request since it is a different request');
@@ -538,4 +538,6 @@ module('Store | CacheHandler + Lifetimes', function (hooks) {
       'we are no longer hard expired due to the createRecord response'
     );
   });
+
+  test('An AdHoc createRecord request can invalidate the request cache', async function (assert) {});
 });