alepha/dist/scheduler/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Alepha, Async, KIND, Primitive, Static } from "alepha";
import { DateTime, DateTimeProvider, DurationLike } from "alepha/datetime";
//#region ../../src/scheduler/constants/CRON.d.ts
declare const CRON: {
  EVERY_MINUTE: string;
  EVERY_5_MINUTES: string;
  EVERY_15_MINUTES: string;
  EVERY_30_MINUTES: string;
  EVERY_HOUR: string;
  EVERY_DAY_AT_MIDNIGHT: string;
};
//#endregion
//#region ../../../../node_modules/cron-schedule/dist/cron.d.ts
/**
 * An object with contains for each element of a date, which values are allowed.
 * Everything starting at 0, except for days.
 */
interface ICronDefinition {
  readonly seconds: Set<number>;
  readonly minutes: Set<number>;
  readonly hours: Set<number>;
  readonly days: Set<number>;
  readonly months: Set<number>;
  readonly weekdays: Set<number>;
}
declare class Cron {
  readonly seconds: ReadonlyArray<number>;
  readonly minutes: ReadonlyArray<number>;
  readonly hours: ReadonlyArray<number>;
  readonly days: ReadonlyArray<number>;
  readonly months: ReadonlyArray<number>;
  readonly weekdays: ReadonlyArray<number>;
  readonly reversed: {
    seconds: ReadonlyArray<number>;
    minutes: ReadonlyArray<number>;
    hours: ReadonlyArray<number>;
    days: ReadonlyArray<number>;
    months: ReadonlyArray<number>;
    weekdays: ReadonlyArray<number>;
  };
  constructor({ seconds, minutes, hours, days, months, weekdays }: ICronDefinition);
  /**
   * Find the next or previous hour, starting from the given start hour that matches the hour constraint.
   * startHour itself might also be allowed.
   */
  private findAllowedHour;
  /**
   * Find the next or previous minute, starting from the given start minute that matches the minute constraint.
   * startMinute itself might also be allowed.
   */
  private findAllowedMinute;
  /**
   * Find the next or previous second, starting from the given start second that matches the second constraint.
   * startSecond itself IS NOT allowed.
   */
  private findAllowedSecond;
  /**
   * Find the next or previous time, starting from the given start time that matches the hour, minute
   * and second constraints. startTime itself might also be allowed.
   */
  private findAllowedTime;
  /**
   * Find the next or previous day in the given month, starting from the given startDay
   * that matches either the day or the weekday constraint. startDay itself might also be allowed.
   */
  private findAllowedDayInMonth;
  /** Gets the next date starting from the given start date or now. */
  getNextDate(startDate?: Date): Date;
  /** Gets the specified amount of future dates starting from the given start date or now. */
  getNextDates(amount: number, startDate?: Date): Date[];
  /**
   * Get an ES6 compatible iterator which iterates over the next dates starting from startDate or now.
   * The iterator runs until the optional endDate is reached or forever.
   */
  getNextDatesIterator(startDate?: Date, endDate?: Date): Generator<Date, undefined, undefined>;
  /** Gets the previous date starting from the given start date or now. */
  getPrevDate(startDate?: Date): Date;
  /** Gets the specified amount of previous dates starting from the given start date or now. */
  getPrevDates(amount: number, startDate?: Date): Date[];
  /**
   * Get an ES6 compatible iterator which iterates over the previous dates starting from startDate or now.
   * The iterator runs until the optional endDate is reached or forever.
   */
  getPrevDatesIterator(startDate?: Date, endDate?: Date): Generator<Date, undefined, undefined>;
  /** Returns true when there is a cron date at the given date. */
  matchDate(date: Date): boolean;
}
//#endregion
//#region ../../src/scheduler/providers/CronProvider.d.ts
declare class CronProvider {
  protected readonly dt: DateTimeProvider;
  protected readonly alepha: Alepha;
  protected readonly log: import("alepha/logger").Logger;
  protected readonly cronJobs: Array<CronJob>;
  getCronJobs(): Array<CronJob>;
  protected readonly start: import("alepha").HookPrimitive<"start">;
  protected readonly stop: import("alepha").HookPrimitive<"stop">;
  /**
   * Generic serverless cron trigger. Vercel's platform-emitted entry
   * point fires `serverless:cron` with the job name; we run the matching
   * job in-process. On long-running runtimes this listener is harmless
   * (no one fires the event).
   */
  protected readonly onServerlessCron: import("alepha").HookPrimitive<"serverless:cron">;
  protected boot(name: string | CronJob): void;
  abort(name: string | CronJob): void;
  /**
   * Registers a cron job.
   *
   * It's automatically done when using the `$scheduler` primitive but can also be used manually.
   */
  createCronJob(name: string, expression: string, handler: (context: {
    now: DateTime;
  }) => Promise<void>, start?: boolean): void;
  protected run(task: CronJob, now?: DateTime): void;
  /**
   * Trigger a specific cron job by name.
   */
  trigger(name: string): Promise<void>;
  /**
   * Trigger all registered cron jobs.
   */
  triggerAll(): Promise<void>;
  /**
   * Run multiple cron jobs in parallel.
   */
  protected runJobs(jobs: CronJob[], now: DateTime): Promise<void>;
}
interface CronJob {
  name: string;
  expression: string;
  handler: (context: {
    now: DateTime;
  }) => Promise<void>;
  cron: Cron;
  loop: boolean;
  running?: boolean;
  executing?: boolean;
  onError?: (error: Error) => void;
  abort?: AbortController;
}
//#endregion
//#region ../../src/scheduler/primitives/$scheduler.d.ts
/**
 * Scheduler primitive.
 */
