@warp-drive-mirror/core 5.10.0-alpha.21 → 5.10.0-alpha.23

package/dist/build-config/babel-macros.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @module
+ * @summary The `macros` function, which returns the Babel plugins that strip WarpDrive deprecation, canary-feature,
+ * debug-logging and env code at build time.
+ */
 import { macros } from "@warp-drive-mirror/build-config/babel-macros";
 export { macros };

package/dist/build-config/canary-features.d.ts

@@ -1 +1,6 @@
+/**
+ * @module
+ * @summary Build-time flags, such as `JSON_API_CACHE_VALIDATION_ERRORS`, that gate unreleased WarpDrive features for
+ * canary builds.
+ */
 export * from "@warp-drive-mirror/build-config/canary-features";

package/dist/build-config/debugging.d.ts

@@ -1 +1,60 @@
+/**
+ * # Log Instrumentation <Badge type="tip" text="debug only" />
+ *
+ * Many portions of the internals are helpfully instrumented with logging.
+ * This instrumentation is always removed from production builds.
+ *
+ * The [Debugging](/guides/the-manual/debugging/) guide explains what each flag logs.
+ *
+ * Log instrumentation is "regionalized" to specific concepts and concerns
+ * to enable you to enable/disable just the areas you are interested in.
+ *
+ * To activate a particular group of logs set the appropriate flag to `true`
+ * either in your build config or via the runtime helper.
+ *
+ *
+ * ## Runtime Activation
+ *
+ * ::: tip 💡 Just Works in browser Dev Tools!
+ * No import is needed, and the logging config is preserved when the page is refreshed
+ * :::
+ *
+ * ```ts
+ * setWarpDriveLogging({
+ *   LOG_CACHE: true,
+ *   LOG_REQUESTS: true,
+ * })
+ * ```
+ *
+ * A runtime helper is attached to `globalThis` to enable activation of the logs
+ * from anywhere in your application including from the devtools panel.
+ *
+ * The runtime helper overrides any build config settings for the given flag
+ * for the current browser tab. It stores the configuration you give it in
+ * `sessionStorage` so that it persists across page reloads of the current tab,
+ * but not across browser tabs or windows.
+ *
+ * If you need to deactivate the logging, you can call the helper again with the
+ * same flag set to `false` or just open a new tab/window.
+ *
+ * ## Buildtime Activation
+ *
+ * ```ts
+ * setConfig(__dirname, app, {
+ *   debug: {
+ *     LOG_CACHE: true,
+ *     LOG_REQUESTS: false,
+ *     LOG_NOTIFICATIONS: true,
+ *   }
+ * });
+ * ```
+ *
+ * The build config settings are used to set the default values for the
+ * logging flags. Any logging flag that is not set in the build config
+ * will default to `false`.
+ *
+ * @summary Debug-only logging flags, such as `LOG_CACHE` and `LOG_REQUESTS`, set in build config or at runtime
+ * via `setWarpDriveLogging`.
+ * @module
+ */
 export * from "@warp-drive-mirror/build-config/debugging";

package/dist/build-config/deprecations.d.ts

@@ -1 +1,6 @@
+/**
+ * @module
+ * @summary Deprecation flags, such as `DEPRECATE_NON_STRICT_TYPES`, that keep deprecated WarpDrive behavior active
+ * until the build config drops it by `compatWith` version or by flag.
+ */
 export * from "@warp-drive-mirror/build-config/deprecations";

package/dist/build-config.d.ts

@@ -1,2 +1,19 @@
+/**
+ * This module provides a build-plugin that enables configuration of deprecations,
+ * optional features, development/testing support and debug logging.
+ *
+ * Available settings include:
+ *
+ * - {@link LOGGING | debugging}
+ * - {@link DEPRECATIONS | deprecations}
+ * - {@link FEATURES | features}
+ * - {@link WarpDriveConfig.polyfillUUID | polyfillUUID}
+ * - {@link WarpDriveConfig.includeDataAdapterInProduction | includeDataAdapterInProduction}
+ * - {@link WarpDriveConfig.compatWith | compatWith}
+ *
+ * @summary Build-time configuration for WarpDrive: `setConfig` and its babel plugin for deprecations, features,
+ * debug logging, and polyfill settings.
+ * @module
+ */
 import { WarpDriveConfig, babelPlugin, setConfig } from "@warp-drive-mirror/build-config";
 export { type WarpDriveConfig, babelPlugin, setConfig };

