@aws-amplify/data-schema 1.1.4 → 1.1.6

package/src/ModelRelationalField.ts

@@ -60,7 +60,7 @@ type ModelRelationalFieldFunctions<
     K | 'required'
   >;
   /**
-   * Configures field-level authorization rules. Pass in an array of authorizations `(a.allow.____)` to mix and match
+   * Configures field-level authorization rules. Pass in an array of authorizations `(allow => allow.____)` to mix and match
    * multiple authorization rules for this field.
    */
   authorization<AuthRuleType extends Authorization<any, any, any>>(
@@ -184,10 +184,28 @@ export type ModelRelationalTypeArgFactory<
 };
 
 /**
- * Create a one-directional one-to-one relationship between two models using the `hasOne("MODEL_NAME")` method.
+ * Create one-to-one relationship between two models using the `hasOne("MODEL_NAME", "REFERENCE_FIELD(s)")` method.
  * A hasOne relationship always uses a reference to the related model's identifier. Typically this is the `id` field
  * unless overwritten with the `identifier()` method.
+ * @example
+ * const schema = a.schema({
+ *   Cart: a.model({
+ *     items: a.string().required().array(),
+ *     // 1. Create reference field
+ *     customerId: a.id(),
+ *     // 2. Create relationship field with the reference field
+ *     customer: a.belongsTo('Customer', 'customerId'),
+ *   }),
+ *   Customer: a.model({
+ *     name: a.string(),
+ *     // 3. Create relationship field with the reference field
+ *     //    from the Cart model
+ *     activeCart: a.hasOne('Cart', 'customerId')
+ *   }),
+ * });
+ * @see {@link https://docs.amplify.aws/react/build-a-backend/data/data-modeling/relationships/#model-a-one-to-one-relationship}
  * @param relatedModel the name of the related model
+ * @param references the field(s) that should be used to reference the related model
  * @returns a one-to-one relationship definition
  */
 export function hasOne<RM extends string>(
@@ -206,8 +224,29 @@ export function hasOne<RM extends string>(
 }
 
 /**
- * Create a one-directional one-to-many relationship between two models using the `hasMany()` method.
+ * Create a one-directional one-to-many relationship between two models using the `hasMany("MODEL_NAME", "REFERENCE_FIELD(s)")` method.
+ * @example
+ * const schema = a.schema({
+ *   Member: a.model({
+ *     name: a.string().required(),
+ *     // 1. Create a reference field
+ *     teamId: a.id(),
+ *     // 2. Create a belongsTo relationship with the reference field
+ *     team: a.belongsTo('Team', 'teamId'),
+ *   })
+ *   .authorization(allow => [allow.publicApiKey()]),
+ * 
+ *   Team: a.model({
+ *     mantra: a.string().required(),
+ *     // 3. Create a hasMany relationship with the reference field
+ *     //    from the `Member`s model.
+ *     members: a.hasMany('Member', 'teamId'),
+ *   })
+ *   .authorization(allow => [allow.publicApiKey()]),
+ * });
+ * @see {@link https://docs.amplify.aws/react/build-a-backend/data/data-modeling/relationships/#model-one-to-many-relationships}
  * @param relatedModel the name of the related model
+ * @param references the field(s) that should be used to reference the related model
  * @returns a one-to-many relationship definition
  */
 export function hasMany<RM extends string>(
@@ -226,10 +265,50 @@ export function hasMany<RM extends string>(
 }
 
 /**
- * Make a `hasOne()` or `hasMany()` relationship bi-directional using the `belongsTo()` method.
+ * Use `belongsTo()` to create a field to query the related `hasOne()` or `hasMany()` relationship.
  * The belongsTo() method requires that a hasOne() or hasMany() relationship already exists from
  * parent to the related model.
+ * 
+ * @example 
+ * // one-to-many relationship
+ * const schema = a.schema({
+ *   Member: a.model({
+ *     name: a.string().required(),
+ *     // 1. Create a reference field
+ *     teamId: a.id(),
+ *     // 2. Create a belongsTo relationship with the reference field
+ *     team: a.belongsTo('Team', 'teamId'),
+ *   })
+ *   .authorization(allow => [allow.publicApiKey()]),
+ * 
+ *   Team: a.model({
+ *     mantra: a.string().required(),
+ *     // 3. Create a hasMany relationship with the reference field
+ *     //    from the `Member`s model.
+ *     members: a.hasMany('Member', 'teamId'),
+ *   })
+ *   .authorization(allow => [allow.publicApiKey()]),
+ * });
+ * @example
+ * // one-to-one relationship
+ * const schema = a.schema({
+ *   Cart: a.model({
+ *     items: a.string().required().array(),
+ *     // 1. Create reference field
+ *     customerId: a.id(),
+ *     // 2. Create relationship field with the reference field
+ *     customer: a.belongsTo('Customer', 'customerId'),
+ *   }),
+ *   Customer: a.model({
+ *     name: a.string(),
+ *     // 3. Create relationship field with the reference field
+ *     //    from the Cart model
+ *     activeCart: a.hasOne('Cart', 'customerId')
+ *   }),
+ * });
+ * @see {@link https://docs.amplify.aws/react/build-a-backend/data/data-modeling/relationships/}
  * @param relatedModel name of the related `.hasOne()` or `.hasMany()` model
+ * @param references the field(s) that should be used to reference the related model
  * @returns a belong-to relationship definition
  */
 export function belongsTo<RM extends string>(

package/src/ModelSchema.ts

@@ -7,14 +7,13 @@ import type {
   UnionToIntersection,
 } from '@aws-amplify/data-schema-types';
 import {
-  type ModelType,
-  type ModelTypeParamShape,
   type InternalModel,
   isSchemaModelType,
   SchemaModelType,
   AddRelationshipFieldsToModelTypeFields,
+  type BaseModelType,
 } from './ModelType';
-import type { EnumType, EnumTypeParamShape } from './EnumType';
+import type { EnumType } from './EnumType';
 import type { CustomType, CustomTypeParamShape } from './CustomType';
 import type {
   CustomOperation,
@@ -41,9 +40,9 @@ const ddbSchemaBrand = brand(ddbSchemaBrandName);
 export type DDBSchemaBrand = Brand<typeof ddbSchemaBrandName>;
 
 type SchemaContent =
-  | ModelType<ModelTypeParamShape, any>
+  | BaseModelType
   | CustomType<CustomTypeParamShape>
-  | EnumType<EnumTypeParamShape>
+  | EnumType
   | CustomOperation<CustomOperationParamShape, any>;
 
 type NonEmpty<T> = keyof T extends never ? never : T;
@@ -76,10 +75,7 @@ export type BaseSchema<
 > = {
   data: T;
   models: {
-    [TypeKey in keyof T['types']]: T['types'][TypeKey] extends ModelType<
-      ModelTypeParamShape,
-      never | 'identifier'
-    >
+    [TypeKey in keyof T['types']]: T['types'][TypeKey] extends BaseModelType
       ? SchemaModelType<T['types'][TypeKey], TypeKey & string, IsRDS>
       : never;
   };
@@ -334,7 +330,7 @@ function _rdsSchema<
         models[newName] = currentType;
         data.types[newName] = currentType;
         models[newName].data.originalName = curName;
-        
+
         delete models[curName];
         delete data.types[curName];
       });
@@ -348,7 +344,7 @@ function _rdsSchema<
 function _ddbSchema<
   T extends ModelSchemaParamShape,
   DSC extends SchemaConfiguration<any, any>,
->(types: T['types'], config: DSC) {
+>(types: T['types'], config: DSC): ModelSchema<T> {
   const data: ModelSchemaParamShape = {
     types,
     authorization: [],
@@ -369,7 +365,7 @@ function _ddbSchema<
     },
     models: filterSchemaModelTypes(data.types),
     ...ddbSchemaBrand,
-  } as ModelSchema<T>;
+  } satisfies ModelSchema<any> as never;
 }
 
 type SchemaReturnType<

package/src/ModelType.ts

@@ -1,7 +1,7 @@
 import type { SetTypeSubArg } from '@aws-amplify/data-schema-types';
 import type { PrimaryIndexIrShape, SecondaryIndexIrShape } from './runtime';
-import { type Brand, brand } from './util';
-import type { ModelField, InternalField } from './ModelField';
+import { brand } from './util';
+import type { InternalField, BaseModelField } from './ModelField';
 import type {
   ModelRelationalField,
   InternalRelationalField,
@@ -9,7 +9,7 @@ import type {
 } from './ModelRelationalField';
 import { type AllowModifier, type Authorization, allow } from './Authorization';
 import type { RefType, RefTypeParamShape } from './RefType';
-import type { EnumType, EnumTypeParamShape } from './EnumType';
+import type { EnumType } from './EnumType';
 import type { CustomType, CustomTypeParamShape } from './CustomType';
 import {
   type ModelIndexType,
@@ -20,16 +20,18 @@ import type {
   PrimaryIndexFieldsToIR,
   SecondaryIndexToIR,
 } from './MappedTypes/MapIndexes';
+import type { brandSymbol } from './util/Brand.js';
+import type { methodKeyOf } from './util/usedMethods.js';
 
 const brandName = 'modelType';
 export type deferredRefResolvingPrefix = 'deferredRefResolving:';
 
 type ModelFields = Record<
   string,
-  | ModelField<any, any, any>
+  | BaseModelField
   | ModelRelationalField<any, string, any, any>
   | RefType<any, any, any>
-  | EnumType<EnumTypeParamShape>
+  | EnumType
   | CustomType<CustomTypeParamShape>
 >;
 
@@ -78,10 +80,8 @@ export type ExtractSecondaryIndexIRFields<
   T extends ModelTypeParamShape,
   RequiredOnly extends boolean = false,
 > = {
-  [FieldProp in keyof T['fields'] as T['fields'][FieldProp] extends ModelField<
-    infer R,
-    any,
-    any
+  [FieldProp in keyof T['fields'] as T['fields'][FieldProp] extends BaseModelField<
+    infer R
   >
     ? NonNullable<R> extends string | number
       ? RequiredOnly extends false
@@ -91,26 +91,22 @@ export type ExtractSecondaryIndexIRFields<
           : FieldProp
       : never
     : T['fields'][FieldProp] extends
-          | EnumType<EnumTypeParamShape>
+          | EnumType
           | RefType<RefTypeParamShape, any, any>
       ? FieldProp
-      : never]: T['fields'][FieldProp] extends ModelField<infer R, any, any>
+      : never]: T['fields'][FieldProp] extends BaseModelField<infer R>
     ? R
-    : T['fields'][FieldProp] extends EnumType<infer R>
-      ? R['values'][number]
+    : T['fields'][FieldProp] extends EnumType<infer values>
+      ? values[number]
       : T['fields'][FieldProp] extends RefType<infer R, any, any>
         ? `${deferredRefResolvingPrefix}${R['link']}`
         : never;
 };
 
 type ExtractType<T extends ModelTypeParamShape> = {
-  [FieldProp in keyof T['fields'] as T['fields'][FieldProp] extends ModelField<
-    any,
-    any,
-    any
-  >
+  [FieldProp in keyof T['fields'] as T['fields'][FieldProp] extends BaseModelField
     ? FieldProp
-    : never]: T['fields'][FieldProp] extends ModelField<infer R, any, any>
+    : never]: T['fields'][FieldProp] extends BaseModelField<infer R>
     ? R
     : never;
 };
@@ -197,11 +193,17 @@ export type AddRelationshipFieldsToModelTypeFields<
 type _ConflictingAuthRules<T extends ModelTypeParamShape> =
   ConflictingAuthRulesMap<T>[keyof ConflictingAuthRulesMap<T>];
 
+export type BaseModelType<T extends ModelTypeParamShape = ModelTypeParamShape> =
+  ModelType<T, UsableModelTypeKey>;
+
+export type UsableModelTypeKey = methodKeyOf<ModelType>;
+
 export type ModelType<
-  T extends ModelTypeParamShape,
-  K extends keyof ModelType<T> = never,
+  T extends ModelTypeParamShape = ModelTypeParamShape,
+  UsedMethod extends UsableModelTypeKey = never,
 > = Omit<
   {
+    [brandSymbol]: typeof brandName;
     identifier<
       PrimaryIndexFields = ExtractSecondaryIndexIRFields<T, true>,
       PrimaryIndexPool extends string = keyof PrimaryIndexFields & string,
@@ -214,7 +216,7 @@ export type ModelType<
       identifier: ID,
     ): ModelType<
       SetTypeSubArg<T, 'identifier', PrimaryIndexIR>,
-      K | 'identifier'
+      UsedMethod | 'identifier'
     >;
     secondaryIndexes<
       const SecondaryIndexFields = ExtractSecondaryIndexIRFields<T>,
@@ -243,7 +245,7 @@ export type ModelType<
       ) => Indexes,
     ): ModelType<
       SetTypeSubArg<T, 'secondaryIndexes', IndexesIR>,
-      K | 'secondaryIndexes'
+      UsedMethod | 'secondaryIndexes'
     >;
     authorization<AuthRuleType extends Authorization<any, any, any>>(
       callback: (
@@ -251,22 +253,18 @@ export type ModelType<
       ) => AuthRuleType | AuthRuleType[],
     ): ModelType<
       SetTypeSubArg<T, 'authorization', AuthRuleType[]>,
-      K | 'authorization'
+      UsedMethod | 'authorization'
     >;
   },
-  K
-> &
-  Brand<typeof brandName>;
+  UsedMethod
+>;
 
 /**
  * External representation of Model Type that exposes the `relationships` modifier.
  * Used on the complete schema object.
  */
 export type SchemaModelType<
-  T extends ModelType<ModelTypeParamShape, never | 'identifier'> = ModelType<
-    ModelTypeParamShape,
-    never | 'identifier'
-  >,
+  T extends BaseModelType = ModelType<ModelTypeParamShape, 'identifier'>,
   ModelName extends string = string,
   IsRDS extends boolean = false,
 > = IsRDS extends true
@@ -279,9 +277,7 @@ export type SchemaModelType<
       >(
         relationships: Param,
       ): Record<ModelName, Param>;
-      fields: T extends ModelType<infer R extends ModelTypeParamShape, any>
-        ? R['fields']
-        : never;
+      fields: T extends ModelType<infer R, any> ? R['fields'] : never;
     }
   : T;
 

