@warp-drive-mirror/core 5.9.0-alpha.17 → 5.9.0-alpha.19

package/declarations/graph/-private/-state.d.ts

@@ -1,5 +1,6 @@
 export interface RelationshipState {
 	hasReceivedData: boolean;
+	hasReceivedRemoteData: boolean;
 	isEmpty: boolean;
 	isStale: boolean;
 	hasFailedLoadAttempt: boolean;

package/declarations/index.d.ts

@@ -39,8 +39,17 @@ export interface StoreSetupOptions<T extends Cache = Cache> {
 	* The request handlers to use. {@link Fetch} will automatically
 	* be added to the end of the handler chain and {@link CacheHandler}
 	* will automatically be added as the cache handler.
+	*
+	* May also be given as a function that receives the {@link Store} instance
+	* and returns the handlers to use. This is useful when a handler needs
+	* access to the store (e.g. to look up its owner for injections) or when
+	* the set of handlers should be decided lazily (e.g. based on a feature
+	* flag service that may not be ready until after the store is constructed).
+	*
+	* The function is invoked lazily, the first time the store's `requestManager`
+	* is accessed, and only once per store instance.
 	*/
-	handlers?: Handler[];
+	handlers?: Handler[] | ((store: Store) => Handler[]);
 	/**
 	* Schemas describing the structure of your resource data.
 	*

package/declarations/reactive/-private/default-mode.d.ts

@@ -1,8 +1,6 @@
-import type { SignalStore } from "../../signals/-private.js";
 import type { Store } from "../../store/-private.js";
 import type { ResourceKey } from "../../types.js";
 import type { FieldSchema, HashField, IdentityField, SchemaArrayField, SchemaObjectField } from "../../types/schema/fields.js";
-import type { ReactiveResource } from "./record.js";
 export type PathLike = string | symbol | Array<string | symbol>;
 export type ModeName = "polaris" | "legacy";
 export interface ModeInfo {
@@ -11,10 +9,32 @@ export interface ModeInfo {
 	editable: boolean;
 }
 export interface BaseContext {
+	/**
+	* The {@link Store} instance that owns
+	* the reactive context we are within.
+	*/
 	store: Store;
+	/**
+	* The {@link ResourceKey} of the resource that
+	* the reactive context we are within is for.
+	*/
 	resourceKey: ResourceKey;
+	/**
+	* The name of the {@link ModeName | mode} that the
+	* reactive context we are within is operating in.
+	*/
 	modeName: ModeName;
+	/**
+	* Whether we are in legacy {@link ModeName | mode}
+	* or not.
+	*/
 	legacy: boolean;
+	/**
+	* Whether the ReactiveResource instance we are operating
+	* in is currently editable or not. This should be true if the
+	* record is currently checked out for editing or is in legacy mode
+	* and false if the record is currently in a read-only state.
+	*/
 	editable: boolean;
 }
 export interface ResourceContext extends BaseContext {
@@ -27,13 +47,6 @@ export interface ObjectContext extends BaseContext {
 	field: SchemaObjectField | SchemaArrayField;
 	value: string;
 }
-export interface KindContext<T extends FieldSchema | IdentityField | HashField> extends BaseContext {
-	path: string[];
-	field: T;
-	value: unknown;
-	record: ReactiveResource;
-	signals: SignalStore;
-}
 export interface KindImpl<T extends FieldSchema | IdentityField | HashField> {
 	/**
 	* A function which produces the value for the field when invoked.

package/declarations/reactive/-private/kind/belongs-to-field.d.ts

@@ -1,4 +1,7 @@
+import type { ResourceKey } from "../../../types.js";
 import type { LegacyBelongsToField } from "../../../types/schema/fields.js";
 import type { KindContext } from "../default-mode.js";
+import type { ReactiveResource } from "../record.js";
 export declare function getBelongsToField(context: KindContext<LegacyBelongsToField>): unknown;
 export declare function setBelongsToField(context: KindContext<LegacyBelongsToField>): boolean;
+export declare function getResourceKey(record: ReactiveResource | null): ResourceKey | null;

package/declarations/types/runtime.d.ts

@@ -1,6 +1,7 @@
 import type { LOG_CONFIG } from "@warp-drive-mirror/build-config/-private/utils/logging";
 declare const RuntimeConfig: {
 	debug: Partial<LOG_CONFIG>;
+	mirage?: boolean;
 };
 export declare function getRuntimeConfig(): typeof RuntimeConfig;
 /**
@@ -11,4 +12,19 @@ export declare function getRuntimeConfig(): typeof RuntimeConfig;
 *
 */
 export declare function setLogging(config: Partial<LOG_CONFIG>): void;
+/**
+* Explicitly declares whether requests may be served by Mirage (or another
+* Pretender-based fetch mock) instead of a native `fetch` implementation.
+*
+* The `Fetch` request handler otherwise infers this via a heuristic (the
+* presence of `window.server.pretender`, or `window.fetch` appearing to be
+* patched), which can be wrong in either direction: some Mirage setups don't
+* expose `window.server`, while some unrelated tools (APM agents, browser
+* extensions) also patch `fetch`. Call this to override that heuristic:
+* `true` to force Mirage-compatible behavior on, `false` to force it off.
+*
+* globalThis.setWarpDriveIsMaybeMirage(true);
+*
+*/
+export declare function setIsMaybeMirage(value: boolean): void;
 export {};

package/declarations/types/schema/fields.d.ts

@@ -1315,9 +1315,16 @@ export interface LegacyBelongsToField {
 		* adapters and serializers.
 		*
 		* When true, none of the legacy support will be utilized. Sync relationships
-		* will be expected to already have all their data. When reloading a sync relationship
-		* you would be expected to have a `related link` available from a prior relationship
-		* payload e.g.
+		* (`async: false`, currently the only supported combination) must satisfy
+		* one of the following whenever pushed to the cache:
+		*
+		* - a `links.related` link is present, **or**
+		* - the relationship is fully linked: `data` is `null`, or `data` points
+		*   to a resource present in the document's `included` array
+		*
+		* A related link lets you omit the related resource from `included`; a
+		* `data` key that is missing entirely, or explicitly `undefined`, is never
+		* valid unless a `links.related` link is present.
 		*
 		* ```ts
 		* {
@@ -1468,9 +1475,16 @@ export interface LinksModeBelongsToField {
 		* MUST be true for PolarisMode + LinksMode
 		*
 		* When true, none of the legacy support will be utilized. Sync relationships
-		* will be expected to already have all their data. When reloading a sync relationship
-		* you would be expected to have a `related link` available from a prior relationship
-		* payload e.g.
+		* (`async: false`, currently the only supported combination) must satisfy
+		* one of the following whenever pushed to the cache:
+		*
+		* - a `links.related` link is present, **or**
+		* - the relationship is fully linked: `data` is `null`, or `data` points
+		*   to a resource present in the document's `included` array
+		*
+		* A related link lets you omit the related resource from `included`; a
+		* `data` key that is missing entirely, or explicitly `undefined`, is never
+		* valid unless a `links.related` link is present.
 		*
 		* ```ts
 		* {
@@ -1640,9 +1654,16 @@ export interface LegacyHasManyField {
 		* from @warp-drive-mirror/legacy/model and the LegacyNetworkMiddleware for adapters and serializers.
 		*
 		* When true, none of the legacy support will be utilized. Sync relationships
-		* will be expected to already have all their data. When reloading a sync relationship
-		* you would be expected to have a `related link` available from a prior relationship
-		* payload e.g.
+		* (`async: false`, currently the only supported combination) must satisfy
+		* one of the following whenever pushed to the cache:
+		*
+		* - a `links.related` link is present, **or**
+		* - the relationship is fully linked: `data` is `[]`, or every resource
+		*   identifier in `data` is present in the document's `included` array
+		*
+		* A related link lets you omit the related resources from `included`; a
+		* `data` key that is missing entirely, or explicitly `undefined`, is never
+		* valid unless a `links.related` link is present.
 		*
 		* ```ts
 		* {
@@ -1818,9 +1839,16 @@ export interface LinksModeHasManyField {
 		* MUST be true for PolarisMode + LinksMode
 		*
 		* When true, none of the legacy support will be utilized. Sync relationships
-		* will be expected to already have all their data. When reloading a sync relationship
-		* you would be expected to have a `related link` available from a prior relationship
-		* payload e.g.
+		* (`async: false`, currently the only supported combination) must satisfy
+		* one of the following whenever pushed to the cache:
+		*
+		* - a `links.related` link is present, **or**
+		* - the relationship is fully linked: `data` is `[]`, or every resource
+		*   identifier in `data` is present in the document's `included` array
+		*
+		* A related link lets you omit the related resources from `included`; a
+		* `data` key that is missing entirely, or explicitly `undefined`, is never
+		* valid unless a `links.related` link is present.
 		*
 		* ```ts
 		* {

package/dist/graph/-private.js

@@ -67,9 +67,14 @@ function assertValidRelationshipPayload(graph, op) {
     kind
   } = definition;
   if (payload.links) {
-    warn(`You pushed a record of type '${type}' with a relationship '${field}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, isAsync || payload.data === null || !!payload.data || state.hasReceivedData, {
-      id: 'ds.store.push-link-for-sync-relationship'
-    });
+    // once JSON_API_CACHE_VALIDATION_ERRORS is active, this warning is instead
+    // the responsibility of the new document validator (see validateResourceRelationships
+    // in warp-drive-packages/json-api/src/-private/validator/1.1/7.2_resource-objects.ts)
+    if (macroCondition(!getGlobalConfig().WarpDriveMirror.features.JSON_API_CACHE_VALIDATION_ERRORS)) {
+      warn(`You pushed a record of type '${type}' with a relationship '${field}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, isAsync || payload.data === null || !!payload.data || state.hasReceivedData, {
+        id: 'ds.store.push-link-for-sync-relationship'
+      });
+    }
   } else if (payload.data) {
     if (kind === 'belongsTo') {
       macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
@@ -748,7 +753,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
       errors.set('type', ` <---- should be '${definition.inverseType}'`);
     }
     if (definition.inverseKind !== meta.kind) {
-      errors.set('type', ` <---- should be '${definition.inverseKind}'`);
+      errors.set('kind', ` <---- should be '${definition.inverseKind}'`);
     }
     if (definition.inverseIsAsync !== meta.options.async) {
       errors.set('async', ` <---- should be ${definition.inverseIsAsync}`);
@@ -759,7 +764,12 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
     if (definition.key !== meta.options.inverse) {
       errors.set('inverse', ` <---- should be '${definition.key}'`);
     }
-    if (definition.type !== meta.options.as) {
+    // `as` is only meaningful when `definition` itself is polymorphic (i.e. it
+    // points at an abstract type that `meta` is expected to implement). When
+    // `definition` isn't polymorphic, there's no abstract type for `meta` to
+    // declare `as` against, so `meta.options.as` is correctly absent - that's
+    // not an error to report.
+    if (definition.isPolymorphic && definition.type !== meta.options.as) {
       errors.set('as', ` <---- should be '${definition.type}'`);
     }
     return errors;
@@ -798,18 +808,6 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
 
 `;
   }
-  function metaFrom(definition) {
-    return {
-      name: definition.key,
-      type: definition.type,
-      kind: definition.kind,
-      options: {
-        async: definition.isAsync,
-        polymorphic: definition.isPolymorphic,
-        inverse: definition.inverseKey
-      }
-    };
-  }
   function inverseMetaFrom(definition) {
     return {
       name: definition.inverseKey,
@@ -852,15 +850,18 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
     });
   }
   assertInheritedSchema = function assertInheritedSchema(definition, type) {
-    const meta1 = metaFrom(definition);
+    // `definition` is the only source of truth we have here - there is no
+    // second, independently-declared schema available to diff it against.
+    // That means the only thing we can actually verify is internal: does
+    // `definition`'s own resolved inverse agree that this relationship is
+    // polymorphic? Every other field of `meta2` below (name/type/kind/async/
+    // inverse) is derived directly from `definition` itself, so comparing
+    // them back to `definition` can never disagree - only the polymorphic
+    // flag is independently meaningful, because `definitionWithPolymorphic`
+    // asserts what it *should* be rather than mirroring what it already is.
     const meta2 = inverseMetaFrom(definition);
-    const errors1 = validateSchema(inverseDefinition(definition), meta1);
     const errors2 = validateSchema(definitionWithPolymorphic(definition), meta2);
-    if (errors2.size === 0 && errors1.size > 0) {
-      throw new Error(`The schema for the relationship '${type}.${definition.key}' is not configured to satisfy '${definition.inverseType}' and thus cannot utilize the '${definition.inverseType}.${definition.key}' relationship to connect with '${definition.type}.${definition.inverseKey}'\n\nIf using this relationship in a polymorphic manner is desired, the relationships schema definition for '${type}' should include:${printSchema(meta1, errors1)}`);
-    } else if (errors1.size > 0) {
-      throw new Error(`The schema for the relationship '${type}.${definition.key}' is not configured to satisfy '${definition.inverseType}' and thus cannot utilize the '${definition.inverseType}.${definition.key}' relationship to connect with '${definition.type}.${definition.inverseKey}'\n\nIf using this relationship in a polymorphic manner is desired, the relationships schema definition for '${type}' should include:${printSchema(meta1, errors1)} and the relationships schema definition for '${definition.type}' should include:${printSchema(meta2, errors2)}`);
-    } else if (errors2.size > 0) {
+    if (errors2.size > 0) {
       throw new Error(`The schema for the relationship '${type}.${definition.key}' satisfies '${definition.inverseType}' but cannot utilize the '${definition.inverseType}.${definition.key}' relationship to connect with '${definition.type}.${definition.inverseKey}' because that relationship is not polymorphic.\n\nIf using this relationship in a polymorphic manner is desired, the relationships schema definition for '${definition.type}' should include:${printSchema(meta2, errors2)}`);
     }
   };
@@ -1414,8 +1415,10 @@ function replaceRelatedRecord(graph, op, isRemote = false) {
   if (op.value === existingState) {
     // if we were empty before but now know we are empty this needs to be true
     state.hasReceivedData = true;
+
     // if this is a remote update we still sync
     if (isRemote) {
+      state.hasReceivedRemoteData = true;
       const {
         localState
       } = relationship;
@@ -1455,6 +1458,15 @@ function replaceRelatedRecord(graph, op, isRemote = false) {
   // update value to the new value
   relationship[prop] = op.value;
   state.hasReceivedData = true;
+  /**
+   * Local mutations never give us additional information about
+   * whether the relationship has received *remote* data. This is
+   * what `getRemoteRelationship` relies on to avoid reflecting
+   * local-only edits.
+   */
+  if (isRemote) {
+    state.hasReceivedRemoteData = true;
+  }
   state.isEmpty = op.value === null;
   state.isStale = false;
   state.hasFailedLoadAttempt = false;
@@ -2133,8 +2145,30 @@ function rollbackRelationship(graph, key, field, relationship) {
   }
 }
 function createState() {
+  if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
+    if (macroCondition(getGlobalConfig().WarpDriveMirror.activeLogging.LOG_GRAPH)) {
+      if (getGlobalConfig().WarpDriveMirror.debug.LOG_GRAPH || globalThis.getWarpDriveRuntimeConfig().debug.LOG_GRAPH) {
+        let hasReceivedData = false;
+        return {
+          get hasReceivedData() {
+            return hasReceivedData;
+          },
+          set hasReceivedData(value) {
+            hasReceivedData = value;
+          },
+          hasReceivedRemoteData: false,
+          isEmpty: true,
+          isStale: false,
+          hasFailedLoadAttempt: false,
+          shouldForceReload: false,
+          hasDematerializedInverse: false
+        };
+      }
+    }
+  }
   return {
     hasReceivedData: false,
+    hasReceivedRemoteData: false,
     isEmpty: true,
     isStale: false,
     hasFailedLoadAttempt: false,
@@ -2239,13 +2273,10 @@ function legacyGetResourceRelationshipData(source, getRemoteState) {
   source.accessed = true;
   let data;
   const payload = {};
-  if (getRemoteState && source.remoteState) {
-    data = source.remoteState;
-  } else if (!getRemoteState && source.localState) {
-    data = source.localState;
-  }
-  if ((getRemoteState && source.remoteState === null || source.localState === null) && source.state.hasReceivedData) {
-    data = null;
+  if (getRemoteState && (source.remoteState || source.state.hasReceivedRemoteData)) {
+    data = source.remoteState ?? null;
+  } else if (!getRemoteState && (source.localState || source.state.hasReceivedData)) {
+    data = source.localState ?? null;
   }
   if (source.links) {
     payload.links = source.links;
@@ -2459,7 +2490,6 @@ function updateRelationshipOperation(graph, op) {
   })(isHasMany(relationship) || isBelongsTo(relationship)) : {};
   const {
     definition,
-    state,
     identifier
   } = relationship;
   const {
@@ -2499,23 +2529,6 @@ function updateRelationshipOperation(graph, op) {
         value: payload.data ? graph.store.cacheKeyManager.upgradeIdentifier(payload.data) : null
       }, true);
     }
-  } else if (definition.isAsync === false && !state.hasReceivedData) {
-    hasRelationshipDataProperty = true;
-    if (isCollection) {
-      graph.update({
-        op: 'replaceRelatedRecords',
-        record: identifier,
-        field: op.field,
-        value: []
-      }, true);
-    } else {
-      graph.update({
-        op: 'replaceRelatedRecord',
-        record: identifier,
-        field: op.field,
-        value: null
-      }, true);
-    }
   }
   if (payload.links) {
     const originalLinks = relationship.links;
@@ -2525,9 +2538,10 @@ function updateRelationshipOperation(graph, op) {
       const currentLink = originalLinks && originalLinks.related ? _normalizeLink(originalLinks.related) : null;
       const currentLinkHref = currentLink ? currentLink.href : null;
       if (relatedLink && relatedLink.href && relatedLink.href !== currentLinkHref) {
-        warn(`You pushed a record of type '${identifier.type}' with a relationship '${definition.key}' configured as 'async: false'. You've included a link but no primary data, this may be an error in your payload. WarpDrive will treat this relationship as known-to-be-empty.`, definition.isAsync || state.hasReceivedData, {
-          id: 'ds.store.push-link-for-sync-relationship'
-        });
+        // Note: the equivalent warning for this case is issued eagerly (and with a more
+        // complete condition, since it also accounts for `payload.data` being present) by
+        // `assertValidRelationshipPayload` in `-utils.ts`, which always runs immediately
+        // before this operation in DEBUG builds. Warning here too would double-warn.
         macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
           if (!test) {
             throw new Error(`You have pushed a record of type '${identifier.type}' with '${definition.key}' as a link, but the value of that link is not a string.`);
@@ -2558,6 +2572,7 @@ function updateRelationshipOperation(graph, op) {
     // we don't need to notify here as the update op we pushed in above will notify once
     // membership is in the correct state.
     relationship.state.hasReceivedData = true;
+    relationship.state.hasReceivedRemoteData = true;
     relationship.state.isStale = false;
     relationship.state.hasDematerializedInverse = false;
     relationship.state.isEmpty = relationshipIsEmpty;