@aws-amplify/data-schema 1.25.5 → 1.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-amplify/data-schema",
-  "version": "1.25.5",
+  "version": "1.26.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -65,7 +65,7 @@
     "rimraf": "^5.0.5",
     "rollup": "^4.59.0",
     "ts-jest": "^29.1.1",
-    "turbo": "^1.10.14",
+    "turbo": "^2.9.14",
     "typescript": "^5.1.6"
   },
   "files": [

package/src/ClientSchema/Core/ClientModel.ts

@@ -33,7 +33,7 @@ import type {
 
 export interface ClientModel<
   Bag extends Record<string, unknown>,
-  Metadata extends SchemaMetadata<any>,
+  Metadata extends SchemaMetadata<any, any>,
   IsRDS extends boolean,
   T extends ModelTypeParamShape,
   K extends keyof Bag & string,
@@ -92,7 +92,7 @@ type DisabledOpsToMap<Ops extends ReadonlyArray<DisableOperationsOptions>> = {
 
 type ClientFields<
   Bag extends Record<string, unknown>,
-  Metadata extends SchemaMetadata<any>,
+  Metadata extends SchemaMetadata<any, any>,
   IsRDS extends boolean,
   T extends ModelTypeParamShape,
 > = ResolveFields<Bag, T['fields']> &
@@ -102,11 +102,16 @@ type ClientFields<
 
 type FlatClientFields<
   Bag extends Record<string, unknown>,
-  Metadata extends SchemaMetadata<any>,
+  Metadata extends SchemaMetadata<any, any>,
   IsRDS extends boolean,
   T extends ModelTypeParamShape,
   ModelName extends keyof Bag & string,
-> = FlatResolveFields<Bag, T['fields'], ModelName> &
+> = FlatResolveFields<
+  Bag,
+  T['fields'],
+  ModelName,
+  Metadata['selectionSetDepth']
+> &
   If<Not<IsRDS>, ImplicitIdentifier<T>> &
   AuthFields<Metadata, T> &
   Omit<SystemFields<IsRDS>, keyof ResolveFields<Bag, T['fields']>>;
@@ -169,7 +174,7 @@ export type ListOptionsPkParams<
   : Prettify<Partial<IndexQueryInput<Bag, T['identifier']>>>;
 
 type AuthFields<
-  SchemaMeta extends SchemaMetadata<any>,
+  SchemaMeta extends SchemaMetadata<any, any>,
   Model extends ModelTypeParamShape,
 > = (Model['authorization'][number] extends never
   ? SchemaMeta['authFields'] extends never

package/src/ClientSchema/index.ts

@@ -1,6 +1,7 @@
 import type { __modelMeta__ } from '../runtime/client';
 import type {
   BaseSchema,
+  ClientSchemaOptions,
   ConversationType,
   CustomOperation,
   CustomType,
@@ -24,18 +25,22 @@ import type { SchemaMetadata } from './utilities/SchemaMetadata';
 import type { Brand, Select, SpreadTuple } from '../util';
 import { ClientConversation } from './ai/ClientConversation';
 
+export type { ClientSchemaOptions } from '../ModelSchema';
+
 export type ClientSchema<
   Schema extends GenericModelSchema<any> | CombinedModelSchema<any>,
+  Options extends ClientSchemaOptions = ClientSchemaOptions,
 > =
   Schema extends GenericModelSchema<any>
-    ? InternalClientSchema<Schema>
+    ? InternalClientSchema<Schema, Options>
     : Schema extends CombinedModelSchema<any>
-      ? InternalCombinedSchema<Schema>
+      ? InternalCombinedSchema<Schema, Options>
       : never;
 
 type InternalClientSchema<
   CustomerSchema extends ModelSchemaContents | BaseSchema<any, any>,
-  Metadata extends SchemaMetadata<any> = never,
+  Options extends ClientSchemaOptions = ClientSchemaOptions,
+  Metadata extends SchemaMetadata<any, any> = never,
   IsRDS extends boolean = never,
 > = CustomerSchema extends ModelSchemaContents
   ? {
@@ -48,14 +53,15 @@ type InternalClientSchema<
   : CustomerSchema extends BaseSchema<any, any>
     ? InternalClientSchema<
         CustomerSchema['data']['types'],
-        SchemaMetadata<CustomerSchema>,
+        Options,
+        SchemaMetadata<CustomerSchema, Options>,
         CustomerSchema extends Brand<'RDSSchema'> ? true : false
       >
     : never;
 
 type ClientSchemaProperty<
   T extends ModelSchemaContents,
-  Metadata extends SchemaMetadata<any>,
+  Metadata extends SchemaMetadata<any, any>,
   IsRDS extends boolean,
   K extends keyof T & string,
 > =
@@ -81,34 +87,34 @@ type RemapEnum<_T extends ModelSchemaContents, E> =
 
 type RemapCustomType<
   T extends ModelSchemaContents,
-  Metadata extends SchemaMetadata<any>,
+  Metadata extends SchemaMetadata<any, any>,
   IsRDS extends boolean,
   E,
 > =
   E extends CustomType<infer CT>
-    ? ClientCustomType<InternalClientSchema<T, Metadata, IsRDS>, CT>
+    ? ClientCustomType<InternalClientSchema<T, ClientSchemaOptions, Metadata, IsRDS>, CT>
     : never;
 
 type RemapCustomOperation<
   T extends ModelSchemaContents,
-  Metadata extends SchemaMetadata<any>,
+  Metadata extends SchemaMetadata<any, any>,
   IsRDS extends boolean,
   E,
 > =
   E extends CustomOperation<infer CO, any>
-    ? ClientCustomOperation<InternalClientSchema<T, Metadata, IsRDS>, CO>
+    ? ClientCustomOperation<InternalClientSchema<T, ClientSchemaOptions, Metadata, IsRDS>, CO>
     : never;
 
 type RemapModel<
   T extends ModelSchemaContents,
-  Metadata extends SchemaMetadata<any>,
+  Metadata extends SchemaMetadata<any, any>,
   IsRDS extends boolean,
   E,
   K extends keyof T & string,
 > =
   E extends ModelType<infer MT, any>
     ? ClientModel<
-        InternalClientSchema<T, Metadata, IsRDS>,
+        InternalClientSchema<T, ClientSchemaOptions, Metadata, IsRDS>,
         Metadata,
         IsRDS,
         MT,
@@ -121,14 +127,19 @@ type RemapAIRoute<
   E,
 > = E extends ConversationType ? ClientConversation : never;
 
-type GetInternalClientSchema<Schema> =
-  Schema extends GenericModelSchema<any> ? InternalClientSchema<Schema> : never;
+type GetInternalClientSchema<
+  Schema,
+  Options extends ClientSchemaOptions = ClientSchemaOptions,
+> = Schema extends GenericModelSchema<any>
+  ? InternalClientSchema<Schema, Options>
+  : never;
 
 type CombinedClientSchemas<
   Schemas extends CombinedModelSchema<any>['schemas'],
+  Options extends ClientSchemaOptions = ClientSchemaOptions,
 > = {
   [Index in keyof Schemas]: Index extends CombinedSchemaIndexesUnion
-    ? GetInternalClientSchema<Schemas[Index]>
+    ? GetInternalClientSchema<Schemas[Index], Options>
     : never;
 };
 
@@ -142,7 +153,8 @@ type CombinedClientSchemas<
  */
 type InternalCombinedSchema<
   Combined extends CombinedModelSchema<any>,
-  ClientSchemas extends [...any] = CombinedClientSchemas<Combined['schemas']>,
+  Options extends ClientSchemaOptions = ClientSchemaOptions,
+  ClientSchemas extends [...any] = CombinedClientSchemas<Combined['schemas'], Options>,
 > = SpreadTuple<{
   [I in keyof ClientSchemas]: I extends CombinedSchemaIndexesUnion
     ? Omit<ClientSchemas[I], typeof __modelMeta__>

package/src/ClientSchema/utilities/ResolveField.ts

@@ -8,6 +8,7 @@ import { CustomType } from '../../CustomType';
 import { RefType, RefTypeParamShape } from '../../RefType';
 import { ResolveRef } from './ResolveRef';
 import { LazyLoader } from '../../runtime';
+import type { DefaultSelectionSetDepth } from '../../ModelSchema';
 import type { ModelTypeParamShape } from '../../ModelType';
 
 type ExtendsNever<T> = [T] extends [never] ? true : false;
@@ -37,8 +38,9 @@ export type FlatResolveFields<
   Bag extends Record<string, any>,
   T,
   FlatModelName extends keyof Bag & string = never,
+  Depth extends number = DefaultSelectionSetDepth,
 > = ShallowPretty<{
-  [K in keyof T]: ResolveIndividualField<Bag, T[K], FlatModelName>;
+  [K in keyof T]: ResolveIndividualField<Bag, T[K], FlatModelName, Depth>;
 }>;
 
 // TODO: Remove ShallowPretty from this layer of resolution. Re-incorporate prettification
@@ -53,13 +55,14 @@ export type ResolveIndividualField<
   Bag extends Record<string, any>,
   T,
   FlatModelName extends keyof Bag & string = never,
+  Depth extends number = DefaultSelectionSetDepth,
 > =
   T extends BaseModelField<infer FieldShape>
     ? FieldShape
     : T extends RefType<infer RefShape, any, any>
       ? ResolveRef<RefShape, Bag>
       : T extends ModelRelationshipField<infer RelationshipShape, any, any, any>
-        ? ResolveRelationship<Bag, RelationshipShape, FlatModelName>
+        ? ResolveRelationship<Bag, RelationshipShape, FlatModelName, Depth>
         : T extends CustomType<infer CT>
           ? ResolveFields<Bag, CT['fields']> | null
           : T extends EnumType<infer values>
@@ -112,34 +115,109 @@ type ShortCircuitBiDirectionalRelationship<
     : Field]: Model[Field];
 };
 
+/** Subtract 1 from a depth counter, bounded at 0. Outside 0–5 falls through to 0. */
+type Decrement<N extends number> =
+  N extends 5 ? 4
+  : N extends 4 ? 3
+  : N extends 3 ? 2
+  : N extends 2 ? 1
+  : N extends 1 ? 0
+  : 0;
+
+/**
+ * Replaces each relationship field on the inlined related-model `type` with the
+ * related model's `type` recursively flattened, decrementing `Depth` per hop.
+ * At `Depth=0`, strips relationships entirely so ModelPathInner can't recurse
+ * into a LazyLoader leaf and the cascade terminates.
+ */
+type FlattenRelationships<
+  Bag extends Record<string, any>,
+  Model extends Record<string, any>,
+  RawFields extends Record<string, any>,
+  Depth extends number = DefaultSelectionSetDepth,
+> = Depth extends 0
+  ? OmitRelationships<Model, RawFields>
+  : {
+      [K in keyof Model]: K extends keyof RawFields
+        ? RawFields[K] extends ModelRelationshipField<infer RS, any, any, any>
+          ? RS['array'] extends true
+            ? Array<
+                FlattenRelationships<
+                  Bag,
+                  Bag[RS['relatedModel']]['type'],
+                  Bag[RS['relatedModel']]['__meta']['rawType']['fields'],
+                  Decrement<Depth>
+                >
+              >
+            : FlattenRelationships<
+                Bag,
+                Bag[RS['relatedModel']]['type'],
+                Bag[RS['relatedModel']]['__meta']['rawType']['fields'],
+                Decrement<Depth>
+              >
+          : Model[K]
+        : Model[K];
+    };
+
+/** Terminal case at the depth boundary: drop relationships entirely. */
+type OmitRelationships<
+  Model extends Record<string, any>,
+  RawFields extends Record<string, any>,
+> = {
+  [K in keyof Model as K extends keyof RawFields
+    ? RawFields[K] extends ModelRelationshipField<any, any, any, any>
+      ? never
+      : K
+    : K]: Model[K];
+};
+
+/** Shared `LazyLoader` shape used by the non-flat branch and the depth=0 short-circuit. */
+type LazyLoaderForRelationship<
+  Bag extends Record<string, any>,
+  RelationshipShape extends ModelRelationshipFieldParamShape,
+> = DependentLazyLoaderOpIsAvailable<Bag, RelationshipShape> extends true
+  ? LazyLoader<
+      RelationshipShape['valueRequired'] extends true
+        ? Bag[RelationshipShape['relatedModel']]['type']
+        : Bag[RelationshipShape['relatedModel']]['type'] | null,
+      RelationshipShape['array']
+    >
+  : never;
+
 type ResolveRelationship<
   Bag extends Record<string, any>,
   RelationshipShape extends ModelRelationshipFieldParamShape,
   ParentModelName extends keyof Bag & string = never,
+  Depth extends number = DefaultSelectionSetDepth,
 > =
   ExtendsNever<ParentModelName> extends true
-    ? DependentLazyLoaderOpIsAvailable<Bag, RelationshipShape> extends true
-      ? LazyLoader<
-          RelationshipShape['valueRequired'] extends true
-            ? Bag[RelationshipShape['relatedModel']]['type']
-            : Bag[RelationshipShape['relatedModel']]['type'] | null,
-          RelationshipShape['array']
-        >
-      : never
-    : // Array-ing inline here vs. (inside of ShortCircuitBiDirectionalRelationship or in a separate conditional type) is significantly more performant
-      RelationshipShape['array'] extends true
-      ? Array<
-          ShortCircuitBiDirectionalRelationship<
-            Bag[RelationshipShape['relatedModel']]['__meta']['flatModel'],
+    ? LazyLoaderForRelationship<Bag, RelationshipShape>
+    : Depth extends 0
+      ? LazyLoaderForRelationship<Bag, RelationshipShape>
+      : // Array-ing inline here vs. (inside of ShortCircuitBiDirectionalRelationship or in a separate conditional type) is significantly more performant
+        RelationshipShape['array'] extends true
+        ? Array<
+            ShortCircuitBiDirectionalRelationship<
+              FlattenRelationships<
+                Bag,
+                Bag[RelationshipShape['relatedModel']]['type'],
+                Bag[RelationshipShape['relatedModel']]['__meta']['rawType']['fields'],
+                Decrement<Depth>
+              >,
+              ParentModelName,
+              Bag[RelationshipShape['relatedModel']]['__meta']['rawType']['fields']
+            >
+          >
+        : ShortCircuitBiDirectionalRelationship<
+            FlattenRelationships<
+              Bag,
+              Bag[RelationshipShape['relatedModel']]['type'],
+              Bag[RelationshipShape['relatedModel']]['__meta']['rawType']['fields'],
+              Decrement<Depth>
+            >,
             ParentModelName,
             Bag[RelationshipShape['relatedModel']]['__meta']['rawType']['fields']
-          >
-        >
-      : ShortCircuitBiDirectionalRelationship<
-          Bag[RelationshipShape['relatedModel']]['__meta']['flatModel'],
-          ParentModelName,
-          Bag[RelationshipShape['relatedModel']]['__meta']['rawType']['fields']
-        >;
+          >;
 
 type DependentLazyLoaderOpIsAvailable<
   Bag extends Record<string, any>,

package/src/ClientSchema/utilities/SchemaMetadata.ts

@@ -1,8 +1,22 @@
-import { ImpliedAuthFields } from '../../Authorization';
-import { BaseSchema } from '../../ModelSchema';
+import type { ImpliedAuthFields } from '../../Authorization';
+import type {
+  BaseSchema,
+  ClientSchemaOptions,
+  DefaultSelectionSetDepth,
+  SelectionSetDepthValue,
+} from '../../ModelSchema';
 
-export interface SchemaMetadata<Schema extends BaseSchema<any, any>> {
+export interface SchemaMetadata<
+  Schema extends BaseSchema<any, any>,
+  Options extends ClientSchemaOptions = ClientSchemaOptions,
+> {
   authFields: AuthFields<Schema>;
+  // Non-distributive `[T] extends [U]` so a default `Options = ClientSchemaOptions`
+  // (where selectionSetDepth is optional, type `... | undefined`) falls through
+  // to the default rather than producing a union with undefined.
+  selectionSetDepth: [Options['selectionSetDepth']] extends [SelectionSetDepthValue]
+    ? Options['selectionSetDepth']
+    : DefaultSelectionSetDepth;
 }
 
 type AuthFields<Schema extends Record<string, any>> =

package/src/ModelSchema.ts

@@ -59,6 +59,15 @@ type AddToSchemaContents = Record<string, AddToSchemaContent>;
 
 type NonEmpty<T> = keyof T extends never ? never : T;
 
+export type SelectionSetDepthValue = 0 | 1 | 2 | 3 | 4 | 5;
+
+/** Default depth applied when ClientSchema is used without an explicit Options arg. */
+export type DefaultSelectionSetDepth = 5;
+
+export type ClientSchemaOptions = {
+  selectionSetDepth?: SelectionSetDepthValue;
+};
+
 export type ModelSchemaContents = Record<string, SchemaContent>;
 
 type InternalSchemaModels = Record<
@@ -258,9 +267,8 @@ type ModelWithRelationships<
     Record<string, RelationshipTemplate | undefined>
   >,
   ModelName extends keyof Types,
-  RelationshipMap extends UnionToIntersection<
-    Relationships[number]
-  > = UnionToIntersection<Relationships[number]>,
+  RelationshipMap extends UnionToIntersection<Relationships[number]> =
+    UnionToIntersection<Relationships[number]>,
 > = ModelName extends keyof RelationshipMap
   ? RelationshipMap[ModelName] extends Record<
       string,

package/src/util/Filters.ts

@@ -142,5 +142,11 @@ export type ModelPrimaryCompositeKeyInput<
   ge?: SkIr;
   gt?: SkIr;
   between?: [SkIr, SkIr];
-  beginsWith?: SkIr;
+  // `beginsWith` accepts a partial because the underlying AppSync VTL builds
+  // the `begins_with` prefix by skipping null fields. Requiring all fields
+  // (as the other operators do) forces callers to pass empty strings for
+  // trailing fields, which the VTL then appends as `#` delimiters — yielding
+  // a malformed prefix on 3+ field composite sort keys. Allowing partial
+  // input lets callers express "all rows under this leading prefix".
+  beginsWith?: Partial<SkIr>;
 };