@nestjs/workflows 0.0.1

package/dist/services/workflow-schedules.service.js

@@ -0,0 +1,193 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { assertScheduleId, nextOccurrences, parseSchedule } from '../core/scheduling/schedule-spec.js';
+import { systemClock } from '../core/time/clock.js';
+import { WorkflowNotFoundError } from '../errors/workflow-not-found.error.js';
+import { WorkflowStateError } from '../errors/workflow-state.error.js';
+import { normalize } from '../utils/normalize.util.js';
+import { scheduleSpec } from '../utils/schedule-spec.util.js';
+import { WORKFLOWS_MODULE_OPTIONS } from '../workflows.module-definition.js';
+import { WorkflowRegistry } from './workflow-registry.service.js';
+import { WorkflowScheduler } from './workflow-scheduler.service.js';
+import { WorkflowWorker } from './workflow-worker.service.js';
+/**
+ * Schedules that start workflow instances: a cron expression, an interval or an RFC 5545 rule, in a time zone.
+ * Declare them with `@Workflow(name, { schedules })`, or save them at runtime with `upsert()`; every worker that
+ * runs the workflow starts their occurrences, each exactly once. Also `WorkflowClient.schedules`.
+ */
+let WorkflowSchedules = class WorkflowSchedules {
+    constructor(options, registry, scheduler, worker) {
+        this.registry = registry;
+        this.scheduler = scheduler;
+        this.worker = worker;
+        this.clock = options.clock ?? systemClock;
+    }
+    /** The core's engine of schedules, over the registered store's. */
+    get engine() {
+        return this.scheduler.engine;
+    }
+    /**
+     * Creates or replaces the schedule with this id, and returns it. A schedule whose timing (`cron`, `every`,
+     * `rrule`, `tz`, `startAt`, `endAt`) changes starts over from now, with its first occurrence after now; one
+     * whose timing doesn't keeps its next occurrence, whatever else changes. Its runs, and whether it is paused,
+     * carry over. Throws `WorkflowStateError` for a schedule a workflow declares (change it in the code), and a
+     * `TypeError` for invalid options.
+     */
+    async upsert(id, schedule) {
+        assertScheduleId(id);
+        const owner = `Schedule "${id}"`;
+        if (schedule === null || typeof schedule !== 'object') {
+            throw new TypeError(`${owner}: expected options with workflow and cron, every or rrule.`);
+        }
+        const workflow = this.registry.resolve(schedule.workflow, schedule.version);
+        const spec = scheduleSpec(owner, schedule, { version: schedule.version ?? null, inputFn: false });
+        if (typeof schedule.input === 'function') {
+            throw new TypeError(`${owner}: upsert() stores its input, so it can't be a function. Pass a value; a declared schedule (@Workflow(name, { schedules })) can compute it.`);
+        }
+        let input;
+        try {
+            input = normalize(schedule.input) ?? null;
+        }
+        catch (error) {
+            throw new TypeError(`${owner}: its input is not JSON-serializable: ${error.message}`);
+        }
+        const saved = await this.engine.save(id, (current) => {
+            if (current?.declared) {
+                throw declaredError(current);
+            }
+            return this.engine.changed(current, { target: workflow.name, declared: false, spec, payload: input });
+        }, { replacing: true });
+        this.worker.kick();
+        return this.scheduler.view(saved);
+    }
+    /** The schedule, or `null` for an unknown id. */
+    async get(id) {
+        const record = await this.engine.read(id);
+        return record ? this.scheduler.view(record) : null;
+    }
+    /** Schedules by id, all or a workflow's; at most `limit` (default 100). */
+    async list(filter = {}) {
+        const limit = filter.limit ?? 100;
+        const offset = filter.offset ?? 0;
+        if (!Number.isSafeInteger(limit) || limit < 0 || !Number.isSafeInteger(offset) || offset < 0) {
+            throw new TypeError(`schedules.list(): limit (${limit}) and offset (${offset}) must be non-negative integers.`);
+        }
+        if (limit === 0) {
+            return [];
+        }
+        // Read as stored, then decoded one by one: one whose input no codec can read any more doesn't hide the others.
+        const records = await this.engine.store.listSchedules({ limit, offset, ...(filter.workflow !== undefined ? { target: filter.workflow } : {}) });
+        return Promise.all(records.map((record) => this.scheduler.readableView(record)));
+    }
+    /**
+     * Deletes the schedule, and returns whether it existed. The instances it started keep running. Throws
+     * `WorkflowStateError` for a schedule a workflow declares: remove it from the code, or `pause()` it.
+     */
+    async remove(id) {
+        const record = await this.engine.store.getSchedule(id);
+        if (!record) {
+            return false;
+        }
+        if (record.declared) {
+            throw declaredError(record);
+        }
+        return this.engine.store.deleteSchedule(id);
+    }
+    /**
+     * Stops starting occurrences until `resume()`, at once: a worker that is starting the schedule's occurrences at
+     * that moment starts only those it had already decided on. The instances it started keep running. A declared
+     * schedule stays paused across deploys. Throws `WorkflowNotFoundError` for an unknown id.
+     */
+    async pause(id) {
+        const saved = await this.engine.pause(id);
+        if (!saved) {
+            throw notFound(id);
+        }
+        return this.scheduler.readableView(saved);
+    }
+    /**
+     * Starts occurrences again, from the first one after now: those due while it was paused are passed over,
+     * whatever `missed` says. Throws `WorkflowNotFoundError` for an unknown id.
+     */
+    async resume(id) {
+        const saved = await this.engine.resume(id);
+        if (!saved) {
+            throw notFound(id);
+        }
+        this.worker.kick();
+        return this.scheduler.readableView(saved);
+    }
+    /**
+     * Starts an instance of the schedule now, whatever its `overlap`, even while it is paused, and outside its
+     * `limit`; its id is `<schedule id>@<ISO time of now>`, and it counts as the schedule's for the overlap of the
+     * occurrences after it. Throws `WorkflowNotFoundError` for an unknown id.
+     */
+    async trigger(id) {
+        const record = await this.engine.read(id);
+        if (!record) {
+            throw notFound(id);
+        }
+        const spec = record.spec;
+        const declared = record.declared ? this.scheduler.declaration(id) : undefined;
+        if (spec.inputFn && !declared) {
+            throw new TypeError(`Schedule "${id}" computes its input with a function, which this process doesn't declare: trigger it from one that registers workflow "${record.target}".`);
+        }
+        const workflow = this.registry.resolve(record.target, spec.version ?? undefined);
+        const now = this.clock.now();
+        const { instance, created } = (await this.scheduler.startOccurrence(record, spec, declared, workflow, now, now, true));
+        if (created) {
+            this.worker.kick();
+        }
+        return { id: instance.id, workflow: instance.workflow, version: instance.version, created, status: instance.status };
+    }
+    /**
+     * The times (epoch milliseconds) of the next occurrences after `from` (default: now), at most `count` (default
+     * 10), as a schedule saved at `from` would start them: of a stored schedule (by id, within what its `limit` has
+     * left, paused or not), or of a spec, which isn't saved. Throws `WorkflowNotFoundError` for an unknown id.
+     */
+    async preview(schedule, options = {}) {
+        const count = options.count ?? 10;
+        if (!Number.isSafeInteger(count) || count < 1 || count > 1_000) {
+            throw new TypeError(`schedules.preview(): count (${count}) must be an integer from 1 to 1000.`);
+        }
+        const from = options.from === undefined ? this.clock.now() : options.from instanceof Date ? options.from.getTime() : options.from;
+        if (typeof from !== 'number' || !Number.isFinite(from)) {
+            throw new TypeError(`schedules.preview(): invalid from ${String(options.from)}. Pass a valid Date or a timestamp in milliseconds.`);
+        }
+        if (typeof schedule !== 'string') {
+            const { cron, every, rrule, tz, startAt, endAt, limit } = schedule;
+            return nextOccurrences(parseSchedule({ cron, every, rrule, tz, startAt, endAt, limit }, 'schedules.preview()'), { from, count }, 'schedules.preview()');
+        }
+        const record = await this.engine.store.getSchedule(schedule);
+        if (!record) {
+            throw notFound(schedule);
+        }
+        return nextOccurrences(record.spec, { from, count, runs: this.engine.progress(record).runs }, 'schedules.preview()');
+    }
+};
+WorkflowSchedules = __decorate([
+    Injectable(),
+    __param(0, Inject(WORKFLOWS_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object, WorkflowRegistry,
+        WorkflowScheduler,
+        WorkflowWorker])
+], WorkflowSchedules);
+export { WorkflowSchedules };
+function notFound(id) {
+    return new WorkflowNotFoundError(`No workflow schedule with id "${id}".`);
+}
+function declaredError(record) {
+    return new WorkflowStateError(`Schedule "${record.id}" is declared by workflow "${record.target}" (@Workflow(name, { schedules })): change or remove it there. ` +
+        'pause(), resume() and trigger() work on it.');
+}

