@stacksjs/scheduler 0.70.23 → 0.70.26

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+// export { Schedule } from './schedule'
+export * from './run';
+export * from './schedule';
+export * from './types';

package/dist/src/run.d.ts

@@ -0,0 +1,2 @@
+import type { Err, Ok } from '@stacksjs/error-handling';
+export declare function runScheduler(): Promise<Ok<string, never> | Err<string, any>>;

package/dist/src/schedule.d.ts

@@ -0,0 +1,73 @@
+import type { CatchCallbackFn } from '@stacksjs/cron';
+import type { ScheduledJob, TimedSchedule, Timezone, UntimedSchedule } from './types';
+/**
+ * Get the next run time for a cron expression.
+ *
+ * @param cronExpression - Standard 5-field cron expression or nickname
+ * @returns The next Date the expression matches, or null
+ */
+export declare function sendAt(cronExpression: string | Date): Date | null;
+/**
+ * Get the number of milliseconds until the next run of a cron expression.
+ *
+ * @param cronExpression - Standard 5-field cron expression or nickname
+ * @returns Milliseconds until next run, or -1 if no upcoming run
+ */
+export declare function timeout(cronExpression: string | Date): number;
+export declare const schedule: Scheduler;
+export type Scheduler = typeof Schedule;
+/**
+ * Schedule class for creating and managing scheduled tasks.
+ *
+ * Uses standard 5-field cron patterns (minute hour day month weekday)
+ * powered by `@stacksjs/cron` — auto-upgrades to native `Bun.cron.parse()`
+ * when available.
+ *
+ * @example
+ * ```ts
+ * import { schedule } from '@stacksjs/scheduler'
+ *
+ * schedule.job('Inspire').hourly().setTimeZone('America/Los_Angeles')
+ * schedule.action('CleanupTempFiles').everyFiveMinutes()
+ * schedule.command('echo "maintenance"').daily()
+ * ```
+ */
+export declare class Schedule implements UntimedSchedule {
+  constructor(task: () => void);
+  get pattern(): string;
+  everySecond(): TimedSchedule;
+  everyMinute(): TimedSchedule;
+  everyTwoMinutes(): TimedSchedule;
+  everyFiveMinutes(): TimedSchedule;
+  everyTenMinutes(): TimedSchedule;
+  everyThirtyMinutes(): TimedSchedule;
+  everyHour(): TimedSchedule;
+  everyDay(): TimedSchedule;
+  hourly(): TimedSchedule;
+  daily(): TimedSchedule;
+  weekly(): TimedSchedule;
+  monthly(): TimedSchedule;
+  yearly(): TimedSchedule;
+  annually(): TimedSchedule;
+  onDays(days: number[]): TimedSchedule;
+  at(time: string): TimedSchedule;
+  setTimeZone(timezone: Timezone): this;
+  withErrorHandler(handler: CatchCallbackFn): this;
+  withMaxRuns(runs: number): this;
+  withProtection(callback?: (job: ScheduledJob) => void): this;
+  withName(name: string): this;
+  withContext(context: any): this;
+  withInterval(seconds: number): this;
+  between(startAt: string | Date, stopAt: string | Date): this;
+  withoutOverlapping(expiresAfterMinutes?: number): this;
+  onOneServer(): this;
+  runInBackground(): this;
+  static job(name: string): UntimedSchedule;
+  static action(name: string): UntimedSchedule;
+  static command(cmd: string): UntimedSchedule;
+  static gracefulShutdown(): Promise<void>;
+}
+export declare class Queue extends Schedule {
+
+}
+export default Schedule;

package/dist/{types.d.ts → src/types.d.ts}