declare const $scheduler: {
  (options: SchedulerPrimitiveOptions): SchedulerPrimitive;
  [KIND]: typeof SchedulerPrimitive;
};
type SchedulerPrimitiveOptions = {
  /**
   * Function to run on schedule.
   */
  handler: (args: SchedulerHandlerArguments) => Async<void>;
  /**
   * Name of the scheduler. Defaults to the function name.
   */
  name?: string;
  /**
   * Optional description of the scheduler.
   */
  description?: string;
  /**
   * Cron expression or interval to run the scheduler.
   */
  cron?: string;
  /**
   * Cron expression or interval to run the scheduler.
   */
  interval?: DurationLike;
  /**
   * If true, the scheduler will be locked and only one instance will run at a time.
   * You probably need to import {@link AlephaLockRedis} for distributed locking.
   *
   * @default true
   */
  lock?: boolean;
};
/**
 * Scheduler configuration atom.
 */
declare const schedulerOptions: import("alepha").Atom<import("zod").ZodObject<{
  prefix: import("zod").ZodOptional<import("zod").ZodString>;
}, import("zod/v4/core").$strip>, "alepha.scheduler.options">;
type SchedulerAtomOptions = Static<typeof schedulerOptions.schema>;
declare module "alepha" {
  interface State {
    [schedulerOptions.key]: SchedulerAtomOptions;
  }
}
declare class SchedulerPrimitive extends Primitive<SchedulerPrimitiveOptions> {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly settings: Readonly<{
    prefix?: string | undefined;
  }>;
  protected readonly alepha: Alepha;
  protected readonly dateTimeProvider: DateTimeProvider;
  protected readonly cronProvider: CronProvider;
  get name(): string;
  protected onInit(): void;
  trigger(): Promise<void>;
  protected schedulerLock: import("alepha").PipelinePrimitiveFn<(args: SchedulerHandlerArguments) => Promise<void>>;
}
interface SchedulerHandlerArguments {
  now: DateTime;
}
//#endregion
//#region ../../src/scheduler/providers/WorkerdCronProvider.d.ts
declare module "alepha" {
  interface Hooks {
    /**
     * Cloudflare Workers scheduled event.
     *
     * Emitted when a cron trigger fires in Cloudflare Workers.
     */
    "cloudflare:scheduled": {
      cron: string;
      scheduledTime: number;
    };
  }
}
/**
 * Cloudflare Workers cron provider.
 *
 * This provider handles scheduled events from Cloudflare Workers Cron Triggers.
 * Unlike the Node.js CronProvider, this doesn't use intervals/timeouts - instead,
 * it reacts to scheduled events triggered by Cloudflare.
 *
 * **Usage:**
 * 1. Define schedulers with `$scheduler({ cron: "0 * * * *", handler: ... })`
 * 2. Build your app with `alepha build` - cron triggers are automatically added to `wrangler.jsonc`
 * 3. Deploy to Cloudflare Workers
 *
 * **How it works:**
 * - During build, all registered `$scheduler` cron expressions are collected
 * - The build generates `wrangler.jsonc` with `triggers.crons` automatically filled
 * - When Cloudflare fires a cron trigger, the `scheduled` handler emits `cloudflare:scheduled`
 * - This provider listens to that event and runs matching schedulers
 *
 * @see https://developers.cloudflare.com/workers/configuration/cron-triggers/
 */
declare class WorkerdCronProvider extends CronProvider {
  /**
   * Override to avoid creating AbortController in global scope.
   * Cloudflare Workers doesn't allow this during initialization.
   */
  createCronJob(name: string, expression: string, handler: (context: {
    now: DateTime;
  }) => Promise<void>): void;
  /**
   * Handle a scheduled event from Cloudflare Workers.
   */
  protected readonly onScheduledEvent: import("alepha").HookPrimitive<"cloudflare:scheduled">;
}
//#endregion
//#region ../../src/scheduler/index.d.ts
declare module "alepha" {
  interface Hooks {
    "scheduler:begin": {
      name: string;
      now: DateTime;
      context: string;
    };
    "scheduler:success": {
      name: string;
      context: string;
    };
    "scheduler:error": {
      name: string;
      error: Error;
      context: string;
    };
    "scheduler:end": {
      name: string;
      context: string;
    };
    /**
     * Generic serverless cron trigger event.
     *
     * Emitted by serverless platform entry points (Vercel `/api/cron/...`,
     * etc.) to trigger a registered cron job by name. `CronProvider`
     * listens to this and calls `trigger(name)` so the same `$scheduler`
     * / `$job({ cron })` declarations work across runtimes.
     *
     * Cloudflare Workers uses the platform-specific `cloudflare:scheduled`
     * event instead (matched by cron expression), see
     * `WorkerdCronProvider`.
     */
    "serverless:cron": {
      name: string;
    };
  }
}
/**
 * Cron and interval-based task execution.
 *
 * **Features:**
 * - Scheduled tasks with cron expressions (e.g., `0 0 * * *`)
 * - Interval-based scheduling
 * - Distributed locking to prevent duplicate execution
 * - Lifecycle hooks: `begin`, `success`, `error`, `end`
 *
 * @module alepha.scheduler
 */
declare const AlephaScheduler: import("alepha").Service<import("alepha").Module>;
//#endregion
export { $scheduler, AlephaScheduler, CRON, CronJob, CronProvider, SchedulerAtomOptions, SchedulerHandlerArguments, SchedulerPrimitive, SchedulerPrimitiveOptions, WorkerdCronProvider, schedulerOptions };
//# sourceMappingURL=index.d.ts.map