enhance: Remove INVALID symbol from endpoints in favor of delegate access

Author: ntucker

.changeset/major-boxes-glow.md

@@ -0,0 +1,26 @@
+---
+'@data-client/normalizr': minor
+'@data-client/endpoint': minor
+'@data-client/rest': minor
+'@data-client/graphql': minor
+---
+
+Add delegate.INVALID to queryKey
+
+This is used in schema.All.queryKey().
+
+#### Before
+
+```ts
+queryKey(args: any, unvisit: any, delegate: IQueryDelegate): any {
+  if (!found) return INVALID;
+}
+```
+
+#### After
+
+```ts
+queryKey(args: any, unvisit: any, delegate: IQueryDelegate): any {
+  if (!found) return delegate.INVALID;
+}
+```

.changeset/open-shrimps-warn.md

@@ -0,0 +1,38 @@
+---
+'@data-client/normalizr': minor
+'@data-client/endpoint': minor
+'@data-client/rest': minor
+'@data-client/graphql': minor
+---
+
+Add delegate.invalidate() to normalization
+
+#### Before
+
+```ts
+normalize(
+  input: any,
+  parent: any,
+  key: string | undefined,
+  args: any[],
+  visit: (...args: any) => any,
+  delegate: INormalizeDelegate,
+): string {
+  delegate.setEntity(this as any, pk, INVALID);
+}
+```
+
+#### After
+
+```ts
+normalize(
+  input: any,
+  parent: any,
+  key: string | undefined,
+  args: any[],
+  visit: (...args: any) => any,
+  delegate: INormalizeDelegate,
+): string {
+  delegate.invalidate(this as any, pk);
+}
+```

.changeset/tough-areas-show.md

@@ -0,0 +1,9 @@
+---
+'@data-client/endpoint': minor
+'@data-client/graphql': minor
+'@data-client/rest': minor
+---
+
+Remove `INVALID` symbol export
+
+Schemas can use delegate.invalidate() in normalize() or return delegate.INVALID in queryKey().

packages/core/src/state/__tests__/reducer.ts

@@ -1,4 +1,5 @@
-import { INVALID, Entity } from '@data-client/endpoint';
+import { Entity } from '@data-client/endpoint';
+import { INVALID } from '@data-client/normalizr';
 import { ArticleResource, Article, PaginatedArticle } from '__tests__/new';
 
 import { Controller } from '../..';

packages/endpoint/src/index.ts

@@ -16,7 +16,6 @@ export type { Array, Invalidate, Collection, DefaultArgs } from './schema.js';
 export { default as Entity } from './schemas/Entity.js';
 export { default as EntityMixin } from './schemas/EntityMixin.js';
 export { default as validateRequired } from './validateRequired.js';
-export { INVALID } from './special.js';
 export type {
   EndpointInterface,
   ReadEndpoint,

packages/endpoint/src/interface.ts

@@ -133,6 +133,8 @@ export interface GetIndex {
 export interface IQueryDelegate {
   getEntity: GetEntity;
   getIndex: GetIndex;
+  /** Return to consider results invalid */
+  INVALID: symbol;
 }
 
 /** Helpers during schema.normalize() */
@@ -154,6 +156,8 @@ export interface INormalizeDelegate {
     entity: any,
     meta?: { fetchedAt: number; date: number; expiresAt: number },
   ): void;
+  /** Invalidates an entity, potentially triggering suspense */
+  invalidate(schema: { key: string; indexes?: any }, pk: string): void;
   /** Returns true when we're in a cycle, so we should not continue recursing */
   checkLoop(key: string, pk: string, input: object): boolean;
 }

packages/endpoint/src/schemas/All.ts

@@ -1,7 +1,6 @@
 import ArraySchema from './Array.js';
 import { IQueryDelegate, Visit } from '../interface.js';
 import { EntityInterface, EntityMap, SchemaFunction } from '../schema.js';
-import { INVALID } from '../special.js';
 
 /**
  * Retrieves all entities in cache
@@ -29,7 +28,7 @@ export default class AllSchema<
     if (this.isSingleSchema) {
       const entitiesEntry = delegate.getEntity(this.schema.key);
       // we must wait until there are entries for any 'All' query to be Valid
-      if (entitiesEntry === undefined) return INVALID;
+      if (entitiesEntry === undefined) return delegate.INVALID;
       return Object.values(entitiesEntry).map(
         entity => entity && this.schema.pk(entity),
       );
@@ -47,7 +46,7 @@ export default class AllSchema<
       },
     );
     // we need at least one table entry of the Union for this to count as Valid.
-    if (!found) return INVALID;
+    if (!found) return delegate.INVALID;
     return list;
   }
 }

packages/endpoint/src/schemas/EntityMixin.ts

@@ -3,10 +3,8 @@ import type {
   Visit,
   IQueryDelegate,
   INormalizeDelegate,
-  Mergeable,
 } from '../interface.js';
 import { AbstractInstanceType } from '../normal.js';
-import { INVALID } from '../special.js';
 import type {
   IEntityClass,
   IEntityInstance,
@@ -256,8 +254,7 @@ export default function EntityMixin<TBase extends Constructor>(
         id = `${this.pk(input, parent, key, args)}`;
         // TODO: add undefined id check
 
-        // set directly: any queued updates are meaningless with delete
-        delegate.setEntity(this, id, INVALID);
+        delegate.invalidate(this, id);
         return id;
       }
       id = this.pk(processedEntity, parent, key, args);

packages/endpoint/src/schemas/Invalidate.ts

@@ -4,7 +4,6 @@ import type {
   SchemaSimple,
 } from '../interface.js';
 import type { AbstractInstanceType } from '../normal.js';
-import { INVALID } from '../special.js';
 
 /**
  * Marks entity as Invalid.
@@ -74,7 +73,7 @@ export default class Invalidate<
 
     // any queued updates are meaningless with delete, so we should just set it
     // and creates will have a different pk
-    delegate.setEntity(this as any, pk, INVALID);
+    delegate.invalidate(this as any, pk);
     return pk;
   }
 

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

@@ -1,11 +1,15 @@
 // eslint-env jest
 import { initialState, State, Controller } from '@data-client/core';
-import { normalize, MemoCache, denormalize } from '@data-client/normalizr';
+import {
+  normalize,
+  MemoCache,
+  denormalize,
+  INVALID,
+} from '@data-client/normalizr';
 import { IDEntity } from '__tests__/new';
 
 import { schema } from '../..';
 import { fromJSState } from './denormalize';
-import { INVALID } from '../../special';
 
 let dateSpy: jest.SpyInstance<number, []>;
 beforeAll(() => {