@@ -1,7 +1,46 @@
-import type { CatchCallbackFn, Cron } from '@stacksjs/cron';
-
-export declare type Timezone =
-  | 'Africa/Abidjan'
+import type { CatchCallbackFn } from '@stacksjs/cron';
+export declare interface ScheduledJob {
+  stop: () => void
+  nextRun: () => Date | null
+}
+// Base interface for common methods
+export declare interface BaseSchedule {
+  withErrorHandler: (handler: CatchCallbackFn) => this
+  withMaxRuns: (runs: number) => this
+  withProtection: (callback?: (job: ScheduledJob) => void) => this
+  withName: (name: string) => this
+  withContext: (context: any) => this
+  withInterval: (seconds: number) => this
+  between: (startAt: string | Date, stopAt: string | Date) => this
+  setTimeZone: (timezone: Timezone) => this
+  withoutOverlapping: (expiresAfterMinutes?: number) => this
+  onOneServer: () => this
+  runInBackground: () => this
+}
+// Interface for schedule after timing is set
+export declare interface TimedSchedule extends BaseSchedule {
+}
+// Interface for schedule before timing is set
+export declare interface UntimedSchedule extends BaseSchedule {
+  everySecond: () => TimedSchedule
+  everyMinute: () => TimedSchedule
+  everyTwoMinutes: () => TimedSchedule
+  everyFiveMinutes: () => TimedSchedule
+  everyTenMinutes: () => TimedSchedule
+  everyThirtyMinutes: () => TimedSchedule
+  everyHour: () => TimedSchedule
+  everyDay: () => TimedSchedule
+  hourly: () => TimedSchedule
+  daily: () => TimedSchedule
+  weekly: () => TimedSchedule
+  monthly: () => TimedSchedule
+  yearly: () => TimedSchedule
+  annually: () => TimedSchedule
+  onDays: (days: number[]) => TimedSchedule
+  at: (time: string) => TimedSchedule
+}
+// IANA Timezone
+export type Timezone = | 'Africa/Abidjan'
   | 'Africa/Accra'
   | 'Africa/Addis_Ababa'
   | 'Africa/Algiers'
@@ -65,37 +104,4 @@ export declare type Timezone =
   | 'Pacific/Auckland'
   | 'Pacific/Fiji'
   | 'Pacific/Honolulu'
-  | 'UTC'
-
-export interface BaseSchedule {
-  withErrorHandler: (handler: CatchCallbackFn) => this
-  withMaxRuns: (runs: number) => this
-  withProtection: (callback?: (job: Cron) => void) => this
-  withName: (name: string) => this
-  withContext: (context: any) => this
-  withInterval: (seconds: number) => this
-  between: (startAt: string | Date, stopAt: string | Date) => this
-  setTimeZone: (timezone: Timezone) => this
-}
-
-export interface TimedSchedule extends BaseSchedule {
-}
-
-export interface UntimedSchedule extends BaseSchedule {
-  everySecond: () => TimedSchedule
-  everyMinute: () => TimedSchedule
-  everyTwoMinutes: () => TimedSchedule
-  everyFiveMinutes: () => TimedSchedule
-  everyTenMinutes: () => TimedSchedule
-  everyThirtyMinutes: () => TimedSchedule
-  everyHour: () => TimedSchedule
-  everyDay: () => TimedSchedule
-  hourly: () => TimedSchedule
-  daily: () => TimedSchedule
-  weekly: () => TimedSchedule
-  monthly: () => TimedSchedule
-  yearly: () => TimedSchedule
-  annually: () => TimedSchedule
-  onDays: (days: number[]) => TimedSchedule
-  at: (time: string) => TimedSchedule
-}
+  | 'UTC';

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/scheduler",
   "type": "module",
-  "version": "0.70.23",
+  "version": "0.70.26",
   "description": "The Stacks scheduler.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/scheduler#readme",
@@ -16,26 +18,38 @@
   "bugs": {
     "url": "https://github.com/stacksjs/stacks/issues"
   },
