@gravito/horizon 1.0.0-alpha.6 → 1.0.0-beta.6

package/dist/index.d.ts

@@ -0,0 +1,366 @@
+import { CacheManager } from '@gravito/stasis';
+import { GravitoOrbit, PlanetCore, ActionCallback, Logger, HookManager } from 'gravito-core';
+
+declare class CronParser {
+    /**
+     * Get the next execution date based on a cron expression.
+     *
+     * @param expression - Cron expression
+     * @param timezone - Timezone identifier
+     * @param currentDate - Reference date
+     */
+    static nextDate(expression: string, timezone?: string, currentDate?: Date): Promise<Date>;
+    /**
+     * Check if the cron expression is due to run at the current time (minute precision).
+     *
+     * @param expression - Cron expression
+     * @param timezone - Timezone identifier
+     * @param currentDate - Reference date
+     */
+    static isDue(expression: string, timezone?: string, currentDate?: Date): Promise<boolean>;
+    private static minuteMatches;
+}
+
+interface LockStore {
+    /**
+     * Attempt to acquire a lock
+     * @param key The lock key
+     * @param ttlSeconds Time to live in seconds
+     * @returns true if lock acquired, false if lock already exists
+     */
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Release a lock
+     * @param key The lock key
+     */
+    release(key: string): Promise<void>;
+    /**
+     * Force acquire a lock (overwrite existing)
+     * @param key The lock key
+     * @param ttlSeconds Time to live in seconds
+     */
+    forceAcquire(key: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Check if a lock exists
+     * @param key The lock key
+     */
+    exists(key: string): Promise<boolean>;
+}
+
+declare class CacheLockStore implements LockStore {
+    private cache;
+    private prefix;
+    constructor(cache: CacheManager, prefix?: string);
+    private getKey;
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+    forceAcquire(key: string, ttlSeconds: number): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+
+declare class LockManager {
+    private store;
+    constructor(driver: 'memory' | 'cache' | LockStore, context?: {
+        cache?: CacheManager;
+    });
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+    forceAcquire(key: string, ttlSeconds: number): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+
+declare class MemoryLockStore implements LockStore {
+    private locks;
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+    forceAcquire(key: string, ttlSeconds: number): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+
+declare class OrbitHorizon implements GravitoOrbit {
+    /**
+     * Install the Horizon Orbit into PlanetCore.
+     *
+     * @param core - The PlanetCore instance.
+     */
+    install(core: PlanetCore): void;
+}
+
+interface ProcessResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    success: boolean;
+}
+declare function runProcess(command: string): Promise<ProcessResult>;
+declare class Process {
+    static run(command: string): Promise<ProcessResult>;
+}
+
+interface ScheduledTask {
+    name: string;
+    expression: string;
+    timezone: string;
+    callback: () => void | Promise<void>;
+    shouldRunOnOneServer: boolean;
+    lockTtl: number;
+    background: boolean;
+    nodeRole?: string;
+    command?: string;
+    onSuccessCallbacks: ActionCallback[];
+    onFailureCallbacks: ActionCallback[];
+}
+/**
+ * Fluent API for defining task schedules.
+ *
+ * @example
+ * scheduler.task('backup')
+ *   .daily()
+ *   .at('02:00')
+ *   .onOneServer()
+ */
+declare class TaskSchedule {
+    private task;
+    /**
+     * Create a new TaskSchedule instance.
+     *
+     * @param name - The unique name of the task.
+     * @param callback - The function to execute.
+     */
+    constructor(name: string, callback: () => void | Promise<void>);
+    /**
+     * Set a custom cron expression.
+     *
+     * @param expression - Standard cron expression (e.g., "* * * * *")
+     * @returns The TaskSchedule instance.
+     */
+    cron(expression: string): this;
+    /**
+     * Run the task every minute.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    everyMinute(): this;
+    /**
+     * Run the task every 5 minutes.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    everyFiveMinutes(): this;
+    /**
+     * Run the task every 10 minutes.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    everyTenMinutes(): this;
+    /**
+     * Run the task every 15 minutes.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    everyFifteenMinutes(): this;
+    /**
+     * Run the task every 30 minutes.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    everyThirtyMinutes(): this;
+    /**
+     * Run the task hourly (at minute 0).
+     *
+     * @returns The TaskSchedule instance.
+     */
+    hourly(): this;
+    /**
+     * Run the task hourly at a specific minute.
+     *
+     * @param minute - Minute (0-59)
+     * @returns The TaskSchedule instance.
+     */
+    hourlyAt(minute: number): this;
+    /**
+     * Run the task daily at midnight (00:00).
+     *
+     * @returns The TaskSchedule instance.
+     */
+    daily(): this;
+    /**
+     * Run the task daily at a specific time.
+     *
+     * @param time - Time in "HH:mm" format (24h)
+     * @returns The TaskSchedule instance.
+     */
+    dailyAt(time: string): this;
+    /**
+     * Run the task weekly on Sunday at midnight.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    weekly(): this;
+    /**
+     * Run the task weekly on a specific day and time.
+     *
+     * @param day - Day of week (0-7, 0 or 7 is Sunday)
+     * @param time - Time in "HH:mm" format (default "00:00")
+     * @returns The TaskSchedule instance.
+     */
+    weeklyOn(day: number, time?: string): this;
+    /**
+     * Run the task monthly on the 1st day at midnight.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    monthly(): this;
+    /**
+     * Run the task monthly on a specific day and time.
+     *
+     * @param day - Day of month (1-31)
+     * @param time - Time in "HH:mm" format (default "00:00")
+     * @returns The TaskSchedule instance.
+     */
+    monthlyOn(day: number, time?: string): this;
+    /**
+     * Set the timezone for the task execution.
+     *
+     * @param timezone - Timezone identifier (e.g., "Asia/Taipei", "UTC")
+     * @returns The TaskSchedule instance.
+     */
+    timezone(timezone: string): this;
+    /**
+     * Set the time of execution for the current frequency.
+     * Useful when chaining with daily(), weekly(), etc.
+     *
+     * @param time - Time in "HH:mm" format
+     * @returns The TaskSchedule instance.
+     */
+    at(time: string): this;
+    /**
+     * Ensure task runs on only one server at a time (Distributed Locking).
+     * Requires a configured LockStore (Cache or Redis).
+     *
+     * @param lockTtlSeconds - Time in seconds to hold the lock (default 300)
+     * @returns The TaskSchedule instance.
+     */
+    onOneServer(lockTtlSeconds?: number): this;
+    /**
+     * Alias for onOneServer.
+     * Prevents overlapping executions of the same task.
+     *
+     * @param expiresAt - Lock TTL in seconds
+     * @returns The TaskSchedule instance.
+     */
+    withoutOverlapping(expiresAt?: number): this;
+    /**
+     * Run task in background (do not wait for completion in the loop).
+     * Note: In Node.js non-blocking environment this is largely semantic,
+     * but affects how we handle error catching and lock release.
+     *
+     * @returns The TaskSchedule instance.
+     */
+    runInBackground(): this;
+    /**
+     * Restrict task execution to a specific node role.
+     *
+     * @param role - The required node role (e.g., 'api', 'worker')
+     * @returns The TaskSchedule instance.
+     */
+    onNode(role: string): this;
+    /**
+     * Set the command string for exec tasks.
+     *
+     * @param command - The command string.
+     * @returns The TaskSchedule instance.
+     * @internal
+     */
+    setCommand(command: string): this;
+    /**
+     * Register a callback to run on task success.
+     *
+     * @param callback - The callback function.
+     * @returns The TaskSchedule instance.
+     */
+    onSuccess(callback: ActionCallback): this;
+    /**
+     * Register a callback to run on task failure.
+     *
+     * @param callback - The callback function.
+     * @returns The TaskSchedule instance.
+     */
+    onFailure(callback: ActionCallback): this;
+    /**
+     * Set a description for the task (useful for listing).
+     *
+     * @param _text - The description text.
+     * @returns The TaskSchedule instance.
+     */
+    description(_text: string): this;
+    /**
+     * Get the underlying task configuration.
+     *
+     * @returns The ScheduledTask object.
+     */
+    getTask(): ScheduledTask;
+}
+
+/**
+ * Core Scheduler Manager responsible for managing and executing tasks.
+ */
+declare class SchedulerManager {
+    lockManager: LockManager;
+    private logger?;
+    private hooks?;
+    private currentNodeRole?;
+    private tasks;
+    constructor(lockManager: LockManager, logger?: Logger | undefined, hooks?: HookManager | undefined, currentNodeRole?: string | undefined);
+    /**
+     * Define a new scheduled task.
+     *
+     * @param name - Unique name for the task
+     * @param callback - Function to execute
+     * @returns The newly created TaskSchedule.
+     */
+    task(name: string, callback: () => void | Promise<void>): TaskSchedule;
+    /**
+     * Define a new scheduled command execution task.
+     *
+     * @param name - Unique name for the task
+     * @param command - Shell command to execute
+     * @returns The newly created TaskSchedule.
+     */
+    exec(name: string, command: string): TaskSchedule;
+    /**
+     * Add a pre-configured task schedule object.
+     *
+     * @param schedule - The task schedule to add.
+     */
+    add(schedule: TaskSchedule): void;
+    /**
+     * Get all registered task definitions.
+     *
+     * @returns An array of scheduled tasks.
+     */
+    getTasks(): ScheduledTask[];
+    /**
+     * Trigger the scheduler to check and run due tasks.
+     * This is typically called every minute by a system cron or worker loop.
+     *
+     * @param date - The current reference date (default: now)
+     * @returns A promise that resolves when the scheduler run is complete.
+     */
+    run(date?: Date): Promise<void>;
+    /**
+     * Execute a specific task with locking logic.
+     *
+     * @param task - The task to execute.
+     * @internal
+     */
+    runTask(task: ScheduledTask, date?: Date): Promise<void>;
+    /**
+     * Execute the task callback and handle hooks.
+     *
+     * @param task - The task to execute.
+     */
+    private executeTask;
+}
+
+export { CacheLockStore, CronParser, LockManager, type LockStore, MemoryLockStore, OrbitHorizon, Process, type ProcessResult, type ScheduledTask, SchedulerManager, TaskSchedule, runProcess };