@aws-amplify/data-schema 0.15.0 → 0.16.0

package/src/MappedTypes/CustomOperations.ts

@@ -0,0 +1,256 @@
+import type { GenericModelSchema } from '../ModelSchema';
+import type { NonModelTypesShape } from './ExtractNonModelTypes';
+import type {
+  CustomOperation,
+  CustomOperationParamShape,
+} from '../CustomOperation';
+import type { ModelField } from '../ModelField';
+import type { RefType, RefTypeParamShape } from '../RefType';
+import type {
+  ResolveCustomTypeFieldsRequirements,
+  ResolveRefsOfCustomType,
+  ResolveRefValueArrayTraits,
+} from './ResolveFieldProperties';
+import type { AppSyncResolverHandler } from 'aws-lambda';
+import type { CustomType } from '../CustomType';
+import type { FieldTypesOfCustomType } from './ResolveSchema';
+
+/**
+ * Creates meta types for custom operations from a schema.
+ */
+export type ResolveCustomOperations<
+  Schema extends GenericModelSchema<any>,
+  FullyResolvedSchema extends Record<string, unknown>,
+  NonModelTypes extends NonModelTypesShape,
+  CustomOperations extends Record<
+    string,
+    CustomOperationParamShape
+  > = CustomOpShapes<Schema>,
+> = {
+  customOperations: {
+    [OpName in keyof CustomOperations]: {
+      arguments: CustomOpArguments<CustomOperations[OpName]>;
+      returnType: CustomOpReturnType<
+        CustomOperations[OpName],
+        FullyResolvedSchema,
+        NonModelTypes,
+        CustomOperations
+      >;
+      functionRef: CustomOperations[OpName]['functionRef'];
+      typeName: CustomOperations[OpName]['typeName'];
+      authorization: CustomOperations[OpName]['authorization'];
+    };
+  };
+};
+
+/**
+ * Filtered, mapped list of custom operations shapes from a schema.
+ */
+export type CustomOpShapes<Schema extends GenericModelSchema<any>> = {
+  [K in keyof Schema['data']['types'] as Schema['data']['types'][K] extends CustomOperation<
+    any,
+    any
+  >
+    ? K
+    : never]: Schema['data']['types'][K] extends CustomOperation<
+    infer Shape,
+    any
+  >
+    ? Shape
+    : never;
+};
+
+/**
+ * Digs out custom operation arguments, mapped to the intended graphql types.
+ */
+export type CustomOpArguments<Shape extends CustomOperationParamShape> =
+  Shape['arguments'] extends null
+    ? never
+    : {
+        [FieldName in keyof Shape['arguments']]: Shape['arguments'][FieldName] extends ModelField<
+          infer R,
+          any,
+          any
+        >
+          ? R
+          : never;
+      };
+
+/**
+ * Computes the return type from the `returnType` of a custom operation shape.
+ *
+ * This entails dereferencing refs and inferring graphql types from field-type defs.
+ */
+export type CustomOpReturnType<
+  Shape extends CustomOperationParamShape,
+  FullyResolvedSchema extends Record<string, unknown>,
+  NonModelTypes extends NonModelTypesShape,
+  CustomOperations extends Record<string, CustomOperationParamShape>,
+> =
+  Shape['returnType'] extends RefType<infer RefShape, any, any>
+    ? RefShape['link'] extends keyof CustomOperations
+      ? // The case that a custom subscription's return type is set from its resource
+        CustomOpReturnType<
+          CustomOperations[RefShape['link']],
+          FullyResolvedSchema,
+          NonModelTypes,
+          CustomOperations
+        >
+      : ResolveRef<
+          RefShape,
+          FullyResolvedSchema,
+          NonModelTypes,
+          CustomOperations
+        >
+    : Shape['returnType'] extends ModelField<infer R, any, any>
+      ? R
+      : Shape['returnType'] extends CustomType<infer R>
+        ?
+            | ResolveCustomTypeFieldsRequirements<
+                FieldTypesOfCustomType<{
+                  thisCustomType: R['fields'];
+                }>['thisCustomType']
+              > // The inline `.customType()` with a custom operation doesn't have
+              // `.required()` modifier, hence it's nullable
+            | null
+        : never;
+
+/**
+ * `a.ref()` resolution specific to custom operations, for which `a.ref()`
+ * can refer to a model, custom type, or enum.
+ *
+ * This utility is a duplication of ResolveRef (src/MappedTypes/ResolveFieldProperties.ts)
+ * with the addition that allows .ref() a model with custom operations.
+ */
+export type ResolveRef<
+  Shape extends RefTypeParamShape,
+  FullyResolvedSchema extends Record<string, unknown>,
+  NonModelTypes extends NonModelTypesShape,
+  CustomOperations extends Record<string, CustomOperationParamShape>,
+  Link = Shape['link'],
+  RefValue = Link extends keyof FullyResolvedSchema
+    ? FullyResolvedSchema[Link]
+    : Link extends keyof NonModelTypes['enums']
+      ? NonModelTypes['enums'][Link]
+      : Link extends keyof NonModelTypes['customTypes']
+        ? ResolveRefsOfCustomType<
+            NonModelTypes,
+            NonModelTypes['customTypes'][Link]
+          >
+        : Link extends keyof CustomOperations
+          ? // e.g. .subscription().for(a.ref('aCustomMutation'))
+            CustomOpReturnType<
+              CustomOperations[Link],
+              FullyResolvedSchema,
+              NonModelTypes,
+              CustomOperations
+            >
+          : never,
+  Value = Shape['valueRequired'] extends true ? RefValue : RefValue | null,
+> = ResolveRefValueArrayTraits<Shape, Value>;
+
+//
+// To support exposing custom handler types.
+//
+
+/**
+ * The kind of shape we need to map to custom handler (e.g., lambda) function
+ * signatures.
+ */
+type CustomOperationsMap = Record<string, CustomOperationMinimalDef>;
+
+/**
+ * The minimal amount of structure needed to extract types for a custom handler.
+ */
+type CustomOperationMinimalDef = {
+  arguments: any;
+  returnType: any;
+};
+
+/**
+ * Derives the signature and types for a lambda handler for a particular
+ * custom Query or Mutation from a Schema.
+ */
+type IndividualCustomHandlerTypes<Op extends CustomOperationMinimalDef> = {
+  /**
+   * Handler type for lambda function implementations. E.g.,
+   *
+   * ```typescript
+   * import type { Schema } from './resource';
+   *
+   * export const handler: Schema['echo']['functionHandler'] = async (event, context) => {
+   *  // event and context will be fully typed inside here.
+   * }
+   * ```
+   */
+  functionHandler: AppSyncResolverHandler<
+    Op['arguments'],
+    LambdaReturnType<Op['returnType']>
+  >;
+
+  /**
+   * The `context.arguments` type for lambda function implementations.
+   *
+   * ```typescript
+   * import type { Schema } from './resource';
+   *
+   * export const handler: Schema['echo']['functionHandler'] = async (event, context) => {
+   *  // Provides this type, if needed:
+   *  const args: Schema['echo']['functionHandlerArguments'] = event.arguments;
+   * }
+   * ```
+   */
+  functionHandlerArguments: Op['arguments'];
+
+  /**
+   * The return type expected by a lambda function handler.
+   *
+   * ```typescript
+   * import type { Schema } from './resource';
+   *
+   * export const handler: Schema['echo']['functionHandler'] = async (event, context) => {
+   *  // Result type enforced here:
+   *  const result: Schema['echo']['functionHandlerResult'] = buildResult(...);
+   *
+   *  // `Result` type matches expected function return type here:
+   *  return result;
+   * }
+   * ```
+   */
+  functionHandlerResult: LambdaReturnType<Op['returnType']>;
+};
+
+/**
+ * Derives the function signatures for a lambda handlers for all the provided
+ * custom queries and mutations.
+ */
+export type CustomOperationHandlerTypes<
+  CustomOperations extends CustomOperationsMap,
+> = {
+  [K in keyof CustomOperations]: IndividualCustomHandlerTypes<
+    CustomOperations[K]
+  >;
+};
+
+/**
+ * Returns a return type with lazy loaders removed.
+ *
+ * (Custom handlers should not return lazy loaded fields -- they're *lazy loaded*.)
+ */
+type LambdaReturnType<T> = T extends Record<string, any>
+  ? {
+      // Return type can include `null | undefined`, which we can't meaningfully
+      // map over.
+      [K in keyof Exclude<T, null | undefined> as Exclude<
+        T,
+        null | undefined
+      >[K] extends (...args: any) => any
+        ? never
+        : K]: Exclude<T, null | undefined>[K];
+    }
+  :
+      | T
+      // If the original return type allowed null | undefined, mix them back into
+      // the final return type
+      | (null extends T ? null : never)
+      | (undefined extends T ? undefined : never);

