change to nested object for cron

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

packages/backend-tasks/README.md

@@ -22,7 +22,7 @@ const scheduler = TaskScheduler.fromConfig(rootConfig).forPlugin('my-plugin');
 
 await scheduler.scheduleTask({
   id: 'refresh_things',
-  cadence: '*/5 * * * *', // every 5 minutes
+  frequency: { cron: '*/5 * * * *' }, // every 5 minutes, also supports Duration
   timeout: Duration.fromObject({ minutes: 15 }),
   fn: async () => {
     await entityProvider.run();

packages/backend-tasks/api-report.md

@@ -36,7 +36,11 @@ export interface TaskRunner {
 
 // @public
 export interface TaskScheduleDefinition {
-  frequency: string | Duration;
+  frequency:
+    | {
+        cron: string;
+      }
+    | Duration;
   initialDelay?: Duration;
   timeout: Duration;
 }

packages/backend-tasks/package.json

@@ -48,14 +48,9 @@
     "zod": "^3.9.5"
   },
   "devDependencies": {
-<<<<<<< HEAD
     "@backstage/backend-test-utils": "^0.1.21-next.0",
     "@backstage/cli": "^0.15.2-next.0",
-=======
-    "@backstage/backend-test-utils": "^0.1.20",
-    "@backstage/cli": "^0.15.0",
     "@types/cron": "^1.7.3",
->>>>>>> ab18600147 (Add cron support to `@backstage/backend-tasks`)
     "jest": "^26.0.1",
     "wait-for-expect": "^3.0.2"
   },

packages/backend-tasks/src/tasks/PluginTaskSchedulerImpl.test.ts

@@ -68,7 +68,7 @@ describe('PluginTaskManagerImpl', () => {
         await manager.scheduleTask({
           id: 'task2',
           timeout: Duration.fromMillis(5000),
-          frequency: '* * * * * *',
+          frequency: { cron: '* * * * * *' },
           fn,
         });
 

packages/backend-tasks/src/tasks/PluginTaskSchedulerImpl.ts

@@ -46,8 +46,8 @@ export class PluginTaskSchedulerImpl implements PluginTaskScheduler {
       {
         version: 2,
         cadence:
-          typeof task.frequency === 'string'
-            ? task.frequency
+          'cron' in task.frequency
+            ? task.frequency.cron
             : task.frequency.toISO(),
         initialDelayDuration: task.initialDelay?.toISO(),
         timeoutAfterDuration: task.timeout.toISO(),

packages/backend-tasks/src/tasks/TaskScheduler.test.ts

@@ -69,7 +69,7 @@ describe('TaskScheduler', () => {
       await manager.scheduleTask({
         id: 'task2',
         timeout: Duration.fromMillis(5000),
-        frequency: '* * * * * *',
+        frequency: { cron: '* * * * * *' },
         fn,
       });
 

packages/backend-tasks/src/tasks/types.ts

@@ -38,18 +38,8 @@ export type TaskFunction =
  */
 export interface TaskScheduleDefinition {
   /**
-   * The maximum amount of time that a single task invocation can take, before
-   * it's considered timed out and gets "released" such that a new invocation
-   * is permitted to take place (possibly, then, on a different worker).
-   *
-   * This is a required field.
-   */
-  timeout: Duration;
-
-  /**
-   * The amount of time that should pass between task invocation starts.
-   * Essentially, this equals roughly how often you want the task to run.
-   * The system does its best to avoid overlapping invocations.
+   * How often you want the task to run. The system does its best to avoid
+   * overlapping invocations.
    *
    * This is a best effort value; under some circumstances there can be
    * deviations. For example, if the task runtime is longer than the frequency
@@ -57,24 +47,37 @@ export interface TaskScheduleDefinition {
    * invocation of this task will be delayed until after the previous one
    * finishes.
    *
-   * This value can be a crontab style string (see below), or an ISO period
-   * string (e.g. 'PT1M').
-   *
    * This is a required field.
-   *
-   * Cron expressions help:
-   *
-   *   ┌────────────── second (optional)
-   *   │ ┌──────────── minute
-   *   │ │ ┌────────── hour
-   *   │ │ │ ┌──────── day of month
-   *   │ │ │ │ ┌────── month
-   *   │ │ │ │ │ ┌──── day of week
-   *   │ │ │ │ │ │
-   *   │ │ │ │ │ │
-   *   * * * * * *
    */
-  frequency: string | Duration;
+  frequency:
+    | {
+        /**
+         * A crontab style string.
+         *
+         * Overview:
+         *
+         * ```
+         *   ┌────────────── second (optional)
+         *   │ ┌──────────── minute
+         *   │ │ ┌────────── hour
+         *   │ │ │ ┌──────── day of month
+         *   │ │ │ │ ┌────── month
+         *   │ │ │ │ │ ┌──── day of week
+         *   │ │ │ │ │ │
+         *   │ │ │ │ │ │
+         *   * * * * * *
+         * ```
+         */
+        cron: string;
+      }
+    | Duration;
+
+  /**
+   * The maximum amount of time that a single task invocation can take, before
+   * it's considered timed out and gets "released" such that a new invocation
+   * is permitted to take place (possibly, then, on a different worker).
+   */
+  timeout: Duration;
 
   /**
    * The amount of time that should pass before the first invocation happens.