@warp-drive/schema-record 5.4.0-alpha.149 → 5.4.0-alpha.151

package/README.md

@@ -1,23 +1,21 @@
 <p align="center">
   <img
     class="project-logo"
-    src="./logos/NCC-1701-a-blue.svg#gh-light-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    src="./logos/github-header.svg#gh-light-mode-only"
+    alt="WarpDrive | Boldly go where no app has gone before"
+    title="WarpDrive | Boldly go where no app has gone before"
+    />
   <img
     class="project-logo"
-    src="./logos/NCC-1701-a.svg#gh-dark-mode-only"
-    alt="WarpDrive"
-    width="120px"
-    title="WarpDrive" />
+    src="./logos/github-header.svg#gh-dark-mode-only"
+    alt="WarpDrive | Boldly go where no app has gone before"
+    title="WarpDrive | Boldly go where no app has gone before"
+    />
 </p>
 
 <h3 align="center">Your Data, Managed.</h3>
 <p align="center">🌲 Get back to Nature 🐿️ Or shipping 💚</p>
 
-SchemaRecord is:
-
 - ⚡️ Fast
 - 📦 Tiny
 - ✨ Optimized
@@ -25,11 +23,15 @@ SchemaRecord is:
 - ⚛️ Universal
 - ☢️ Reactive
 
