silent-cronx 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,321 @@
+type RetryBackoff = "fixed" | "linear" | "exponential";
+type RetryConfig = {
+    attempts: number;
+    delayMs?: number;
+    backoff?: RetryBackoff;
+    shouldRetry?: (error: unknown) => boolean;
+};
+
+type JobStatus = "pending" | "scheduled" | "running" | "success" | "failed" | "cancelled" | "paused" | "timeout";
+type SerializedError = {
+    name: string;
+    message: string;
+    stack?: string;
+};
+type JobTask<TPayload = unknown, TResult = unknown> = (context: {
+    jobId: string;
+    name: string;
+    payload: TPayload;
+    attempt: number;
+    signal: AbortSignal;
+    createdAt: Date;
+    startedAt: Date;
+}) => Promise<TResult> | TResult;
+type ScheduleJobOptions<TPayload = unknown> = {
+    cron: string;
+    payload?: TPayload;
+    timezone?: string;
+    enabled?: boolean;
+    preventOverlap?: boolean;
+    timeout?: number;
+    retry?: RetryConfig;
+    priority?: number;
+    task: JobTask<TPayload>;
+};
+type DelayJobOptions<TPayload = unknown, TResult = unknown> = {
+    delayMs: number;
+    payload?: TPayload;
+    timeout?: number;
+    retry?: RetryConfig;
+    priority?: number;
+    task: JobTask<TPayload, TResult>;
+};
+type EveryJobOptions<TPayload = unknown, TResult = unknown> = {
+    intervalMs: number;
+    payload?: TPayload;
+    enabled?: boolean;
+    preventOverlap?: boolean;
+    timeout?: number;
+    retry?: RetryConfig;
+    priority?: number;
+    task: JobTask<TPayload, TResult>;
+};
+type RunNowOptions<TPayload = unknown, TResult = unknown> = {
+    payload?: TPayload;
+    timeout?: number;
+    retry?: RetryConfig;
+    priority?: number;
+    task: JobTask<TPayload, TResult>;
+};
+type WorkerModuleReference = {
+    path: string | URL;
+    exportName?: string;
+};
+type WorkerJobOptions<TPayload = unknown> = {
+    payload?: TPayload;
+    timeout?: number;
+    retry?: RetryConfig;
+    priority?: number;
+    worker: WorkerModuleReference | JobTask<TPayload>;
+};
+type JobResult<TResult = unknown> = {
+    jobId: string;
+    name: string;
+    status: JobStatus;
+    result?: TResult;
+    error?: SerializedError;
+    attempt: number;
+    durationMs: number;
+    startedAt?: string;
+    finishedAt?: string;
+};
+type JobKind = "cron" | "delay" | "every" | "runNow" | "worker" | "queue";
+type JobRecord<TPayload = unknown, TResult = unknown> = {
+    id: string;
+    name: string;
+    kind: JobKind;
+    status: JobStatus;
+    payload?: TPayload;
+    priority: number;
+    attempts: number;
+    maxAttempts: number;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    lastRunAt?: string;
+    nextRunAt?: string;
+    result?: TResult;
+    error?: SerializedError;
+    successCount: number;
+    failureCount: number;
+    queueName?: string;
+    metadata?: Record<string, unknown>;
+};
+type JobFilter = {
+    status?: JobStatus;
+    name?: string;
+    kind?: JobKind;
+    queueName?: string;
+};
+
+interface StorageAdapter {
+    saveJob(job: JobRecord): Promise<void>;
+    updateJob(jobId: string, patch: Partial<JobRecord>): Promise<void>;
+    getJob(jobId: string): Promise<JobRecord | null>;
+    listJobs(filter?: JobFilter): Promise<JobRecord[]>;
+    deleteJob(jobId: string): Promise<void>;
+    acquireLock(lockKey: string, ttlMs: number): Promise<boolean>;
+    releaseLock(lockKey: string): Promise<void>;
+}
+
+type SilentCronXLogger = {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+    debug?: (...args: unknown[]) => void;
+};
+type SilentCronXConfig = {
+    timezone?: string;
+    maxWorkers?: number;
+    maxConcurrency?: number;
+    defaultTimeout?: number;
+    preventOverlapping?: boolean;
+    lockTimeout?: number;
+    maxPayloadBytes?: number;
+    logger?: SilentCronXLogger;
+    storage?: "memory" | StorageAdapter;
+    debug?: boolean;
+};
+
+type SilentCronXEventMap = {
+    "scheduler:started": {
+        running: true;
+        at: string;
+    };
+    "scheduler:stopped": {
+        running: false;
+        at: string;
+    };
+    "scheduler:shutdown": {
+        at: string;
+    };
+    "job:scheduled": {
+        jobId: string;
+        name: string;
+        nextRunAt?: string;
+    };
+    "job:started": {
+        jobId: string;
+        name: string;
+        attempt: number;
+    };
+    "job:success": JobResult;
+    "job:failed": JobResult;
+    "job:timeout": JobResult;
+    "job:cancelled": {
+        jobId: string;
+        name: string;
+    };
+    "job:paused": {
+        jobId: string;
+        name: string;
+    };
+    "job:resumed": {
+        jobId: string;
+        name: string;
+    };
+    "job:retry": {
+        jobId: string;
+        name: string;
+        attempt: number;
+        delayMs: number;
+    };
+    "queue:created": {
+        queueName: string;
+        concurrency: number;
+    };
+    "queue:drain": {
+        queueName: string;
+    };
+    "error": {
+        error: unknown;
+        jobId?: string;
+        name?: string;
+    };
+};
+type SilentCronXEventName = keyof SilentCronXEventMap;
+type SilentCronXEventHandler<TName extends SilentCronXEventName> = (event: SilentCronXEventMap[TName]) => void;
+type StatusSnapshot = {
+    jobId: string;
+    name: string;
+    status: JobStatus;
+    attempt: number;
+    nextRunAt?: string;
+    lastRunAt?: string;
+};
+
+type QueueOptions<TPayload = unknown, TResult = unknown> = {
+    concurrency?: number;
+    retry?: RetryConfig;
+    timeout?: number;
+    maxSize?: number;
+    rateLimit?: {
+        limit: number;
+        intervalMs: number;
+    };
+    processor?: JobTask<TPayload, TResult>;
+};
+type AddQueueJobOptions<TPayload = unknown, TResult = unknown> = {
+    id?: string;
+    name: string;
+    payload?: TPayload;
+    priority?: number;
+    timeout?: number;
+    retry?: RetryConfig;
+    task?: JobTask<TPayload, TResult>;
+};
+
+type SilentCronXHealth = {
+    running: boolean;
+    scheduledJobs: number;
+    runningJobs: number;
+    queuedJobs: number;
+    workers: {
+        max: number;
+        busy: number;
+        idle: number;
+    };
+    memory: {
+        storage: string;
+    };
+};
+
+declare class SilentCronX {
+    private readonly config;
+    private readonly storage;
+    private readonly eventBus;
+    private readonly runner;
+    private readonly workerPool;
+    private readonly lockManager;
+    private readonly queueManager;
+    private readonly logger;
+    private readonly entries;
+    private readonly controllers;
+    private running;
+    constructor(config?: SilentCronXConfig);
+    schedule<TPayload = unknown>(name: string, options: ScheduleJobOptions<TPayload>): Promise<string>;
+    delay<TPayload = unknown, TResult = unknown>(name: string, options: DelayJobOptions<TPayload, TResult>): Promise<string>;
+    every<TPayload = unknown, TResult = unknown>(name: string, options: EveryJobOptions<TPayload, TResult>): Promise<string>;
+    runNow<TPayload = unknown, TResult = unknown>(name: string, options: RunNowOptions<TPayload, TResult>): Promise<JobResult<TResult>>;
+    runWorker<TPayload = unknown, TResult = unknown>(name: string, options: WorkerJobOptions<TPayload>): Promise<JobResult<TResult>>;
+    queue<TPayload = unknown, TResult = unknown>(name: string, options?: QueueOptions<TPayload, TResult>): void;
+    addJob<TPayload = unknown, TResult = unknown>(queueName: string, job: AddQueueJobOptions<TPayload, TResult>): Promise<string>;
+    cancel(jobId: string): Promise<void>;
+    pause(jobId: string): Promise<void>;
+    resume(jobId: string): Promise<void>;
+    getStatus(jobId: string): Promise<StatusSnapshot | null>;
+    getJobs(): Promise<JobRecord[]>;
+    start(): void;
+    stop(): void;
+    shutdown(): Promise<void>;
+    on<TName extends SilentCronXEventName>(eventName: TName, handler: SilentCronXEventHandler<TName>): void;
+    off<TName extends SilentCronXEventName>(eventName: TName, handler: SilentCronXEventHandler<TName>): void;
+    getHealth(): Promise<SilentCronXHealth>;
+    private executeJob;
+    private armEntry;
+    private armCron;
+    private armDelay;
+    private armEvery;
+    private clearTimer;
+    private createRecord;
+}
+
+declare function createSilentCronX(config?: SilentCronXConfig): SilentCronX;
+
+declare class MemoryStorageAdapter implements StorageAdapter {
+    private readonly jobs;
+    private readonly locks;
+    saveJob(job: JobRecord): Promise<void>;
+    updateJob(jobId: string, patch: Partial<JobRecord>): Promise<void>;
+    getJob(jobId: string): Promise<JobRecord | null>;
+    listJobs(filter?: JobFilter): Promise<JobRecord[]>;
+    deleteJob(jobId: string): Promise<void>;
+    acquireLock(lockKey: string, ttlMs: number): Promise<boolean>;
+    releaseLock(lockKey: string): Promise<void>;
+    private cleanupExpiredLocks;
+}
+
+declare class RedisStorageAdapter implements StorageAdapter {
+    constructor();
+    saveJob(_job: JobRecord): Promise<void>;
+    updateJob(_jobId: string, _patch: Partial<JobRecord>): Promise<void>;
+    getJob(_jobId: string): Promise<JobRecord | null>;
+    listJobs(_filter?: JobFilter): Promise<JobRecord[]>;
+    deleteJob(_jobId: string): Promise<void>;
+    acquireLock(_lockKey: string, _ttlMs: number): Promise<boolean>;
+    releaseLock(_lockKey: string): Promise<void>;
+}
+
+declare class PostgresStorageAdapter implements StorageAdapter {
+    constructor();
+    saveJob(_job: JobRecord): Promise<void>;
+    updateJob(_jobId: string, _patch: Partial<JobRecord>): Promise<void>;
+    getJob(_jobId: string): Promise<JobRecord | null>;
+    listJobs(_filter?: JobFilter): Promise<JobRecord[]>;
+    deleteJob(_jobId: string): Promise<void>;
+    acquireLock(_lockKey: string, _ttlMs: number): Promise<boolean>;
+    releaseLock(_lockKey: string): Promise<void>;
+}
+
+export { type AddQueueJobOptions, type DelayJobOptions, type EveryJobOptions, type JobFilter, type JobKind, type JobRecord, type JobResult, type JobStatus, type JobTask, MemoryStorageAdapter, PostgresStorageAdapter, type QueueOptions, RedisStorageAdapter, type RetryBackoff, type RetryConfig, type RunNowOptions, type ScheduleJobOptions, type SerializedError, SilentCronX, type SilentCronXConfig, type SilentCronXEventHandler, type SilentCronXEventMap, type SilentCronXEventName, type SilentCronXHealth, type SilentCronXLogger, type StatusSnapshot, type StorageAdapter, type WorkerJobOptions, type WorkerModuleReference, createSilentCronX };