@aws-amplify/data-schema 0.15.0 → 0.16.0

package/src/ClientSchema.ts

@@ -0,0 +1,118 @@
+import type { __modelMeta__ } from './runtime/client';
+import type { GenericModelSchema, RDSModelSchema } from './ModelSchema';
+
+// MappedTypes
+import type { ResolveSchema, SchemaTypes } from './MappedTypes/ResolveSchema';
+import type {
+  ResolveFieldProperties,
+  ResolveStaticFieldProperties,
+} from './MappedTypes/ResolveFieldProperties';
+import type {
+  ModelIdentifier,
+  ModelSecondaryIndexes,
+  RelationalMetadata,
+} from './MappedTypes/ModelMetadata';
+import type {
+  ExtractNonModelTypes,
+  NonModelTypesShape,
+} from './MappedTypes/ExtractNonModelTypes';
+import type {
+  ResolveCustomOperations,
+  CustomOperationHandlerTypes,
+} from './MappedTypes/CustomOperations';
+import type {
+  CombinedModelSchema,
+  CombinedSchemaIndexesUnion,
+} from './CombineSchema';
+import type { SpreadTuple } from './util';
+
+export type ClientSchema<
+  Schema extends GenericModelSchema<any> | CombinedModelSchema<any>,
+> =
+  Schema extends GenericModelSchema<any>
+    ? InternalClientSchema<Schema>
+    : Schema extends CombinedModelSchema<any>
+      ? InternalCombinedSchema<Schema>
+      : never;
+
+/**
+ * Types for unwrapping generic type args into client-consumable types
+ *
+ * @typeParam Schema - Data schema builder model type
+ *
+ * The following params are used solely as variables in order to simplify mapped type usage.
+ * They should not receive external type args.
+ *
+ * @internal @typeParam NonModelTypes - Custom Types, Enums, and Custom Operations
+ * @internal @typeParam ResolvedSchema - Resolve the schema types used by other generics
+ * @internal @typeParam ResolvedFields - Resolved client-facing types used for CRUDL response shapes
+ * @internal @typeParam IdentifierMeta - Resolve the identifier fields for all models
+ * @internal @typeParam SecondaryIndexes - Map of model secondary index metadata
+ */
+type InternalClientSchema<
+  Schema extends GenericModelSchema<any>,
+  NonModelTypes extends NonModelTypesShape = ExtractNonModelTypes<Schema>,
+  ResolvedSchema = ResolveSchema<Schema>,
+  ResolvedFields extends Record<
+    string,
+    unknown
+  > = Schema extends RDSModelSchema<any, any>
+    ? ResolveStaticFieldProperties<Schema, NonModelTypes, object>
+    : ResolveFieldProperties<Schema, NonModelTypes>,
+  IdentifierMeta extends Record<string, any> = ModelIdentifier<
+    SchemaTypes<Schema>
+  >,
+  SecondaryIndexes extends Record<string, any> = Schema extends RDSModelSchema<
+    any,
+    any
+  >
+    ? object
+    : ModelSecondaryIndexes<SchemaTypes<Schema>>,
+> = CustomOperationHandlerTypes<
+  ResolveCustomOperations<
+    Schema,
+    ResolvedFields,
+    NonModelTypes
+  >['customOperations']
+> &
+  ResolvedFields & {
+    [__modelMeta__]: IdentifierMeta &
+      SecondaryIndexes &
+      RelationalMetadata<ResolvedSchema, ResolvedFields, IdentifierMeta> &
+      NonModelTypes &
+      ResolveCustomOperations<Schema, ResolvedFields, NonModelTypes>;
+  };
+
+type GetInternalClientSchema<Schema> =
+  Schema extends GenericModelSchema<any> ? InternalClientSchema<Schema> : never;
+
+type CombinedClientSchemas<
+  Schemas extends CombinedModelSchema<any>['schemas'],
+> = {
+  [Index in keyof Schemas]: Index extends CombinedSchemaIndexesUnion
+    ? GetInternalClientSchema<Schemas[Index]>
+    : never;
+};
+
+/**
+ * Types for unwrapping and combining generic type args into client-consumable types
+ * for multiple schemas
+ *
+ * @typeParam Combined - A container of multiple schemas
+ *
+ * @internal @typeParam ClientSchemas - The tuple of client schemas to combine
+ */
+type InternalCombinedSchema<
+  Combined extends CombinedModelSchema<any>,
+  ClientSchemas extends [...any] = CombinedClientSchemas<Combined['schemas']>,
+> = SpreadTuple<{
+  [I in keyof ClientSchemas]: I extends CombinedSchemaIndexesUnion
+    ? Omit<ClientSchemas[I], typeof __modelMeta__>
+    : never;
+}> & {
+  [__modelMeta__]: SpreadTuple<{
+    [I in keyof ClientSchemas]: I extends CombinedSchemaIndexesUnion
+      ? ClientSchemas[I][typeof __modelMeta__]
+      : never;
+  }>;
+};

