Use duration field for cronjobs

Author: Mrtenz

packages/snaps-controllers/src/cronjob/CronjobController.ts

@@ -17,7 +17,11 @@ import { castDraft } from 'immer';
 import { DateTime } from 'luxon';
 import { nanoid } from 'nanoid';
 
-import { getCurrentDate, getExecutionDate } from './utils';
+import {
+  getCronjobSpecificationSchedule,
+  getCurrentDate,
+  getExecutionDate,
+} from './utils';
 import type {
   GetAllSnaps,
   HandleSnapRequest,
@@ -441,7 +445,7 @@ export class CronjobController extends BaseController<
         snapId,
         id: `cronjob-${snapId}-${idx}`,
         request: definition.request,
-        schedule: definition.expression,
+        schedule: getCronjobSpecificationSchedule(definition),
         recurring: true,
       };
     });

packages/snaps-controllers/src/cronjob/utils.test.ts

@@ -1,8 +1,32 @@
-import { getCurrentDate, getExecutionDate } from './utils';
+import {
+  getCronjobSpecificationSchedule,
+  getCurrentDate,
+  getExecutionDate,
+} from './utils';
 
 jest.useFakeTimers();
 jest.setSystemTime(1747994147000);
 
+describe('getCronjobSpecificationSchedule', () => {
+  it('returns the duration if specified', () => {
+    const specification = {
+      duration: 'PT1H',
+      request: { method: 'foo' },
+    };
+
+    expect(getCronjobSpecificationSchedule(specification)).toBe('PT1H');
+  });
+
+  it('returns the expression if no duration is specified', () => {
+    const specification = {
+      expression: '0 0 * * *',
+      request: { method: 'foo' },
+    };
+
+    expect(getCronjobSpecificationSchedule(specification)).toBe('0 0 * * *');
+  });
+});
+
 describe('getCurrentDate', () => {
   it('returns the current date in ISO 8601 format without milliseconds', () => {
     expect(getCurrentDate()).toBe('2025-05-23T09:55:47Z');

packages/snaps-controllers/src/cronjob/utils.ts

@@ -1,7 +1,29 @@
-import { assert } from '@metamask/utils';
+import type { CronjobSpecification } from '@metamask/snaps-utils';
+import { assert, hasProperty } from '@metamask/utils';
 import { parseExpression } from 'cron-parser';
 import { DateTime, Duration } from 'luxon';
 
+/**
+ * Get the schedule from a cronjob specification.
+ *
+ * This function assumes the cronjob specification is valid and contains
+ * either a `duration` or an `expression` property.
+ *
+ * @param specification - The cronjob specification to extract the schedule
+ * from.
+ * @returns The schedule of the cronjob, which can be either an ISO 8601
+ * duration or a cron expression.
+ */
+export function getCronjobSpecificationSchedule(
+  specification: CronjobSpecification,
+) {
+  if (hasProperty(specification, 'duration')) {
+    return specification.duration as string;
+  }
+
+  return specification.expression;
+}
+
 /**
  * Get a duration with a minimum of 1 second. This function assumes the provided
  * duration is valid.

packages/snaps-utils/coverage.json

@@ -2,5 +2,5 @@
   "branches": 99.76,
   "functions": 99.02,
   "lines": 98.66,
-  "statements": 97.25
+  "statements": 97.32
 }

packages/snaps-utils/src/cronjob.test.ts

@@ -1,69 +1,113 @@
+import { create } from '@metamask/superstruct';
+
 import {
+  CronjobSpecificationStruct,
   isCronjobSpecification,
   isCronjobSpecificationArray,
-  parseCronExpression,
 } from './cronjob';
 
-describe('Cronjob Utilities', () => {
-  describe('isCronjobSpecification', () => {
-    it('returns true for a valid cronjob specification', () => {
-      const cronjobSpecification = {
-        expression: '* * * * *',
+describe('CronjobSpecificationStruct', () => {
+  it.each([
+    ['100 * * * * *', 'Expected an object, but received: "100 * * * * *"'],
+    ['PT10S', 'Expected an object, but received: "PT10S"'],
+    [
+      {
+        expression: '100 * * * * *',
         request: {
           method: 'exampleMethodOne',
           params: ['p1'],
         },
-      };
-      expect(isCronjobSpecification(cronjobSpecification)).toBe(true);
-    });
-
-    it('returns false for an invalid cronjob specification', () => {
-      const cronjobSpecification = {
-        expression: '* * * * * * * * * * *',
+      },
+      'At path: expression -- Expected a cronjob expression, but received: "100 * * * * *"',
+    ],
+    [
+      {
+        duration: '10S',
+        request: {
+          method: 'exampleMethodOne',
+          params: ['p1'],
+        },
+      },
+      'At path: duration -- Not a valid ISO 8601 duration',
+    ],
+    [
+      {
         request: {
           method: 'exampleMethodOne',
           params: ['p1'],
         },
-      };
-      expect(isCronjobSpecification(cronjobSpecification)).toBe(false);
-    });
+      },
+      'At path: expression -- Expected a string, but received: undefined',
+    ],
+  ])('return a readable error for %p', (value, error) => {
+    expect(() => create(value, CronjobSpecificationStruct)).toThrow(error);
   });
+});
 
-  describe('isCronjobSpecificationArray', () => {
-    it('returns true for a valid cronjob specification array', () => {
-      const cronjobSpecificationArray = [
-        {
-          expression: '* * * * *',
-          request: {
-            method: 'exampleMethodOne',
-            params: ['p1'],
-          },
-        },
-      ];
-      expect(isCronjobSpecificationArray(cronjobSpecificationArray)).toBe(true);
-    });
+describe('isCronjobSpecification', () => {
+  it('returns true for a valid cronjob specification with an expression', () => {
+    const cronjobSpecification = {
+      expression: '* * * * *',
+      request: {
+        method: 'exampleMethodOne',
+        params: ['p1'],
+      },
+    };
+    expect(isCronjobSpecification(cronjobSpecification)).toBe(true);
+  });
 
-    it('returns false for an invalid cronjob specification array', () => {
-      const cronjobSpecificationArray = {
+  it('returns true for a valid cronjob specification with a duration', () => {
+    const cronjobSpecification = {
+      duration: 'PT10S',
+      request: {
+        method: 'exampleMethodOne',
+        params: ['p1'],
+      },
+    };
+    expect(isCronjobSpecification(cronjobSpecification)).toBe(true);
+  });
+
+  it('returns false for an invalid cronjob specification', () => {
+    const cronjobSpecification = {
+      expression: '* * * * * * * * * * *',
+      request: {
+        method: 'exampleMethodOne',
+        params: ['p1'],
+      },
+    };
+    expect(isCronjobSpecification(cronjobSpecification)).toBe(false);
+  });
+});
+
+describe('isCronjobSpecificationArray', () => {
+  it('returns true for a valid cronjob specification array', () => {
+    const cronjobSpecificationArray = [
+      {
         expression: '* * * * *',
         request: {
           method: 'exampleMethodOne',
           params: ['p1'],
         },
-      };
-      expect(isCronjobSpecificationArray(cronjobSpecificationArray)).toBe(
-        false,
-      );
-    });
+      },
+      {
+        duration: 'PT10S',
+        request: {
+          method: 'exampleMethodOne',
+          params: ['p1'],
+        },
+      },
+    ];
+    expect(isCronjobSpecificationArray(cronjobSpecificationArray)).toBe(true);
   });
 
-  describe('parseCronExpression', () => {
-    it('successfully parses cronjob expression that is provided as a string', () => {
-      const cronjobExpression = '* * * * *';
-
-      const parsedExpression = parseCronExpression(cronjobExpression);
-      expect(parsedExpression.next()).toBeDefined();
-      expect(typeof parsedExpression.next().getTime()).toBe('number');
-    });
+  it('returns false for an invalid cronjob specification array', () => {
+    const cronjobSpecificationArray = {
+      expression: '* * * * *',
+      request: {
+        method: 'exampleMethodOne',
+        params: ['p1'],
+      },
+    };
+    expect(isCronjobSpecificationArray(cronjobSpecificationArray)).toBe(false);
   });
 });

packages/snaps-utils/src/cronjob.ts

@@ -1,4 +1,4 @@
-import { union } from '@metamask/snaps-sdk';
+import { selectiveUnion } from '@metamask/snaps-sdk';
 import type { Infer } from '@metamask/superstruct';
 import {
   array,
@@ -9,6 +9,8 @@ import {
   string,
 } from '@metamask/superstruct';
 import {
+  hasProperty,
+  isObject,
   JsonRpcIdStruct,
   JsonRpcParamsStruct,
   JsonRpcVersionStruct,
@@ -34,29 +36,31 @@ export const CronExpressionStruct = refine(
       parseExpression(value);
       return true;
     } catch {
-      return false;
+      return `Expected a cronjob expression, but received: "${value}"`;
     }
   },
 );
 
 export type CronExpression = Infer<typeof CronExpressionStruct>;
 
-/**
- * Parses a cron expression.
- *
- * @param expression - Expression to parse.
- * @returns A CronExpression class instance.
- */
-export function parseCronExpression(expression: string | object) {
-  const ensureStringExpression = create(expression, CronExpressionStruct);
-  return parseExpression(ensureStringExpression);
-}
+const CronjobExpressionSpecificationStruct = object({
+  expression: CronExpressionStruct,
+  request: CronjobRpcRequestStruct,
+});
 
-export const CronjobSpecificationStruct = object({
-  expression: union([CronExpressionStruct, ISO8601DurationStruct]),
+const CronjobDurationSpecificationStruct = object({
+  duration: ISO8601DurationStruct,
   request: CronjobRpcRequestStruct,
 });
 
+export const CronjobSpecificationStruct = selectiveUnion((value) => {
+  if (isObject(value) && hasProperty(value, 'duration')) {
+    return CronjobDurationSpecificationStruct;
+  }
+
+  return CronjobExpressionSpecificationStruct;
+});
+
 export type CronjobSpecification = Infer<typeof CronjobSpecificationStruct>;
 
 /**