package/src/MappedTypes/ExtractNonModelTypes.ts

@@ -0,0 +1,154 @@
+import type { UnionToIntersection } from '@aws-amplify/data-schema-types';
+import type { CustomType, CustomTypeParamShape } from '../CustomType';
+import type { EnumType, EnumTypeParamShape } from '../EnumType';
+import type {
+  SchemaTypes,
+  ModelAndCustomTypes,
+  FieldTypesOfCustomType,
+} from './ResolveSchema';
+import type { ModelType, ModelTypeParamShape } from '../ModelType';
+
+export type NonModelTypesShape = {
+  enums: Record<string, EnumType<any>>;
+  customTypes: Record<string, any>;
+};
+
+export type ExtractNonModelTypes<Schema> = ResolveNonModelFields<
+  ResolveNonModelTypes<Schema, ExtractImplicitNonModelTypes<Schema>>
+>;
+
+/**
+ * Extract all implicit non-model types a `FieldName: Field` map recursively,
+ * and store them in a flat map. The keys are serialized property path.
+ *
+ * For example, with the following schema structure:
+ * ```
+ * ExtractAndFlattenImplicitNonModelTypesFromFields<
+ *   'Post',
+ *   {
+ *     content: string,
+ *     status: enum(['reviewing'], ['published']),
+ *     meta: customType({
+ *       tag: enum(['internal', 'external']),
+ *       views: number
+ *     }),
+ *     tag: ref('SomeExplicitEnum'),
+ *   }
+ * >
+ * ```
+ * It generates the result as:
+ * ```
+ * {
+ *   PostStatus: enum(['reviewing'], ['published']),
+ *   PostMeta: customType({
+ *     tag: enum(['internal', 'external']),
+ *     views: number
+ *   }),
+ *   PostMetaTag: enum(['internal', 'external']),
+ * }
+ * ```
+ */
+export type ExtractAndFlattenImplicitNonModelTypesFromFields<
+  ParentTypeName extends string,
+  Fields,
+> = {
+  // loop through the fields - omit the field that's not a non-model type
+  [FieldProp in keyof Fields as Fields[FieldProp] extends
+    | EnumType<EnumTypeParamShape>
+    | CustomType<CustomTypeParamShape>
+    ? FieldProp
+    : never]: (
+    x: NonNullable<Fields[FieldProp]> extends infer FieldType
+      ? // if the filed is a enum extract it as is
+        FieldType extends EnumType<EnumTypeParamShape>
+        ? {
+            [Key in `${ParentTypeName}${Capitalize<
+              FieldProp & string
+            >}`]: Fields[FieldProp];
+          }
+        : // if the field is a CustomType
+          FieldType extends CustomType<
+              infer CustomTypeShape extends CustomTypeParamShape
+            >
+          ? // recursively extract to the Nested CustomType, and return the
+            // merge of the current CustomType and the extracted (if any)
+            ExtractAndFlattenImplicitNonModelTypesFromFields<
+              `${ParentTypeName}${Capitalize<FieldProp & string>}`,
+              CustomTypeShape['fields']
+            > & {
+              [Key in `${ParentTypeName}${Capitalize<
+                FieldProp & string
+              >}`]: Fields[FieldProp];
+            }
+          : never
+      : never,
+  ) => void;
+} extends Record<string, infer Func>
+  ? Func extends (x: infer P) => void
+    ? P // extract the union of all types of the `x` param used above
+    : Record<never, never> // return an empty mapped object (nothing got extracted)
+  : Record<never, never>; // return an empty mapped object (nothing got extracted)
+
+/**
+ * Pulls out implicit, i.e. field-level non-model types from `ModelType` and
+ * `CustomType` which may contain deeply nested implicit (inline) non-model
+ * types.
+ */
+export type ExtractImplicitNonModelTypes<
+  Schema,
+  Targets = ModelAndCustomTypes<SchemaTypes<Schema>>,
+> = UnionToIntersection<
+  {
+    [Model in keyof Targets]: Targets[Model] extends CustomType<
+      // if the target is a CustomType
+      infer R extends CustomTypeParamShape
+    >
+      ? // extract nested non-model types from it, and include itself
+        ExtractAndFlattenImplicitNonModelTypesFromFields<
+          Capitalize<Model & string>,
+          R['fields']
+        > & { [key in Model]: Targets[Model] }
+      : // if the target is a ModelType
+        Targets[Model] extends ModelType<
+            infer R extends ModelTypeParamShape,
+            any
+          >
+        ? // extract nested non-model types from it
+          ExtractAndFlattenImplicitNonModelTypesFromFields<
+            Capitalize<Model & string>,
+            R['fields']
+          >
+        : // otherwise, do nothing
+          Targets[Model];
+  }[keyof Targets]
+>;
+
+type ResolveNonModelTypes<
+  Schema,
+  Extracted,
+  ResolvedSchema = SchemaTypes<Schema> & Extracted,
+> = {
+  enums: {
+    [Model in keyof ResolvedSchema as ResolvedSchema[Model] extends EnumType<EnumTypeParamShape>
+      ? Model
+      : never]: ResolvedSchema[Model] extends EnumType<
+      infer R extends EnumTypeParamShape
+    >
+      ? R['values'][number]
+      : never;
+  };
+  customTypes: {
+    [Model in keyof ResolvedSchema as ResolvedSchema[Model] extends CustomType<CustomTypeParamShape>
+      ? Model
+      : never]: ResolvedSchema[Model] extends CustomType<
+      infer R extends CustomTypeParamShape
+    >
+      ? R['fields']
+      : never;
+  };
+};
+
+type ResolveNonModelFields<T extends NonModelTypesShape> = {
+  enums: T['enums'];
+  customTypes: FieldTypesOfCustomType<T['customTypes']>;
+};

