Make backfillPeriod optional in exported CronItem type (#516)

RELEASE_NOTES.md

@@ -43,6 +43,7 @@ Read more:
   experimental!
 - `helpers.abortPromise` added; will reject when `abortSignal` aborts (useful
   for `Promise.race()`)
+- `backfillPeriod` is now marked as optional in TypeScript (defaults to 0).
 
 ## v0.16.6
 

__tests__/crontab.test.ts

@@ -1,5 +1,5 @@
 import { CronItemOptions, ParsedCronMatch } from "../src";
-import { parseCrontab } from "../src/crontab";
+import { parseCronItem, parseCrontab } from "../src/crontab";
 
 // 0...59
 const ALL_MINUTES = Array.from(Array(60).keys());
@@ -237,3 +237,26 @@ describe("gives error on syntax error", () => {
     );
   });
 });
+
+describe("parses JS cron items correctly", () => {
+  test("defaults backfillPeriod to 0", () => {
+    expect(
+      parseCronItem({
+        task: "task",
+        match: "* * * * *",
+        options: {},
+      }).options.backfillPeriod,
+    ).toEqual(0);
+  });
+
+  test("validates match strings", () => {
+    const matchString = "foo";
+    expect(() =>
+      parseCronItem({
+        task: "task",
+        match: matchString,
+        options: {},
+      }),
+    ).toThrow(`Invalid cron pattern '${matchString}' in parseCronItem call`);
+  });
+});

src/crontab.ts

@@ -20,6 +20,7 @@ import {
   CronItem,
   CronItemOptions,
   ParsedCronItem,
+  ParsedCronItemOptions,
 } from "./interfaces";
 import { coerceError } from "./lib";
 
@@ -60,7 +61,7 @@ const parseTimePhrase = (timePhrase: string): number => {
 const parseCrontabOptions = (
   lineNumber: number,
   optionsString: string | undefined,
-): { options: CronItemOptions; identifier: string | undefined } => {
+): { options: ParsedCronItemOptions; identifier: string | undefined } => {
   const parsed = optionsString != null ? parse(optionsString) : {};
   let backfillPeriod: number | undefined = undefined;
   let maxAttempts: number | undefined = undefined;
@@ -149,9 +150,8 @@ const parseCrontabOptions = (
     }
   });
 
-  if (!backfillPeriod) {
-    backfillPeriod = 0;
-  }
+  // Apply some sensible defaults
+  backfillPeriod ??= 0;
   if (!jobKeyMode && jobKey) {
     jobKeyMode = "replace";
   }
@@ -294,7 +294,7 @@ export const parseCronItem = (
   const {
     match: rawMatch,
     task,
-    options = {} as CronItemOptions,
+    options,
     payload = {},
     identifier = task,
   } = cronItem;
@@ -308,11 +308,17 @@ export const parseCronItem = (
   if (typeof match !== "function") {
     throw new Error("Invalid 'match' configuration");
   }
+
+  const parsedOptions: ParsedCronItemOptions = {
+    ...options,
+    backfillPeriod: options?.backfillPeriod ?? 0,
+  };
+
   return {
     [$$isParsed]: true,
     match,
     task,
-    options,
+    options: parsedOptions,
     payload,
     identifier,
   };

src/interfaces.ts

@@ -331,7 +331,7 @@ export interface WatchedCronItems {
  */
 export interface CronItemOptions {
   /** How far back (in milliseconds) should we backfill jobs when worker starts? (Only backfills since when the identifier was first used.) */
-  backfillPeriod: number;
+  backfillPeriod?: number;
 
   /** Optionally override the default job max_attempts */
   maxAttempts?: number;
@@ -353,6 +353,10 @@ export interface CronItemOptions {
   jobKeyMode?: "replace" | "preserve_run_at";
 }
 
+export interface ParsedCronItemOptions extends CronItemOptions {
+  backfillPeriod: number;
+}
+
 /**
  * Crontab ranges from the minute, hour, day of month, month and day of week
  * parts of the crontab line
@@ -419,7 +423,7 @@ export interface ParsedCronItem {
   task: string;
 
   /** Options influencing backfilling and properties of the scheduled job */
-  options: CronItemOptions;
+  options: ParsedCronItemOptions;
 
   /** A payload object to merge into the default cron payload object for the scheduled job */
   payload: { [key: string]: unknown } | null;