@spinajs/tasks 2.0.553 → 2.0.555

package/lib/cjs/decorators.d.ts

@@ -1,18 +1,48 @@
 export declare const TASK_COMMAND = "task:command";
-interface TaskOptions {
+export interface TaskOptions {
+    /**
+     * Allow several runs of the same task at once, e.g. a long run that overlaps the next start.
+     */
     taskStacking: boolean;
+    /**
+     * Lifetime of the task mutex in ms, renewed every lockTtl / 3 while the task runs, so a
+     * crashed process frees the task after at most lockTtl. 0 = never expires.
+     */
+    lockTtl: number;
 }
+export declare const DEFAULT_TASK_OPTIONS: TaskOptions;
+export interface TaskDeclaration {
+    name: string;
+    description: string;
+    options: TaskOptions;
+    /** The class that declares the method (the constructor itself for a static method). */
+    target: Function;
+    isStatic: boolean;
+    propertyKey: string | symbol;
+    /** The undecorated method. */
+    method: (...args: any[]) => unknown;
+}
+export interface RunTaskOptions {
+    /** false: skip the task mutex, its heartbeat and the in-process guard (the caller holds a lock of its own). */
+    lock: boolean;
+    /** true: rethrow the task's error after history is written, instead of resolving with `{ error: true }`. */
+    rethrow: boolean;
+}
+export declare function getTaskDeclarations(name?: string): TaskDeclaration[];
 /**
- * Cli command, wrapper for lib commander. For more docs on command options & args check
- * https://github.com/tj/commander.js
- *
- * It allows to use all features that spinajs provides eg. DI, logging, intl support etc.
- * inside command functions without hassle.
+ * Runs a task method with the `@Task` bookkeeping: `__tasks` state, a `__task_history` row and
+ * TaskSuccess / TaskFailed. The decorator calls it with `{ lock: true, rethrow: false }`.
+ */
+export declare function runTask(decl: TaskDeclaration, thisArg: unknown, args: unknown[], opts: RunTaskOptions): Promise<unknown>;
+/**
+ * Marks a method as a task: records runs in `__tasks` / `__task_history`, emits
+ * TaskSuccess / TaskFailed and, unless `taskStacking` is set, lets only one run
+ * happen at a time across all processes sharing the database. The declaration is
+ * also recorded, so `@spinajs/scheduler` can schedule the method by task name.
  *
- * @param nameAndArgs - name of command with optional args defined
- * @param description  - short description
- * @param opts - additional options, see https://github.com/tj/commander.js
+ * @param taskName - unique task name
+ * @param description - short description
+ * @param opts - see {@link TaskOptions}, defaults to {@link DEFAULT_TASK_OPTIONS}
  */
-export declare function Task(taskName: string, description: string, opts?: TaskOptions): (_target: any, _propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
-export {};
+export declare function Task(taskName: string, description: string, opts?: Partial<TaskOptions>): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 //# sourceMappingURL=decorators.d.ts.map

package/lib/cjs/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,UAAU,WAAW;IAInB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,aAIlD,GAAG,gBAAgB,MAAM,GAAG,MAAM,cAAc,kBAAkB,UA4E7F"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,oBAAoB,EAAE,WAGlC,CAAC;AAqDF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,uFAAuF;IACvF,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,+GAA+G;IAC/G,IAAI,EAAE,OAAO,CAAC;IACd,4GAA4G;IAC5G,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,CAKpE;AAQD;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,OAAO,CAAC,CAsFlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,YAK5D,GAAG,eAAe,MAAM,GAAG,MAAM,cAAc,kBAAkB,UAiB3F"}

package/lib/cjs/decorators.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TASK_COMMAND = void 0;
+exports.DEFAULT_TASK_OPTIONS = exports.TASK_COMMAND = void 0;
+exports.getTaskDeclarations = getTaskDeclarations;
+exports.runTask = runTask;
 exports.Task = Task;
 const threading_1 = require("@spinajs/threading");
 const util_1 = require("@spinajs/util");
@@ -11,87 +13,181 @@ const __task_history_js_1 = require("./models/__task_history.js");
 const TaskSuccess_js_1 = require("./events/TaskSuccess.js");
 const TaskFailed_js_1 = require("./events/TaskFailed.js");
 exports.TASK_COMMAND = 'task:command';
+exports.DEFAULT_TASK_OPTIONS = {
+    taskStacking: false,
+    lockTtl: 60000,
+};
+// The mutex is re-entrant per tenant and the default tenant is per process,
+// so overlapping runs inside one process are excluded here, not by the mutex.
+const runningInProcess = new Set();
+async function lockTask(name, opts, log) {
+    if (opts.taskStacking) {
+        return async () => { };
+    }
+    if (runningInProcess.has(name)) {
+        log.warn(`Task ${name} is already running in this process`);
+        return null;
+    }
+    runningInProcess.add(name);
+    const mutexName = `task-${name}`;
+    try {
+        const lock = await (0, threading_1.mutex_acquire)({ Name: mutexName, ttl: opts.lockTtl });
+        if (!lock.Locked) {
+            runningInProcess.delete(name);
+            log.warn(`Cannot acquire mutex for task ${name}, already locked !`);
+            return null;
+        }
+    }
+    catch (err) {
+        runningInProcess.delete(name);
+        throw err;
+    }
+    const heartbeat = opts.lockTtl > 0
+        ? setInterval(() => {
+            (0, threading_1.mutex_renew)({ Name: mutexName, ttl: opts.lockTtl })
+                .then((renewed) => {
+                if (!renewed) {
+                    log.warn(`Task ${name} lost its mutex, another process may run it now`);
+                }
+            })
+                .catch((err) => log.error(err, `Cannot renew mutex for task ${name}`));
+        }, Math.max(1, Math.floor(opts.lockTtl / 3)))
+        : undefined;
+    return async () => {
+        clearInterval(heartbeat);
+        runningInProcess.delete(name);
+        await (0, threading_1.mutex_release)({ Name: mutexName });
+    };
+}
+const declarations = new Map();
+function getTaskDeclarations(name) {
+    if (name !== undefined) {
+        return [...(declarations.get(name) ?? [])];
+    }
+    return [...declarations.values()].flat();
+}
+function errorMessage(err) {
+    return err?.message ?? String(err);
+}
+const NO_LOCK = () => Promise.resolve();
 /**
- * Cli command, wrapper for lib commander. For more docs on command options & args check
- * https://github.com/tj/commander.js
- *
- * It allows to use all features that spinajs provides eg. DI, logging, intl support etc.
- * inside command functions without hassle.
+ * Runs a task method with the `@Task` bookkeeping: `__tasks` state, a `__task_history` row and
+ * TaskSuccess / TaskFailed. The decorator calls it with `{ lock: true, rethrow: false }`.
+ */
+async function runTask(decl, thisArg, args, opts) {
+    const log = di_1.DI.resolve('__log__', ['TASKS']);
+    log.info(`Executing task ${decl.name} ...`);
+    let task;
+    let unlock;
+    try {
+        task = await __task_js_1.__task.getOrCreate(null, {
+            Name: decl.name,
+            Description: decl.description,
+            State: 'stopped',
+        });
+        const lock = opts.lock ? await lockTask(decl.name, decl.options, log) : NO_LOCK;
+        if (!lock) {
+            return undefined;
+        }
+        unlock = lock;
+        try {
+            task.State = 'running';
+            task.LastRunAt = luxon_1.DateTime.now();
+            await task.update();
+        }
+        catch (err) {
+            await unlock();
+            throw err;
+        }
+    }
+    catch (err) {
+        log.error(err, `Cannot start task ${decl.name}`);
+        throw err;
+    }
+    let taskResult = null;
+    let failure = null;
+    const start = luxon_1.DateTime.now();
+    try {
+        try {
+            taskResult = await decl.method.apply(thisArg, args);
+        }
+        catch (err) {
+            failure = { error: err };
+            log.error(err, `Cannot execute task ${decl.name}`);
+            taskResult = {
+                error: true,
+                message: errorMessage(err),
+            };
+        }
+        // An emit failure (queue outage) is logged only: it must not turn a run whose side effects
+        // already happened into a failure that a caller would retry.
+        try {
+            if (failure) {
+                await TaskFailed_js_1.TaskFailed.emit({
+                    TaskName: decl.name,
+                    Reason: errorMessage(failure.error),
+                });
+            }
+            else {
+                await TaskSuccess_js_1.TaskSuccess.emit({
+                    TaskName: decl.name,
+                });
+                log.success(`Task ${decl.name} executed !`);
+            }
+        }
+        catch (emitErr) {
+            log.error(emitErr, `Cannot emit ${failure ? 'TaskFailed' : 'TaskSuccess'} for ${decl.name}`);
+        }
+    }
+    finally {
+        try {
+            await unlock();
+            await task.update({
+                State: 'stopped',
+            });
+            await __task_history_js_1.__task_history.insert({
+                TaskId: task.Id,
+                Result: taskResult,
+                Duration: luxon_1.DateTime.now().diff(start).milliseconds,
+            });
+        }
+        catch (err) {
+            log.error(err, `Cannot finalize task`);
+        }
+    }
+    if (failure && opts.rethrow) {
+        throw failure.error;
+    }
+    return taskResult;
+}
+/**
+ * Marks a method as a task: records runs in `__tasks` / `__task_history`, emits
+ * TaskSuccess / TaskFailed and, unless `taskStacking` is set, lets only one run
+ * happen at a time across all processes sharing the database. The declaration is
+ * also recorded, so `@spinajs/scheduler` can schedule the method by task name.
  *
- * @param nameAndArgs - name of command with optional args defined
- * @param description  - short description
- * @param opts - additional options, see https://github.com/tj/commander.js
+ * @param taskName - unique task name
+ * @param description - short description
+ * @param opts - see {@link TaskOptions}, defaults to {@link DEFAULT_TASK_OPTIONS}
  */
 function Task(taskName, description, opts) {
     const _name = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(taskName, 'Task name is empty');
     const _description = (0, util_1._check_arg)((0, util_1._trim)(), (0, util_1._non_empty)())(description, 'Task description is empty');
-    return function (_target, _propertyKey, descriptor) {
-        const oldFunction = descriptor.value;
-        descriptor.value = async function (...args) {
-            const log = di_1.DI.resolve('__log__', ['TASKS']);
-            log.info(`Executing task ${_name} ...`);
-            try {
-                const task = await __task_js_1.__task.getOrCreate(null, {
-                    Name: _name,
-                    Description: _description,
-                    State: 'stopped',
-                });
-                if (!opts.taskStacking) {
-                    const lock = await (0, threading_1.mutex_acquire)({
-                        Name: `task-${_name}`,
-                    });
-                    if (!lock.Locked) {
-                        log.warn(`Cannot acquire mutex for task ${_name}, already locked !`);
-                        return;
-                    }
-                }
-                task.State = 'running';
-                task.LastRunAt = luxon_1.DateTime.now();
-                await task.update();
-                let taskResult = null;
-                const start = luxon_1.DateTime.now();
-                try {
-                    taskResult = await oldFunction.apply(this, args);
-                    await TaskSuccess_js_1.TaskSuccess.emit({
-                        TaskName: taskName,
-                    });
-                    log.success(`Task ${taskName} executed !`);
-                }
-                catch (err) {
-                    log.error(err, `Cannot execute task ${taskName}`);
-                    taskResult = {
-                        error: true,
-                        message: err.Message,
-                    };
-                    await TaskFailed_js_1.TaskFailed.emit({
-                        TaskName: taskName,
-                        Reason: err.Message,
-                    });
-                }
-                finally {
-                    try {
-                        await (0, threading_1.mutex_release)({
-                            Name: `task-${name}`,
-                        });
-                        await task.update({
-                            State: 'stopped',
-                        });
-                        await __task_history_js_1.__task_history.insert({
-                            TaskId: task.Id,
-                            Result: taskResult,
-                            Duration: luxon_1.DateTime.now().diff(start).milliseconds,
-                        });
-                    }
-                    catch (err) {
-                        log.error(err, `Cannot finalize task`);
-                    }
-                    return taskResult;
-                }
-            }
-            catch (err) {
-                log.error(err, `Cannot start task ${taskName}`);
-                throw err;
-            }
+    const _opts = { ...exports.DEFAULT_TASK_OPTIONS, ...opts };
+    return function (target, propertyKey, descriptor) {
+        const isStatic = typeof target === 'function';
+        const decl = {
+            name: _name,
+            description: _description,
+            options: _opts,
+            target: isStatic ? target : target.constructor,
+            isStatic,
+            propertyKey,
+            method: descriptor.value,
+        };
+        declarations.set(_name, [...(declarations.get(_name) ?? []), decl]);
+        descriptor.value = function (...args) {
+            return runTask(decl, this, args, { lock: true, rethrow: false });
         };
     };
 }

package/lib/cjs/decorators.js.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":";;;;;;AAAA,kDAA+E;AAC/E,wCAA8D;AAC9D,oCAAiC;AACjC,kDAA4C;AAC5C,iCAAiC;AACjC,kEAA4D;AAE5D,4DAAsD;AACtD,0DAAoD;AAEvC,QAAA,YAAY,GAAG,cAAc,CAAC;AAe9B,QAAA,oBAAoB,GAAgB;IAC/C,YAAY,EAAE,KAAK;IACnB,OAAO,EAAE,KAAK;CACf,CAAC;AAIF,4EAA4E;AAC5E,8EAA8E;AAC9E,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;AAE3C,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,IAAiB,EAAE,GAAQ;IAC/D,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,OAAO,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,qCAAqC,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,SAAS,GAAG,QAAQ,IAAI,EAAE,CAAC;IAEjC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAA,yBAAa,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC9B,GAAG,CAAC,IAAI,CAAC,iCAAiC,IAAI,oBAAoB,CAAC,CAAC;YACpE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,SAAS,GACb,IAAI,CAAC,OAAO,GAAG,CAAC;QACd,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE;YACf,IAAA,uBAAW,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;iBAChD,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;gBAChB,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,iDAAiD,CAAC,CAAC;gBAC1E,CAAC;YACH,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,+BAA+B,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3E,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO,KAAK,IAAI,EAAE;QAChB,aAAa,CAAC,SAAS,CAAC,CAAC;QACzB,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,IAAA,yBAAa,EAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC;AACJ,CAAC;AAqBD,MAAM,YAAY,GAAG,IAAI,GAAG,EAA6B,CAAC;AAE1D,6BAAoC,IAAa;IAC/C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,OAAQ,GAA+C,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,OAAO,GAAW,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;AAEhD;;;GAGG;AACI,KAAK,kBACV,IAAqB,EACrB,OAAgB,EAChB,IAAe,EACf,IAAoB;IAEpB,MAAM,GAAG,GAAG,OAAE,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAQ,CAAC;IACpD,GAAG,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,MAAM,CAAC,CAAC;IAE5C,IAAI,IAAY,CAAC;IACjB,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,kBAAM,CAAC,WAAW,CAAC,IAAI,EAAE;YACpC,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAChF,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,GAAG,IAAI,CAAC;QAEd,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;YACvB,IAAI,CAAC,SAAS,GAAG,gBAAQ,CAAC,GAAG,EAAE,CAAC;YAChC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,EAAE,CAAC;YACf,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,qBAAqB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACjD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,IAAI,UAAU,GAAY,IAAI,CAAC;IAC/B,IAAI,OAAO,GAA8B,IAAI,CAAC;IAC9C,MAAM,KAAK,GAAG,gBAAQ,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,IAAI,CAAC;YACH,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;YACzB,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,uBAAuB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACnD,UAAU,GAAG;gBACX,KAAK,EAAE,IAAI;gBACX,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC;aAC3B,CAAC;QACJ,CAAC;QAED,2FAA2F;QAC3F,6DAA6D;QAC7D,IAAI,CAAC;YACH,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,0BAAU,CAAC,IAAI,CAAC;oBACpB,QAAQ,EAAE,IAAI,CAAC,IAAI;oBACnB,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC;iBACpC,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,4BAAW,CAAC,IAAI,CAAC;oBACrB,QAAQ,EAAE,IAAI,CAAC,IAAI;iBACpB,CAAC,CAAC;gBACH,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,IAAI,aAAa,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAAC,OAAO,OAAO,EAAE,CAAC;YACjB,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,MAAM,EAAE,CAAC;YAEf,MAAM,IAAI,CAAC,MAAM,CAAC;gBAChB,KAAK,EAAE,SAAS;aACjB,CAAC,CAAC;YAEH,MAAM,kCAAc,CAAC,MAAM,CAAC;gBAC1B,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,MAAM,EAAE,UAAU;gBAClB,QAAQ,EAAE,gBAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY;aAClD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,IAAI,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;GASG;AACH,cAAqB,QAAgB,EAAE,WAAmB,EAAE,IAA2B;IACrF,MAAM,KAAK,GAAW,IAAA,iBAAU,EAAC,IAAA,YAAK,GAAE,EAAE,IAAA,iBAAU,GAAE,CAAC,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;IACxF,MAAM,YAAY,GAAW,IAAA,iBAAU,EAAC,IAAA,YAAK,GAAE,EAAE,IAAA,iBAAU,GAAE,CAAC,CAAC,WAAW,EAAE,2BAA2B,CAAC,CAAC;IACzG,MAAM,KAAK,GAAgB,EAAE,GAAG,QAAA,oBAAoB,EAAE,GAAG,IAAI,EAAE,CAAC;IAEhE,OAAO,UAAU,MAAW,EAAE,WAA4B,EAAE,UAA8B;QACxF,MAAM,QAAQ,GAAG,OAAO,MAAM,KAAK,UAAU,CAAC;QAC9C,MAAM,IAAI,GAAoB;YAC5B,IAAI,EAAE,KAAK;YACX,WAAW,EAAE,YAAY;YACzB,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW;YAC9C,QAAQ;YACR,WAAW;YACX,MAAM,EAAE,UAAU,CAAC,KAAK;SACzB,CAAC;QACF,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAEpE,UAAU,CAAC,KAAK,GAAG,UAAU,GAAG,IAAW;YACzC,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACnE,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/lib/mjs/decorators.d.ts

@@ -1,18 +1,48 @@
 export declare const TASK_COMMAND = "task:command";
-interface TaskOptions {
+export interface TaskOptions {
+    /**
+     * Allow several runs of the same task at once, e.g. a long run that overlaps the next start.
+     */
     taskStacking: boolean;
+    /**
+     * Lifetime of the task mutex in ms, renewed every lockTtl / 3 while the task runs, so a
+     * crashed process frees the task after at most lockTtl. 0 = never expires.
+     */
+    lockTtl: number;
 }
+export declare const DEFAULT_TASK_OPTIONS: TaskOptions;
+export interface TaskDeclaration {
+    name: string;
+    description: string;
+    options: TaskOptions;
+    /** The class that declares the method (the constructor itself for a static method). */
+    target: Function;
+    isStatic: boolean;
+    propertyKey: string | symbol;
+    /** The undecorated method. */
+    method: (...args: any[]) => unknown;
+}
+export interface RunTaskOptions {
+    /** false: skip the task mutex, its heartbeat and the in-process guard (the caller holds a lock of its own). */
+    lock: boolean;
+    /** true: rethrow the task's error after history is written, instead of resolving with `{ error: true }`. */
+    rethrow: boolean;
+}
+export declare function getTaskDeclarations(name?: string): TaskDeclaration[];
 /**
- * Cli command, wrapper for lib commander. For more docs on command options & args check
- * https://github.com/tj/commander.js
- *
- * It allows to use all features that spinajs provides eg. DI, logging, intl support etc.
- * inside command functions without hassle.
+ * Runs a task method with the `@Task` bookkeeping: `__tasks` state, a `__task_history` row and
+ * TaskSuccess / TaskFailed. The decorator calls it with `{ lock: true, rethrow: false }`.
+ */
+export declare function runTask(decl: TaskDeclaration, thisArg: unknown, args: unknown[], opts: RunTaskOptions): Promise<unknown>;
+/**
+ * Marks a method as a task: records runs in `__tasks` / `__task_history`, emits
+ * TaskSuccess / TaskFailed and, unless `taskStacking` is set, lets only one run
+ * happen at a time across all processes sharing the database. The declaration is
+ * also recorded, so `@spinajs/scheduler` can schedule the method by task name.
  *
- * @param nameAndArgs - name of command with optional args defined
- * @param description  - short description
- * @param opts - additional options, see https://github.com/tj/commander.js
+ * @param taskName - unique task name
+ * @param description - short description
+ * @param opts - see {@link TaskOptions}, defaults to {@link DEFAULT_TASK_OPTIONS}
  */
-export declare function Task(taskName: string, description: string, opts?: TaskOptions): (_target: any, _propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
-export {};
+export declare function Task(taskName: string, description: string, opts?: Partial<TaskOptions>): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 //# sourceMappingURL=decorators.d.ts.map

package/lib/mjs/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,UAAU,WAAW;IAInB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,aAIlD,GAAG,gBAAgB,MAAM,GAAG,MAAM,cAAc,kBAAkB,UA4E7F"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,oBAAoB,EAAE,WAGlC,CAAC;AAqDF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,uFAAuF;IACvF,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,+GAA+G;IAC/G,IAAI,EAAE,OAAO,CAAC;IACd,4GAA4G;IAC5G,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,CAKpE;AAQD;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,OAAO,CAAC,CAsFlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,YAK5D,GAAG,eAAe,MAAM,GAAG,MAAM,cAAc,kBAAkB,UAiB3F"}