@warp-drive/core 5.7.0-alpha.3 → 5.7.0-alpha.5

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

@@ -29,6 +29,29 @@ export interface GenericField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link GenericField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* the name of the transform to use, if any
 	*
 	* @public
@@ -234,6 +257,27 @@ export interface IdentityField {
 	* @public
 	*/
 	name: string;
+	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link IdentityField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   entityUrn: '324523-sadf34-345'
+	* }
+	* ```
+	*
+	* But the app desires to use `record.id; // '324523-sadf34-345'`
+	*
+	* Then `name` would be set to `'id'` and
+	* `sourceKey` would be set to `'entityUrn'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
 }
 /**
 * Represents a specialized field whose computed value
@@ -250,7 +294,7 @@ export interface IdentityField {
 * perform those itself.
 *
 * A schema-array can declare its "key" value to be `@hash` if
-* a schema-object has such a field.
+* the schema-objects it contains have such a field.
 *
 * Only one hash field is permittable per schema-object, and
 * it should be placed in the `ResourceSchema`'s `@id` field
@@ -374,6 +418,29 @@ export interface ObjectField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link ObjectField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* The name of a transform to pass the entire object
 	* through before displaying or serializing it.
 	*
@@ -409,11 +476,13 @@ export interface ObjectField {
 /**
 * Represents a field whose value is an object
 * with a well-defined structure described by
-* a non-resource schema.
+* a schema-object (a non-resource schema).
 *
 * If the object's structure is not well-defined,
 * use 'object' instead.
 *
+* By default, a SchemaObject within
+*
 * @public
 */
 export interface SchemaObjectField {
@@ -430,12 +499,42 @@ export interface SchemaObjectField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link SchemaObjectField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
+	* If the field is not polymorphic:
+	*
 	* The name of the ObjectSchema that describes the
 	* structure of the object.
 	*
+	* If the field is polymorphic:
+	*
+	* The name of the hashFn to use to extract
+	* the type from the contained value or null.
+	*
 	* @public
 	*/
-	type: string;
+	type: string | null;
 	/**
 	* Options for configuring the behavior of the
 	* SchemaObject.
@@ -472,7 +571,15 @@ export interface SchemaObjectField {
 		* If the SchemaObject is Polymorphic, the key on the raw cache data to use
 		* as the "resource-type" value for the schema-object.
 		*
-		* Defaults to "type".
+		* The default is `'type'`.
+		*
+		* Valid options are:
+		*
+		* - `'@hash'`                : will lookup the `@hash` function specified by
+		*       SchemaObjectField.type and use it to calculate the type for each value.
+		* - \<field-name> (string)   : the name of a field to use as the key, only GenericFields (kind `field`)
+		*       Are valid field names for this purpose. The cache state without transforms applied will be
+		*       used when comparing values.
 		*
 		* @public
 		*/
@@ -502,6 +609,29 @@ export interface ArrayField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link ArrayField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* The name of a transform to pass each item
 	* in the array through before displaying or
 	* or serializing it.
@@ -558,12 +688,42 @@ export interface SchemaArrayField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link SchemaArrayField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
+	* If the SchemaArray is not polymorphic:
+	*
 	* The name of the ObjectSchema that describes the
 	* structure of the objects in the array.
 	*
+	* If the SchemaArray is polymorphic:
+	*
+	* The name of the hashFn to use to extract
+	* the type from contained members or null.
+	*
 	* @public
 	*/
-	type: string;
+	type: string | null;
 	/**
 	* Options for configuring the behavior of the
 	* SchemaArray.
@@ -577,13 +737,13 @@ export interface SchemaArrayField {
 	*
 	* Valid options are:
 	*
-	* - `'@identity'` (default) : the cached object's referential identity will be used.
+	* - `'@identity'`(default)  : the cached object's referential identity will be used.
 	*       This may result in significant instability when resource data is updated from the API
 	* - `'@index'`              : the cached object's index in the array will be used.
 	*       This is only a good choice for arrays that rarely if ever change membership
 	* - `'@hash'`               : will lookup the `@hash` function supplied in the ResourceSchema for
 	*       The contained schema-object and use the computed result to determine and compare identity.
-	* - \<field-name> (string)   : the name of a field to use as the key, only GenericFields (kind `field`)
+	* - \<field-name> (string)  : the name of a field to use as the key, only GenericFields (kind `field`)
 	*       Are valid field names for this purpose. The cache state without transforms applied will be
 	*       used when comparing values. The field value should be unique enough to guarantee two schema-objects
 	*       of the same type will not collide.
@@ -655,8 +815,15 @@ export interface SchemaArrayField {
 		* If the SchemaArray is Polymorphic, the key on the raw cache data to use
 		* as the "resource-type" value for the schema-object.
 		*
-		* Defaults to "type".
+		* The default is `'type'`.
+		*
+		* Valid options are:
 		*
+		* - `'@hash'`                : will lookup the `@hash` function specified by
+		*       SchemaArrayField.type and use it to calculate the type for each value.
+		* - \<field-name> (string)   : the name of a field to use as the key, only GenericFields (kind `field`)
+		*       Are valid field names for this purpose. The cache state without transforms applied will be
+		*       used when comparing values.
 		*/
 		type?: string;
 	};
@@ -743,6 +910,29 @@ export interface ResourceField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link ResourceField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* The name of the resource that this field
 	* refers to. In the case of a polymorphic
 	* relationship, this should be the trait
@@ -825,6 +1015,29 @@ export interface CollectionField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link CollectionField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* The name of the resource that this field
 	* refers to. In the case of a polymorphic
 	* relationship, this should be the trait
@@ -925,6 +1138,29 @@ export interface LegacyAttributeField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link LegacyAttributeField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* The name of the transform to use, if any
 	*
 	* @public
@@ -964,6 +1200,29 @@ export interface LegacyBelongsToField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link LegacyBelongsToField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* The name of the resource that this field
 	* refers to. In the case of a polymorphic
 	* relationship, this should be the trait
@@ -1094,6 +1353,29 @@ export interface LinksModeBelongsToField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link LinksModeBelongsToField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* The name of the resource that this field
 	* refers to. In the case of a polymorphic
 	* relationship, this should be the trait
@@ -1219,6 +1501,29 @@ export interface LegacyHasManyField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link LegacyHasManyField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* the name of the resource that this field
 	* refers to. In the case of a polymorphic
 	* relationship, this should be the trait
@@ -1367,6 +1672,29 @@ export interface LinksModeHasManyField {
 	*/
 	name: string;
 	/**
+	* The name of the field as returned by the API
+	* and inserted into the {@link Cache} if it differs
+	* from {@link LinksModeHasManyField.name}
+	*
+	* For instance, if the API returns:
+	*
+	* ```ts
+	* {
+	*   attributes: {
+	*     'first-name': 'Chris'
+	*   }
+	* }
+	* ```
+	*
+	* But the app desires to use `record.firstName; // 'Chris'`
+	*
+	* Then `name` would be set to `'firstName'` and
+	* `sourceKey` would be set to `'first-name'`.
+	*
+	* This option is only needed when the value differs from name.
+	*/
+	sourceKey?: string;
+	/**
 	* the name of the resource that this field
 	* refers to. In the case of a polymorphic
 	* relationship, this should be the trait
@@ -1548,12 +1876,23 @@ export type PolarisModeFieldSchema = GenericField | PolarisAliasField | LocalFie
 */
 export type FieldSchema = GenericField | LegacyAliasField | PolarisAliasField | LocalField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | DerivedField | ResourceField | CollectionField | LegacyAttributeField | LegacyBelongsToField | LegacyHasManyField | LinksModeBelongsToField | LinksModeHasManyField;
 /**
+* A union of all possible LegacyMode and PolarisMode
+* field schemas that represent data that could be in
+* the cache.
+*
+* In other words this will not include types like alias
+* fields, local fields, or derived fields.
+*
+* @public
+*/
+export type CacheableFieldSchema = IdentityField | GenericField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | ResourceField | CollectionField | LegacyAttributeField | LegacyBelongsToField | LegacyHasManyField | LinksModeBelongsToField | LinksModeHasManyField;
+/**
 * A union of all possible field schemas that can be
 * used in an ObjectSchema.
 *
 * @public
 */
