feat: schema type utils (emberjs#9757)

* minor type improvements

* chore: fixup types

* add api docs

* nice things

* account for schema presence

* cleanup test

Author: runspired

packages/core-types/src/index.ts

@@ -1 +1,8 @@
+/**
+ * This package provides core types, type-utilities, symbols
+ * and constants used across the WarpDrive ecosystem.
+ *
+ * @module @warp-drive/core-types
+ * @main @warp-drive/core-types
+ */
 export type { StableRecordIdentifier } from './identifier';

packages/core-types/src/schema/fields.ts

@@ -1,3 +1,6 @@
+/**
+ * @module @warp-drive/core-types
+ */
 import type { ObjectValue, PrimitiveValue } from '../json/raw';
 
 /**
@@ -919,25 +922,51 @@ export type FieldSchema =
   | LegacyBelongsToField
   | LegacyHasManyField;
 
-export type ResourceSchema = {
+export type ObjectFieldSchema =
+  | GenericField
+  | AliasField
+  | LocalField
+  | ObjectField
+  | SchemaObjectField
+  | ArrayField
+  | SchemaArrayField
+  | DerivedField;
+
+/**
+ * Represents a schema for a primary resource.
+ *
+ * Primary resources are objects with a unique identity of their
+ * own which may allow them to appear in relationships, or is multiple
+ * response document.
+ *
+ * @typedoc
+ */
+export interface ResourceSchema {
   legacy?: boolean;
+
   /**
    * For primary resources, this should be an IdentityField
    *
    * for schema-objects, this should be either a HashField or null
    *
    * @typedoc
    */
-  identity: IdentityField | HashField | null;
+  identity: IdentityField;
+
   /**
    * The name of the schema
    *
    * For cacheable resources, this should be the
    * primary resource type.
    *
    * For object schemas, this should be the name
-   * of the object schema. object schemas should
-   * follow the following guidelines for naming
+   * of the object schema.
+   *
+   * The names of object and resource schemas share
+   * a single namespace and must not conflict.
+   *
+   * We recommend a naming convention for object schemas
+   * such as below for ensuring uniqueness:
    *
    * - for globally shared objects: The pattern `$field:${KlassName}` e.g. `$field:AddressObject`
    * - for resource-specific objects: The pattern `$${ResourceKlassName}:$field:${KlassName}` e.g. `$User:$field:ReusableAddress`
@@ -946,9 +975,123 @@ export type ResourceSchema = {
    * @typedoc
    */
   type: string;
-  traits?: string[];
+
+  /**
+   * The fields that make up the shape of the resource
+   *
+   * @typedoc
+   */
   fields: FieldSchema[];
-};
+
+  /**
+   * A list of traits that this resource implements. The fields for these
+   * traits should still be defined in the fields array.
+   *
+   * Each trait should be a string that matches the `type` of another
+   * resource schema. The trait can be abstract and reference a resource
+   * type that is never defined as a schema.
+   *
+   * @typedoc
+   */
+  traits?: string[];
+}
+
+/**
+ * Represents a schema for an object that is not
+ * a primary resource (has no unique identity of its own).
+ *
+ * ObjectSchemas may not currently contain relationships.
+ *
+ * @typedoc
+ */
+export interface ObjectSchema {
+  /**
+   * Either a HashField from which to calculate an identity or null
+   *
+   * In the case of `null`, the object's identity will be based
+   * on the referential identity of the object in the cache itself
+   * when an identity is needed.
+   *
+   * @typedoc
+   */
+  identity: HashField | null;
+
+  /**
+   * The name of the schema
+   *
+   * The names of object and resource schemas share
+   * a single namespace and must not conflict.
+   *
+   * We recommend a naming convention for object schemas
+   * such as below for ensuring uniqueness:
+   *
+   * - for globally shared objects: The pattern `$field:${KlassName}` e.g. `$field:AddressObject`
+   * - for resource-specific objects: The pattern `$${ResourceKlassName}:$field:${KlassName}` e.g. `$User:$field:ReusableAddress`
+   * - for inline objects: The pattern `$${ResourceKlassName}.${fieldPath}:$field:anonymous` e.g. `$User.shippingAddress:$field:anonymous`
+   *
+   * @typedoc
+   */
+  type: string;
+
+  /**
+   * The fields that make up the shape of the object
+   *
+   * @typedoc
+   */
+  fields: ObjectFieldSchema[];
+}
+
+/**
+ * A no-op type utility that enables type-checking resource schema
+ * definitions.
+ *
+ * Will return the passed in schema.
+ *
+ * This will not validate relationship inverses or related types,
+ * as doing so would require a full schema graph to be passed in
+ * and no cycles in the graph to be present.
+ *
+ * @method resourceSchema
+ * @static
+ * @for @warp-drive/core-types
+ * @param {ResourceSchema} schema
+ * @returns {ResourceSchema} the passed in schema
+ * @public
+ */
+export function resourceSchema<T extends ResourceSchema>(schema: T): T {
+  return schema;
+}
+
+/**
+ * A no-op type utility that enables type-checking object schema
+ * definitions.
+ *
+ * Will return the passed in schema.
+ *
+ * @method objectSchema
+ * @static
+ * @for @warp-drive/core-types
+ * @param {ObjectSchema} schema
+ * @returns {ObjectSchema} the passed in schema
+ * @public
+ */
+export function objectSchema<T extends ObjectSchema>(schema: T): T {
+  return schema;
+}
+
+/**
+ * A type utility to narrow a schema to a ResourceSchema
+ *
+ * @method isResourceSchema
+ * @static
+ * @for @warp-drive/core-types
+ * @param schema
+ * @returns {boolean}
+ * @public
+ */
+export function isResourceSchema(schema: ResourceSchema | ObjectSchema): schema is ResourceSchema {
+  return schema?.identity?.kind === '@id';
+}
 
 export type LegacyFieldSchema = LegacyAttributeField | LegacyBelongsToField | LegacyHasManyField;
 export type LegacyRelationshipSchema = LegacyBelongsToField | LegacyHasManyField;

