@zerotal/scheduler 1.6.3 → 1.7.0

package/api-surface.md

@@ -0,0 +1,236 @@
+# @zerotal/scheduler — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class CronExpression = {
+  new (expression?: string): CronExpression
+  static describe: (expression: string) => string
+  static isValid: (expression: string) => boolean
+  static nextRunAfter: (expression: string, from?: Date) => Date | null
+  static readonly SEARCH_HORIZON_DAYS: number
+  dayOfMonth: (v: number | string) => CronExpression
+  hour: (v: number | string) => CronExpression
+  matches: (date?: Date) => boolean
+  minute: (v: number | string) => CronExpression
+  month: (v: number | string) => CronExpression
+  nextRun: (from?: Date) => Date | null
+  toString: () => string
+  weekday: (v: number | string) => CronExpression
+}
+
+class FileScheduleRunStore = {
+  new (_path: string, _keep?: number): FileScheduleRunStore
+  lastFor: (name: string) => ScheduleRunRecord | undefined
+  recent: (limit?: number, name?: string) => ScheduleRunRecord[]
+  record: (run: ScheduleRunRecord) => void
+}
+
+class Schedule = {
+  new (): Schedule
+  appendOutputTo?: string
+  between?: [string, string]
+  cron?: string
+  emailOutputTo?: string
+  environments?: string[]
+  frequency?: (every: SchedulerBuilder) => ScheduledTask
+  handle: () => void | Promise<void>
+  inBackground?: boolean
+  name?: string
+  pingAfter?: string
+  pingBefore?: string
+  pingOnFailure?: string
+  pingOnSuccess?: string
+  skip?: () => boolean | Promise<boolean>
+  timezone?: string
+  unlessBetween?: [string, string]
+  when?: () => boolean | Promise<boolean>
+  withoutOverlapping?: boolean | OverlapLockOptions
+}
+
+class ScheduledTask = {
+  new (name: string, schedule: string, callback: TaskCallback): ScheduledTask
+  static lockManager: LockManager | null
+  static outputMailer: OutputMailer | undefined
+  appendOutputTo: (path: string) => ScheduledTask
+  at: (time: string) => ScheduledTask
+  between: (start: string, end: string) => ScheduledTask
+  emailOutputTo: (email: string) => ScheduledTask
+  environments: (envs: string[]) => ScheduledTask
+  isRunning: boolean
+  lastDurationMs: number | undefined
+  lastOk: boolean | undefined
+  lastRunAt: Date | undefined
+  name: string
+  nextRunAt: (from?: Date) => Date | null
+  onFailure: (fn: (err: Error) => void | Promise<void>) => ScheduledTask
+  onStart: (fn: TaskHook) => ScheduledTask
+  onSuccess: (fn: () => void | Promise<void>) => ScheduledTask
+  pingAfter: (url: string) => ScheduledTask
+  pingBefore: (url: string) => ScheduledTask
+  pingOnFailure: (url: string) => ScheduledTask
+  pingOnSuccess: (url: string) => ScheduledTask
+  runInBackground: () => ScheduledTask
+  runNow: () => Promise<void>
+  schedule: string
+  sendOutputTo: (path: string) => ScheduledTask
+  skip: (predicate: TaskGuard) => ScheduledTask
+  start: () => void
+  stop: () => void
+  timezone: (tz: string) => ScheduledTask
+  unlessBetween: (start: string, end: string) => ScheduledTask
+  when: (predicate: TaskGuard) => ScheduledTask
+  withoutOverlapping: (options?: OverlapLockOptions) => ScheduledTask
+}
+
+class SchedulerBuilder = {
+  new (_manager: SchedulerManager, _name: string, _callback: TaskCallback): SchedulerBuilder
+  cron: (expression: string) => ScheduledTask
+  daily: () => ScheduledTask
+  dailyAt: (time: string) => ScheduledTask
+  days: (daysOfWeek: number[]) => ScheduledTask
+  everyFifteenMinutes: () => ScheduledTask
+  everyFiveMinutes: () => ScheduledTask
+  everyFiveSeconds: () => ScheduledTask
+  everyFourMinutes: () => ScheduledTask
+  everyMinute: () => ScheduledTask
+  everyOddHour: () => ScheduledTask
+  everySecond: () => ScheduledTask
+  everyTenMinutes: () => ScheduledTask
+  everyTenSeconds: () => ScheduledTask
+  everyThirtyMinutes: () => ScheduledTask
+  everyThirtySeconds: () => ScheduledTask
+  everyThreeMinutes: () => ScheduledTask
+  everyTwoMinutes: () => ScheduledTask
+  everyTwoSeconds: () => ScheduledTask
+  fridays: () => ScheduledTask
+  hourly: () => ScheduledTask
+  hourlyAt: (minute: number) => ScheduledTask
+  lastDayOfMonth: (time?: string) => ScheduledTask
+  mondays: () => ScheduledTask
+  monthly: () => ScheduledTask
+  quarterly: () => ScheduledTask
+  quarterlyOn: (dayOfMonth?: number, time?: string) => ScheduledTask
+  saturdays: () => ScheduledTask
+  sundays: () => ScheduledTask
+  thursdays: () => ScheduledTask
+  tuesdays: () => ScheduledTask
+  twiceDaily: (first?: number, second?: number) => ScheduledTask
+  twiceMonthly: (first?: number, second?: number) => ScheduledTask
+  twiceWeekly: (first?: number, second?: number) => ScheduledTask
+  wednesdays: () => ScheduledTask
+  weekdays: () => ScheduledTask
+  weekends: () => ScheduledTask
+  weekly: () => ScheduledTask
+  yearly: () => ScheduledTask
+  yearlyOn: (month?: number, dayOfMonth?: number, time?: string) => ScheduledTask
+}
+
+class SchedulerManager = {
+  new (): SchedulerManager
+  add: (name: string, cronExpression: string, callback: TaskCallback) => ScheduledTask
+  job: (name: string, callback: TaskCallback) => SchedulerBuilder
+  readonly staticConfigFindings: {    className: string;    keys: string[];}[]
+  start: () => void
+  stop: () => void
+  tasks: ReadonlyMap<string, ScheduledTask>
+}
+
+class SchedulerProvider = {
+  new (app: Application): SchedulerProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly ['scheduler']
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class TaskFailed = {
+  new (name: string, durationMs: number, error: string): TaskFailed
+  readonly durationMs: number
+  readonly error: string
+  readonly name: string
+}
+
+class TaskRan = {
+  new (name: string, durationMs: number, ok: boolean): TaskRan
+  readonly durationMs: number
+  readonly name: string
+  readonly ok: boolean
+}
+
+class TaskSkipped = {
+  new (name: string, reason: 'env' | 'window' | 'when' | 'skip' | 'overlap' | 'lock'): TaskSkipped
+  readonly name: string
+  readonly reason: 'lock' | 'window' | 'env' | 'when' | 'skip' | 'overlap'
+}
+
+const DEFAULT_RUN_LOG_KEEP = 500
+
+const DEFAULT_RUN_LOG_PATH = 'storage/framework/schedule-runs.jsonl'
+
+const Scheduler = SchedulerManager
+
+const schedulesConcern = ConcernDescriptor
+
+function installScheduleRunLog = (app: Application) => (() => void) | undefined
+
+function registerSchedule = (manager: SchedulerManager, schedule: Schedule, fallbackName: string) => ScheduledTask | undefined
+
+function resolveRunLogConfig = (app: Application) => RunLogConfig
+
+function SchedulerConfig = (options?: Partial<SchedulerConfigShape>) => SchedulerConfigShape
+
+interface OverlapLockOptions = {
+  crossProcess?: boolean
+  expiresAfterMinutes?: number
+  refresh?: boolean
+}
+
+interface RunLogConfig = {
+  enabled: boolean
+  keep: number
+  path: string
+}
+
+interface SchedulerConfigShape = {
+  runLog: {    enabled?: boolean;    path: string;    keep: number;}
+  timezone: string
+}
+
+interface ScheduleRunRecord = {
+  durationMs: number
+  error?: string
+  finishedAt: string
+  name: string
+  ok: boolean
+  startedAt: string
+}
+
+interface ScheduleRunStore = {
+  lastFor: (name: string) => ScheduleRunRecord | undefined
+  recent: (limit?: number, name?: string) => ScheduleRunRecord[]
+  record: (run: ScheduleRunRecord) => void
+}
+
+type OutputMailer = (email: string, subject: string, body: string) => void | Promise<void>
+
+type TaskCallback = () => void | Promise<void>
+
+type TaskGuard = () => boolean | Promise<boolean>
+
+type TaskHook = () => void | Promise<void>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/scheduler",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -12,6 +12,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -29,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.3"
+    "@zerotal/core": "1.7.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"