feat: add support for scheduling functions

.changeset/green-coins-lie.md

@@ -0,0 +1,5 @@
+---
+'@aws-amplify/backend-function': minor
+---
+
+add support for scheduling functions

.eslint_dictionary.json

@@ -27,6 +27,7 @@
   "commonjs",
   "corepack",
   "cors",
+  "cron",
   "ctor",
   "darwin",
   "datastore",

packages/backend-function/API.md

@@ -15,6 +15,9 @@ export type AddEnvironmentFactory = {
     addEnvironment: (key: string, value: string | BackendSecret) => void;
 };
 
+// @public (undocumented)
+export type Cron = `${string} ${string} ${string} ${string} ${string}` | `${string} ${string} ${string} ${string} ${string} ${string}`;
+
 // @public
 export const defineFunction: (props?: FunctionProps) => ConstructFactory<ResourceProvider<FunctionResources> & ResourceAccessAcceptorFactory & AddEnvironmentFactory>;
 
@@ -26,11 +29,18 @@ export type FunctionProps = {
     memoryMB?: number;
     environment?: Record<string, string | BackendSecret>;
     runtime?: NodeVersion;
+    schedule?: TimeInterval | TimeInterval[];
 };
 
 // @public (undocumented)
 export type NodeVersion = 16 | 18 | 20;
 
+// @public (undocumented)
+export type Rate = `every ${number}m` | `every ${number}h` | `every day` | `every week` | `every month` | `every year`;
+
+// @public (undocumented)
+export type TimeInterval = Rate | Cron;
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/backend-function/src/factory.test.ts

@@ -334,6 +334,59 @@ void describe('AmplifyFunctionFactory', () => {
     });
   });
 
+  void describe('schedule property', () => {
+    void it('sets valid schedule - rate', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+        schedule: 'every 5m',
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(*/5 * * * ? *)',
+      });
+    });
+
+    void it('sets valid schedule - cron', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+        schedule: '0 1 * * *',
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(0 1 * * ? *)',
+      });
+    });
+
+    void it('sets valid schedule array', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+        schedule: ['0 1 * * *', 'every 5m'],
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.resourceCountIs('AWS::Events::Rule', 2);
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(0 1 * * ? *)',
+      });
+
+      template.hasResourceProperties('AWS::Events::Rule', {
+        ScheduleExpression: 'cron(*/5 * * * ? *)',
+      });
+    });
+
+    void it('defaults to no event rule created', () => {
+      const lambda = defineFunction({
+        entry: './test-assets/default-lambda/handler.ts',
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(Stack.of(lambda.resources.lambda));
+
+      template.resourceCountIs('AWS::Events::Rule', 0);
+    });
+  });
+
   void describe('resourceAccessAcceptor', () => {
     void it('attaches policy to execution role and configures ssm environment context', () => {
       const functionFactory = defineFunction({

packages/backend-function/src/factory.ts

@@ -31,13 +31,26 @@ import { FunctionEnvironmentTypeGenerator } from './function_env_type_generator.
 import { AttributionMetadataStorage } from '@aws-amplify/backend-output-storage';
 import { fileURLToPath } from 'node:url';
 import { AmplifyUserError, TagName } from '@aws-amplify/platform-core';
+import { ScheduleParser } from './schedule_parser.js';
 
 const functionStackType = 'function-Lambda';
 
 export type AddEnvironmentFactory = {
   addEnvironment: (key: string, value: string | BackendSecret) => void;
 };
 
+export type Cron =
+  | `${string} ${string} ${string} ${string} ${string}`
+  | `${string} ${string} ${string} ${string} ${string} ${string}`;
+export type Rate =
+  | `every ${number}m`
+  | `every ${number}h`
+  | `every day`
+  | `every week`
+  | `every month`
+  | `every year`;
+export type TimeInterval = Rate | Cron;
+
 /**
  * Entry point for defining a function in the Amplify ecosystem
  */
@@ -93,6 +106,19 @@ export type FunctionProps = {
    * Defaults to the oldest NodeJS LTS version. See https://nodejs.org/en/about/previous-releases
    */
   runtime?: NodeVersion;
+
+  /**
+   * A time interval string to periodically run the function.
+   * This can be either a string of `"every <positive whole number><m (minute) or h (hour)>"`, `"every day|week|month|year"` or cron expression.
+   * Defaults to no scheduling for the function.
+   * @example
+   * schedule: "every 5m"
+   * @example
+   * schedule: "every week"
+   * @example
+   * schedule: "0 9 * * 2" // every Monday at 9am
+   */
+  schedule?: TimeInterval | TimeInterval[];
 };
 
 /**
@@ -137,6 +163,7 @@ class FunctionFactory implements ConstructFactory<AmplifyFunction> {
       memoryMB: this.resolveMemory(),
       environment: this.props.environment ?? {},
       runtime: this.resolveRuntime(),
+      schedule: this.resolveSchedule(),
     };
   };
 
@@ -226,6 +253,18 @@ class FunctionFactory implements ConstructFactory<AmplifyFunction> {
 
     return this.props.runtime;
   };
+
+  private resolveSchedule = () => {
+    if (!this.props.schedule) {
+      return [];
+    }
+
+    const schedules = Array.isArray(this.props.schedule)
+      ? this.props.schedule
+      : [this.props.schedule];
+
+    return schedules;
+  };
 }
 
 type HydratedFunctionProps = Required<FunctionProps>;
@@ -335,6 +374,12 @@ class AmplifyFunction
       );
     }
 
+    const schedules = Array.isArray(props.schedule)
+      ? props.schedule
+      : [props.schedule];
+
+    new ScheduleParser(functionLambda, schedules);
+
     Tags.of(functionLambda).add(TagName.FRIENDLY_NAME, id);
 
     this.functionEnvironmentTranslator = new FunctionEnvironmentTranslator(