package/src/CombineSchema.ts

@@ -0,0 +1,58 @@
+import { GenericModelSchema } from './ModelSchema';
+import { brand, Brand, IndexLimitUnion } from './util';
+
+const COMBINED_SCHEMA_LIMIT = 50;
+
+export type CombinedSchemaIndexesUnion = IndexLimitUnion<
+  typeof COMBINED_SCHEMA_LIMIT
+>[number];
+
+const CombinedSchemaBrandName = 'CombinedSchema';
+export const combinedSchemaBrand = brand(CombinedSchemaBrandName);
+export type CombinedSchemaBrand = Brand<typeof CombinedSchemaBrandName>;
+
+export type CombinedModelSchema<Schemas extends GenericModelSchema<any>[]> =
+  CombinedSchemaBrand & { schemas: [...Schemas] };
+
+/**
+ * The interface for merging up to 50 schemas into a single API.
+ * @param schemas The schemas to combine into a single API
+ * @returns An API and data model definition to be deployed with Amplify (Gen 2) experience (`processSchema(...)`)
+ * or with the Amplify Data CDK construct (`@aws-amplify/data-construct`)
+ */
+export function combine<Schema extends GenericModelSchema<any>[]>(
+  schemas: [...Schema],
+): CombinedModelSchema<Schema> {
+  return internalCombine(schemas);
+}
+
+function internalCombine<
+  Schema extends GenericModelSchema<any>[],
+  SchemasTuple extends [...Schema],
+>(schemas: SchemasTuple): CombinedModelSchema<Schema> {
+  validateDuplicateTypeNames(schemas);
+  return {
+    ...combinedSchemaBrand,
+    schemas: schemas,
+  };
+}
+
+function validateDuplicateTypeNames<Schema extends GenericModelSchema<any>[]>(
+  schemas: [...Schema],
+) {
+  const allSchemaKeys = schemas.flatMap((s) => Object.keys(s.data.types));
+  const keySet = new Set<string>();
+  const duplicateKeySet = new Set<string>();
+  allSchemaKeys.forEach((key) => {
+    if (keySet.has(key)) {
+      duplicateKeySet.add(key);
+    } else {
+      keySet.add(key);
+    }
+  });
+  if (duplicateKeySet.size > 0) {
+    throw new Error(
+      `The schemas you are attempting to combine have a name collision. Please remove or rename ${Array.from(duplicateKeySet).join(', ')}.`,
+    );
+  }
+}

package/src/CustomOperation.ts

