@aws-amplify/data-schema 0.13.17 → 0.13.18

package/lib-esm/src/CustomOperation.d.ts

@@ -11,6 +11,8 @@ declare const mutationBrand = "mutationCustomOperation";
 declare 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;
 type InternalCustomArguments = Record<string, InternalField>;
@@ -25,11 +27,13 @@ type CustomData = {
     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 = {
@@ -54,6 +58,7 @@ export type CustomOperation<T extends CustomOperationParamShape, K extends keyof
     function<FunctionRef extends CustomFunctionRefType>(functionRefOrName: FunctionRef): CustomOperation<SetTypeSubArg<T, 'functionRef', FunctionRef>, K | 'function', B>;
     authorization<AuthRuleType extends Authorization<any, any, any>>(rules: AuthRuleType[]): CustomOperation<SetTypeSubArg<T, 'authorization', AuthRuleType[]>, K | 'authorization', B>;
     handler<H extends HandlerInputType>(handlers: H): CustomOperation<T, K | 'handler', B>;
+    for(source: SubscriptionSource | SubscriptionSource[]): CustomOperation<T, K | 'for', B>;
 }, K> & Brand<B>;
 /**
  * Internal representation of Custom Type that exposes the `data` property.

package/lib-esm/src/CustomOperation.js

@@ -21,6 +21,7 @@ function _custom(typeName, brand) {
         authorization: [],
         typeName: typeName,
         handlers: null,
+        subscriptionSource: [],
     };
     const builder = brandedBuilder({
         arguments(args) {
@@ -45,6 +46,10 @@ function _custom(typeName, brand) {
                 : [handlers];
             return this;
         },
+        for(source) {
+            data.subscriptionSource = Array.isArray(source) ? source : [source];
+            return this;
+        },
     }, brand);
     return { ...builder, data };
 }

package/lib-esm/src/Handler.d.ts

@@ -23,7 +23,7 @@ type CustomHandlerInput = {
      * Defaults to 'NONE_DS'
      *
      */
-    dataSource?: string | RefType<any, any, any>;
+    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

package/lib-esm/src/RefType.d.ts

@@ -9,6 +9,7 @@ type RefTypeData = {
     valueRequired: boolean;
     array: boolean;
     arrayRequired: boolean;
+    mutationOperations: MutationOperations[];
     authorization: Authorization<any, any, any>[];
 };
 export type RefTypeParamShape = {
@@ -19,6 +20,7 @@ export type RefTypeParamShape = {
     arrayRequired: boolean;
     authorization: Authorization<any, any, any>[];
 };
+type MutationOperations = 'create' | 'update' | 'delete';
 export type RefType<T extends RefTypeParamShape, K extends keyof RefType<T> = never, Auth = undefined> = Omit<{
     /**
      * Marks a field as required.
@@ -33,6 +35,7 @@ export type RefType<T extends RefTypeParamShape, K extends keyof RefType<T> = ne
      * multiple authorization rules for this field.
      */
     authorization<AuthRuleType extends Authorization<any, any, any>>(rules: AuthRuleType[]): RefType<T, K | 'authorization', AuthRuleType>;
+    mutations(operations: MutationOperations[]): RefType<T, K | 'mutations'>;
 }, K> & {
     [__auth]?: Auth;
 } & Brand<typeof brandName>;

package/lib-esm/src/RefType.js

@@ -13,6 +13,7 @@ function _ref(link) {
         valueRequired: false,
         array: false,
         arrayRequired: false,
+        mutationOperations: [],
         authorization: [],
     };
     const builder = brandedBuilder({
@@ -33,6 +34,10 @@ function _ref(link) {
             data.authorization = rules;
             return this;
         },
+        mutations(operations) {
+            data.mutationOperations = operations;
+            return this;
+        },
     });
     return { ...builder, data };
 }

package/lib-esm/src/SchemaProcessor.js

@@ -176,8 +176,8 @@ function transformFunctionHandler(handlers, callSignature) {
     });
     return { gqlHandlerContent, lambdaFunctionDefinition };
 }
