feat(scheduler): schedule expression construct

packages/aws-cdk-lib/aws-scheduler/lib/index.ts

@@ -1 +1,2 @@
-export * from './scheduler.generated';
+export * from './scheduler.generated';
+export * from './schedule-expression';

packages/aws-cdk-lib/aws-scheduler/lib/schedule-expression.ts

@@ -0,0 +1,104 @@
+import { Construct } from 'constructs';
+import * as events from '../../aws-events';
+import { CronOptions } from '../../aws-events';
+import { Duration, TimeZone } from '../../core';
+
+
+/**
+ * ScheduleExpression for EventBridge Schedule
+ *
+ * You can choose from three schedule types when configuring your schedule: rate-based, cron-based, and one-time schedules.
+ * Both rate-based and cron-based schedules are recurring schedules.
+ *
+ * @see https://docs.aws.amazon.com/scheduler/latest/UserGuide/schedule-types.html
+ */
+export abstract class ScheduleExpression {
+
+
+  /**
+   * Construct a one-time schedule from a date.
+   *
+   * @param date The date and time to use. The millisecond part will be ignored.
+   * @param timeZone The time zone to use for interpreting the date. Default: - UTC
+   */
+  public static at(date: Date, timeZone?: TimeZone): ScheduleExpression {
+    try {
+      const literal = date.toISOString().split('.')[0];
+      return new LiteralScheduleExpression(`at(${literal})`, timeZone ?? TimeZone.ETC_UTC);
+    } catch (e) {
+      if (e instanceof RangeError) {
+        throw new Error('Invalid date');
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Construct a schedule from a literal schedule expression
+   * @param expression The expression to use. Must be in a format that EventBridge will recognize
+   * @param timeZone The time zone to use for interpreting the expression. Default: - UTC
+   */
+  public static expression(expression: string, timeZone?: TimeZone): ScheduleExpression {
+    return new LiteralScheduleExpression(expression, timeZone ?? TimeZone.ETC_UTC);
+  }
+
+  /**
+   * Construct a recurring schedule from an interval and a time unit
+   *
+   * Rates may be defined with any unit of time, but when converted into minutes, the duration must be a positive whole number of minutes.
+   */
+  static rate(duration: Duration): ScheduleExpression {
+    const schedule = events.Schedule.rate(duration);
+    return new LiteralScheduleExpression(schedule.expressionString);
+  }
+
+  /**
+   * Create a srecurring chedule from a set of cron fields and time zone.
+   */
+  static cron(options: CronOptionsWithTimezone): ScheduleExpression {
+    const schedule = events.Schedule.cron(options);
+    return new LiteralScheduleExpression(schedule.expressionString, options.timeZone ?? TimeZone.ETC_UTC);
+  }
+
+  /**
+     * Retrieve the expression for this schedule
+     */
+  public abstract readonly expressionString: string;
+  /**
+      * Retrieve the expression for this schedule
+      */
+  public abstract readonly timeZone?: TimeZone;
+
+  protected constructor() {};
+  /**
+      *
+      * @internal
+      */
+  abstract _bind(scope: Construct): void;
+}
+
+/**
+ * Options to configure a cron expression
+ *
+ * All fields are strings so you can use complex expressions. Absence of
+ * a field implies '*' or '?', whichever one is appropriate.
+ *
+ * @see https://docs.aws.amazon.com/eventbridge/latest/userguide/scheduled-events.html#cron-expressions
+ */
+export interface CronOptionsWithTimezone extends CronOptions {
+  /**
+   * The timezone to run the schedule in
+   *
+   * @default - UTC
+   */
+  readonly timeZone?: TimeZone;
+}
+
+class LiteralScheduleExpression extends ScheduleExpression {
+
+  constructor(public readonly expressionString: string, public readonly timeZone?: TimeZone) {
+    super();
+  }
+
+  public _bind() {}
+}

packages/aws-cdk-lib/aws-scheduler/test/schedule-expression.test.ts

@@ -0,0 +1,165 @@
+import { Duration, Stack, Lazy, TimeZone } from '../../core';
+import { ScheduleExpression } from '../lib';
+
+
+describe('schedule expression', () => {
+  test('cron expressions day and dow are mutex: given weekday', () => {
+    // Run every 10 minutes Monday through Friday
+    expect('cron(0/10 * ? * MON-FRI *)').toEqual(ScheduleExpression.cron({
+      minute: '0/10',
+      weekDay: 'MON-FRI',
+    }).expressionString);
+  });
+
+  test('cron expressions day and dow are mutex: given month day', () => {
+    // Run at 8:00 am (UTC) every 1st day of the month
+    expect('cron(0 8 1 * ? *)').toEqual(ScheduleExpression.cron({
+      minute: '0',
+      hour: '8',
+      day: '1',
+    }).expressionString);
+  });
+
+  test('cron expressions day and dow are mutex: given neither', () => {
+    // Run at 10:00 am (UTC) every day
+    expect('cron(0 10 * * ? *)').toEqual(ScheduleExpression.cron({
+      minute: '0',
+      hour: '10',
+    }).expressionString);
+  });
+
+  test('cron expressions saves timezone', () => {
+    expect(TimeZone.EUROPE_LONDON).toEqual(ScheduleExpression.cron(
+      {
+        minute: '0',
+        hour: '10',
+        timeZone: TimeZone.EUROPE_LONDON,
+      }).timeZone);
+  });
+
+  test('cron expressions timezone is UTC if not specified', () => {
+    expect(TimeZone.ETC_UTC).toEqual(ScheduleExpression.cron(
+      {
+        minute: '0',
+        hour: '10',
+      }).timeZone);
+  });
+
+  test('rate cannot be 0', () => {
+    expect(() => {
+      ScheduleExpression.rate(Duration.days(0));
+    }).toThrow(/Duration cannot be 0/);
+  });
+
+  test('rate cannot be negative', () => {
+    expect(() => {
+      ScheduleExpression.rate(Duration.minutes(-2));
+    }).toThrow(/Duration amounts cannot be negative/);
+  });
+
+  test('rate can be from a token', () => {
+    const stack = new Stack();
+    const lazyDuration = Duration.minutes(Lazy.number({ produce: () => 5 }));
+    const rate = ScheduleExpression.rate(lazyDuration);
+    expect('rate(5 minutes)').toEqual(stack.resolve(rate).expressionString);
+  });
+
+  test('rate can be in minutes', () => {
+    expect('rate(10 minutes)').toEqual(
+      ScheduleExpression.rate(Duration.minutes(10))
+        .expressionString);
+  });
+
+  test('rate can be in days', () => {
+    expect('rate(10 days)').toEqual(
+      ScheduleExpression.rate(Duration.days(10))
+        .expressionString);
+  });
+
+  test('rate can be in hours', () => {
+    expect('rate(10 hours)').toEqual(
+      ScheduleExpression.rate(Duration.hours(10))
+        .expressionString);
+  });
+
+  test('rate can be in seconds', () => {
+    expect('rate(2 minutes)').toEqual(
+      ScheduleExpression.rate(Duration.seconds(120))
+        .expressionString);
+  });
+
+  test('rate must not be in seconds when specified as a token', () => {
+    expect(() => {
+      ScheduleExpression.rate(Duration.seconds(Lazy.number({ produce: () => 5 })));
+    }).toThrow(/Allowed units for scheduling/);
+  });
+
+  test('one-time expression string has expected date', () => {
+    const x = ScheduleExpression.at(new Date(2022, 10, 20, 19, 20, 23));
+    expect(x.expressionString).toEqual('at(2022-11-20T19:20:23)');
+  });
+
+  test('one-time expression time zone is UTC if not provided', () => {
+    const x = ScheduleExpression.at(new Date(2022, 10, 20, 19, 20, 23));
+    expect(x.timeZone).toEqual(TimeZone.ETC_UTC);
+  });
+
+  test('one-time expression has expected time zone if provided', () => {
+    const x = ScheduleExpression.at(new Date(2022, 10, 20, 19, 20, 23), TimeZone.EUROPE_LONDON);
+    expect(x.expressionString).toEqual('at(2022-11-20T19:20:23)');
+    expect(x.timeZone).toEqual(TimeZone.EUROPE_LONDON);
+  });
+
+  test('one-time expression milliseconds ignored', () => {
+    const x = ScheduleExpression.at(new Date(Date.UTC(2022, 10, 20, 19, 20, 23, 111)));
+    expect(x.expressionString).toEqual('at(2022-11-20T19:20:23)');
+  });
+
+  test('one-time expression with invalid date throws', () => {
+    expect(() => ScheduleExpression.at(new Date('13-20-1969'))).toThrowError('Invalid date');
+  });
+});
+
+describe('fractional minutes checks', () => {
+  test('rate cannot be a fractional amount of minutes (defined with seconds)', () => {
+    expect(() => {
+      ScheduleExpression.rate(Duration.seconds(150));
+    }).toThrow(/cannot be converted into a whole number of/);
+  });
+
+  test('rate cannot be a fractional amount of minutes (defined with minutes)', () => {
+    expect(()=> {
+      ScheduleExpression.rate(Duration.minutes(5/3));
+    }).toThrow(/must be a whole number of/);
+  });
+
+  test('rate cannot be a fractional amount of minutes (defined with hours)', () => {
+    expect(()=> {
+      ScheduleExpression.rate(Duration.hours(1.03));
+    }).toThrow(/cannot be converted into a whole number of/);
+  });
+
+  test('rate cannot be less than 1 minute (defined with seconds)', () => {
+    expect(() => {
+      ScheduleExpression.rate(Duration.seconds(30));
+    }).toThrow(/'30 seconds' cannot be converted into a whole number of minutes./);
+  });
+
+  test('rate cannot be less than 1 minute (defined with minutes as fractions)', () => {
+    expect(() => {
+      ScheduleExpression.rate(Duration.minutes(1/2));
+    }).toThrow(/must be a whole number of/);
+  });
+
+  test('rate cannot be less than 1 minute (defined with minutes as decimals)', () => {
+    expect(() => {
+      ScheduleExpression.rate(Duration.minutes(0.25));
+    }).toThrow(/must be a whole number of/);
+  });
+
+  test('rate can be in minutes', () => {
+    expect('rate(10 minutes)').toEqual(
+      ScheduleExpression.rate(Duration.minutes(10))
+        .expressionString);
+  });
+});