-export type ObjectFieldSchema = GenericField | ObjectAliasField | LocalField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | DerivedField;
+export type ObjectFieldSchema = LegacyAttributeField | GenericField | ObjectAliasField | LocalField | ObjectField | SchemaObjectField | ArrayField | SchemaArrayField | DerivedField;
 /**
 * Represents a schema for a primary resource in PolarisMode.
 *
@@ -1570,8 +1909,6 @@ export interface PolarisResourceSchema {
 	*
 	* for schema-objects, this should be either a HashField or null
 	*
-	* @property identity
-	* @type {IdentityField}
 	* @public
 	*/
 	identity: IdentityField;

package/dist/graph/-private.js

@@ -1,5 +1,5 @@
 import { deprecate, warn } from '@ember/debug';
-import { p as peekCache } from "../request-state-CejVJgdj.js";
+import { p as peekCache } from "../request-state-CeN66aML.js";
 import '../types/request.js';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 import '../utils/string.js';

package/dist/{handler-D2jjnIA-.js → handler-SdXlte1w.js}

@@ -1,4 +1,4 @@
-import { K as ReactiveDocument } from "./request-state-CejVJgdj.js";
+import { K as ReactiveDocument } from "./request-state-CeN66aML.js";
 import { SkipCache, EnableHydration } from './types/request.js';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 const MUTATION_OPS = new Set(['createRecord', 'updateRecord', 'deleteRecord']);

package/dist/index.js

@@ -3,8 +3,8 @@ import { a as cloneResponseProperties, I as IS_CACHE_HANDLER, b as assertValidRe
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
 import { w as waitFor } from "./configure-B48bFHOl.js";
 import { peekUniversalTransient, setUniversalTransient } from './types/-private.js';
-export { S as Store, r as recordIdentifierFor, O as setIdentifierForgetMethod, L as setIdentifierGenerationMethod, P as setIdentifierResetMethod, N as setIdentifierUpdateMethod, Q as setKeyInfoForResource, s as storeFor } from "./request-state-CejVJgdj.js";
-export { C as CacheHandler } from "./handler-D2jjnIA-.js";
+export { S as Store, r as recordIdentifierFor, O as setIdentifierForgetMethod, L as setIdentifierGenerationMethod, P as setIdentifierResetMethod, N as setIdentifierUpdateMethod, Q as setKeyInfoForResource, s as storeFor } from "./request-state-CeN66aML.js";
+export { C as CacheHandler } from "./handler-SdXlte1w.js";
 import '@ember/debug';
 import './utils/string.js';