@baasix/baasix 0.1.53 → 0.1.56

package/dist/services/TasksService.d.ts

@@ -2,38 +2,69 @@ import type { BackgroundTask } from '../types/index.js';
 declare class TasksService {
     private cache;
     private cacheKey;
-    private taskRunningKey;
     private refreshInterval;
     private refreshIntervalId;
     private initialized;
+    private shuttingDown;
+    private concurrency;
+    private runningCount;
+    private stallTimeout;
     private redisClient;
     private useTaskRedis;
     private instanceId;
     private lockRenewalInterval;
+    private hasInstanceLock;
+    private static readonly LOCK_KEY;
     private static readonly LOCK_TTL_SECONDS;
     private static readonly LOCK_RENEWAL_INTERVAL;
     init(): Promise<void>;
     ensureInitialized(): Promise<void>;
     refreshCache(): Promise<void>;
     getNotStartedTasks(): Promise<BackgroundTask[]>;
-    setTaskRunning(isRunning: boolean): Promise<void>;
-    isTaskRunning(): Promise<boolean>;
     /**
-     * Try to acquire a distributed lock for task processing
-     * This ensures only one instance processes tasks at a time
+     * Atomically claim a task for processing.
+     * Uses UPDATE ... WHERE task_status = 'Not started' to prevent duplicate processing.
+     * If another worker already claimed the task, returns null (0 rows updated).
      *
-     * In multi-instance mode (TASK_REDIS_ENABLED=true):
-     *   Uses Redis SETNX for atomic lock acquisition
+     * @param taskId - The task ID to claim
+     * @returns The claimed task record, or null if already claimed/not found
+     */
+    claimTask(taskId: string | number): Promise<BackgroundTask | null>;
+    /**
+     * Recover tasks stuck in "Running" state beyond the stall timeout.
+     * - If retry_count < max_retries: resets to "Not started" for automatic retry
+     * - Otherwise: marks as "Error" with stall information
      *
-     * In single-instance mode:
-     *   Falls back to cache-based locking
+     * Called during initialization and each periodic cache refresh.
+     */
+    recoverStalledTasks(): Promise<void>;
+    /**
+     * @deprecated Use tryAcquireLock()/releaseLock() for atomic task coordination.
+     * setTaskRunning(true) now delegates to tryAcquireLock() internally.
+     */
+    setTaskRunning(isRunning: boolean): Promise<void>;
+    /**
+     * Check if task processing is at capacity.
+     * Returns true when running task count >= configured TASK_CONCURRENCY.
+     * With default concurrency of 1, returns true if any task is running.
+     */
+    isTaskRunning(): Promise<boolean>;
+    /**
+     * Get the number of currently running tasks.
+     */
+    getRunningCount(): number;
+    /**
+     * Try to acquire a task processing slot.
+     * Respects TASK_CONCURRENCY — allows up to N concurrent tasks per instance.
+     * In multi-instance mode, only one instance can hold the processing lock at a time.
      *
-     * @param lockTimeout - Lock expiration time in seconds (default: 60 seconds)
-     * @returns True if lock acquired, false otherwise
+     * @param lockTimeout - Redis lock TTL in seconds (multi-instance only, default: 60s)
+     * @returns True if slot acquired, false if at capacity or lock held by another instance
      */
     tryAcquireLock(lockTimeout?: number): Promise<boolean>;
     /**
-     * Start automatic lock renewal to prevent expiry during long-running tasks
+     * Start automatic lock renewal to prevent expiry during long-running tasks.
+     * Uses Lua script for atomic check-and-renew (prevents race between GET and EXPIRE).
      */
     private startLockRenewal;
     /**
@@ -41,16 +72,69 @@ declare class TasksService {
      */
     private stopLockRenewal;
     /**
-     * Release the distributed lock
-     * Only releases if the current instance owns the lock
-     * @returns True if lock released, false otherwise
+     * Release a task processing slot.
+     * When all slots are released, the instance lock (Redis) is also released.
+     * @returns True if slot released, false otherwise
      */
     releaseLock(): Promise<boolean>;
+    /**
+     * In-memory set of job locks held by this instance (single-instance fallback).
+     */
+    private heldJobLocks;
+    /**
+     * Acquire a named distributed lock for a scheduled job.
+     * Prevents the same job from running on multiple instances simultaneously.
+     *
+     * - With Redis (`TASK_REDIS_ENABLED=true`): uses `SET NX EX` for cross-instance locking
+     * - Without Redis: uses in-memory set (prevents re-entry within same process)
+     *
+     * @param jobName  - Unique job identifier (e.g., "attendance-cron", "cleanup-job")
+     * @param ttlSeconds - Lock TTL in seconds. Should be >= your job's max execution time.
+     *                     Lock auto-expires after this, so a crashed instance won't block forever.
+     *                     Default: 300 (5 minutes)
+     * @returns `true` if lock acquired, `false` if already held (by this or another instance)
+     *
+     * @example
+     * ```ts
+     * schedule.scheduleJob(everyFifteenMinutes, async () => {
+     *   const locked = await tasksService.acquireJobLock("attendance-cron", 600);
+     *   if (!locked) return; // another instance is running this job
+     *   try {
+     *     await AttendanceUtils.ProcessScheduleAttendance(...);
+     *   } finally {
+     *     await tasksService.releaseJobLock("attendance-cron");
+     *   }
+     * });
+     * ```
+     */
+    acquireJobLock(jobName: string, ttlSeconds?: number): Promise<boolean>;
+    /**
+     * Release a named job lock.
+     * Only releases if this instance owns the lock (atomic check via Lua in Redis mode).
+     *
+     * @param jobName - The job name used in acquireJobLock()
+     * @returns `true` if released, `false` if not owned or error
+     */
+    releaseJobLock(jobName: string): Promise<boolean>;
     startPeriodicRefresh(): void;
     stopPeriodicRefresh(): void;
+    /**
+     * Add a task to the cached "not started" list without querying the DB.
+     * Only adds if the task is "Not started" and scheduled within 4 hours.
+     */
+    private addTaskToCache;
+    /**
+     * Remove a task from the cached "not started" list by ID without querying the DB.
+     */
+    private removeTaskFromCache;
+    /**
+     * Update a task in the cached "not started" list without querying the DB.
+     * Replaces the cached task object with the new document.
+     */
+    private updateTaskInCache;
     registerHooks(): void;
     /**
-     * Wait for any running task to complete (with timeout)
+     * Wait for all running tasks to complete (with timeout)
      */
     waitForTaskCompletion(timeoutMs?: number): Promise<void>;
     /**

package/dist/services/TasksService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TasksService.d.ts","sourceRoot":"","sources":["../../baasix/services/TasksService.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,cAAM,YAAY;IAChB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,WAAW,CAAkB;IAGrC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,mBAAmB,CAA+B;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAM;IAC9C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAEhD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmDrB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B7B,kBAAkB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAuB/C,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAejD,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAgBvC;;;;;;;;;;;;OAYG;IACG,cAAc,CAAC,WAAW,GAAE,MAAsC,GAAG,OAAO,CAAC,OAAO,CAAC;IA+C3F;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IA4CrC,oBAAoB,IAAI,IAAI;IAc5B,mBAAmB,IAAI,IAAI;IAQ3B,aAAa,IAAI,IAAI;IAuBrB;;OAEG;IACG,qBAAqB,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBrE;;OAEG;IACG,QAAQ,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBxD;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CA0CpD;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,qBAAqB,EAAE,YAAY,GAAG,SAAS,CAAC;CACrD;AAOD,QAAA,MAAM,YAAY,cAAmC,CAAC;AAEtD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"TasksService.d.ts","sourceRoot":"","sources":["../../baasix/services/TasksService.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,cAAM,YAAY;IAChB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,WAAW,CAAkB;IAGrC,OAAO,CAAC,YAAY,CAAkB;IAGtC,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,YAAY,CAAa;IAGjC,OAAO,CAAC,YAAY,CAAe;IAGnC,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,mBAAmB,CAA+B;IAC1D,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAM;IAC9C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAEhD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiErB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B7B,kBAAkB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IA4BrD;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAgDxE;;;;;;OAMG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE1C;;;OAGG;IACG,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBvD;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAMvC;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;OAOG;IACG,cAAc,CAAC,WAAW,GAAE,MAAsC,GAAG,OAAO,CAAC,OAAO,CAAC;IAgD3F;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAiCxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAiDrC;;OAEG;IACH,OAAO,CAAC,YAAY,CAA0B;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IA4CjF;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyCvD,oBAAoB,IAAI,IAAI;IAa5B,mBAAmB,IAAI,IAAI;IAU3B;;;OAGG;YACW,cAAc;IAyB5B;;OAEG;YACW,mBAAmB;IAiBjC;;;OAGG;YACW,iBAAiB;IAkB/B,aAAa,IAAI,IAAI;IA8CrB;;OAEG;IACG,qBAAqB,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBrE;;OAEG;IACG,QAAQ,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCxD;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAKnC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAmDpD;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,qBAAqB,EAAE,YAAY,GAAG,SAAS,CAAC;CACrD;AAOD,QAAA,MAAM,YAAY,cAAmC,CAAC;AAEtD,eAAe,YAAY,CAAC"}