package/dist/{concepts-vh86nAcd.d.ts → concepts-Db9ssz1h.d.ts}

@@ -1,7 +1,7 @@
 import { l as ResourceKey } from "./identifier-DmgDehQK.js";
-import { a as Type } from "./symbols-DVa1PMFG.js";
-import { i as OpaqueRecordInstance } from "./record-f5-uOgHt.js";
 import { i as Value, n as ObjectValue } from "./raw-adYGuEGM.js";
+import { i as OpaqueRecordInstance } from "./record-f5-uOgHt.js";
+import { a as Type } from "./symbols-DVa1PMFG.js";
 /**
  * A Transformation converts a cached primitive value into a richer
  * "presentation" value exposed on a record, and back again.
@@ -81,4 +81,4 @@ type HashFn<T extends object = object> = {
   [Type]: string;
 } & ((data: T, options: ObjectValue | null, prop: string | null) => string);
 export { HashFn as n, Transformation as r, Derivation as t };
-//# sourceMappingURL=concepts-vh86nAcd.d.ts.map
+//# sourceMappingURL=concepts-Db9ssz1h.d.ts.map

package/dist/{concepts-vh86nAcd.d.ts.map → concepts-Db9ssz1h.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"concepts-vh86nAcd.d.ts","names":[],"sources":["../src/types/schema/concepts.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KA0BY,eAAe,UAAU,QAAQ,OAAO;;;;;EAKlD,UAAU,OAAO,IAAI,SAAS,oBAAoB,QAAQ,uBAAuB;;;;;EAMjF,QAAQ,OAAO,eAAe,SAAS,oBAAoB,QAAQ,uBAAuB;;;;;EAM1F,cAAc,SAAS,oBAAoB,YAAY,cAAc;;;;GAKpE;;;;;;;;;;;;;;;;;KAkBS,WAAW,aAAa,aAAa,WAAW,qBAAqB;;;;GAI9E;MACG,QAAQ,GAAG,SAAS,IAAI,iBAAiB;;;;;;;;;;;;;;;;KAiBnC,OAAO;;;;GAIhB;MACG,MAAM,GAAG,SAAS,oBAAoB"}
+{"version":3,"file":"concepts-Db9ssz1h.d.ts","names":[],"sources":["../src/types/schema/concepts.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KA0BY,eAAe,UAAU,QAAQ,OAAO;;;;;EAKlD,UAAU,OAAO,IAAI,SAAS,oBAAoB,QAAQ,uBAAuB;;;;;EAMjF,QAAQ,OAAO,eAAe,SAAS,oBAAoB,QAAQ,uBAAuB;;;;;EAM1F,cAAc,SAAS,oBAAoB,YAAY,cAAc;;;;GAKpE;;;;;;;;;;;;;;;;;KAkBS,WAAW,aAAa,aAAa,WAAW,qBAAqB;;;;GAI9E;MACG,QAAQ,GAAG,SAAS,IAAI,iBAAiB;;;;;;;;;;;;;;;;KAiBnC,OAAO;;;;GAIhB;MACG,MAAM,GAAG,SAAS,oBAAoB"}

package/dist/configure.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Provides a configuration API for the reactivity system
+ * that WarpDrive should use.
+ *
+ * @summary Provides `setupSignals`, which tells WarpDrive which signal and reactivity library to build its
+ * reactive values on.
+ * @module
+ */
 import { a as registerSignals, n as HooksOptions, o as setupSignals, r as SignalHooks } from "./configure-BfXDuPUb.js";
 export { type HooksOptions, type SignalHooks, registerSignals, setupSignals };