@@ -0,0 +1,286 @@
+import { SetTypeSubArg } from '@aws-amplify/data-schema-types';
+import { Brand, brand } from './util';
+
+import { ModelField, InternalField } from './ModelField';
+import {
+  AllowModifierForCustomOperation,
+  Authorization,
+  allowForCustomOperations,
+} from './Authorization';
+import { RefType, InternalRef } from './RefType';
+import { EnumType, EnumTypeParamShape } from './EnumType';
+import { CustomType } from './CustomType';
+import type {
+  CustomHandler,
+  FunctionHandler,
+  HandlerType as Handler,
+} from './Handler';
+
+const queryBrand = 'queryCustomOperation';
+const mutationBrand = 'mutationCustomOperation';
+const subscriptionBrand = 'subscriptionCustomOperation';
+
+type CustomOperationBrand =
+  | typeof queryBrand
+  | typeof mutationBrand
+  | typeof subscriptionBrand;
+
+type CustomArguments = Record<
+  string,
+  ModelField<any, any> | EnumType<EnumTypeParamShape>
+>;
+
+type SubscriptionSource = RefType<any, any>;
+type InternalSubscriptionSource = InternalRef;
+
+type CustomReturnType = RefType<any> | CustomType<any>;
+type CustomFunctionRefType = string; // extend to include reference
+
+type InternalCustomArguments = Record<string, InternalField>;
+type InternalCustomReturnType = InternalRef;
+type HandlerInputType = FunctionHandler[] | CustomHandler[] | Handler;
+
+export const CustomOperationNames = [
+  'Query',
+  'Mutation',
+  'Subscription',
+] as const;
+type CustomOperationName = (typeof CustomOperationNames)[number];
+
+type CustomData = {
+  arguments: CustomArguments;
+  returnType: CustomReturnType | null;
+  functionRef: string | null; // extend to include reference
+  authorization: Authorization<any, any, any>[];
+  typeName: CustomOperationName;
+  handlers: Handler[] | null;
+  subscriptionSource: SubscriptionSource[];
+};
+
+type InternalCustomData = CustomData & {
+  arguments: InternalCustomArguments;
+  returnType: InternalCustomReturnType;
+  functionRef: string | null;
+  subscriptionSource: InternalSubscriptionSource[];
+  authorization: Authorization<any, any, any>[];
+};
+
+export type CustomOperationParamShape = {
+  arguments: CustomArguments | null;
+  returnType: CustomReturnType | null;
+  functionRef: string | null;
+  authorization: Authorization<any, any, any>[];
+  typeName: CustomOperationName;
+  handlers: Handler | null;
+};
+
+export type CustomOperation<
+  T extends CustomOperationParamShape,
+  K extends keyof CustomOperation<T> = never,
+  B extends CustomOperationBrand = CustomOperationBrand,
+> = Omit<
+  {
+    arguments<Arguments extends CustomArguments>(
+      args: Arguments,
+    ): CustomOperation<
+      SetTypeSubArg<T, 'arguments', Arguments>,
+      K | 'arguments',
+      B
+    >;
+    returns<ReturnType extends CustomReturnType>(
+      returnType: ReturnType,
+    ): CustomOperation<
+      SetTypeSubArg<T, 'returnType', ReturnType>,
+      K | 'returns',
+      B
+    >;
+    /**
+     *
+     * @deprecated
+     * `.function` should no longer be used and will be removed
+     * in the next minor version of this package.
+     *
+     * Use `.handler(a.handler.function())` instead
+     */
+    function<FunctionRef extends CustomFunctionRefType>(
+      functionRefOrName: FunctionRef,
+    ): CustomOperation<
+      SetTypeSubArg<T, 'functionRef', FunctionRef>,
+      K | 'function',
+      B
+    >;
+    authorization<AuthRuleType extends Authorization<any, any, any>>(
+      callback: (
+        allow: AllowModifierForCustomOperation,
+      ) => AuthRuleType | AuthRuleType[],
+    ): CustomOperation<
+      SetTypeSubArg<T, 'authorization', AuthRuleType[]>,
+      K | 'authorization',
+      B
+    >;
+    handler<H extends HandlerInputType>(
+      handlers: H,
+    ): CustomOperation<T, K | 'handler', B>;
+    for<Source extends SubscriptionSource>(
+      source: Source | Source[],
+    ): CustomOperation<
+      T['typeName'] extends 'Subscription'
+        ? SetTypeSubArg<
+            T,
+            'returnType',
+            // the array contained types are validated in the SchemaProcessor to have the
+            // same return type, so we can safely use Source[number] here as the source
+            // to extra the return type in `packages/data-schema/src/MappedTypes/CustomOperations.ts`
+            Source extends SubscriptionSource[] ? Source[number] : Source
+          >
+        : T,
+      K | 'for',
+      B
+    >;
+  },
+  K
+> &
+  Brand<B>;
+
+function brandedBuilder<T extends CustomOperationParamShape>(
+  builder: Record<keyof CustomOperation<T> & string, any>,
+  brandValue: CustomOperationBrand,
+): CustomOperation<T, never, typeof brandValue> {
+  return { ...builder, ...brand(brandValue) };
+}
+
+/**
+ * Internal representation of Custom Type that exposes the `data` property.
+ * Used at buildtime.
+ */
+export type InternalCustom<B extends CustomOperationBrand = any> =
+  CustomOperation<any, never, B> & {
+    data: InternalCustomData;
+  };
+
+function _custom<
+  T extends CustomOperationParamShape,
+  B extends CustomOperationBrand,
+>(typeName: CustomOperationName, brand: B) {
+  const data: CustomData = {
+    arguments: {},
+    returnType: null,
+    functionRef: null,
+    authorization: [],
+    typeName: typeName,
+    handlers: null,
+    subscriptionSource: [],
+  };
+
+  const builder = brandedBuilder<T>(
+    {
+      arguments(args: CustomArguments) {
+        data.arguments = args;
+
+        return this;
+      },
+      returns(returnType: CustomReturnType) {
+        data.returnType = returnType;
+
+        return this;
+      },
+      function(functionRefOrName: CustomFunctionRefType) {
+        data.functionRef = functionRefOrName;
+
+        return this;
+      },
+      authorization<AuthRuleType extends Authorization<any, any, any>>(
+        callback: (
+          allow: AllowModifierForCustomOperation,
+        ) => AuthRuleType | AuthRuleType[],
+      ) {
+        const rules = callback(allowForCustomOperations);
+        data.authorization = Array.isArray(rules) ? rules : [rules];
+
+        return this;
+      },
+      handler(handlers: HandlerInputType) {
+        data.handlers = Array.isArray(handlers)
+          ? handlers
+          : ([handlers] as Handler[]);
+
+        return this;
+      },
+      for(source: SubscriptionSource | SubscriptionSource[]) {
+        data.subscriptionSource = Array.isArray(source) ? source : [source];
+
+        return this;
+      },
+    },
+    brand,
+  );
+
+  return { ...builder, data } as InternalCustom<B> as CustomOperation<
+    T,
+    never,
+    B
+  >;
+}
+
+export type QueryCustomOperation = CustomOperation<
+  CustomOperationParamShape,
+  any,
+  typeof queryBrand
+>;
+
+export function query(): CustomOperation<
+  {
+    arguments: null;
+    returnType: null;
+    functionRef: null;
+    authorization: [];
+    typeName: 'Query';
+    handlers: null;
+  },
+  never,
+  typeof queryBrand
+> {
+  return _custom('Query', queryBrand);
+}
+
+export type MutationCustomOperation = CustomOperation<
+  CustomOperationParamShape,
+  any,
+  typeof mutationBrand
+>;
+
+export function mutation(): CustomOperation<
+  {
+    arguments: null;
+    returnType: null;
+    functionRef: null;
+    authorization: [];
+    typeName: 'Mutation';
+    handlers: null;
+  },
+  never,
+  typeof mutationBrand
+> {
+  return _custom('Mutation', mutationBrand);
+}
+
+export type SubscriptionCustomOperation = CustomOperation<
+  CustomOperationParamShape,
+  any,
+  typeof subscriptionBrand
+>;
+
+export function subscription(): CustomOperation<
+  {
+    arguments: null;
+    returnType: null;
+    functionRef: null;
+    authorization: [];
+    typeName: 'Subscription';
+    handlers: null;
+  },
+  'returns',
+  typeof subscriptionBrand
+> {
+  return _custom('Subscription', subscriptionBrand);
+}

