@warp-drive/core 5.7.0-alpha.0 → 5.7.0-alpha.1

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

@@ -1761,6 +1761,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.d.ts

@@ -6,6 +6,7 @@
 */
 export type { StableRecordIdentifier, ResourceKey } from "./types/identifier.js";
 export type { CacheCapabilitiesManager } from "./store/-types/q/cache-capabilities-manager.js";
-export type { ModelSchema } from "./store/-types/q/ds-model.js";
+// FIXME this should come from somewhere more intelligent
+export type { ModelSchema } from "./store/deprecated/-private.js";
 export type { SchemaService } from "./store/-types/q/schema-service.js";
 export type { BaseFinderOptions, FindRecordOptions, LegacyResourceQuery, QueryOptions, FindAllOptions } from "./store/-types/q/store.js";

package/dist/graph/-private.js

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

package/dist/{handler-C2T-IyJK.js → handler-D2jjnIA-.js}

@@ -1,4 +1,4 @@
-import { J as ReactiveDocument } from "./request-state-CjLph1LP.js";
+import { K as ReactiveDocument } from "./request-state-CejVJgdj.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, N as setIdentifierForgetMethod, K as setIdentifierGenerationMethod, O as setIdentifierResetMethod, L as setIdentifierUpdateMethod, P as setKeyInfoForResource, s as storeFor } from "./request-state-CjLph1LP.js";
-export { C as CacheHandler } from "./handler-C2T-IyJK.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";
 import '@ember/debug';
 import './utils/string.js';
 

package/dist/reactive.js

@@ -1,8 +1,8 @@
 import { isResourceSchema } from './types/schema/fields.js';
-import { E as withSignalStore, Q as isExtensionProp, T as performExtensionSet, G as consumeInternalSignal, U as performArrayExtensionGet, x as entangleSignal, V as performObjectExtensionGet, d as SOURCE$1, f as fastPush, y as defineSignal, l as RelatedCollection, H as getOrCreateInternalSignal, F as notifyInternalSignal, A as Signals, h as setRecordIdentifier, r as recordIdentifierFor } from "./request-state-CjLph1LP.js";
+import { F as withSignalStore, T as isExtensionProp, U as performExtensionSet, H as consumeInternalSignal, V as performArrayExtensionGet, x as entangleSignal, W as performObjectExtensionGet, d as SOURCE$1, f as fastPush, y as defineSignal, l as RelatedCollection, J as getOrCreateInternalSignal, G as notifyInternalSignal, B as Signals, h as setRecordIdentifier, r as recordIdentifierFor } from "./request-state-CejVJgdj.js";
 import { EnableHydration, STRUCTURED } from './types/request.js';
 import { macroCondition, getGlobalConfig } from '@embroider/macros';
-import { deprecate } from '@ember/debug';
+import { warn, deprecate } from '@ember/debug';
 import './utils/string.js';
 import { A as ARRAY_SIGNAL, O as OBJECT_SIGNAL, c as createMemo } from "./configure-B48bFHOl.js";
 import { RecordStore, Type } from './types/symbols.js';