packages/model/src/-private/schema-provider.ts

@@ -17,6 +17,7 @@ import type {
   LegacyFieldSchema,
   LegacyRelationshipSchema,
   ObjectField,
+  ObjectSchema,
   ResourceSchema,
 } from '@warp-drive/core-types/schema/fields';
 
@@ -69,7 +70,7 @@ export class ModelSchemaProvider implements SchemaService {
   hashFn(field: HashField | { type: string }): HashFn {
     assert(`hashFn is not available with @ember-data/model's SchemaService`);
   }
-  resource(resource: StableRecordIdentifier | { type: string }): ResourceSchema {
+  resource(resource: StableRecordIdentifier | { type: string }): ResourceSchema | ObjectSchema {
     const type = normalizeModelName(resource.type);
 
     if (!this._schemas.has(type)) {
@@ -78,10 +79,10 @@ export class ModelSchemaProvider implements SchemaService {
 
     return this._schemas.get(type)!.schema;
   }
-  registerResources(schemas: ResourceSchema[]): void {
+  registerResources(schemas: Array<ResourceSchema | ObjectSchema>): void {
     assert(`registerResources is not available with @ember-data/model's SchemaService`);
   }
-  registerResource(schema: ResourceSchema): void {
+  registerResource(schema: ResourceSchema | ObjectSchema): void {
     assert(`registerResource is not available with @ember-data/model's SchemaService`);
   }
   registerTransformation(transform: Transformation): void {

packages/model/src/migration-support.ts

@@ -15,6 +15,7 @@ import type {
   GenericField,
   HashField,
   ObjectField,
+  ObjectSchema,
   ResourceSchema,
 } from '@warp-drive/core-types/schema/fields';
 import { Type } from '@warp-drive/core-types/symbols';
@@ -227,16 +228,16 @@ export class DelegatingSchemaService implements SchemaService {
   derivation(field: DerivedField | { type: string }): Derivation {
     return this._preferred.derivation(field);
   }
-  resource(resource: StableRecordIdentifier | { type: string }): ResourceSchema {
+  resource(resource: StableRecordIdentifier | { type: string }): ResourceSchema | ObjectSchema {
     if (this._preferred.hasResource(resource)) {
       return this._preferred.resource(resource);
     }
     return this._secondary.resource(resource);
   }
-  registerResources(schemas: ResourceSchema[]): void {
+  registerResources(schemas: Array<ResourceSchema | ObjectSchema>): void {
     this._preferred.registerResources(schemas);
   }
-  registerResource(schema: ResourceSchema): void {
+  registerResource(schema: ResourceSchema | ObjectSchema): void {
     this._preferred.registerResource(schema);
   }
   registerTransformation(transform: Transformation): void {

packages/request/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "include": ["src/**/*"],
   "compilerOptions": {
-    "target": "ES2024",
+    "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
     "skipLibCheck": true,

packages/schema-record/src/-private/hooks.ts

@@ -1,6 +1,7 @@
 import type Store from '@ember-data/store';
 import { assert } from '@warp-drive/build-config/macros';
 import type { StableRecordIdentifier } from '@warp-drive/core-types';
+import { isResourceSchema } from '@warp-drive/core-types/schema/fields';
 
 import { SchemaRecord } from './record';
 import type { SchemaService } from './schema';
@@ -12,7 +13,9 @@ export function instantiateRecord(
   createArgs?: Record<string, unknown>
 ): SchemaRecord {
   const schema = store.schema as unknown as SchemaService;
-  const isLegacy = schema.resource(identifier)?.legacy ?? false;
+  const resourceSchema = schema.resource(identifier);
+  assert(`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,

packages/schema-record/src/-private/schema.ts

@@ -11,16 +11,18 @@ import type { StableRecordIdentifier } from '@warp-drive/core-types';
 import { getOrSetGlobal } from '@warp-drive/core-types/-private';
 import type { ObjectValue, Value } from '@warp-drive/core-types/json/raw';
 import type { Derivation, HashFn } from '@warp-drive/core-types/schema/concepts';
-import type {
-  ArrayField,
-  DerivedField,
-  FieldSchema,
-  GenericField,
-  HashField,
-  LegacyAttributeField,
-  LegacyRelationshipSchema,
-  ObjectField,
-  ResourceSchema,
+import {
+  type ArrayField,
+  type DerivedField,
+  type FieldSchema,
+  type GenericField,
+  type HashField,
+  isResourceSchema,
+  type LegacyAttributeField,
+  type LegacyRelationshipSchema,
+  type ObjectField,
+  type ObjectSchema,
+  type ResourceSchema,
 } from '@warp-drive/core-types/schema/fields';
 import { Type } from '@warp-drive/core-types/symbols';
 import type { WithPartial } from '@warp-drive/core-types/utils';
@@ -91,13 +93,13 @@ export function registerDerivations(schema: SchemaServiceInterface) {
   schema.registerDerivation(_constructor);
 }
 
-type InternalSchema = {
-  original: ResourceSchema;
+interface InternalSchema {
+  original: ResourceSchema | ObjectSchema;
   traits: Set<string>;
   fields: Map<string, FieldSchema>;
   attributes: Record<string, LegacyAttributeField>;
   relationships: Record<string, LegacyRelationshipSchema>;
-};
+}
 
 export type Transformation<T extends Value = Value, PT = unknown> = {
   serialize(value: PT, options: Record<string, unknown> | null, record: SchemaRecord): T;
@@ -209,16 +211,16 @@ export class SchemaService implements SchemaServiceInterface {
     );
     return this._hashFns.get(field.type)!;
   }
-  resource(resource: StableRecordIdentifier | { type: string }): ResourceSchema {
+  resource(resource: StableRecordIdentifier | { type: string }): ResourceSchema | ObjectSchema {
     assert(`No resource registered with name '${resource.type}'`, this._schemas.has(resource.type));
     return this._schemas.get(resource.type)!.original;
   }
-  registerResources(schemas: ResourceSchema[]): void {
+  registerResources(schemas: Array<ResourceSchema | ObjectSchema>): void {
     schemas.forEach((schema) => {
       this.registerResource(schema);
     });
   }
-  registerResource(schema: ResourceSchema): void {
+  registerResource(schema: ResourceSchema | ObjectSchema): void {
     const fields = new Map<string, FieldSchema>();
     const relationships: Record<string, LegacyRelationshipSchema> = {};
     const attributes: Record<string, LegacyAttributeField> = {};
@@ -237,7 +239,7 @@ export class SchemaService implements SchemaServiceInterface {
       }
     });
 
-    const traits = new Set<string>(schema.traits);
+    const traits = new Set<string>(isResourceSchema(schema) ? schema.traits : []);
     traits.forEach((trait) => {
       this._traits.add(trait);
     });

packages/store/src/-types/q/schema-service.ts

@@ -16,6 +16,7 @@ import type {
   LegacyBelongsToField,
   LegacyHasManyField,
   ObjectField,
+  ObjectSchema,
   ResourceSchema,
 } from '@warp-drive/core-types/schema/fields';
 
@@ -171,7 +172,7 @@ export interface SchemaService {
    * @param {StableRecordIdentifier|{ type: string }} resource
    * @return {ResourceSchema}
    */
-  resource(resource: { type: string } | StableRecordIdentifier): ResourceSchema;
+  resource(resource: { type: string } | StableRecordIdentifier): ResourceSchema | ObjectSchema;
 
   /**
    * Enables registration of multiple ResourceSchemas at once.
@@ -184,7 +185,7 @@ export interface SchemaService {
    * @public
    * @param schemas
    */
-  registerResources(schemas: ResourceSchema[]): void;
+  registerResources(schemas: Array<ResourceSchema | ObjectSchema>): void;
 
   /**
    * Enables registration of a single ResourceSchema.
@@ -197,7 +198,7 @@ export interface SchemaService {
    * @public
    * @param {ResourceSchema} schema
    */
-  registerResource(schema: ResourceSchema): void;
+  registerResource(schema: ResourceSchema | ObjectSchema): void;
 
   /**
    * Enables registration of a transformation.