-function customOperationToGql(typeName, typeDef, authorization, isCustom = false, databaseType) {
-    const { arguments: fieldArgs, returnType, functionRef, handlers, } = typeDef.data;
+function customOperationToGql(typeName, typeDef, authorization, isCustom = false, databaseType, getRefType) {
+    const { arguments: fieldArgs, typeName: opType, returnType, functionRef, handlers, subscriptionSource, } = typeDef.data;
     let callSignature = typeName;
     const implicitModels = [];
     const { authString } = isCustom
@@ -218,6 +218,21 @@ function customOperationToGql(typeName, typeDef, authorization, isCustom = false
     else if (databaseType === 'sql' && handler && brand === 'sqlReference') {
         gqlHandlerContent = `@sql(reference: "${(0, Handler_1.getHandlerData)(handler)}") `;
     }
+    if (opType === 'Subscription') {
+        const subscriptionSources = subscriptionSource
+            .flatMap((source) => {
+            const refTarget = source.data.link;
+            const { type } = getRefType(refTarget, typeName);
+            if (type === 'CustomOperation') {
+                return refTarget;
+            }
+            if (type === 'Model') {
+                return source.data.mutationOperations.map((op) => `${op}${refTarget}`);
+            }
+        })
+            .join('", "');
+        gqlHandlerContent += `@aws_subscribe(mutations: ["${subscriptionSources}"]) `;
+    }
     const gqlField = `${callSignature}: ${returnTypeName} ${gqlHandlerContent}${authString}`;
     return { gqlField, models: implicitModels, lambdaFunctionDefinition };
 }
@@ -732,6 +747,31 @@ const extractFunctionSchemaAccess = (authRules) => {
     }
     return { schemaAuth, functionSchemaAccess };
 };
+/**
+ * Returns a closure for retrieving reference type and definition from schema
+ */
+const getRefTypeForSchema = (schema) => {
+    const getRefType = (source, target) => {
+        const typeDef = schema.data.types[source];
+        if (typeDef === undefined) {
+            throw new Error(`Invalid ref. ${target} is referencing ${source} which is not defined in the schema`);
+        }
+        if (isInternalModel(typeDef)) {
+            return { type: 'Model', def: typeDef };
+        }
+        if (isCustomOperation(typeDef)) {
+            return { type: 'CustomOperation', def: typeDef };
+        }
+        if (isCustomType(typeDef)) {
+            return { type: 'CustomType', def: typeDef };
+        }
+        if (isEnumType(typeDef)) {
+            return { type: 'Enum', def: typeDef };
+        }
+        throw new Error(`Invalid ref. ${target} is referencing ${source} which is neither a Model, Custom Operation, Custom Type, or Enum`);
+    };
+    return getRefType;
+};
 const schemaPreprocessor = (schema) => {
     const gqlModels = [];
     const customQueries = [];
@@ -746,6 +786,7 @@ const schemaPreprocessor = (schema) => {
     const fkFields = allImpliedFKs(schema);
     const topLevelTypes = Object.entries(schema.data.types);
     const { schemaAuth, functionSchemaAccess } = extractFunctionSchemaAccess(schema.data.authorization);
+    const getRefType = getRefTypeForSchema(schema);
     for (const [typeName, typeDef] of topLevelTypes) {
         validateAuth(typeDef.data?.authorization);
         const mostRelevantAuthRules = typeDef.data?.authorization?.length > 0
@@ -773,7 +814,7 @@ const schemaPreprocessor = (schema) => {
             }
             else if (isCustomOperation(typeDef)) {
                 const { typeName: opType } = typeDef.data;
-                const { gqlField, models, jsFunctionForField, lambdaFunctionDefinition, } = transformCustomOperations(typeDef, typeName, mostRelevantAuthRules, databaseType);
+                const { gqlField, models, jsFunctionForField, lambdaFunctionDefinition, } = transformCustomOperations(typeDef, typeName, mostRelevantAuthRules, databaseType, getRefType);
                 lambdaFunctions = lambdaFunctionDefinition;
                 topLevelTypes.push(...models);
                 if (jsFunctionForField) {
@@ -849,8 +890,8 @@ const schemaPreprocessor = (schema) => {
         lambdaFunctions,
     };
 };
-function validateCustomOperations(typeDef, typeName, authRules) {
-    const { functionRef, handlers } = typeDef.data;
+function validateCustomOperations(typeDef, typeName, authRules, getRefType) {
+    const { functionRef, handlers, typeName: opType, subscriptionSource, returnType, } = typeDef.data;
     // TODO: remove `functionRef` after deprecating
     const handlerConfigured = functionRef !== null || handlers?.length;
     const authConfigured = authRules.length > 0;
@@ -873,6 +914,57 @@ function validateCustomOperations(typeDef, typeName, authRules) {
             throw new Error(`Field handlers must be of the same type. ${typeName} has been configured with ${configuredHandlersStr}`);
         }
     }
+    if (opType === 'Subscription') {
+        if (subscriptionSource.length < 1) {
+            throw new Error(`${typeName} is missing a mutation source. Custom subscriptions must reference a mutation source via subscription().for(a.ref('ModelOrOperationName')) `);
+        }
+        subscriptionSource.forEach((source) => {
+            const sourceName = source.data.link;
+            const { type, def } = getRefType(sourceName, typeName);
+            if (type !== 'Model' && source.data.mutationOperations.length > 0) {
+                throw new Error(`Invalid subscription definition. .mutations() modifier can only be used with a Model ref. ${typeName} is referencing ${type}`);
+            }
+            if (type === 'Model' && source.data.mutationOperations.length === 0) {
+                throw new Error(`Invalid subscription definition. .mutations() modifier must be used with a Model ref subscription source. ${typeName} is referencing ${sourceName} without specifying a mutation`);
+            }
+            if (type === 'CustomOperation' && def.data.typeName !== 'Mutation') {
+                throw new Error(`Invalid subscription definition. .for() can only reference a mutation. ${typeName} is referencing ${sourceName} which is a ${def.data.typeName}`);
+            }
+            // Ensure subscription return type matches the return type of triggering mutation(s)
+            // TODO: when we remove .returns() for custom subscriptions, minor changes will be needed here. Instead of comparing subscriptionSource return val
+            //  to a root returnType, we'll need to ensure that each subscriptionSource has the same return type
+            if (returnType.data.type === 'ref') {
+                const returnTypeName = returnType.data.link;
+                if (type === 'Model') {
+                    if (returnTypeName !== sourceName ||
+                        returnType.data.array !== source.data.array) {
+                        throw new Error(`Invalid subscription definition. Subscription return type must match the return type of the mutation triggering it. ${typeName} is referencing ${sourceName} which has a different return type`);
+                    }
+                }
+                if (type === 'CustomOperation') {
+                    const customOperationReturnType = def.data.returnType.data.link;
+                    const customOperationReturnTypeArray = def.data.returnType.data.array;
+                    if (returnTypeName !== customOperationReturnType ||
+                        returnType.data.array !== customOperationReturnTypeArray) {
+                        throw new Error(`Invalid subscription definition. Subscription return type must match the return type of the mutation triggering it. ${typeName} is referencing ${sourceName} which has a different return type`);
+                    }
+                }
+            }
+            else if (returnType.data.fieldType !== undefined) {
+                if (type === 'Model') {
+                    throw new Error(`Invalid subscription definition. Subscription return type must match the return type of the mutation triggering it. ${typeName} is referencing ${sourceName} which has a different return type`);
+                }
+                if (type === 'CustomOperation') {
+                    const customOperationReturnType = def.data.returnType.data.fieldType;
+                    const customOperationReturnTypeArray = def.data.returnType.data.array;
+                    if (returnType.data.fieldType !== customOperationReturnType ||
+                        returnType.data.array !== customOperationReturnTypeArray) {
+                        throw new Error(`Invalid subscription definition. Subscription return type must match the return type of the mutation triggering it. ${typeName} is referencing ${sourceName} which has a different return type`);
+                    }
+                }
+            }
+        });
+    }
 }
 const isCustomHandler = (handler) => {
     return Array.isArray(handler) && (0, util_1.getBrand)(handler[0]) === 'customHandler';
@@ -933,15 +1025,15 @@ const handleCustom = (handlers, opType, typeName) => {
     };
     return jsFn;
 };
-function transformCustomOperations(typeDef, typeName, authRules, databaseType) {
+function transformCustomOperations(typeDef, typeName, authRules, databaseType, getRefType) {
     const { typeName: opType, handlers } = typeDef.data;
     let jsFunctionForField = undefined;
-    validateCustomOperations(typeDef, typeName, authRules);
+    validateCustomOperations(typeDef, typeName, authRules, getRefType);
     if (isCustomHandler(handlers)) {
         jsFunctionForField = handleCustom(handlers, opType, typeName);
     }
     const isCustom = Boolean(jsFunctionForField);
-    const { gqlField, models, lambdaFunctionDefinition } = customOperationToGql(typeName, typeDef, authRules, isCustom, databaseType);
+    const { gqlField, models, lambdaFunctionDefinition } = customOperationToGql(typeName, typeDef, authRules, isCustom, databaseType, getRefType);
     return { gqlField, models, jsFunctionForField, lambdaFunctionDefinition };
 }
 function generateCustomOperationTypes({ queries, mutations, subscriptions, }) {