feat: Support dynamic invalidation/deletes (#3407)

Author: ntucker

.changeset/wide-berries-smell.md

@@ -0,0 +1,32 @@
+---
+'@data-client/endpoint': patch
+'@data-client/graphql': patch
+'@data-client/rest': patch
+---
+
+Support dynamic invalidation/deletes
+
+Returning `undefined` from [Entity.process](https://dataclient.io/rest/api/Entity#process)
+will cause the [Entity](https://dataclient.io/rest/api/Entity) to be [invalidated](https://dataclient.io/docs/concepts/expiry-policy#invalidate-entity).
+This this allows us to invalidate dynamically; based on the particular response data.
+
+```ts
+class PriceLevel extends Entity {
+  price = 0;
+  amount = 0;
+
+  pk() {
+    return this.price;
+  }
+
+  static process(
+    input: [number, number],
+    parent: any,
+    key: string | undefined,
+  ): any {
+    const [price, amount] = input;
+    if (amount === 0) return undefined;
+    return { price, amount };
+  }
+}
+```

docs/rest/api/Entity.md

@@ -411,6 +411,34 @@ class Stream extends Entity {
 }
 ```
 
+#### Dynamic Invalidation
+
+Returning `undefined` from [Entity.process](https://dataclient.io/rest/api/Entity#process)
+will cause the [Entity](https://dataclient.io/rest/api/Entity) to be [invalidated](https://dataclient.io/docs/concepts/expiry-policy#invalidate-entity).
+This this allows us to invalidate dynamically; based on the particular response data.
+
+```ts
+class PriceLevel extends Entity {
+  price = 0;
+  amount = 0;
+
+  pk() {
+    return this.price;
+  }
+
+  static process(
+    input: [number, number],
+    parent: any,
+    key: string | undefined,
+  ): any {
+    const [price, amount] = input;
+    // highlight-next-line
+    if (amount === 0) return undefined;
+    return { price, amount };
+  }
+}
+```
+
 ### static mergeWithStore(existingMeta, incomingMeta, existing, incoming): mergedValue {#mergeWithStore}
 
 ```typescript

packages/endpoint/src/schemas/EntityMixin.ts

@@ -6,6 +6,7 @@ import type {
   Visit,
 } from '../interface.js';
 import { AbstractInstanceType } from '../normal.js';
+import { INVALID } from '../special.js';
 import type {
   IEntityClass,
   IEntityInstance,
@@ -252,7 +253,13 @@ export default function EntityMixin<TBase extends Constructor>(
       checkLoop: CheckLoop,
     ): any {
       const processedEntity = this.process(input, parent, key, args);
-      let id = this.pk(processedEntity, parent, key, args);
+      let id: string | number | undefined;
+      if (typeof processedEntity === 'undefined') {
+        id = this.pk(input, parent, key, args);
+        addEntity(this, INVALID, id);
+        return id;
+      }
+      id = this.pk(processedEntity, parent, key, args);
       if (id === undefined || id === '' || id === 'undefined') {
         // create a random id if a valid one cannot be computed
         // this is useful for optimistic creates that don't need real ids - just something to hold their place

packages/endpoint/src/schemas/__tests__/Entity.test.ts

@@ -590,6 +590,39 @@ describe(`${Entity.name} normalization`, () => {
       expect(final?.type).toEqual('message');
       expect(final).toMatchSnapshot();
     });
+
+    test('when undefined is returned, INVALIDate the entity', () => {
+      class ProcessTaco extends Tacos {
+        readonly slug: string = '';
+        static process(input: any, parent: any, key: string | undefined): any {
+          if (input.id === 'DELETE') return undefined;
+          return {
+            ...input,
+            slug: `thing-${(input as unknown as ProcessTaco).id}`,
+          };
+        }
+      }
+      let { entities, result } = normalize(ProcessTaco, {
+        id: 'DELETE',
+        name: 'foo',
+      });
+      let final = new SimpleMemoCache().denormalize(
+        ProcessTaco,
+        result,
+        entities,
+      );
+      expect(final).toEqual(expect.any(Symbol));
+
+      // still work in normal cases
+      ({ entities, result } = normalize(ProcessTaco, {
+        id: '1',
+        name: 'foo',
+      }));
+      final = new SimpleMemoCache().denormalize(ProcessTaco, result, entities);
+      expect(final).not.toEqual(expect.any(Symbol));
+      if (typeof final === 'symbol') return;
+      expect(final?.slug).toEqual('thing-1');
+    });
   });
 });