package/dist/configure.js

@@ -1,3 +1,3 @@
-import { M as registerSignals, N as setupSignals } from "./-private-CvZfrDZl.js";
+import { M as registerSignals, N as setupSignals } from "./-private-DhEjiHue.js";
 
 export { registerSignals, setupSignals };

package/dist/{document-B8Fup751.d.ts → document-BUmwSPVO.d.ts}

@@ -1,6 +1,6 @@
 import { s as PersistedResourceKey } from "./identifier-DmgDehQK.js";
-import { d as Meta, m as PaginationLinks, u as Links } from "./json-api-raw-juUdIITO.js";
 import { t as ApiError } from "./error-j5n1yL9m.js";
+import { d as Meta, m as PaginationLinks, u as Links } from "./json-api-raw-juUdIITO.js";
 /**
  * This type represents a raw {json:api} document for a meta-only
  * document returned by a request intended to be inserted into the cache.
@@ -142,4 +142,4 @@ interface ResourceErrorDocument {
  */
 type ResourceDocument<T = PersistedResourceKey> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;
 export { ResourceMetaDocument as a, ResourceErrorDocument as i, ResourceDataDocument as n, SingleResourceDataDocument as o, ResourceDocument as r, CollectionResourceDataDocument as t };
-//# sourceMappingURL=document-B8Fup751.d.ts.map
+//# sourceMappingURL=document-BUmwSPVO.d.ts.map

package/dist/{document-B8Fup751.d.ts.map → document-BUmwSPVO.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"document-B8Fup751.d.ts","names":[],"sources":["../src/types/spec/document.ts"],"mappings":";;;;;;;;;;UAmBiB;;;;EAIf;;;;EAIA,MAAM;;;;EAIN,QAAQ,QAAQ;;;;;;;;;;;UAYD,2BAA2B,IAAI,sBAAsB,IAAI;;;;EAIxE;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;;;;UAYI,+BAA+B,IAAI;;;;EAIlD;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;;;;;;;;KAgBD,qBAAqB,IAAI,wBACjC,2BAA2B,KAC3B,+BAA+B;;;;;;;;;;UAWlB;;;;EAIf;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,QAAQ;;;;;;;;;;;;;;;;;KAkBE,iBAAiB,IAAI,wBAC7B,uBACA,2BAA2B,KAC3B,+BAA+B,KAC/B"}
+{"version":3,"file":"document-BUmwSPVO.d.ts","names":[],"sources":["../src/types/spec/document.ts"],"mappings":";;;;;;;;;;UAmBiB;;;;EAIf;;;;EAIA,MAAM;;;;EAIN,QAAQ,QAAQ;;;;;;;;;;;UAYD,2BAA2B,IAAI,sBAAsB,IAAI;;;;EAIxE;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;;;;UAYI,+BAA+B,IAAI;;;;EAIlD;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,MAAM;;;;EAIN,WAAW;;;;;;;;;;;;;;;KAgBD,qBAAqB,IAAI,wBACjC,2BAA2B,KAC3B,+BAA+B;;;;;;;;;;UAWlB;;;;EAIf;;;;EAIA,QAAQ,QAAQ;;;;EAIhB,OAAO;;;;EAIP,QAAQ;;;;;;;;;;;;;;;;;KAkBE,iBAAiB,IAAI,wBAC7B,uBACA,2BAA2B,KAC3B,+BAA+B,KAC/B"}

package/dist/{fields-r1rZJB9d.d.ts → fields-B-jO-dzB.d.ts}