package/src/CustomType.ts

@@ -0,0 +1,67 @@
+import type { Brand } from './util';
+import type {
+  ModelField,
+  InternalField,
+  ModelFieldTypeParamOuter,
+} from './ModelField';
+import type { RefType } from './RefType';
+import type { EnumType, EnumTypeParamShape } from './EnumType';
+
+/**
+ * Custom Types
+ *
+ * can be defined in-line to strongly type object types
+ *
+ */
+
+// `.default()` is not allowed on a Custom Type field
+export type CustomTypeAllowedModifiers = 'authorization' | 'array' | 'required';
+
+type CustomTypeFields = Record<
+  string,
+  | ModelField<ModelFieldTypeParamOuter, CustomTypeAllowedModifiers, any>
+  | RefType<any, any, any>
+  | EnumType<EnumTypeParamShape>
+  | CustomType<CustomTypeParamShape>
+>;
+
+type InternalModelFields = Record<string, InternalField>;
+
+type CustomTypeData = {
+  fields: CustomTypeFields;
+  type: 'customType';
+};
+
+type InternalCustomTypeData = CustomTypeData & {
+  fields: InternalModelFields;
+};
+
+export type CustomTypeParamShape = {
+  fields: CustomTypeFields;
+};
+
+export type CustomType<T extends CustomTypeParamShape> = T &
+  Brand<'customType'>;
+
+/**
+ * Internal representation of CustomType that exposes the `data` property.
+ * Used at buildtime.
+ */
+export type InternalCustomType = CustomType<any> & {
+  data: InternalCustomTypeData;
+};
+
+function _customType<T extends CustomTypeParamShape>(fields: T['fields']) {
+  const data: CustomTypeData = {
+    fields,
+    type: 'customType',
+  };
+
+  return { data } as InternalCustomType as CustomType<T>;
+}
+
+export function customType<T extends CustomTypeFields>(
+  fields: T,
+): CustomType<{ fields: T }> {
+  return _customType(fields);
+}

package/src/EnumType.ts

