@warp-drive/core 5.6.0-beta.0 → 5.6.0-beta.2

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

@@ -1,5 +1,15 @@
 import type { ObjectValue, PrimitiveValue, Value } from "../json/raw.js";
 /**
+* Options signature for Legacy Attributes.
+*/
+export interface AttrOptions {
+	/**
+	* A primitive value or a function which produces a value.
+	*/
+	defaultValue?: PrimitiveValue | (() => Value);
+	[key: string]: Value | (() => Value) | undefined;
+}
+/**
 * A generic "field" that can be used to define
 * primitive value fields.
 *
@@ -29,7 +39,30 @@ export interface GenericField {
 	*/
 	name: string;
 	/**
-	* the name of the transform to use, if any
+	* 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 {@link Transformation} to use, if any
 	*
 	* @public
 	*/
@@ -234,6 +267,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 +304,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 +428,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.
 	*
@@ -396,7 +473,7 @@ export interface ObjectField {
 		* Configures which extensions this object should use.
 		*
 		* Extensions are registered with the store's schema service
-		* via {@link SchemaService.registerDangerousObjectExtension}
+		* via {@link SchemaService.CAUTION_MEGA_DANGER_ZONE_registerExtension}
 		*
 		* Extensions should only be used for temporary enhancements
 		* to objects to support migrating away from deprecated patterns
@@ -409,11 +486,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 +509,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.
@@ -446,6 +555,15 @@ export interface SchemaObjectField {
 	* @public
 	*/
 	options?: {
+		/**
+		* If true, if no value for this field exists in the cache,
+		* an empty `{}` will be used as the source for a new SchemaObject
+		* of the associated schema type, as opposed to the field's
+		* value being `null`.
+		*
+		* If `polymorphic` is `true`, defaultValue will be considered `false`.
+		*/
+		defaultValue?: boolean;
 		/**
 		* ::: warning ⚠️ Dangerous Feature Ahead
 		* :::
@@ -472,7 +590,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 +628,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 +707,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 +756,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.
@@ -594,6 +773,13 @@ export interface SchemaArrayField {
 	* @public
 	*/
 	options?: {
+		/**
+		* If true, if no value for this field exists in the cache,
+		* an empty `[]` will be used as the value of the field,
+		* as opposed to the field's value being `null`.
+		*
+		*/
+		defaultValue?: boolean;
 		/**
 		* ::: warning ⚠️ Dangerous Feature Ahead
 		* :::
@@ -655,8 +841,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 +936,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 +1041,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 +1164,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
@@ -936,8 +1198,9 @@ export interface LegacyAttributeField {
 	* Must comply to the specific transform's options
 	* schema.
 	*
+	* See {@link AttrOptions} for more info.
 	*/
-	options?: ObjectValue;
+	options?: AttrOptions;
 }
 /**
 * > [!CAUTION]
@@ -964,6 +1227,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 +1380,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 +1528,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 +1699,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 +1903,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 +1936,6 @@ export interface PolarisResourceSchema {
 	*
 	* for schema-objects, this should be either a HashField or null
 	*
-	* @property identity
-	* @type {IdentityField}
 	* @public
 	*/
 	identity: IdentityField;
@@ -1761,6 +2125,19 @@ export interface ObjectSchema {
 	objectExtensions?: string[];
 }
 export type Schema = ResourceSchema | ObjectSchema;
+export interface PolarisTrait {
+	name: string;
+	mode: "polaris";
+	fields: PolarisModeFieldSchema[];
+	traits?: string[];
+}
+export interface LegacyTrait {
+	name: string;
+	mode: "legacy";
+	fields: LegacyModeFieldSchema[];
+	traits?: string[];
+}
+export type Trait = LegacyTrait | PolarisTrait;
 /**
 * A no-op type utility that enables type-checking resource schema
 * definitions.

package/declarations/types/spec/document.d.ts

@@ -1,4 +1,4 @@
-import type { StableExistingRecordIdentifier } from "../identifier.js";
+import type { PersistedResourceKey } from "../identifier.js";
 import type { ApiError } from "./error.js";
 import type { Links, Meta, PaginationLinks } from "./json-api-raw.js";
 export interface ResourceMetaDocument {
@@ -8,8 +8,8 @@ export interface ResourceMetaDocument {
 	links?: Links | PaginationLinks;
 }
 export interface SingleResourceDataDocument<
-	T = StableExistingRecordIdentifier,
-	R = StableExistingRecordIdentifier
+	T = PersistedResourceKey,
+	R = PersistedResourceKey
 > {
 	// the url or cache-key associated with the structured document
 	lid?: string;
@@ -18,7 +18,7 @@ export interface SingleResourceDataDocument<
 	data: T | null;
 	included?: R[];
 }
-export interface CollectionResourceDataDocument<T = StableExistingRecordIdentifier> {
+export interface CollectionResourceDataDocument<T = PersistedResourceKey> {
 	// the url or cache-key associated with the structured document
 	lid?: string;
 	links?: Links | PaginationLinks;
@@ -26,7 +26,7 @@ export interface CollectionResourceDataDocument<T = StableExistingRecordIdentifi
 	data: T[];
 	included?: T[];
 }
-export type ResourceDataDocument<T = StableExistingRecordIdentifier> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
+export type ResourceDataDocument<T = PersistedResourceKey> = SingleResourceDataDocument<T> | CollectionResourceDataDocument<T>;
 export interface ResourceErrorDocument {
 	// the url or cache-key associated with the structured document
 	lid?: string;
@@ -34,4 +34,4 @@ export interface ResourceErrorDocument {
 	meta?: Meta;
 	errors: ApiError[];
 }
-export type ResourceDocument<T = StableExistingRecordIdentifier> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;
+export type ResourceDocument<T = PersistedResourceKey> = ResourceMetaDocument | SingleResourceDataDocument<T> | CollectionResourceDataDocument<T> | ResourceErrorDocument;

package/declarations/types/spec/json-api-raw.d.ts

@@ -23,7 +23,8 @@ export interface PaginationLinks extends Links {
 * to address data that may not be available synchronously.
 *
 * [JSON:API Spec](https://jsonapi.org/format/#document-resource-identifier-objects)
-* @internal
+*
+* @private
 */
 export interface ExistingResourceIdentifierObject<T extends string = string> {
 	id: string;
@@ -42,7 +43,7 @@ export interface ExistingResourceIdentifierObject<T extends string = string> {
 	* is `lid` considered optional.
 	*
 	* [Identifiers RFC](https://github.com/emberjs/rfcs/blob/main/text/0403-ember-data-identifiers.md#ember-data--identifiers)
-	* @internal
+	*
 	*/
 	lid?: string;
 	/**
@@ -50,7 +51,7 @@ export interface ExistingResourceIdentifierObject<T extends string = string> {
 	* `ember-data` ignores `meta` on `ResourceIdentifierObjects`
 	*
 	* @ignored this property goes un-utilized and will be lost
-	* @internal
+	* @private
 	*/
 	meta?: Meta;
 }
@@ -58,7 +59,7 @@ export interface ExistingResourceIdentifierObject<T extends string = string> {
 * Serves as a reference to a resource created on the client
 * but not yet persisted.
 *
-* @internal
+* @private
 */
 export interface NewResourceIdentifierObject<T extends string = string> {
 	/**
@@ -68,14 +69,12 @@ export interface NewResourceIdentifierObject<T extends string = string> {
 	*
 	* `id` will be `null` in this case.
 	*
-	* @internal
 	*/
 	id: string | null;
 	type: T;
 	/**
 	* Resources newly created on the client _will always_
 	* have an `lid` assigned immediately and available.
-	* @internal
 	*/
 	lid: string;
 }
@@ -98,7 +97,6 @@ export type InnerRelationshipDocument<T = ExistingResourceIdentifierObject | New
 export type ResourceRelationshipsObject<T = ExistingResourceIdentifierObject | NewResourceIdentifierObject> = Record<string, InnerRelationshipDocument<T>>;
 /**
 * Contains the data for an existing resource in JSON:API format
-* @internal
 */
 export interface ExistingResourceObject<T extends string = string> extends ExistingResourceIdentifierObject<T> {
 	meta?: Meta;
@@ -136,7 +134,7 @@ export type CollectionResourceDocument<T extends string = string> = Document & {
 * These documents should follow the JSON:API spec but do not
 * have the same level of guarantees as their `spec` counterparts.
 *
-* @internal
+* @private
 */
 export type JsonApiDocument<T extends string = string> = EmptyResourceDocument | SingleResourceDocument<T> | CollectionResourceDocument<T>;
 export {};