-This package provides reactive capabilities for your resource data.
-It works together with a [*Warp***Drive**](https://github.com/emberjs/data/)
-[Cache](https://github.com/emberjs/data/blob/main/packages/core-types/src/cache.ts)
-and associated Schemas to simplify the most complex parts of your
-app's state management.
+SchemaRecord is a reactive object that transforms raw data from an [associated cache](https://github.com/emberjs/data/blob/main/packages/core-types/src/cache.ts) into reactive data backed by Signals.
+
+The shape of the object and the transformation of raw cache data into its
+reactive form is controlled by a resource schema.
+
+Resource schemas are simple JSON, allowing them to be defined and delivered from anywhere.
+
+The capabilities that SchemaRecord brings to [*Warp***Drive**](https://github.com/emberjs/data/)
+will simplify even the most complex parts of your app's state management.
 
 ## Installation
 
@@ -150,7 +152,8 @@ store.registerSchemas([
         options: {
           async: false,
           inverse: 'owner',
-          polymorphic: true
+          polymorphic: true,
+          linksMode: true,
         }
       }
     ]
@@ -174,6 +177,7 @@ store.registerSchemas([
           async: false,
           inverse: 'pets',
           as: 'pet',
+          linksMode: true,
         }
       }
     ]
@@ -286,6 +290,16 @@ store.registerSchemas([
 ]);
 ```
 
+Additionally, `@warp-drive/core-types` provides several utilities for type-checking and narrowing schemas.
+
+- (type) [PolarisResourceSchema]()
+- (type) [LegacyResourceSchema]()
+- (type) [ObjectSchema]()
+- [resourceSchema]()
+- [objectSchema]()
+- [isResourceSchema]()
+- [isLegacyResourceSchema]()
+
 
 ### Field Schemas
 

package/dist/index.js

@@ -878,49 +878,24 @@ class SchemaRecord {
               return lastValue;
             }
           case 'field':
-            macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
-              if (!test) {
-                throw new Error(`SchemaRecord.${field.name} is not available in legacy mode because it has type '${field.kind}'`);
-              }
-            })(!target[Legacy]) : {};
             entangleSignal(signals, receiver, field.name);
             return computeField(schema, cache, target, identifier, field, propArray, IS_EDITABLE);
           case 'attribute':
             entangleSignal(signals, receiver, field.name);
             return computeAttribute(cache, identifier, prop, IS_EDITABLE);
           case 'resource':
-            macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
-              if (!test) {
-                throw new Error(`SchemaRecord.${field.name} is not available in legacy mode because it has type '${field.kind}'`);
-              }
-            })(!target[Legacy]) : {};
             entangleSignal(signals, receiver, field.name);
             return computeResource(store, cache, target, identifier, field, prop, IS_EDITABLE);
           case 'derived':
             return computeDerivation(schema, receiver, identifier, field, prop);
           case 'schema-array':
           case 'array':
-            macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
-              if (!test) {
-                throw new Error(`SchemaRecord.${field.name} is not available in legacy mode because it has type '${field.kind}'`);
-              }
-            })(!target[Legacy]) : {};
             entangleSignal(signals, receiver, field.name);
             return computeArray(store, schema, cache, target, identifier, field, propArray, Mode[Editable], Mode[Legacy]);
           case 'object':
-            macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
-              if (!test) {
-                throw new Error(`SchemaRecord.${field.name} is not available in legacy mode because it has type '${field.kind}'`);
-              }
-            })(!target[Legacy]) : {};
             entangleSignal(signals, receiver, field.name);
             return computeObject(schema, cache, target, identifier, field, propArray, Mode[Editable], Mode[Legacy]);
           case 'schema-object':
-            macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
-              if (!test) {
-                throw new Error(`SchemaRecord.${field.name} is not available in legacy mode because it has type '${field.kind}'`);
-              }
-            })(!target[Legacy]) : {};
             entangleSignal(signals, receiver, field.name);
             // run transform, then use that value as the object to manage
             return computeSchemaObject(store, cache, target, identifier, field, propArray, Mode[Legacy], Mode[Editable]);
@@ -1443,6 +1418,10 @@ function teardownRecord(record) {
   assertSchemaRecord(record);
   record[Destroy]();
 }
+
+/**
+ * @module @warp-drive/schema-record
+ */
 const Support = getOrSetGlobal('Support', new WeakMap());
 const ConstructorField = {
   type: '@constructor',
@@ -1484,6 +1463,13 @@ _constructor[Type] = '@constructor';
 /**
  * Utility for constructing a ResourceSchema with the recommended fields
  * for the Polaris experience.
+ *
+ * @method withDefaults
+ * @for @warp-drive/schema-record
+ * @static
+ * @public
+ * @param schema
+ * @return {ResourceSchema}
  */
 function withDefaults(schema) {
   schema.identity = schema.identity || DefaultIdentityField;
@@ -1495,6 +1481,32 @@ function withDefaults(schema) {
   schema.fields.push(ConstructorField);
   return schema;
 }
+
+/**
+ * A derivation that computes its value from the
+ * record's identity.
+ *
+ * It can be used via a derived field definition like:
+ *
+ * ```ts
+ * {
+ *   kind: 'derived',
+ *   name: 'id',
+ *   type: '@identity',
+ *   options: { key: 'id' }
+ * }
+ * ```
+ *
+ * Valid keys are `'id'`, `'lid'`, `'type'`, and `'^'`.
+ *
+ * `^` returns the entire identifier object.
+ *
+ * @method fromIdentity
+ * @for @warp-drive/schema-record
+ * @static
+ * @public
+ */
+
 function fromIdentity(record, options, key) {
   const identifier = record[Identifier];
   macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
@@ -1510,6 +1522,16 @@ function fromIdentity(record, options, key) {
   return options.key === '^' ? identifier : identifier[options.key];
 }
 fromIdentity[Type] = '@identity';
+
+/**
+ * Registers the default derivations for the SchemaRecord
+ *
+ * @method registerDerivations
+ * @for @warp-drive/schema-record
+ * @static
+ * @public
+ * @param {SchemaService} schema
+ */
 function registerDerivations(schema) {
   schema.registerDerivation(fromIdentity);
   schema.registerDerivation(_constructor);
@@ -1518,9 +1540,7 @@ function registerDerivations(schema) {
  * Wraps a derivation in a new function with Derivation signature but that looks
  * up the value in the cache before recomputing.
  *
- * @param record
- * @param options
- * @param prop
+ * @internal
  */
 function makeCachedDerivation(derivation) {
   const memoizedDerivation = (record, options, prop) => {
@@ -1537,6 +1557,12 @@ function makeCachedDerivation(derivation) {
   memoizedDerivation[Type] = derivation[Type];
   return memoizedDerivation;
 }
+/**
+ * A SchemaService designed to work with dynamically registered schemas.
+ *
+ * @class SchemaService
+ * @public
+ */
 class SchemaService {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any