package/src/RefType.ts

@@ -53,7 +53,7 @@ export type RefType<
       Exclude<K, 'required'> | 'array'
     >;
     /**
-     * Configures field-level authorization rules. Pass in an array of authorizations `(a.allow.____)` to mix and match
+     * Configures field-level authorization rules. Pass in an array of authorizations `(allow => allow.____)` to mix and match
      * multiple authorization rules for this field.
      */
     authorization<AuthRuleType extends Authorization<any, any, any>>(

package/src/SchemaProcessor.ts

@@ -3,10 +3,10 @@ import {
   type ModelField,
   type InternalField,
   string,
-  ModelFieldTypeParamOuter,
+  type BaseModelField,
 } from './ModelField';
 import { type InternalRelationalField } from './ModelRelationalField';
-import type { ModelType, InternalModel } from './ModelType';
+import type { InternalModel } from './ModelType';
 import type { InternalModelIndexType } from './ModelIndex';
 import {
   type Authorization,
@@ -25,11 +25,7 @@ import {
 } from '@aws-amplify/data-schema-types';
 import type { InternalRef, RefType } from './RefType';
 import type { EnumType } from './EnumType';
-import type {
-  CustomType,
-  CustomTypeAllowedModifiers,
-  CustomTypeParamShape,
-} from './CustomType';
+import type { CustomType, CustomTypeParamShape } from './CustomType';
 import { type InternalCustom, CustomOperationNames } from './CustomOperation';
 import { Brand, getBrand } from './util';
 import {
@@ -57,7 +53,7 @@ type CustomOperationFields = {
   subscriptions: string[];
 };
 
-function isInternalModel(model: ModelType<any, any>): model is InternalModel {
+function isInternalModel(model: unknown): model is InternalModel {
   if (
     (model as any).data &&
     !isCustomType(model) &&
@@ -68,9 +64,7 @@ function isInternalModel(model: ModelType<any, any>): model is InternalModel {
   return false;
 }
 
-function isEnumType(
-  data: any,
-): data is EnumType<{ type: 'enum'; values: string[] }> {
+function isEnumType(data: any): data is EnumType {
   if (data?.type === 'enum') {
     return true;
   }
@@ -120,13 +114,13 @@ function dataSourceIsRef(
 }
 
 function isScalarField(
-  field: ModelField<any, any>,
+  field: unknown,
 ): field is { data: ScalarFieldDef } & Brand<'modelField'> {
   return isScalarFieldDef((field as any)?.data);
 }
 
 function isRefField(
-  field: ModelField<any, any>,
+  field: unknown,
 ): field is { data: RefFieldDef } & Brand<'modelField'> {
   return isRefFieldDef((field as any)?.data);
 }
@@ -501,10 +495,7 @@ function escapeGraphQlString(str: string) {
  * @param right
  * @returns
  */
-function areConflicting(
-  left: ModelField<any, any>,
-  right: ModelField<any, any>,
-): boolean {
+function areConflicting(left: BaseModelField, right: BaseModelField): boolean {
   // These are the only props we care about for this comparison, because the others
   // (required, arrayRequired, etc) are not specified on auth or FK directives.
   const relevantProps = ['array', 'fieldType'] as const;
@@ -527,8 +518,8 @@ function areConflicting(
  * @param additions A field map to merge in
  */
 function addFields(
-  existing: Record<string, ModelField<any, any>>,
-  additions: Record<string, ModelField<any, any>>,
+  existing: Record<string, BaseModelField>,
+  additions: Record<string, BaseModelField>,
 ): void {
   for (const [k, addition] of Object.entries(additions)) {
     if (!existing[k]) {
@@ -550,8 +541,8 @@ function addFields(
  * @throws An error when an undefined field is used or when a field is used in a way that conflicts with its generated definition
  */
 function validateStaticFields(
-  existing: Record<string, ModelField<any, any>>,
-  implicitFields: Record<string, ModelField<any, any>> | undefined,
+  existing: Record<string, BaseModelField>,
+  implicitFields: Record<string, BaseModelField> | undefined,
 ) {
   if (implicitFields === undefined) {
     return;
@@ -574,8 +565,8 @@ function validateStaticFields(
  * @throws An error when an undefined field is used or when a field is used in a way that conflicts with its generated definition
  */
 function validateImpliedFields(
-  existing: Record<string, ModelField<any, any>>,
-  implicitFields: Record<string, ModelField<any, any>> | undefined,
+  existing: Record<string, BaseModelField>,
+  implicitFields: Record<string, BaseModelField> | undefined,
 ) {
   if (implicitFields === undefined) {
     return;
@@ -631,7 +622,7 @@ function validateRefUseCases(
  * @returns
  */
 function calculateAuth(authorization: Authorization<any, any, any>[]) {
-  const authFields: Record<string, ModelField<any, any>> = {};
+  const authFields: Record<string, BaseModelField> = {};
   const rules: string[] = [];
 
   for (const entry of authorization) {
@@ -799,8 +790,8 @@ function capitalize<T extends string>(s: T): Capitalize<T> {
 }
 
 function processFieldLevelAuthRules(
-  fields: Record<string, ModelField<any, any>>,
-  authFields: Record<string, ModelField<any, any>>,
+  fields: Record<string, BaseModelField>,
+  authFields: Record<string, BaseModelField>,
 ) {
   const fieldLevelAuthRules: {
     [k in keyof typeof fields]: string | null;
@@ -1203,16 +1194,8 @@ const schemaPreprocessor = (
 
         const fieldAuthApplicableFields = Object.fromEntries(
           Object.entries(fields).filter(
-            (
-              pair: [string, unknown],
-            ): pair is [
-              string,
-              ModelField<
-                ModelFieldTypeParamOuter,
-                CustomTypeAllowedModifiers,
-                any
-              >,
-            ] => isModelField(pair[1]),
+            (pair: [string, unknown]): pair is [string, BaseModelField] =>
+              isModelField(pair[1]),
           ),
         );
 
@@ -1296,7 +1279,7 @@ const schemaPreprocessor = (
     } else if (staticSchema) {
       const fields = { ...typeDef.data.fields } as Record<
         string,
-        ModelField<any, any>
+        BaseModelField
       >;
 
       validateRefUseCases(typeName, 'model', fields, getRefType);
@@ -1341,10 +1324,7 @@ const schemaPreprocessor = (
       const model = `type ${typeName} @model(timestamps: null) ${authString}${refersToString}\n{\n  ${joined}\n}`;
       gqlModels.push(model);
     } else {
-      const fields = typeDef.data.fields as Record<
-        string,
-        ModelField<any, any>
-      >;
+      const fields = typeDef.data.fields as Record<string, BaseModelField>;
 
       validateRefUseCases(typeName, 'model', fields, getRefType);
 

package/src/util/Brand.ts

@@ -1,4 +1,4 @@
-const brandSymbol = Symbol('brand');
+export const brandSymbol = Symbol('brand');
 
 /**
  * @typeParam BrandStr - String type to brand this object with

package/src/util/usedMethods.ts

@@ -0,0 +1,5 @@
+export type methodKeyOf<o> = {
+  [k in keyof o]-?: o[k] extends (...args: never) => unknown ? k : never;
+}[keyof o];
+
+export type satisfy<base, t extends base> = t;