Merge pull request #266 from renejfc/fix/typesafe-constructor

fix(types): improve type-safety for cron callback functions

docs/src/usage/examples.md

@@ -63,7 +63,7 @@ console.log('Will run first time at', job.nextRun().toLocaleString());
 ### Interval
 ```ts
 // Trigger on specific interval combined with cron expression
-Cron('* * 7-16 * * MON-FRI', { interval: 90 }, function () {
+new Cron('* * 7-16 * * MON-FRI', { interval: 90 }, function () {
 	console.log('This will trigger every 90th second at 7-16 on mondays to fridays.');
 });
 ```
@@ -214,7 +214,7 @@ const blockForAWhile = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 const protectCallback = (job) => console.log(`Call at ${new Date().toISOString()} were blocked by call started at ${job.currentRun().toISOString()}`);
 
 // protect: can be set to ether true or a callback function, to enable over-run protection
-Cron("* * * * * *", { protect: protectCallback }, async (job) => {
+new Cron("* * * * * *", { protect: protectCallback }, async (job) => {
     console.log(`Call started at ${job.currentRun().toISOString()} started`);
     await blockForAWhile(4000);
     console.log(`Call started at ${job.currentRun().toISOString()} finished ${new Date().toISOString()}`);

src/croner.ts

@@ -31,7 +31,7 @@
 import { CronDate } from "./date.ts";
 import { CronPattern } from "./pattern.ts";
 import { type CronOptions, CronOptionsHandler } from "./options.ts";
-import { isFunction, unrefTimer } from "./utils.ts";
+import { isCronCallback, isFunction, unrefTimer } from "./utils.ts";
 
 /**
  * Many JS engines stores the delay as a 32-bit signed integer internally.
@@ -84,6 +84,19 @@ type CronState = {
   pattern: CronPattern;
 };
 
+/**
+ * Callback function type
+ *
+ * @param self - Reference to the Cron instance that triggered the callback
+ * @param context - Optional context value passed through options.context
+ *
+ * @returns void or Promise<void> for async callbacks
+ */
+export type CronCallback = (
+  self: InstanceType<typeof Cron>,
+  context: unknown,
+) => void | Promise<void>;
+
 /**
  * Cron entrypoint
  *
@@ -96,11 +109,11 @@ class Cron {
   name: string | undefined;
   options: CronOptions;
   private _states: CronState;
-  private fn?: Function;
+  private fn?: CronCallback;
   constructor(
     pattern: string | Date,
-    fnOrOptions1?: CronOptions | Function,
-    fnOrOptions2?: CronOptions | Function,
+    fnOrOptions1?: CronOptions | CronCallback,
+    fnOrOptions2?: CronOptions | CronCallback,
   ) {
     // Make options and func optional and interchangable
     let options, func;
@@ -164,8 +177,8 @@ class Cron {
     }
 
     // Allow shorthand scheduling
-    if (func !== void 0 && isFunction(func)) {
-      this.fn = func as Function;
+    if (func !== void 0 && isCronCallback(func)) {
+      this.fn = func;
       this.schedule();
     }
 
@@ -339,7 +352,7 @@ class Cron {
    *
    * @param func - Function to be run each iteration of pattern
    */
-  public schedule(func?: Function): Cron {
+  public schedule(func?: CronCallback): Cron {
     // If a function is already scheduled, bail out
     if (func && this.fn) {
       throw new Error(

src/utils.ts

@@ -1,3 +1,5 @@
+import type { CronCallback } from "./croner.ts";
+
 /**
  * Helper function to check if a variable is a function.
  *
@@ -13,6 +15,17 @@ function isFunction(v: unknown) {
   );
 }
 
+/**
+ * Type guard to check if a variable is a valid CronCallback function.
+ *
+ * @param v The variable to check.
+ * @returns Type predicate indicating if the variable is a CronCallback.
+ * @private
+ */
+export function isCronCallback(v: unknown): v is CronCallback {
+  return isFunction(v);
+}
+
 /**
  * Helper function to unref a timer in both Deno and Node.js.
  *

test/croner.test.ts

@@ -108,9 +108,9 @@ test(
   //@ts-ignore
   timeout(2000, (resolve, reject) => {
     const c = { a: "b" };
-    new Cron("* * * * * *", { context: c }, (self: Cron, context: { a: string }) => {
+    new Cron("* * * * * *", { context: c }, (self, context) => {
       self.stop();
-      if (!context || (context && context.a && context.a !== "b")) {
+      if (typeof context !== "object" || !context || !("a" in context) || context.a !== "b") {
         reject(new Error("Failure"));
       } else {
         resolve();