@@ -1724,7 +1724,7 @@ class SchemaService {
     this._transforms = new Map();
     this._hashFns = new Map();
     this._derivations = new Map();
-    this._traits = new Set();
+    this._traits = new Map();
     this._modes = new Map();
     this._extensions = {
       object: new Map(),
@@ -1821,7 +1821,7 @@ class SchemaService {
     const fields = new Map();
     const relationships = {};
     const attributes = {};
-    schema.fields.forEach(field => {
+    for (const field of schema.fields) {
       macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
         if (!test) {
           throw new Error(`${field.kind} is not valid inside a ResourceSchema's fields.`);
@@ -1835,13 +1835,12 @@ class SchemaService {
       } else if (field.kind === 'belongsTo' || field.kind === 'hasMany') {
         relationships[field.name] = field;
       }
-    });
+    }
     const traits = new Set(isResourceSchema(schema) ? schema.traits : []);
-    traits.forEach(trait => {
-      this._traits.add(trait);
-    });
+    const finalized = traits.size === 0;
     const internalSchema = {
       original: schema,
+      finalized,
       fields,
       relationships,
       attributes,
@@ -1849,6 +1848,44 @@ class SchemaService {
     };
     this._schemas.set(schema.type, internalSchema);
   }
+
+  /**
+   * Registers a {@link Trait} for use by resource schemas.
+   *
+   * Traits are re-usable collections of fields that can be composed to
+   * build up a resource schema. Often they represent polymorphic behaviors
+   * a resource should exhibit.
+   *
+   * When we finalize a resource, we walk its traits and apply their fields
+   * to the resource's fields. All specified traits must be registered by
+   * this time or an error will be thrown.
+   *
+   * Traits are applied left-to-right, with traits of traits being applied in the same
+   * way. Thus for the most part, application of traits is a post-order graph traversal
+   * problem.
+   *
+   * A trait is only ever processed once. If multiple traits (A, B, C) have the same
+   * trait (D) as a dependency, D will be included only once when first encountered by
+   * A.
+   *
+   * If a cycle exists such that trait A has trait B which has Trait A, trait A will
+   * be applied *after* trait B in production. In development a cycle error will be thrown.
+   *
+   * Fields are finalized on a "last wins principle". Thus traits appearing higher in
+   * the tree and further to the right of a traits array take precedence, with the
+   * resource's fields always being applied last and winning out.
+   *
+   * @public
+   */
+  registerTrait(trait) {
+    const internalTrait = Object.assign({}, trait, {
+      fields: new Map()
+    });
+    for (const field of trait.fields) {
+      internalTrait.fields.set(field.name, field);
+    }
+    this._traits.set(trait.name, internalTrait);
+  }
   registerTransformation(transformation) {
     this._transforms.set(transformation[Type], transformation);
   }
@@ -1873,6 +1910,9 @@ class SchemaService {
   CAUTION_MEGA_DANGER_ZONE_arrayExtensions(field) {
     return processExtensions(this, field, 'array');
   }
+  CAUTION_MEGA_DANGER_ZONE_hasExtension(ext) {
+    return this._extensions[ext.kind].has(ext.name);
+  }
 
   /**
    * This is an internal method used to register behaviors for legacy mode.
@@ -1926,8 +1966,13 @@ class SchemaService {
     type
   }) {
     const schema = this._schemas.get(type);
-    if (!schema) {
-      throw new Error(`No schema defined for ${type}`);
+    macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`No schema defined for ${type}`);
+      }
+    })(schema) : {};
+    if (!schema.finalized) {
+      finalizeResource(this, schema);
     }
     return schema.fields;
   }
@@ -1985,4 +2030,84 @@ if (macroCondition(getGlobalConfig().WarpDrive.deprecations.ENABLE_LEGACY_SCHEMA
     return this._schemas.has(type);
   };
 }
+
+/**
+ * When we finalize a resource, we walk its traits and apply their fields
+ * to the resource's fields.
+ *
+ * Traits are applied left-to-right, with traits of traits being applied in the same
+ * way. Thus for the most part, application of traits is a post-order graph traversal
+ * problem.
+ *
+ * A trait is only ever processed once. If multiple traits (A, B, C) have the same
+ * trait (D) as a dependency, D will be included only once when first encountered by
+ * A.
+ *
+ * If a cycle exists such that trait A has trait B which has Trait A, trait A will
+ * be applied *after* trait B in production. In development a cycle error will be thrown.
+ *
+ * Fields are finalized on a "last wins principle". Thus traits appearing higher in
+ * the tree and further to the right of a traits array take precedence, with the
+ * resource's fields always being applied last and winning out.
+ */
+function finalizeResource(schema, resource) {
+  const fields = new Map();
+  const seen = new Set();
+  for (const traitName of resource.traits) {
+    const trait = schema._traits.get(traitName);
+    macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+      if (!test) {
+        throw new Error(`The trait ${traitName} MUST be supplied before the resource ${resource.original.type} can be finalized for use.`);
+      }
+    })(trait) : {};
+    walkTrait(schema, trait, fields, seen, resource.original.type, macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? [] : null);
+  }
+  mergeMap(fields, resource.fields);
+  resource.fields = fields;
+  resource.finalized = true;
+}
+function walkTrait(schema, trait, fields, seen, type, debugPath) {
+  if (seen.has(trait)) {
+    // if the trait is in the current path, we throw a cycle error in dev.
+    if (macroCondition(getGlobalConfig().WarpDrive.env.DEBUG)) {
+      if (debugPath.includes(trait.name)) {
+        throw new Error(`CycleError: The Trait '${trait.name}' utilized by the Resource '${type}' includes the following circular reference "${debugPath.join(' > ')} > ${trait.name}"`);
+      }
+    }
+    return;
+  }
+  const ownPath = macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? [...debugPath, trait.name] : null;
+
+  // immediately mark as seen to prevent cycles
+  // further down the tree from looping back
+  seen.add(trait);
+
+  // first apply any child traits
+  if (trait.traits?.length) {
+    for (const traitName of trait.traits) {
+      const subtrait = schema._traits.get(traitName);
+      if (macroCondition(getGlobalConfig().WarpDrive.features.ENFORCE_STRICT_RESOURCE_FINALIZATION)) {
+        macroCondition(getGlobalConfig().WarpDrive.env.DEBUG) ? (test => {
+          if (!test) {
+            throw new Error(`The trait ${traitName} used by the trait ${trait.name} MUST be supplied before the resource ${type} can be finalized for use.`);
+          }
+        })(subtrait) : {};
+      } else {
+        warn(`The trait ${traitName} used by the trait ${trait.name} MUST be supplied before the resource ${type} can be finalized for use.`, !!subtrait, {
+          id: 'warp-drive:missing-trait-schema-for-resource'
+        });
+      }
+      if (!subtrait) continue;
+      walkTrait(schema, subtrait, fields, seen, type, ownPath);
+    }
+  }
+
+  // then apply our own fields
+  mergeMap(fields, trait.fields);
+}
+function mergeMap(base, toApply) {
+  for (const [key, value] of toApply) {
+    base.set(key, value);
+  }
+}
 export { Checkout, SchemaService, fromIdentity, instantiateRecord, registerDerivations, teardownRecord, withDefaults };