@@ -0,0 +1,36 @@
+import { Brand } from './util';
+
+type EnumTypeData = {
+  type: 'enum';
+  values: readonly string[];
+};
+
+export type EnumTypeParamShape = {
+  type: 'enum';
+  values: readonly string[];
+};
+
+export type EnumType<T extends EnumTypeParamShape> = T & Brand<'enum'>;
+
+function _enum<T extends EnumTypeParamShape>(values: T['values']) {
+  const data: EnumTypeData = {
+    type: 'enum',
+    values,
+  };
+
+  return data as EnumType<T>;
+}
+
+type EnumTypeArgFactory<Values extends readonly string[]> = {
+  type: 'enum';
+  values: Values;
+};
+
+/**
+ * this type param pattern allows us to infer literal type values from the array without using the `as const` suffix
+ */
+export function enumType<Value extends string, T extends readonly Value[]>(
+  values: T,
+) {
+  return _enum<EnumTypeArgFactory<T>>(values);
+}

package/src/Handler.ts

@@ -0,0 +1,127 @@
+import type { DefineFunction } from '@aws-amplify/data-schema-types';
+import { Brand, brand } from './util';
+import { RefType } from './RefType';
+
+export type HandlerType =
+  | InlineSqlHandler
+  | SqlReferenceHandler
+  | CustomHandler
+  | FunctionHandler;
+
+const dataSymbol = Symbol('Data');
+
+function buildHandler<B extends string>(brandName: B): Brand<B> {
+  return brand(brandName);
+}
+
+type AllHandlers =
+  | InlineSqlHandler
+  | SqlReferenceHandler
+  | CustomHandler
+  | FunctionHandler;
+
+export function getHandlerData<H extends AllHandlers>(
+  handler: H,
+): H[typeof dataSymbol] {
+  return handler[dataSymbol];
+}
+
+//#region handler.inlineSql
+
+const inlineSqlBrand = 'inlineSql';
+
+export type InlineSqlHandler = { [dataSymbol]: string } & Brand<
+  typeof inlineSqlBrand
+>;
+
+function inlineSql(sql: string): InlineSqlHandler {
+  return { [dataSymbol]: sql, ...buildHandler(inlineSqlBrand) };
+}
+
+//#endregion
+
+//#region handler.sqlReference
+
+const sqlReferenceBrand = 'sqlReference';
+
+export type SqlReferenceHandlerData = {
+  entry: string;
+  stack: string | undefined;
+};
+
+export type SqlReferenceHandler = {
+  [dataSymbol]: SqlReferenceHandlerData;
+} & Brand<typeof sqlReferenceBrand>;
+
+function sqlReference(sqlFilePath: string): SqlReferenceHandler {
+  // used to determine caller directory in order to resolve relative path downstream
+  const stack = new Error().stack;
+  return {
+    [dataSymbol]: { stack, entry: sqlFilePath },
+    ...buildHandler(sqlReferenceBrand),
+  };
+}
+
+//#endregion
+
+//#region handler.custom
+
+type CustomHandlerInput = {
+  /**
+   * The data source used by the function.
+   * Can reference a model in the schema with a.ref('ModelName') or any string data source name configured in your API
+   *
+   * Defaults to 'NONE_DS'
+   *
+   */
+  dataSource?: string | RefType<any>;
+  /**
+   * The path to the file that contains the function entry point.
+   * If this is a relative path, it is computed relative to the file where this handler is defined
+   */
+  entry: string;
+};
+
+export type CustomHandlerData = CustomHandlerInput & {
+  stack: string | undefined;
+};
+
+const customHandlerBrand = 'customHandler';
+
+export type CustomHandler = { [dataSymbol]: CustomHandlerData } & Brand<
+  typeof customHandlerBrand
+>;
+
+function custom(customHandler: CustomHandlerInput): CustomHandler {
+  // used to determine caller directory in order to resolve relative path downstream
+  const stack = new Error().stack;
+  return {
+    [dataSymbol]: { ...customHandler, stack },
+    ...buildHandler(customHandlerBrand),
+  };
+}
+
+//#endregion
+
+//#region handler.function
+
+export type FunctionHandlerData = DefineFunction | string;
+
+const functionHandlerBrand = 'functionHandler';
+
+export type FunctionHandler = {
+  [dataSymbol]: FunctionHandlerData;
+} & Brand<typeof functionHandlerBrand>;
+
+function fcn(fn: FunctionHandlerData): FunctionHandler {
+  return { [dataSymbol]: fn, ...buildHandler(functionHandlerBrand) };
+}
+
+//#endregion
+
+export const handler = {
+  inlineSql,
+  sqlReference,
+  custom,
+  function: fcn,
+};