@strav/queue 0.3.19 → 0.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/queue",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "type": "module",
   "description": "Background job processing and task scheduling for the Strav framework",
   "license": "MIT",
@@ -28,8 +28,8 @@
     "./providers/*": "./src/providers/*.ts"
   },
   "peerDependencies": {
-    "@strav/kernel": "0.3.19",
-    "@strav/database": "0.3.19"
+    "@strav/kernel": "0.3.21",
+    "@strav/database": "0.3.21"
   },
   "scripts": {
     "test": "bun test tests/",

package/src/scheduler/schedule.ts

@@ -38,6 +38,7 @@ export class Schedule {
 
   private _cron: CronExpression | null = null
   private _noOverlap = false
+  private _runImmediately = false
 
   private _sporadicMin: number | null = null
   private _sporadicMax: number | null = null
@@ -179,6 +180,22 @@ export class Schedule {
     return this
   }
 
+  /**
+   * Execute this task immediately upon registration, then follow the configured schedule.
+   * Useful for bootstrap tasks, cache warming, or ensuring tasks run on deployment.
+   */
+  runImmediately(): this {
+    this._runImmediately = true
+
+    // Execute the handler immediately
+    this.executeHandler().catch(error => {
+      const message = error instanceof Error ? error.message : String(error)
+      console.error(`[scheduler] Immediate execution of "${this.name}" failed: ${message}`)
+    })
+
+    return this
+  }
+
   // ── Internal ──────────────────────────────────────────────────────────────
 
   /** Check if this task is due at the given Date (evaluated in UTC). */
@@ -201,6 +218,11 @@ export class Schedule {
     return this._noOverlap
   }
 
+  /** Whether this task should run immediately upon registration. */
+  get shouldRunImmediately(): boolean {
+    return this._runImmediately
+  }
+
   /** The parsed cron expression (for testing/debugging). */
   get expression(): CronExpression | null {
     return this._cron
@@ -211,6 +233,14 @@ export class Schedule {
     return this._nextRunAt
   }
 
+  /** Execute the task handler, handling both sync and async cases. */
+  private async executeHandler(): Promise<void> {
+    const result = this.handler()
+    if (result instanceof Promise) {
+      await result
+    }
+  }
+
   /** Compute the next random run time from a reference point. */
   private computeNextRun(from: Date): Date {
     const ms = unitToMs(this._sporadicUnit!)

package/src/scheduler/scheduler.ts

@@ -40,6 +40,30 @@ export default class Scheduler {
     return Scheduler._tasks.filter(t => t.isDue(date))
   }
 
+  /**
+   * Manually execute a task by name immediately.
+   *
+   * @param name The name of the task to execute
+   * @returns Promise that resolves when the task completes
+   * @throws Error if task is not found
+   */
+  static async runNow(name: string): Promise<void> {
+    const task = Scheduler._tasks.find(t => t.name === name)
+    if (!task) {
+      throw new Error(`Task "${name}" not found. Available tasks: ${Scheduler._tasks.map(t => t.name).join(', ')}`)
+    }
+
+    try {
+      const result = task.handler()
+      if (result instanceof Promise) {
+        await result
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(`Manual execution of task "${name}" failed: ${message}`)
+    }
+  }
+
   /** Clear all registered tasks. For testing. */
   static reset(): void {
     Scheduler._tasks = []