@cleverbrush/scheduler 1.1.10 → 2.0.0

package/README.md

@@ -1,66 +1,174 @@
-# Task scheduler for NodeJS
+# @cleverbrush/scheduler
+<!-- coverage-badge-start -->
+![Coverage](https://img.shields.io/badge/coverage-96.7%25-brightgreen)
+<!-- coverage-badge-end -->
 
-To install the scheduler, run:
+A job scheduler for Node.js that runs tasks in worker threads on configurable schedules.
+
+## Installation
 
 ```bash
-    npm install @cleverbrush/scheduler
+npm install @cleverbrush/scheduler
 ```
 
-This library makes use of Node.js `worker_threads` module to run tasks in parallel. It's tested
-on Node.js v16, but should work on older versions as well.
+This library uses the Node.js `worker_threads` module. It is tested on Node.js v16+.
 
-### An example:
+## Quick Start
 
 ```typescript
-    import { JobScheduler } from '@cleverbrush/scheduler';
-
-    const scheduler = new JobScheduler({
-        rootFolder: '/some/path/to/your/tasks/root/folder'
-    });
-
-    scheduler.addJob({
-        id: 'my-job-1',
-        path: 'path/to/file/under/rootFolder/job1.js',
-        schedule: {
-            every: 'minute',
-            // every 5 minutes
-            interval: 5,
-            timeout: 1000 * 60 * 4,
-            maxRetries: 3
-        }
-    });
-
-    scheduler.addJob({
-        id: 'my-job-2',
-        path: 'another/path/to/file/under/rootFolder/job2.js',
-        schedule: {
-            every: 'week',
-            // every second week
-            interval: 2,
-            // at Monday, Wednesday and Friday
-            dayOfWeek: [1, 3, 5],
-            // at 9:30 AM (UTC)
-            hour: 9,
-            minute 30,
-            timeout: 1000 * 60 * 4,
-            maxRetries: 3
-        }
-    });
-
-    scheduler.start();
+import { JobScheduler } from '@cleverbrush/scheduler';
+
+const scheduler = new JobScheduler({
+    rootFolder: '/path/to/your/jobs'
+});
+
+scheduler.addJob({
+    id: 'my-job-1',
+    path: 'job1.js',
+    schedule: {
+        every: 'minute',
+        interval: 5
+    }
+});
+
+scheduler.addJob({
+    id: 'my-job-2',
+    path: 'job2.js',
+    schedule: {
+        every: 'week',
+        interval: 2,
+        dayOfWeek: [1, 3, 5],
+        hour: 9,
+        minute: 30
+    },
+    timeout: 1000 * 60 * 4,
+    maxRetries: 3
+});
+
+scheduler.start();
 ```
 
-This will run `job1.js` and `job2.js` according to the schedules defined in the code above.
-You can subscribe to several events to get notified about the job status:
+## API
+
+### `JobScheduler`
+
+The main class for scheduling and running jobs. Extends `EventEmitter`.
+
+#### Constructor
 
 ```typescript
-scheduler.on(
-    'job:start',
-    ({ jobId, instanceId, stdout, stderr, startDate, endDate }) => {
-        console.log(`Job ${jobId} started`);
-    }
-);
+const scheduler = new JobScheduler(props: JobSchedulerProps);
+```
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `rootFolder` | `string` | — | Path to the folder containing job files |
+| `defaultTimeZone` | `string` | `'UTC'` | Timezone used for scheduling |
+
+#### Methods
+
+| Method | Description |
+| --- | --- |
+| `start()` | Starts the scheduler |
+| `stop()` | Stops the scheduler |
+| `addJob(job)` | Adds a job to the scheduler |
+| `removeJob(jobId)` | Removes a job by ID |
+| `jobExists(jobId)` | Returns `true` if a job with the given ID exists |
+| `status` | Current scheduler status: `'started'` or `'stopped'` |
+
+#### Events
+
+```typescript
+scheduler.on('job:start', ({ jobId, instanceId, startDate }) => {
+    console.log(`Job ${jobId} started`);
+});
+
+scheduler.on('job:end', ({ jobId, instanceId, startDate, endDate, stdout, stderr }) => {
+    console.log(`Job ${jobId} finished`);
+});
+
+scheduler.on('job:error', ({ jobId, instanceId, startDate, endDate, stdout, stderr }) => {
+    console.error(`Job ${jobId} failed`);
+});
+
+scheduler.on('job:timeout', ({ jobId, instanceId, startDate, endDate }) => {
+    console.warn(`Job ${jobId} timed out`);
+});
+
+scheduler.on('job:message', ({ jobId, instanceId, message }) => {
+    console.log(`Message from ${jobId}:`, message);
+});
+```
+
+### Job Configuration
+
+```typescript
+scheduler.addJob({
+    id: 'unique-job-id',
+    path: 'relative/path/to/job.js',
+    schedule: { /* see Schedule Types */ },
+    timeout: 60000,                // timeout in milliseconds
+    maxRetries: 3,                 // retry on failure
+    maxConsequentFails: 10,        // disable after N consecutive failures
+    noConcurrentRuns: true,        // prevent overlapping executions
+    props: { key: 'value' }        // data passed to the worker
+});
+```
+
+### Schedule Types
 
-// other possible events are 'job:end', 'job:error', 'job:timeout', 'job:message'
-// passing the same parameters to callback as above
+All schedules share these optional properties:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `interval` | `number` | Number of periods between repeats (1–356) |
+| `startsOn` | `Date` | Do not start before this date |
+| `endsOn` | `Date` | Do not repeat after this date |
+| `maxOccurences` | `number` | Maximum number of executions |
+| `skipFirst` | `number` | Skip this many initial executions |
+
+#### Minute
+
+```typescript
+{ every: 'minute', interval: 5 }
+```
+
+Runs every N minutes.
+
+#### Day
+
+```typescript
+{ every: 'day', interval: 1, hour: 9, minute: 30 }
+```
+
+Runs every N days at the specified time.
+
+#### Week
+
+```typescript
+{ every: 'week', interval: 2, dayOfWeek: [1, 3, 5], hour: 9, minute: 30 }
 ```
+
+Runs every N weeks on the specified days (1 = Monday, 7 = Sunday).
+
+#### Month
+
+```typescript
+{ every: 'month', interval: 1, day: 15, hour: 0, minute: 0 }
+// or on the last day of the month:
+{ every: 'month', interval: 1, day: 'last', hour: 0, minute: 0 }
+```
+
+Runs every N months on the specified day (1–28 or `'last'`).
+
+#### Year
+
+```typescript
+{ every: 'year', interval: 1, month: 6, day: 1, hour: 12, minute: 0 }
+```
+
+Runs every N years on the specified month (1–12) and day (1–28 or `'last'`).
+
+## License
+
+BSD-3-Clause

package/dist/ScheduleCalculator.d.ts

@@ -1,8 +1,50 @@
-import { Schedule } from './types.js';
+import type { Schedule } from './types.js';
+/**
+ * Iterates over the dates defined by a {@link Schedule}.
+ *
+ * Given a schedule configuration (e.g. every 2 days, every week on Monday/Friday,
+ * every month on the 15th) the calculator produces the sequence of `Date` objects
+ * that match that schedule. Use {@link hasNext} / {@link next} to walk through
+ * the sequence.
+ *
+ * @example
+ * ```ts
+ * const calc = new ScheduleCalculator({
+ *   every: 'day',
+ *   interval: 1,
+ *   hour: 9,
+ *   minute: 0,
+ *   startsOn: new Date('2025-01-01T00:00:00Z'),
+ *   maxOccurences: 5
+ * });
+ *
+ * while (calc.hasNext()) {
+ *   const { date, index } = calc.next();
+ *   console.log(`Run #${index} at ${date.toISOString()}`);
+ * }
+ * ```
+ */
 export declare class ScheduleCalculator {
     #private;
+    /**
+     * @param schedule - The schedule definition to iterate over.
+     * @throws If `schedule` is falsy.
+     */
     constructor(schedule: Schedule);
+    /**
+     * Returns `true` when the schedule has at least one more date.
+     *
+     * @param span - Optional millisecond window. When provided the method
+     *   returns `true` only if the next date falls within `span` ms from now.
+     */
     hasNext(span?: number): boolean;
+    /**
+     * Advances to the next scheduled date and returns it together with
+     * its 1-based index in the sequence.
+     *
+     * @returns An object with the scheduled `date` and its `index`.
+     * @throws If the schedule has no more dates ({@link hasNext} is `false`).
+     */
     next(): {
         date: Date;
         index: number;

package/dist/index.d.ts

@@ -1,13 +1,10 @@
-/// <reference types="node" />
-/// <reference types="node" />
-/// <reference types="node" />
 import { EventEmitter } from 'events';
-import { Readable } from 'stream';
+import { type Readable } from 'stream';
 import { Worker } from 'worker_threads';
-import { JobSchedulerProps, CreateJobRequest, SchedulerStatus, Schedule, Job, JobInstance, JobInstanceStatus, Schemas } from './types.js';
+import { type IJobRepository } from './jobRepository.js';
 import { ScheduleCalculator } from './ScheduleCalculator.js';
-import { IJobRepository } from './jobRepository.js';
-export { ScheduleCalculator, Schedule as TaskSchedule, Schemas };
+import { type CreateJobRequest, type Job, type JobInstance, type JobInstanceStatus, type JobSchedulerProps, Schedule, type SchedulerStatus, Schemas } from './types.js';
+export { Schedule as TaskSchedule, ScheduleCalculator, Schemas };
 type WorkerResult = {
     status: JobInstanceStatus;
     exitCode: number;
@@ -49,7 +46,7 @@ export declare class JobScheduler extends EventEmitter implements IJobScheduler
     protected _rootFolder: string;
     protected _status: SchedulerStatus;
     protected _defaultTimezone: string;
-    protected _checkTimer: any;
+    protected _checkTimer: ReturnType<typeof setTimeout> | undefined;
     protected _jobsRepository: IJobRepository;
     protected _jobProps: Map<string, any>;
     /**
@@ -63,7 +60,7 @@ export declare class JobScheduler extends EventEmitter implements IJobScheduler
      * @param {Job} job
      * @returns {Promise<ScheduleCalculator>}
      */
-    protected getJobSchedule(job: Job): Promise<ScheduleCalculator>;
+    protected getJobSchedule(job: Job): Promise<ScheduleCalculator | undefined>;
     protected runWorkerWithTimeout(file: string, props: any, timeout: number): {
         promise: Promise<WorkerResult>;
         worker: Worker;