@@ -963,16 +963,29 @@ interface DerivedField {
  * Represents a field that is a reference to
  * another resource.
  *
- * SUPPORT FOR THIS FEATURE IS NOT YET COMPLETE
- * IN ReactiveResource. It is not yet part of
- * {@link PolarisModeFieldSchema} or {@link LegacyModeFieldSchema}.
- * Reading the field returns an object with the related
- * record as `data`, plus `links`, `meta` and a `fetch()`
- * method, but it does not yet update when the
- * relationship changes, and setting it is not supported.
- *
- * @summary Field schema of kind `resource` for a reference to another resource; not yet implemented by
- * `ReactiveResource`.
+ * The value of a `resource` field on a ReactiveResource is a
+ * `ReactiveRelationshipDocument` whose `data` is the related
+ * resource (or `null`), and whose `links` and `meta` mirror the
+ * relationship payload received from the API.
+ *
+ * ```ts
+ * const user = store.peekRecord<User>('user', '1');
+ * user.bestFriend.data; // User | null | undefined
+ * user.bestFriend.links; // { related: '/users/1/best-friend' }
+ * ```
+ *
+ * The relationship payload for this field is expected to have the
+ * shape `{ data?: { type, id } | null, links?: Links, meta?: Meta }`.
+ * When `data` is omitted from the payload `doc.data` is `undefined`
+ * and `doc.fetch()` may be used to load the related resource via
+ * the `related` link.
+ *
+ * In LegacyMode the relationship is mutable via `doc.data = record`.
+ * In PolarisMode it is immutable unless the parent resource has been
+ * checked out for editing.
+ *
+ * @summary Field schema of kind `resource` for a reference to another resource, whose value is a
+ * `ReactiveRelationshipDocument`.
  * @public
  */
 interface ResourceField {
@@ -1029,12 +1042,22 @@ interface ResourceField {
    */
   options?: {
     /**
-     * Whether the relationship is async
+     * Whether the relationship is async.
      *
-     * If true, it is expected that the cache
-     * data for this field will contain a link
-     * that can be used to fetch the related
-     * resource when needed.
+     * For `resource` fields `async` describes what the API
+     * sends for the relationship (see the Relationship
+     * Specification in the manual):
+     *
+     * - `true`: every payload for the relationship MUST carry a
+     *   `links` object with a `related` link. `data` may be
+     *   omitted; when present, the referenced resource MUST be
+     *   included in the payload.
+     * - `false` (default): whenever the relationship is present
+     *   in a payload its `data` member MUST be present and the
+     *   referenced resource MUST be included in the payload.
+     *   The relationship SHOULD NOT carry `links`.
+     *
+     * Related resources are never fetched automatically.
      *
      * @public
      */
@@ -1072,17 +1095,37 @@ interface ResourceField {
 }
 /**
  * Represents a field that is a reference to
- * a collection of other resources, potentially
- * paginate.
- *
- * SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
- * BY ReactiveResource. It is not yet part of
- * {@link PolarisModeFieldSchema} or {@link LegacyModeFieldSchema},
- * and reading or setting the field fails an assertion
- * in development builds.
+ * a collection of other resources.
  *
- * @summary Field schema of kind `collection` for a possibly paginated reference to other resources; not yet implemented
- * by `ReactiveResource`.
+ * The value of a `collection` field on a ReactiveResource is a
+ * `ReactiveRelationshipDocument` whose `data` is a reactive array
+ * of the related resources, and whose `links` and `meta` mirror the
+ * relationship payload received from the API.
+ *
+ * ```ts
+ * const user = store.peekRecord<User>('user', '1');
+ * user.friends.data; // User[] | undefined
+ * user.friends.links; // { related: '/users/1/friends' }
+ * ```
+ *
+ * The relationship payload for this field is expected to have the
+ * shape `{ data?: { type, id }[], links?: Links, meta?: Meta }`.
+ * When `data` is omitted from the payload `doc.data` is `undefined`
+ * and `doc.fetch()` may be used to load the related resources via
+ * the `related` link.
+ *
+ * Collection relationships are not paginated: pagination links present
+ * on the relationship are surfaced on `doc.links` but are never merged
+ * into the relationship's membership. Large, sortable, filterable or
+ * paginated lists should be loaded with a top-level request instead.
+ *
+ * In LegacyMode the relationship is mutable via `doc.data.push(record)`
+ * (and the other array mutation methods) or `doc.data = [records]`.
+ * In PolarisMode it is immutable unless the parent resource has been
+ * checked out for editing.
+ *
+ * @summary Field schema of kind `collection` for a reference to other resources, whose value is a
+ * `ReactiveRelationshipDocument`.
  * @public
  */
 interface CollectionField {
@@ -1139,23 +1182,24 @@ interface CollectionField {
    */
   options?: {
     /**
-     * Whether the relationship is async
+     * Whether the relationship is async.
      *
-     * If true, it is expected that the cache
-     * data for this field will contain links
-     * that can be used to fetch the related
-     * resources when needed.
+     * For `collection` fields `async` describes what the API
+     * sends for the relationship (see the Relationship
+     * Specification in the manual):
      *
-     * When false, it is expected that all related
-     * resources are loaded together with this resource,
-     * and that the cache data for this field will
-     * contain the full list of pointers.
+     * - `true`: every payload for the relationship MUST carry a
+     *   `links` object with a `related` link. `data` may be
+     *   omitted; when present, every referenced resource MUST be
+     *   included in the payload.
+     * - `false` (default): whenever the relationship is present
+     *   in a payload its `data` member MUST be present (an array,
+     *   possibly empty) and every referenced resource MUST be
+     *   included in the payload. The relationship SHOULD NOT
+     *   carry `links`.
      *
-     * When true, it is expected that the relationship
-     * is paginated. If the relationship is not paginated,
-     * then the cache data for "page 1" would contain the
-     * full list of pointers, and loading "page 1" would
-     * load all related resources.
+     * Related resources are never fetched automatically. Use
+     * `doc.fetch()` or a top-level request to load them.
      *
      * @public
      */
@@ -1984,8 +2028,8 @@ interface LinksModeHasManyField {
  * - {@link ArrayField}
  * - {@link SchemaArrayField}
  * - {@link DerivedField}
- * - {@link ResourceField | ResourceField (not yet implemented)}
- * - {@link CollectionField | CollectionField (not yet implemented)}
+ * - {@link ResourceField}
+ * - {@link CollectionField}
  * - {@link LegacyAttributeField}
  * - {@link LegacyBelongsToField}
  * - {@link LegacyHasManyField}
@@ -1994,7 +2038,7 @@ interface LinksModeHasManyField {
  * and hasMany fields.
  * @public
  */
-type LegacyModeFieldSchema = GenericField | LegacyAliasField | LocalField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | DerivedField | LegacyAttributeField | LegacyBelongsToField | LegacyHasManyField;
+type LegacyModeFieldSchema = GenericField | LegacyAliasField | LocalField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | DerivedField | ResourceField | CollectionField | LegacyAttributeField | LegacyBelongsToField | LegacyHasManyField;
 /**
  * A union of all possible PolarisMode field schemas.
  *
@@ -2008,8 +2052,8 @@ type LegacyModeFieldSchema = GenericField | LegacyAliasField | LocalField | Obje
  * - {@link ArrayField}
  * - {@link SchemaArrayField}
  * - {@link DerivedField}
- * - {@link ResourceField | ResourceField (not yet implemented)}
- * - {@link CollectionField | CollectionField (not yet implemented)}
+ * - {@link ResourceField}
+ * - {@link CollectionField}
  * - {@link LinksModeBelongsToField}
  * - {@link LinksModeHasManyField}
  *
@@ -2017,7 +2061,7 @@ type LegacyModeFieldSchema = GenericField | LegacyAliasField | LocalField | Obje
  * LinksMode forms.
  * @public
  */
-type PolarisModeFieldSchema = GenericField | PolarisAliasField | LocalField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | DerivedField | LinksModeBelongsToField | LinksModeHasManyField;
+type PolarisModeFieldSchema = GenericField | PolarisAliasField | LocalField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | DerivedField | ResourceField | CollectionField | LinksModeBelongsToField | LinksModeHasManyField;
 /**
  * A union of all possible LegacyMode and PolarisMode
  * field schemas.
@@ -2406,6 +2450,26 @@ declare function objectSchema<T extends ObjectSchema>(schema: T): T;
  * `@id`.
  * @public
  */
+/**
+ * Whether a field kind is a to-many relationship: the legacy `hasMany` or the
+ * `collection` kind.
+ *
+ * @public
+ */
+declare function isManyKind(kind: string): kind is "hasMany" | "collection";
+/**
+ * Whether a field kind is a to-one relationship: the legacy `belongsTo` or the
+ * `resource` kind.
+ *
+ * @public
+ */
+declare function isSingleKind(kind: string): kind is "belongsTo" | "resource";
+/**
+ * Whether a field kind is any relationship kind, legacy or not.
+ *
+ * @public
+ */
+declare function isRelationshipKind(kind: string): kind is "belongsTo" | "hasMany" | "resource" | "collection";
 declare function isResourceSchema(schema: ResourceSchema | ObjectSchema): schema is ResourceSchema;
 /**
  * A type utility to narrow a schema to LegacyResourceSchema
@@ -2448,5 +2512,5 @@ type LegacyField = LegacyAttributeField | LegacyBelongsToField | LegacyHasManyFi
  * @public
  */
 type LegacyRelationshipField = LegacyBelongsToField | LegacyHasManyField | LinksModeBelongsToField | LinksModeHasManyField;
-export { ResourceField as A, ObjectField as C, PolarisModeFieldSchema as D, PolarisAliasField as E, Trait as F, isLegacyResourceSchema as I, isResourceSchema as L, Schema as M, SchemaArrayField as N, PolarisResourceSchema as O, SchemaObjectField as P, objectSchema as R, ObjectAliasField as S, ObjectSchema as T, LegacyResourceSchema as _, DerivedField as a, LinksModeHasManyField as b, HashField as c, LegacyAttributeField as d, LegacyBelongsToField as f, LegacyRelationshipField as g, LegacyModeFieldSchema as h, CollectionField as i, ResourceSchema as j, PolarisTrait as k, IdentityField as l, LegacyHasManyField as m, AttrOptions as n, FieldSchema as o, LegacyField as p, CacheableFieldSchema as r, GenericField as s, ArrayField as t, LegacyAliasField as u, LegacyTrait as v, ObjectFieldSchema as w, LocalField as x, LinksModeBelongsToField as y, resourceSchema as z };
-//# sourceMappingURL=fields-r1rZJB9d.d.ts.map
+export { ResourceField as A, isSingleKind as B, ObjectField as C, PolarisModeFieldSchema as D, PolarisAliasField as E, Trait as F, resourceSchema as H, isLegacyResourceSchema as I, isManyKind as L, Schema as M, SchemaArrayField as N, PolarisResourceSchema as O, SchemaObjectField as P, isRelationshipKind as R, ObjectAliasField as S, ObjectSchema as T, objectSchema as V, LegacyResourceSchema as _, DerivedField as a, LinksModeHasManyField as b, HashField as c, LegacyAttributeField as d, LegacyBelongsToField as f, LegacyRelationshipField as g, LegacyModeFieldSchema as h, CollectionField as i, ResourceSchema as j, PolarisTrait as k, IdentityField as l, LegacyHasManyField as m, AttrOptions as n, FieldSchema as o, LegacyField as p, CacheableFieldSchema as r, GenericField as s, ArrayField as t, LegacyAliasField as u, LegacyTrait as v, ObjectFieldSchema as w, LocalField as x, LinksModeBelongsToField as y, isResourceSchema as z };
+//# sourceMappingURL=fields-B-jO-dzB.d.ts.map

package/dist/fields-B-jO-dzB.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields-B-jO-dzB.d.ts","names":[],"sources":["../src/types/schema/fields.ts"],"mappings":"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"}

package/dist/graph/-private.d.ts

@@ -1,2 +1,2 @@
-import { Gt as GraphEdge, Ht as peekGraph, Jt as CollectionEdge, Kt as ResourceEdge, Ut as isBelongsTo, Vt as graphFor, Wt as Graph, Yt as UpgradedMeta, qt as ImplicitEdge } from "../internal-D_WIXC4r.js";
+import { Gt as GraphEdge, Ht as peekGraph, Jt as CollectionEdge, Kt as ResourceEdge, Ut as isBelongsTo, Vt as graphFor, Wt as Graph, Yt as UpgradedMeta, qt as ImplicitEdge } from "../internal-BrC3kM86.js";
 export { type CollectionEdge, type Graph, type GraphEdge, type ImplicitEdge, type ResourceEdge, type UpgradedMeta, graphFor, isBelongsTo, peekGraph };

package/dist/graph/-private.js

@@ -1,4 +1,5 @@
 import { getOrSetGlobal, peekTransient, setTransient } from "../types/-private.js";
+import { isRelationshipKind } from "../types/schema/fields.js";
 import { getGlobalConfig, macroCondition } from "@embroider/macros";
 import { deprecate, warn } from "@ember/debug";
 
@@ -190,20 +191,14 @@ function assertRelationshipData(store, resourceKey, data, meta) {
 }
 
 // src/graph/-private/-edge-definition.ts
-const RELATIONSHIP_KINDS = [
-	"belongsTo",
-	"hasMany",
-	"resource",
-	"collection"
-];
 function isLegacyField(field) {
 	return field.kind === "belongsTo" || field.kind === "hasMany";
 }
 function isRelationshipField(field) {
-	return RELATIONSHIP_KINDS.includes(field.kind);
+	return isRelationshipKind(field.kind);
 }
 function temporaryConvertToLegacy(field) {
-	return {
+	const legacy = {
 		kind: field.kind === "resource" ? "belongsTo" : "hasMany",
 		name: field.name,
 		type: field.type,
@@ -213,6 +208,8 @@ function temporaryConvertToLegacy(field) {
 			resetOnRemoteUpdate: false
 		}, field.options)
 	};
+	if (field.sourceKey) legacy.sourceKey = field.sourceKey;
+	return legacy;
 }
 /**
 *
@@ -297,10 +294,12 @@ function syncMeta(definition, inverseDefinition) {
 	inverseDefinition.resetOnRemoteUpdate = resetOnRemoteUpdate;
 }
 function upgradeMeta(meta) {
+	const fieldKind = meta.kind;
 	if (!isLegacyField(meta)) meta = temporaryConvertToLegacy(meta);
 	const niceMeta = {};
 	const options = meta.options;
 	niceMeta.kind = meta.kind;
+	niceMeta.fieldKind = fieldKind;
 	niceMeta.key = meta.sourceKey ?? meta.name;
 	niceMeta.name = meta.name;
 	niceMeta.type = meta.type;
@@ -389,7 +388,7 @@ function upgradeDefinition(graph, key, propertyName, isImplicit = false) {
 		})(storeWrapper.schema.hasResource({ type: inverseType }));
 		inverseDefinition = null;
 	} else {
-		inverseKey = inverseForRelationship(getStore(storeWrapper), key, meta.name);
+		inverseKey = inverseNameFor(meta);
 		if (!inverseKey && definition.isPolymorphic && definition.inverseKey) inverseDefinition = {
 			kind: "belongsTo",
 			key: definition.inverseKey,
@@ -413,10 +412,13 @@ function upgradeDefinition(graph, key, propertyName, isImplicit = false) {
 			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
 				if (!test) throw new Error(`Expected ${inverseKey} to be a relationship`);
 			})(isRelationshipField(metaFromInverse));
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error(`'${type}.${propertyName}' is a '${meta.kind}' field, but its inverse '${inverseType}.${inverseKey}' is a '${metaFromInverse.kind}' field. A 'resource' or 'collection' field can only have a 'resource' or 'collection' field as its inverse, and a 'belongsTo' or 'hasMany' field can only have a 'belongsTo' or 'hasMany' field as its inverse.`);
+			})(isLegacyField(meta) === isLegacyField(metaFromInverse));
 			inverseDefinition = upgradeMeta(metaFromInverse);
-			inverseKey = inverseDefinition.key;
 		}
 	}
+	if (inverseDefinition) inverseKey = inverseDefinition.key;
 	if (!inverseDefinition) {
 		inverseKey = implicitKeyFor(type, propertyName);
 		inverseDefinition = {
@@ -497,16 +499,20 @@ function upgradeDefinition(graph, key, propertyName, isImplicit = false) {
 	expandingSet(cache, inverseType, inverseKey, info);
 	return info;
 }
-function inverseForRelationship(store, resourceKey, key) {
-	const definition = store.schema.fields(resourceKey).get(key);
-	if (!definition) return null;
-	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
-		if (!test) throw new Error(`Expected ${key} to be a relationship`);
-	})(isRelationshipField(definition));
+/**
+* The `name` of the field on the related type that `field` declares as its inverse,
+* or `null` when it declares no inverse.
+*
+* `options.inverse` always names the inverse by its `name`, never by its `sourceKey`.
+* `resource` and `collection` fields may omit it, in which case they are unidirectional;
+* the legacy kinds must state it explicitly.
+*/
+function inverseNameFor(field) {
+	const { options } = isLegacyField(field) ? field : temporaryConvertToLegacy(field);
 	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
 		if (!test) throw new Error(`Expected the relationship defintion to specify the inverse type or null.`);
-	})(definition.options?.inverse === null || typeof definition.options?.inverse === "string" && definition.options.inverse.length > 0);
-	return definition.options.inverse;
+	})(options?.inverse === null || typeof options?.inverse === "string" && options.inverse.length > 0);
+	return options.inverse;
 }
 
 // src/graph/-private/debug/assert-polymorphic-type.ts
@@ -577,6 +583,7 @@ if (macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG)) {
 			name: definition.inverseName,
 			type: definition.inverseType,
 			kind: definition.inverseKind,
+			fieldKind: definition.inverseKind,
 			isAsync: definition.inverseIsAsync,
 			isPolymorphic: true,
 			isLinksMode: definition.isLinksMode,
@@ -802,6 +809,7 @@ function addToInverse(graph, resourceKey, key, value, isRemote) {
 			graph._addToTransaction(relationship);
 			if (relationship.remoteState !== null) removeFromInverse(graph, relationship.remoteState, relationship.definition.inverseKey, resourceKey, isRemote);
 			relationship.remoteState = value;
+			relationship.state.hasReceivedRemoteData = true;
 			notifyChange(graph, relationship);
 		}
 		if (relationship.localState !== value) {
@@ -815,8 +823,10 @@ function addToInverse(graph, resourceKey, key, value, isRemote) {
 				graph._addToTransaction(relationship);
 				relationship.remoteState.push(value);
 				relationship.remoteMembers.add(value);
-				if (relationship.additions?.has(value)) relationship.additions.delete(value);
-				else {
+				if (relationship.additions?.has(value)) {
+					relationship.additions.delete(value);
+					flushCanonical(graph, relationship, "remote");
+				} else {
 					relationship.isDirty = true;
 					relationship.state.hasReceivedData = true;
 					flushCanonical(graph, relationship);
@@ -844,6 +854,7 @@ function removeFromInverse(graph, resourceKey, key, value, isRemote) {
 		if (isRemote) {
 			graph._addToTransaction(relationship);
 			relationship.remoteState = null;
+			relationship.state.hasReceivedRemoteData = true;
 			notifyChange(graph, relationship);
 		}
 		if (relationship.localState === value) {
@@ -853,7 +864,9 @@ function removeFromInverse(graph, resourceKey, key, value, isRemote) {
 	} else if (isHasMany(relationship)) {
 		if (isRemote) {
 			graph._addToTransaction(relationship);
+			const wasMember = relationship.remoteMembers.has(value);
 			if (_removeRemote(relationship, value)) notifyChange(graph, relationship);
+			else if (wasMember) notifyChange(graph, relationship, "remote");
 		} else if (_removeLocal(relationship, value)) notifyChange(graph, relationship, "local");
 	} else if (isRemote) {
 		relationship.remoteMembers.delete(value);