package/dist/services/workflow-worker.service.d.ts

@@ -0,0 +1,92 @@
+import { type OnApplicationBootstrap, type OnApplicationShutdown, type OnModuleDestroy } from '@nestjs/common';
+import { WorkflowEvents } from '../events/workflow-events.service.js';
+import { WorkflowStorage } from '../storage/workflow.storage.js';
+import { WorkflowRegistry } from './workflow-registry.service.js';
+import { WorkflowScheduler } from './workflow-scheduler.service.js';
+import type { WorkflowsModuleOptions } from '../interfaces/workflows-module-options.interface.js';
+/**
+ * Claims due instances under a lease, executes them and records the outcome.
+ * Any number of processes can run a worker against the same store. Inject it
+ * for `drain()`, which runs due instances on demand (tests, scripts).
+ */
+export declare class WorkflowWorker implements OnApplicationBootstrap, OnModuleDestroy, OnApplicationShutdown {
+    private readonly storage;
+    private readonly registry;
+    private readonly events;
+    private readonly scheduler;
+    /** Shown as `leaseOwner` on the instances this worker runs. */
+    readonly id: string;
+    private readonly logger;
+    private readonly clock;
+    private readonly deps;
+    private readonly enabled;
+    /** The claim-execute loop: polling, concurrency, lease renewals, the drain at shutdown. */
+    private readonly leased;
+    constructor(storage: WorkflowStorage, options: WorkflowsModuleOptions, registry: WorkflowRegistry, events: WorkflowEvents, scheduler: WorkflowScheduler);
+    onApplicationBootstrap(): void;
+    /** Read at each use, never in the constructor: sources register while providers are created. */
+    private get store();
+    onModuleDestroy(): Promise<void>;
+    /** Stops the worker if `onModuleDestroy` didn't run (an application closed before it initialized). */
+    onApplicationShutdown(): Promise<void>;
+    /** @internal Look for work now instead of at the next poll (after a local start or signal). */
+    kick(): void;
+    /**
+     * @internal After an accepted `WorkflowClient.cancel()` or `terminate()` in this process: an
+     * execution of the instance running here stops at its next `ctx` call now,
+     * instead of when its next heartbeat reads the flag.
+     */
+    noticeCancel(id: string, terminate?: boolean): void;
+    /**
+     * Executes every due instance, repeatedly, until none is left that its workflow's concurrency and rate
+     * limits let start. Returns the number of executions. For tests (with a `ManualWorkflowClock` and
+     * `worker: false`), scripts and cron-driven workers.
+     */
+    drain(options?: {
+        maxRounds?: number;
+    }): Promise<number>;
+    /** After a production of the schedules' occurrences: cancels its executions of the instances it cancelled. */
+    private produced;
+    /**
+     * @internal Called on application shutdown. Stops claiming, asks running
+     * executions to stop (their steps see `signal.aborted`), and waits up to
+     * `shutdownTimeout`. Executions that stopped are handed back at once; the
+     * rest keep their lease until it expires, because their step may still be running.
+     */
+    shutdown(): Promise<void>;
+    /** Leases due instances of the workflow versions this process runs, under their limits. */
+    private claim;
+    /** Extends an instance's lease, and hands its execution the cancel and terminate requests the renewal read. */
+    private renew;
+    private execute;
+    /**
+     * The claimed instance with its journal, or `null` when that can't be read (a codec whose key is gone wrote part of
+     * the journal, as after a key rotation that was rolled back): then it is handed back, as a claim hands back an
+     * instance whose own payloads can't be read, instead of holding its lease and its concurrency slot until the lease
+     * expires, and going first at every claim after that.
+     */
+    private claimed;
+    private conclude;
+    private compensate;
+    /**
+     * Applies each child's `parentClose` to the children of this instance that are still running:
+     * cancels or terminates them. At least once: it runs again after a crash, and a request that
+     * was already accepted is refused, changing nothing.
+     */
+    private closeChildren;
+    /** Ends the instance as `cancelled` without running (more of) its compensations. */
+    private terminate;
+    /**
+     * Handles executions that must not record an outcome. Returns true if
+     * handled. A run that finished cleanly during shutdown is still recorded;
+     * one that was cut short is handed back, and whatever it was doing is
+     * re-derived by the next execution.
+     */
+    private interrupted;
+    private finish;
+    /** A fenced write under the execution's lease, stamped with the clock, with the custom status if it changed. */
+    private write;
+    private release;
+    private leaseLostWarning;
+    private emit;
+}