-  "keywords": ["scheduler", "node-cron", "jobs", "bun", "stacks"],
+  "keywords": [
+    "scheduler",
+    "node-cron",
+    "jobs",
+    "bun",
+    "stacks"
+  ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
       "import": "./dist/index.js"
     },
     "./*": {
+      "bun": "./src/*",
       "import": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["README.md", "dist"],
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@stacksjs/actions": "0.70.22",
-    "@stacksjs/cron": "0.70.22",
-    "@stacksjs/development": "0.70.22"
+    "@stacksjs/actions": "0.70.23",
+    "@stacksjs/cron": "0.70.23",
+    "better-dx": "^0.2.12"
   }
 }

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export * from './run'
-export * from './schedule'
-export * from './types'

package/dist/run.d.ts

@@ -1,7 +0,0 @@
-import type { Err } from '@stacksjs/error-handling';
-import type { JobOptions } from '@stacksjs/types';
-
-export declare function runScheduler(): Promise<Ok<string, never> | Err<string, any>>;
-declare function runSchedulerInstance(): Promise<void>;
-declare function executeJobRate(jobName: string, rate: string): void;
-declare function getJobName(job: JobOptions, jobPath: string): string;

package/dist/schedule.d.ts

@@ -1,239 +0,0 @@
-import type { CatchCallbackFn, CronOptions } from '@stacksjs/cron';
-import type { TimedSchedule, Timezone, UntimedSchedule } from './types';
-
-export declare class Schedule implements UntimedSchedule {
-  private static jobs = new Map<string, Cron>()
-  private cronPattern = ''
-  private timezone: Timezone = 'America/Los_Angeles'
-  private readonly task: () => void
-  private options: {
-    timezone?: string
-    catch?: CatchCallbackFn
-    maxRuns?: number
-    protect?: boolean | ((job: Cron) => void)
-    name?: string
-    context?: any
-    interval?: number
-    startAt?: string | Date
-    stopAt?: string | Date
-  } = {}
-
-  constructor(task: () => void) {
-    this.task = task
-    setTimeout(() => this.start(), 0)
-  }
-
-  everySecond(): TimedSchedule {
-    this.cronPattern = '* * * * * *'
-    return this as TimedSchedule
-  }
-
-  everyMinute(): TimedSchedule {
-    this.cronPattern = '0 * * * * *'
-    return this as TimedSchedule
-  }
-
-  everyTwoMinutes(): TimedSchedule {
-    this.cronPattern = '*/2 * * * * *'
-    return this as TimedSchedule
-  }
-
-  everyFiveMinutes(): TimedSchedule {
-    this.cronPattern = '*/5 * * * *'
-    return this as TimedSchedule
-  }
-
-  everyTenMinutes(): TimedSchedule {
-    this.cronPattern = '*/10 * * * *'
-    return this as TimedSchedule
-  }
-
-  everyThirtyMinutes(): TimedSchedule {
-    this.cronPattern = '*/30 * * * *'
-    return this as TimedSchedule
-  }
-
-  everyHour(): TimedSchedule {
-    this.cronPattern = '0 0 * * * *'
-    return this as TimedSchedule
-  }
-
-  everyDay(): TimedSchedule {
-    this.cronPattern = '0 0 0 * * *'
-    return this as TimedSchedule
-  }
-
-  hourly(): TimedSchedule {
-    this.cronPattern = '0 0 * * * *'
-    return this as TimedSchedule
-  }
-
-  daily(): TimedSchedule {
-    this.cronPattern = '0 0 0 * * *'
-    return this as TimedSchedule
-  }
-
-  weekly(): TimedSchedule {
-    this.cronPattern = '0 0 0 * * 0'
-    return this as TimedSchedule
-  }
-
-  monthly(): TimedSchedule {
-    this.cronPattern = '0 0 0 1 * *'
-    return this as TimedSchedule
-  }
-
-  yearly(): TimedSchedule {
-    this.cronPattern = '0 0 0 1 1 *'
-    return this as TimedSchedule
-  }
-
-  annually(): TimedSchedule {
-    this.cronPattern = '0 0 0 1 1 *'
-    return this as TimedSchedule
-  }
-
-  onDays(days: number[]): TimedSchedule {
-    const dayPattern = days.join(',')
-    this.cronPattern = `0 0 0 * * ${dayPattern}`
-    return this as TimedSchedule
-  }
-
-  at(time: string): TimedSchedule {
-    const [hour, minute] = time.split(':').map(Number)
-    this.cronPattern = `${minute} ${hour} * * *`
-    return this as TimedSchedule
-  }
-
-  setTimeZone(timezone: Timezone): this {
-    this.timezone = timezone
-    this.options.timezone = timezone
-    return this
-  }
-
-  withErrorHandler(handler: CatchCallbackFn): this {
-    this.options.catch = handler
-    return this
-  }
-
-  withMaxRuns(runs: number): this {
-    this.options.maxRuns = runs
-    return this
-  }
-
-  withProtection(callback?: (job: Cron) => void): this {
-    this.options.protect = callback || true
-    return this
-  }
-
-  withName(name: string): this {
-    this.options.name = name
-    return this
-  }
-
-  withContext(context: any): this {
-    this.options.context = context
-    return this
-  }
-
-  withInterval(seconds: number): this {
-    this.options.interval = seconds
-    return this
-  }
-
-  between(startAt: string | Date, stopAt: string | Date): this {
-    this.options.startAt = startAt
-    this.options.stopAt = stopAt
-    return this
-  }
-
-  private start(): Cron {
-    const job = new Cron(
-      this.cronPattern,
-      {
-        ...this.options,
-        timezone: this.timezone,
-      } as CronOptions,
-      this.task,
-    )
-
-    if (this.options.name) {
-      Schedule.jobs.set(this.options.name, job)
-    }
-
-    log.info(`Scheduled task with pattern: ${this.cronPattern} in timezone: ${this.timezone}`)
-    return job
-  }
-
-  static job(name: string): UntimedSchedule {
-    return new Schedule(async () => {
-      log.info(`Running job: ${name}`)
-      try {
-        await runJob(name)
-      }
-      catch (error) {
-        log.error(`Job ${name} failed:`, error)
-        throw error 
-      }
-    }).withName(name) as UntimedSchedule
-  }
-
-  static action(name: string): UntimedSchedule {
-    return new Schedule(async () => {
-      log.info(`Running action: ${name}`)
-      try {
-        await runAction(name)
-      }
-      catch (error) {
-        log.error(`Action ${name} failed:`, error)
-        throw error
-      }
-    }).withName(name) as UntimedSchedule
-  }
-
-  static command(cmd: string): UntimedSchedule {
-    return new Schedule(async () => {
-      try {
-        log.info(`Executing command: ${cmd}`)
-        const result = await runCommand(cmd)
-
-        if (result.isErr()) {
-          log.error(result.error)
-          throw result.error
-        }
-      }
-      catch (error) {
-        log.error(`Command execution failed: ${error}`)
-        throw error
-      }
-    }).withName(`command-${cmd}`) as UntimedSchedule
-  }
-
-  static async gracefulShutdown(): Promise<void> {
-    log.info('Gracefully shutting down scheduled jobs...')
-
-    const shutdownPromises = []
-
-    for (const [name, job] of Schedule.jobs) {
-      log.info(`Stopping job: ${name}`)
-      shutdownPromises.push(
-        new Promise<void>((resolve) => {
-          job.stop()
-          resolve()
-        }),
-      )
-    }
-
-    await Promise.all(shutdownPromises)
-    Schedule.jobs.clear()
-
-    log.info('All jobs have been stopped')
-  }
-}
-export declare class Job extends Schedule { }
-export declare function sendAt(cronTime: string | Date): Date | null;
-export declare function timeout(cronTime: string | Date): number;
-export declare type Scheduler = typeof Schedule
-export const schedule: Scheduler = Schedule
-
-export default Schedule