package/src/MappedTypes/ImplicitFieldInjector.ts

@@ -0,0 +1,69 @@
+type DefaultIdentifierFields = {
+  // implicit `id` is readonly because it's managed by the resolver; explicit `id` is writable
+  readonly id: string;
+};
+
+type DefaultTimestampFields = {
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+type InitialImplicitFields<Identifier> = Identifier extends 'id'
+  ? DefaultIdentifierFields & DefaultTimestampFields
+  : DefaultTimestampFields;
+
+/**
+ * @returns true if a string union `ExplicitFieldNames` contains a given string `FieldName`
+ */
+type FieldExists<
+  ExplicitFieldNames extends string,
+  FieldName extends string,
+> = Extract<ExplicitFieldNames, FieldName> extends never ? false : true;
+
+/**
+ * @returns union of explicitly defined field names for a model
+ */
+type GetModelFieldNames<FlatModel> = FlatModel extends Record<infer R, any>
+  ? R
+  : never;
+
+/**
+ * Generate Record type containing all implicit fields for a given model
+ */
+type ImplicitFields<
+  FlatModel,
+  Identifier,
+  ModelFieldNames = GetModelFieldNames<FlatModel>,
+> = {
+  [ImplicitField in keyof InitialImplicitFields<Identifier> as FieldExists<
+    ModelFieldNames & string,
+    ImplicitField & string
+  > extends true
+    ? never
+    : ImplicitField]: InitialImplicitFields<Identifier>[ImplicitField];
+};
+
+/**
+ * @returns intersection of explicit and implicit model fields
+ */
+type InjectDefaultFieldsForModel<FlatModel, ModelIdentifier> = FlatModel &
+  ImplicitFields<
+    FlatModel,
+    'identifier' extends keyof ModelIdentifier
+      ? ModelIdentifier['identifier']
+      : never
+  >;
+
+/**
+ * Mapped type that injects default implicit fields for a model
+ * 1. Add "id" field to models with neither an explicit field named "id" nor a custom identifier (`.identifier(['some-field'])`)
+ * 2. Add default timestamp fields ("createdAt", "updatedAt") unless they're already explicitly defined
+ *
+ * @typeParam FlattenedSchema - resolved schema type (TODO: add detail/example/link to type)
+ */
+export type InjectImplicitModelFields<FlattenedSchema, IdentifierMeta> = {
+  [ModelName in keyof FlattenedSchema]: InjectDefaultFieldsForModel<
+    FlattenedSchema[ModelName],
+    ModelName extends keyof IdentifierMeta ? IdentifierMeta[ModelName] : object
+  >;
+};

package/src/MappedTypes/MapSecondaryIndexes.ts

@@ -0,0 +1,100 @@
+import { IsEmptyStringOrNever } from '@aws-amplify/data-schema-types';
+import { ModelIndexType } from '../ModelIndex';
+
+type ModelIndexTypeShape = ModelIndexType<any, any, any, any, any>;
+
+/**
+ * Maps array of ModelIndexType to SecondaryIndexIrShape (defined in in data-schema-types)
+ * */
+export type SecondaryIndexToIR<
+  Idxs extends ReadonlyArray<ModelIndexTypeShape>,
+  ResolvedFields,
+  Result extends readonly any[] = readonly [],
+> = Idxs extends readonly [
+  infer First extends ModelIndexTypeShape,
+  ...infer Rest extends ReadonlyArray<ModelIndexTypeShape>,
+]
+  ? SecondaryIndexToIR<
+      Rest,
+      ResolvedFields,
+      [...Result, SingleIndexIrFromType<First, ResolvedFields>]
+    >
+  : Result;
+
+/**
+ * @typeParam Idx - accepts a single ModelIndexType
+ * @typeParam ResolvedFields - resolved model fields
+ *
+ * @returns an IR with the following shape:
+ * {
+ *   queryField: string;
+ *   pk: { [fieldName: string]: string | number }
+ *   sk: { [fieldName: string]: string | number } | never
+ * }
+ *
+ * @remarks - the IR type alias is defined as SecondaryIndexIrShape in data-schema-types
+ */
+type SingleIndexIrFromType<
+  Idx extends ModelIndexTypeShape,
+  ResolvedFields,
+> = Idx extends ModelIndexType<
+  any,
+  infer PK extends string,
+  infer SK,
+  infer QueryField extends string | never,
+  any
+>
+  ? {
+      queryField: IsEmptyStringOrNever<QueryField> extends true
+        ? `listBy${QueryFieldLabelFromTuple<SK, Capitalize<PK>>}`
+        : QueryField;
+      pk: PK extends keyof ResolvedFields
+        ? {
+            [Key in PK]: Exclude<ResolvedFields[PK], null>;
+          }
+        : never;
+      // distribute ResolvedFields over SK
+      sk: unknown extends SK
+        ? never
+        : ResolvedSortKeyFields<SK, ResolvedFields>;
+    }
+  : never;
+
+/**
+ * @typeParam SK - tuple of SortKey field names, e.g. ['viewCount', 'createdAt']
+ * @typeParam StrStart - initial string value; expects capitalized Partition Key field name
+ *
+ * @returns Query field name: concatenated PascalCase string with an `And` separator
+ * @example
+ * QueryFieldLabelFromTuple<['viewCount', 'createdAt'], 'Title'> => 'TitleAndViewCountAndCreatedAt'
+ */
+type QueryFieldLabelFromTuple<
+  SK,
+  StrStart extends string = '',
+> = SK extends readonly [infer A extends string, ...infer B extends string[]]
+  ? QueryFieldLabelFromTuple<B, `${StrStart}And${Capitalize<A>}`>
+  : StrStart;
+
+/**
+ * @typeParam SK - tuple of SortKey field names, e.g. ['viewCount', 'createdAt']
+ * @typeParam ResolvedFields - resolved model fields
+ *
+ * @returns object type where the key is the sort key field name and the value is the resolved model field type
+ * @example
+ * {
+ *   viewCount: number;
+ *   createdAt: string;
+ * }
+ */
+type ResolvedSortKeyFields<SK, ResolvedFields> = SK extends readonly [
+  infer A extends string,
+  ...infer B extends string[],
+]
+  ? A extends keyof ResolvedFields
+    ? {
+        [Key in A]: Exclude<ResolvedFields[A], null>;
+      } & (B extends readonly never[]
+        ? unknown // returning `unknown` for empty arrays because it gets absorbed in an intersection, e.g. `{a: 1} & unknown` => `{a: 1}`
+        : ResolvedSortKeyFields<B, ResolvedFields>)
+    : never
+  : never;

package/src/MappedTypes/ModelMetadata.ts

@@ -0,0 +1,87 @@
+import {
+  type UnionToIntersection,
+  type ExcludeEmpty,
+} from '@aws-amplify/data-schema-types';
+import { __modelMeta__ } from '../runtime/client';
+import type { ModelType } from '../ModelType';
+import type { ModelRelationalFieldParamShape } from '../ModelRelationalField';
+
+export type ModelIdentifier<T> = {
+  [Property in keyof T]: T[Property] extends ModelType<infer R, any>
+    ? // reduce back to union
+      R['identifier'] extends any[]
+      ? { identifier: R['identifier'][number] }
+      : never
+    : never;
+};
+
+export type ModelSecondaryIndexes<T> = {
+  [Property in keyof T]: T[Property] extends ModelType<infer R, any>
+    ? // reduce back to union
+      R['secondaryIndexes'] extends any[]
+      ? { secondaryIndexes: R['secondaryIndexes'] }
+      : never
+    : never;
+};
+
+export type RelationalMetadata<
+  ResolvedSchema,
+  ResolvedFields extends Record<string, unknown>,
+  IdentifierMeta extends Record<string, any>,
+> = UnionToIntersection<
+  ExcludeEmpty<
+    {
+      [ModelName in keyof ResolvedSchema]: {
+        [Field in keyof ResolvedSchema[ModelName] as ResolvedSchema[ModelName][Field] extends ModelRelationalFieldParamShape
+          ? ResolvedSchema[ModelName][Field]['relationshipType'] extends
+              | 'hasOne'
+              | 'belongsTo'
+            ? // For hasOne we're adding metadata to the model itself
+              // E.g. if Post hasOne Author, we need to add a postAuthorId field to the Post model
+              ModelName
+            : never
+          : never]: ResolvedSchema[ModelName][Field] extends ModelRelationalFieldParamShape
+          ? ResolvedSchema[ModelName][Field] extends ModelRelationalFieldParamShape
+            ? ResolvedSchema[ModelName][Field]['relationshipType'] extends 'hasMany'
+              ? {
+                  relationalInputFields: Partial<
+                    Record<
+                      // For M:N and 1:M we add a parent model field to the child
+                      `${Uncapitalize<ModelName & string>}`,
+                      NormalizeInputFields<
+                        ResolvedFields[ModelName & string],
+                        ExtractModelIdentifier<ModelName, IdentifierMeta>
+                      >
+                    >
+                  >;
+                }
+              : {
+                  relationalInputFields: Partial<
+                    Record<
+                      // For 1:1 and Belongs To we add a child model field to the parent
+                      Field,
+                      NormalizeInputFields<
+                        ResolvedFields[ResolvedSchema[ModelName][Field]['relatedModel']],
+                        ExtractModelIdentifier<
+                          `${Capitalize<Field & string>}`,
+                          IdentifierMeta
+                        >
+                      >
+                    >
+                  >;
+                }
+            : never
+          : never;
+      };
+    }[keyof ResolvedSchema]
+  >
+>;
+
+type ExtractModelIdentifier<ModelName, IdentifierMeta> =
+  ModelName extends keyof IdentifierMeta ? IdentifierMeta[ModelName] : never;
+
+type NormalizeInputFields<
+  ModelFields,
+  IdentifierMeta extends Record<string, any>,
+> = Partial<Omit<ModelFields, IdentifierMeta['identifier']>> &
+  Required<Pick<ModelFields, IdentifierMeta['identifier']>>;