@warp-drive-mirror/core 5.10.0-alpha.12 → 5.10.0-alpha.13

package/dist/unpkg/dev/types/schema/fields.js

@@ -1,11 +1,25 @@
 //#region src/types/schema/fields.ts
 /**
+* The [Schemas](/guides/the-manual/schemas/) guide teaches how these schemas and
+* fields fit together.
+*
+* @module
+* @summary Types for every field schema kind and for PolarisMode and LegacyMode resource, object and trait schemas,
+* plus the `resourceSchema` and `objectSchema` helpers and type guards.
+*/
+/**
 * Options signature for Legacy Attributes.
+*
+* @summary Options object on a legacy `attribute` field schema, holding a `defaultValue` (a primitive or a function
+* producing one) plus any transform-specific options.
 */
 /**
 * A generic "field" that can be used to define
 * primitive value fields.
 *
+* The [SimpleFields](/guides/the-manual/schemas/simple-fields) guide shows how to
+* define them.
+*
 * Replaces "attribute" for primitive value fields.
 * Can also be used to eject from deep-tracking of
 * objects or arrays.
@@ -16,6 +30,8 @@
 * "type" points to a new-style transform on "field"
 * that a record implmentation *must* use.
 *
+* @summary Field schema of kind `field` for a primitive value, optionally converted by a registered `Transformation`;
+* objects and arrays in it are not deep-tracked.
 * @public
 */
 /**
@@ -44,6 +60,8 @@
 * an AliasField could be used to expose both a string and a Date version of the
 * same field, with both being capable of being written to.
 *
+* @summary Field schema of kind `alias` for LegacyMode resources that exposes another field's cache value, including
+* legacy attributes and relationships, under a new name.
 * @public
 */
 /**
@@ -72,6 +90,8 @@
 * an AliasField could be used to expose both a string and a Date version of the
 * same field, with both being capable of being written to.
 *
+* @summary Field schema of kind `alias` for PolarisMode resources that exposes another field's cache value, including
+* LinksMode relationships, under a new name.
 * @public
 */
 /**
@@ -100,12 +120,17 @@
 * an AliasField could be used to expose both a string and a Date version of the
 * same field, with both being capable of being written to.
 *
+* @summary Field schema of kind `alias` for object schemas that exposes another non-relationship field's cache value
+* under a new name.
 * @public
 */
 /**
 * Represents a field whose value is the primary
 * key of the resource.
 *
+* The [ResourceSchemas](/guides/the-manual/schemas/resources/) guide shows where it
+* sits in a schema.
+*
 * This allows any field to serve as the primary
 * key while still being able to drive identity
 * needs within the system.
@@ -114,6 +139,8 @@
 * 'uuid', 'urn' or 'entityUrn' or 'primaryKey' as their
 * primary key field instead of 'id'.
 *
+* @summary Field schema of kind `@id` naming which field holds a resource's primary key, with an optional `sourceKey`
+* when the API uses another name like `uuid`.
 * @public
 */
 /**
@@ -137,6 +164,8 @@
 * it should be placed in the `ResourceSchema`'s `@id` field
 * in place of an `IdentityField`.
 *
+* @summary Field schema of kind `@hash` that computes a schema-object's identity from its cache data using a registered
+* hash function.
 * @public
 */
 /**
@@ -166,6 +195,8 @@
 *
 * Don't make us regret this decision.
 *
+* @summary Field schema of kind `@local` for memoized, writable per-record state that is never cached or sent to the
+* server; currently private to built-in fields.
 * @public
 */
 /**
@@ -177,6 +208,8 @@
 * if the key/value pairs have well-defined shape,
 * use 'schema-object' instead.
 *
+* @summary Field schema of kind `object` for a plain object of primitive values, optionally passed as a whole through a
+* registered transformation.
 * @public
 */
 /**
@@ -184,11 +217,16 @@
 * with a well-defined structure described by
 * a schema-object (a non-resource schema).
 *
+* The [Complex Fields](/guides/the-manual/schemas/complex-fields#schema-objects) guide
+* shows how to use it.
+*
 * If the object's structure is not well-defined,
 * use 'object' instead.
 *
 * By default, a SchemaObject within
 *
+* @summary Field schema of kind `schema-object` for a nested object whose shape is described by an `ObjectSchema`, with
+* optional polymorphism.
 * @public
 */
 /**
@@ -198,6 +236,8 @@
 * If the array's elements are not primitive
 * values, use 'schema-array' instead.
 *
+* @summary Field schema of kind `array` for an array of primitive values, each optionally passed through a registered
+* transformation.
 * @public
 */
 /**
@@ -205,15 +245,23 @@
 * of objects with a well-defined structure
 * described by a non-resource schema.
 *
+* The [Complex Fields](/guides/the-manual/schemas/complex-fields#schema-arrays) guide
+* shows how to use it.
+*
 * If the array's elements are not well-defined,
 * use 'array' instead.
 *
+* @summary Field schema of kind `schema-array` for an array of objects described by an `ObjectSchema`, with options for
+* member identity keys and polymorphism.
 * @public
 */
 /**
 * Represents a field whose value is derived
 * from other fields in the schema.
 *
+* The [Derivations](/guides/the-manual/schemas/derivations) guide explains when to
+* use one and how to register its derivation.
+*
 * The value is read-only, and is not stored
 * in the cache, nor is it sent to the server.
 *
@@ -224,15 +272,24 @@
 * or that require access to related resources
 * that may not be loaded should be avoided.
 *
+* @summary Field schema of kind `derived` for a read-only, memoized value computed by a registered derivation and never
+* cached or sent to the server.
 * @public
 */
 /**
 * Represents a field that is a reference to
 * another resource.
 *
-* SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
-* BY ReactiveResource
+* 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`.
 * @public
 */
 /**
@@ -241,8 +298,13 @@
 * paginate.
 *
 * SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
-* BY ReactiveResource
+* 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.
 *
+* @summary Field schema of kind `collection` for a possibly paginated reference to other resources; not yet implemented
+* by `ReactiveResource`.
 * @public
 */
 /**
@@ -256,10 +318,15 @@
 * If the field points to an object or array,
 * it will not be deep-tracked.
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to use it.
+*
 * Transforms when defined are legacy transforms
 * that a serializer *might* use, but their usage
 * is not guaranteed.
 *
+* @summary Legacy field schema of kind `attribute` for a primitive value whose `type` names a legacy transform a
+* serializer may apply; LegacyMode only.
 * @public
 */
 /**
@@ -271,6 +338,11 @@
 *
 * This is the legacy version of the `ResourceField`.
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to use it.
+*
+* @summary Legacy field schema of kind `belongsTo` for a reference to one related resource, with required `async` and
+* `inverse` options and optional `linksMode`.
 * @public
 */
 /**
@@ -282,6 +354,8 @@
 *
 * This is the legacy version of the `ResourceField`.
 *
+* @summary Legacy field schema of kind `belongsTo` in LinksMode: a sync reference to one related resource, loaded via
+* links without adapters, usable in PolarisMode.
 * @public
 */
 /**
@@ -293,6 +367,11 @@
 *
 * This is the legacy version of the `CollectionField`.
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to use it.
+*
+* @summary Legacy field schema of kind `hasMany` for a reference to many related resources, with required `async` and
+* `inverse` options and optional `linksMode`.
 * @public
 */
 /**
@@ -304,6 +383,8 @@
 *
 * This is the legacy version of the `CollectionField`.
 *
+* @summary Legacy field schema of kind `hasMany` in LinksMode: a sync reference to many related resources, loaded via
+* links without adapters, usable in PolarisMode.
 * @public
 */
 /**
@@ -325,6 +406,8 @@
 * - {@link LegacyBelongsToField}
 * - {@link LegacyHasManyField}
 *
+* @summary Union of every field schema allowed on a LegacyMode resource schema, including legacy attribute, belongsTo,
+* and hasMany fields.
 * @public
 */
 /**
@@ -345,6 +428,8 @@
 * - {@link LinksModeBelongsToField}
 * - {@link LinksModeHasManyField}
 *
+* @summary Union of every field schema allowed on a PolarisMode resource schema, with relationships limited to their
+* LinksMode forms.
 * @public
 */
 /**
@@ -356,6 +441,8 @@
 * as appropriate as they are more specific and will
 * provide better guidance around what is valid.
 *
+* @summary Union of every LegacyMode and PolarisMode field schema; prefer the mode-specific unions for more precise
+* type-checking.
 * @public
 */
 /**
@@ -366,12 +453,14 @@
 * In other words this will not include types like alias
 * fields, local fields, or derived fields.
 *
+* @summary Union of the field schemas whose values live in the cache, excluding alias, local, and derived fields.
 * @public
 */
 /**
 * A union of all possible field schemas that can be
 * used in an ObjectSchema.
 *
+* @summary Union of the field schemas allowed in an `ObjectSchema`, which excludes identity and relationship fields.
 * @public
 */
 /**
@@ -381,15 +470,22 @@
 * own which may allow them to appear in relationships, or in multiple
 * response documents.
 *
+* @summary Schema describing a PolarisMode resource type: its `@id` identity field, its fields, and the traits it
+* implements.
 * @public
 */
 /**
 * Represents a schema for a primary resource in LegacyMode
 *
+* The [LegacyMode](/guides/the-manual/schemas/resources/legacy-mode#defining-legacy-schemas)
+* guide shows how to define one.
+*
 * Primary resources are objects with a unique identity of their
 * own which may allow them to appear in relationships, or in multiple
 * response documents.
 *
+* @summary Schema describing a LegacyMode resource type, marked `legacy: true`, with its identity field, fields,
+* traits, and optional extensions.
 * @public
 */
 /**
@@ -397,24 +493,36 @@
 * definition for either a PolarisMode or a
 * LegacyMode resource.
 *
+* The [ResourceSchemas](/guides/the-manual/schemas/resources/) guide shows how to
+* create and register one.
+*
 * Note, this is separate from the type returned
 * by the SchemaService which provides fields as a Map
 * instead of as an Array.
 *
+* @summary Union of the PolarisMode and LegacyMode schema definitions for a primary resource type, as registered with
+* the schema service.
 * @public
 */
 /**
 * Represents a schema for an object that is not
 * a primary resource (has no unique identity of its own).
 *
+* The [ObjectSchemas](/guides/the-manual/schemas/object-schemas) guide shows how to
+* define and register one.
+*
 * ObjectSchemas may not currently contain relationships.
 *
+* @summary Schema describing an embedded object that has no identity of its own, used by `schema-object` and
+* `schema-array` fields.
 * @public
 */
 /**
 * A union of {@link ResourceSchema} and {@link ObjectSchema} representing
 * any schema that can be registered with or returned by the SchemaService.
 *
+* @summary Union of resource and object schemas, covering any schema that can be registered with or returned by the
+* schema service.
 * @public
 */
 /**
@@ -423,6 +531,9 @@
 * Traits are reusable collections of fields that can be composed onto a
 * resource schema, often to describe a polymorphic capability shared by
 * multiple resource types.
+*
+* @summary A named, reusable set of PolarisMode fields that resource schemas compose in via their `traits`, often to
+* model polymorphic capabilities.
 */
 /**
 * A trait for use on a LegacyMode record.
@@ -430,11 +541,19 @@
 * Traits are reusable collections of fields that can be composed onto a
 * resource schema, often to describe a polymorphic capability shared by
 * multiple resource types.
+*
+* @summary A named, reusable set of LegacyMode fields that resource schemas compose in via their `traits`, often to
+* model polymorphic capabilities.
 */
 /**
 * A union of
 * - {@link LegacyTrait}
 * - {@link PolarisTrait}
+*
+* The [Traits](/guides/the-manual/schemas/traits) guide shows how to create, register
+* and use one.
+*
+* @summary Union of the LegacyMode and PolarisMode trait definitions that can be registered with the schema service.
 */
 /**
 * A no-op type utility that enables type-checking resource schema
@@ -446,6 +565,8 @@
 * as doing so would require a full schema graph to be passed in
 * and no cycles in the graph to be present.
 *
+* @summary Returns the given resource schema unchanged, typed so its definition is type-checked; relationship inverses
+* and related types are not validated.
 * @public
 */
 function resourceSchema(schema) {
@@ -457,6 +578,7 @@ function resourceSchema(schema) {
 *
 * Will return the passed in schema.
 *
+* @summary Returns the given object schema unchanged, typed so its definition is type-checked.
 * @public
 */
 function objectSchema(schema) {
@@ -465,6 +587,8 @@ function objectSchema(schema) {
 /**
 * A type utility to narrow a schema to a ResourceSchema
 *
+* @summary Type guard that returns true when a schema is a resource schema, meaning its identity field is of kind
+* `@id`.
 * @public
 */
 function isResourceSchema(schema) {
@@ -473,6 +597,8 @@ function isResourceSchema(schema) {
 /**
 * A type utility to narrow a schema to LegacyResourceSchema
 *
+* @summary Type guard that returns true when a schema is a LegacyMode resource schema, meaning it is a resource schema
+* with `legacy: true`.
 * @public
 */
 function isLegacyResourceSchema(schema) {
@@ -491,6 +617,8 @@ function isLegacyResourceSchema(schema) {
 * - {@link LinksModeBelongsToField}
 * - {@link LinksModeHasManyField}
 *
+* @summary Union of the legacy attribute, belongsTo, and hasMany field schemas, including the LinksMode relationship
+* variants.
 * @public
 */
 /**
@@ -504,6 +632,7 @@ function isLegacyResourceSchema(schema) {
 * - {@link LinksModeBelongsToField}
 * - {@link LinksModeHasManyField}
 *
+* @summary Union of the legacy belongsTo and hasMany field schemas, including their LinksMode variants.
 * @public
 */
 //#endregion