@warp-drive/schema-record 4.13.0-alpha.5 → 4.13.0-alpha.7

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

@@ -1,3 +1,4 @@
+import { isResourceSchema } from '@warp-drive/core-types/schema/fields';
 import { macroCondition, getGlobalConfig, dependencySatisfies, importSync } from '@embroider/macros';
 import { SOURCE as SOURCE$1, fastPush, RelatedCollection, setRecordIdentifier, recordIdentifierFor } from '@ember-data/store/-private';
 import { createSignal, subscribe, defineSignal, peekSignal, getSignal, Signals, addToTransaction, entangleSignal } from '@ember-data/tracking/-private';
@@ -307,7 +308,7 @@ class ManagedObject {
           return self[prop];
         }
         if (prop === Symbol.toPrimitive) {
-          return null;
+          return () => null;
         }
         if (prop === Symbol.toStringTag) {
           return `ManagedObject<${identifier.type}:${identifier.id} (${identifier.lid})>`;
@@ -322,7 +323,12 @@ class ManagedObject {
         }
         if (prop === 'toHTML') {
           return function () {
-            return '<div>ManagedObject</div>';
+            return '<span>ManagedObject</span>';
+          };
+        }
+        if (prop === 'toJSON') {
+          return function () {
+            return structuredClone(self[SOURCE]);
           };
         }
         if (_SIGNAL.shouldReset) {
@@ -661,6 +667,9 @@ const RecordSymbols = new Set(symbolList);
 function isPathMatch(a, b) {
   return a.length === b.length && a.every((v, i) => v === b[i]);
 }
+function isNonEnumerableProp(prop) {
+  return prop === 'constructor' || prop === 'prototype' || prop === '__proto__' || prop === 'toString' || prop === 'toJSON' || prop === 'toHTML' || typeof prop === 'symbol';
+}
 const Editables = new WeakMap();
 class SchemaRecord {
   constructor(store, identifier, Mode, isEmbedded = false, embeddedType = null, embeddedPath = null) {
@@ -676,22 +685,25 @@ class SchemaRecord {
     this[Legacy] = Mode[Legacy] ?? false;
     const schema = store.schema;
     const cache = store.cache;
-    const identityField = schema.resource(identifier).identity;
+    const identityField = schema.resource(isEmbedded ? {
+      type: embeddedType
+    } : identifier).identity;
+    const BoundFns = new Map();
     this[EmbeddedType] = embeddedType;
     this[EmbeddedPath] = embeddedPath;
-    let fields;
-    if (isEmbedded) {
-      fields = schema.fields({
-        type: embeddedType
-      });
-    } else {
-      fields = schema.fields(identifier);
-    }
+    const fields = isEmbedded ? schema.fields({
+      type: embeddedType
+    }) : schema.fields(identifier);
     const signals = new Map();
     this[Signals] = signals;
     const proxy = new Proxy(this, {
       ownKeys() {
-        return Array.from(fields.keys());
+        const identityKey = identityField?.name;
+        const keys = Array.from(fields.keys());
+        if (identityKey) {
+          keys.unshift(identityKey);
+        }
+        return keys;
       },
       has(target, prop) {
         if (prop === Destroy || prop === Checkout) {
@@ -700,10 +712,19 @@ class SchemaRecord {
         return fields.has(prop);
       },
       getOwnPropertyDescriptor(target, prop) {
-        if (!fields.has(prop)) {
-          throw new Error(`No field named ${String(prop)} on ${identifier.type}`);
+        const schemaForField = prop === identityField?.name ? identityField : fields.get(prop);
+        macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+          if (!test) {
+            throw new Error(`No field named ${String(prop)} on ${identifier.type}`);
+          }
+        })(schemaForField) : {};
+        if (isNonEnumerableProp(prop)) {
+          return {
+            writable: false,
+            enumerable: false,
+            configurable: true
+          };
         }
-        const schemaForField = fields.get(prop);
         switch (schemaForField.kind) {
           case 'derived':
             return {
@@ -711,6 +732,12 @@ class SchemaRecord {
               enumerable: true,
               configurable: true
             };
+          case '@id':
+            return {
+              writable: identifier.id === null,
+              enumerable: true,
+              configurable: true
+            };
           case '@local':
           case 'field':
           case 'attribute':
@@ -728,28 +755,18 @@ class SchemaRecord {
               enumerable: true,
               configurable: true
             };
+          default:
+            return {
+              writable: false,
+              enumerable: false,
+              configurable: false
+            };
         }
       },
       get(target, prop, receiver) {
         if (RecordSymbols.has(prop)) {
           return target[prop];
         }
-        if (prop === Symbol.toStringTag) {
-          return `SchemaRecord<${identifier.type}:${identifier.id} (${identifier.lid})>`;
-        }
-        if (prop === 'toString') {
-          return function () {
-            return `SchemaRecord<${identifier.type}:${identifier.id} (${identifier.lid})>`;
-          };
-        }
-        if (prop === 'toHTML') {
-          return function () {
-            return `<div>SchemaRecord<${identifier.type}:${identifier.id} (${identifier.lid})></div>`;
-          };
-        }
-        if (prop === Symbol.toPrimitive) {
-          return null;
-        }
 
         // TODO make this a symbol
         if (prop === '___notifications') {
@@ -765,18 +782,75 @@ class SchemaRecord {
           if (IgnoredGlobalFields.has(prop)) {
             return undefined;
           }
+
+          /////////////////////////////////////////////////////////////
+          //// Note these bound function behaviors are essentially ////
+          //// built-in but overrideable derivations.              ////
+          ////                                                     ////
+          //// The bar for this has to be "basic expectations of   ////
+          ///  an object" – very, very high                        ////
+          /////////////////////////////////////////////////////////////
+
+          if (prop === Symbol.toStringTag || prop === 'toString') {
+            let fn = BoundFns.get('toString');
+            if (!fn) {
+              fn = function () {
+                entangleSignal(signals, receiver, '@identity');
+                return `Record<${identifier.type}:${identifier.id} (${identifier.lid})>`;
+              };
+              BoundFns.set(prop, fn);
+            }
+            return fn;
+          }
+          if (prop === 'toHTML') {
+            let fn = BoundFns.get('toHTML');
+            if (!fn) {
+              fn = function () {
+                entangleSignal(signals, receiver, '@identity');
+                return `<span>Record<${identifier.type}:${identifier.id} (${identifier.lid})></span>`;
+              };
+              BoundFns.set(prop, fn);
+            }
+            return fn;
+          }
+          if (prop === 'toJSON') {
+            let fn = BoundFns.get('toJSON');
+            if (!fn) {
+              fn = function () {
+                const json = {};
+                for (const key in receiver) {
+                  json[key] = receiver[key];
+                }
+                return json;
+              };
+              BoundFns.set(prop, fn);
+            }
+            return fn;
+          }
+          if (prop === Symbol.toPrimitive) return () => null;
+          if (prop === Symbol.iterator) {
+            let fn = BoundFns.get(Symbol.iterator);
+            if (!fn) {
+              fn = function* () {
+                for (const key in receiver) {
+                  yield [key, receiver[key]];
+                }
+              };
+              BoundFns.set(Symbol.iterator, fn);
+            }
+            return fn;
+          }
           if (prop === 'constructor') {
             return SchemaRecord;
           }
           // too many things check for random symbols
-          if (typeof prop === 'symbol') {
-            return undefined;
-          }
-          let type = identifier.type;
-          if (isEmbedded) {
-            type = embeddedType;
-          }
-          throw new Error(`No field named ${String(prop)} on ${type}`);
+          if (typeof prop === 'symbol') return undefined;
+          macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+            {
+              throw new Error(`No field named ${String(prop)} on ${isEmbedded ? embeddedType : identifier.type}`);
+            }
+          })() : {};
+          return undefined;
         }
         const field = maybeField.kind === 'alias' ? maybeField.options : maybeField;
         macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
@@ -804,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]);
@@ -1292,6 +1341,19 @@ class SchemaRecord {
           break;
       }
     });
+    if (macroCondition(getGlobalConfig().WarpDrive.env.DEBUG)) {
+      Object.defineProperty(this, '__SHOW_ME_THE_DATA_(debug mode only)__', {
+        enumerable: false,
+        configurable: true,
+        get() {
+          const data = {};
+          for (const key of fields.keys()) {
+            data[key] = proxy[key];
+          }
+          return data;
+        }
+      });
+    }
     return proxy;
   }
   [Destroy]() {
@@ -1328,7 +1390,13 @@ class SchemaRecord {
 }
 function instantiateRecord(store, identifier, createArgs) {
   const schema = store.schema;
-  const isLegacy = schema.resource(identifier)?.legacy ?? false;
+  const resourceSchema = schema.resource(identifier);
+  macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+    if (!test) {
+      throw new Error(`Expected a resource schema`);
+    }
+  })(isResourceSchema(resourceSchema)) : {};
+  const isLegacy = resourceSchema?.legacy ?? false;
   const isEditable = isLegacy || store.cache.isNew(identifier);
   const record = new SchemaRecord(store, identifier, {
     [Editable]: isEditable,
@@ -1350,19 +1418,28 @@ function teardownRecord(record) {
   assertSchemaRecord(record);
   record[Destroy]();
 }
+
+/**
+ * @module @warp-drive/schema-record
+ */
 const Support = getOrSetGlobal('Support', new WeakMap());
-const SchemaRecordFields = [{
+const ConstructorField = {
   type: '@constructor',
   name: 'constructor',
   kind: 'derived'
-}, {
+};
+const TypeField = {
   type: '@identity',
   name: '$type',
   kind: 'derived',
   options: {
     key: 'type'
   }
-}];
+};
+const DefaultIdentityField = {
+  name: 'id',
+  kind: '@id'
+};
 function _constructor(record) {
   let state = Support.get(record);
   if (!state) {
@@ -1372,19 +1449,64 @@ function _constructor(record) {
   return state._constructor = state._constructor || {
     name: `SchemaRecord<${recordIdentifierFor$1(record).type}>`,
     get modelName() {
-      throw new Error('Cannot access record.constructor.modelName on non-Legacy Schema Records.');
+      macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+        {
+          throw new Error(`record.constructor.modelName is not available outside of legacy mode`);
+        }
+      })() : {};
+      return undefined;
     }
   };
 }
 _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 || {
-    name: 'id',
-    kind: '@id'
-  };
-  schema.fields.push(...SchemaRecordFields);
+  schema.identity = schema.identity || DefaultIdentityField;
+
+  // because fields gets iterated in definition order,
+  // we add TypeField to the beginning so that it will
+  // appear right next to the identity field
+  schema.fields.unshift(TypeField);
+  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 => {
@@ -1400,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);
@@ -1408,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) => {
@@ -1427,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
 
@@ -1534,7 +1670,7 @@ class SchemaService {
         relationships[field.name] = field;
       }
     });
-    const traits = new Set(schema.traits);
+    const traits = new Set(isResourceSchema(schema) ? schema.traits : []);
     traits.forEach(trait => {
       this._traits.add(trait);
     });