@fluojs/cron 1.0.0-beta.1

package/dist/distributed-lock-manager.js

@@ -0,0 +1,181 @@
+import { getRedisClientToken } from '@fluojs/redis';
+const RELEASE_LOCK_SCRIPT = 'if redis.call("GET", KEYS[1]) == ARGV[1] then return redis.call("DEL", KEYS[1]) else return 0 end';
+const RENEW_LOCK_SCRIPT = 'if redis.call("GET", KEYS[1]) == ARGV[1] then return redis.call("PEXPIRE", KEYS[1], ARGV[2]) else return 0 end';
+export class CronDistributedLockManager {
+  ownedLockKeys = new Set();
+  redisClient;
+  lockOwnershipLosses = 0;
+  lockRenewalFailures = 0;
+  constructor(options, runtimeContainer, logger) {
+    this.options = options;
+    this.runtimeContainer = runtimeContainer;
+    this.logger = logger;
+  }
+  get resolvedClient() {
+    return this.redisClient;
+  }
+  get ownedLocks() {
+    return this.ownedLockKeys.size;
+  }
+  get ownershipLosses() {
+    return this.lockOwnershipLosses;
+  }
+  get renewalFailures() {
+    return this.lockRenewalFailures;
+  }
+  async resolveClient() {
+    if (!this.options.distributed.enabled) {
+      return;
+    }
+    const redisToken = getRedisClientToken(this.options.distributed.clientName);
+    if (!this.runtimeContainer.has(redisToken)) {
+      throw new Error('Cron distributed mode requires the configured Redis client to be registered.');
+    }
+    const redisClient = await this.runtimeContainer.resolve(redisToken);
+    if (!hasRedisLockClient(redisClient)) {
+      throw new Error('Cron distributed mode requires the configured Redis client to implement set/eval lock operations.');
+    }
+    this.redisClient = redisClient;
+  }
+  reset() {
+    this.redisClient = undefined;
+  }
+  async tryAcquireLock(descriptor) {
+    const redis = this.redisClient;
+    if (!redis) {
+      return true;
+    }
+    try {
+      const result = await redis.set(descriptor.lockKey, this.options.distributed.ownerId, 'PX', descriptor.lockTtlMs, 'NX');
+      if (result === 'OK') {
+        this.ownedLockKeys.add(descriptor.lockKey);
+      }
+      return result === 'OK';
+    } catch (error) {
+      this.logger.error(`Failed to acquire distributed cron lock for ${descriptor.taskName}.`, error, 'CronLifecycleService');
+      return false;
+    }
+  }
+  startLockRenewalMonitor(descriptor) {
+    const renewalState = this.createLockRenewalState(descriptor.lockTtlMs);
+    const renewalTimer = setInterval(() => {
+      if (renewalState.stopped) {
+        return;
+      }
+      renewalState.nextRenewalDueAt += renewalState.renewalIntervalMs;
+      renewalState.renewalChain = renewalState.renewalChain.then(async () => {
+        await this.runLockRenewalAttempt(descriptor, renewalState);
+      });
+    }, renewalState.renewalIntervalMs);
+    return {
+      getPostRunError: async () => {
+        this.queueDueLockRenewalAttempts(descriptor, renewalState);
+        await renewalState.renewalChain;
+        return renewalState.lockPostRunError;
+      },
+      stop: () => {
+        if (renewalState.stopped) {
+          return;
+        }
+        renewalState.stopped = true;
+        clearInterval(renewalTimer);
+      }
+    };
+  }
+  async releaseLock(descriptor) {
+    await this.releaseLockKey(descriptor.lockKey, descriptor.taskName);
+  }
+  async releaseOwnedLocks() {
+    if (!this.redisClient || this.ownedLockKeys.size === 0) {
+      return;
+    }
+    const lockKeys = Array.from(this.ownedLockKeys);
+    await Promise.all(lockKeys.map(async lockKey => {
+      await this.releaseLockKey(lockKey, lockKey);
+    }));
+  }
+  createLockRenewalState(lockTtlMs) {
+    const renewalIntervalMs = Math.max(250, Math.floor(lockTtlMs / 2));
+    return {
+      lockPostRunError: undefined,
+      nextRenewalDueAt: Date.now() + renewalIntervalMs,
+      renewalChain: Promise.resolve(),
+      renewalIntervalMs,
+      stopped: false
+    };
+  }
+  queueDueLockRenewalAttempts(descriptor, renewalState) {
+    const now = Date.now();
+    while (now >= renewalState.nextRenewalDueAt) {
+      renewalState.nextRenewalDueAt += renewalState.renewalIntervalMs;
+      renewalState.renewalChain = renewalState.renewalChain.then(async () => {
+        await this.runLockRenewalAttempt(descriptor, renewalState);
+      });
+    }
+  }
+  async runLockRenewalAttempt(descriptor, renewalState) {
+    const outcome = await this.renewLock(descriptor);
+    if (outcome === 'ownership-lost') {
+      this.lockOwnershipLosses += 1;
+    }
+    if (outcome === 'renewal-failed') {
+      this.lockRenewalFailures += 1;
+    }
+    if (renewalState.lockPostRunError) {
+      return;
+    }
+    renewalState.lockPostRunError = this.toLockPostRunError(outcome, descriptor.taskName);
+  }
+  toLockPostRunError(outcome, taskName) {
+    if (outcome === 'ownership-lost') {
+      return new Error(`Distributed cron lock ownership lost for ${taskName}.`);
+    }
+    if (outcome === 'renewal-failed') {
+      return new Error(`Distributed cron lock renewal failed for ${taskName}.`);
+    }
+    return undefined;
+  }
+  async renewLock(descriptor) {
+    const redis = this.redisClient;
+    if (!redis) {
+      return 'renewed';
+    }
+    try {
+      const result = await redis.eval(RENEW_LOCK_SCRIPT, 1, descriptor.lockKey, this.options.distributed.ownerId, String(descriptor.lockTtlMs));
+      if (typeof result === 'number' && result <= 0) {
+        this.logger.warn(`Distributed cron lock ownership was lost for ${descriptor.taskName}.`, 'CronLifecycleService');
+        return 'ownership-lost';
+      }
+      this.logger.log(`Renewed distributed cron lock for ${descriptor.taskName}.`, 'CronLifecycleService');
+      return 'renewed';
+    } catch (error) {
+      this.logger.error(`Failed to renew distributed cron lock for ${descriptor.taskName}.`, error, 'CronLifecycleService');
+      return 'renewal-failed';
+    }
+  }
+  async releaseLockKey(lockKey, taskName) {
+    const redis = this.redisClient;
+    if (!redis) {
+      return;
+    }
+    try {
+      const result = await redis.eval(RELEASE_LOCK_SCRIPT, 1, lockKey, this.options.distributed.ownerId);
+      if (typeof result === 'number' && result <= 0) {
+        this.logger.warn(`Distributed cron lock for ${taskName} was already released or owned by another node.`, 'CronLifecycleService');
+        return;
+      }
+      this.logger.log(`Released distributed cron lock for ${taskName}.`, 'CronLifecycleService');
+    } catch (error) {
+      this.logger.error(`Failed to release distributed cron lock for ${taskName}.`, error, 'CronLifecycleService');
+    } finally {
+      this.ownedLockKeys.delete(lockKey);
+    }
+  }
+}
+function hasRedisLockClient(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const client = value;
+  return typeof client.set === 'function' && typeof client.eval === 'function';
+}

package/dist/expressions.d.ts

@@ -0,0 +1,13 @@
+export declare const CronExpression: {
+    readonly EVERY_SECOND: "* * * * * *";
+    readonly EVERY_5_SECONDS: "*/5 * * * * *";
+    readonly EVERY_10_SECONDS: "*/10 * * * * *";
+    readonly EVERY_30_SECONDS: "*/30 * * * * *";
+    readonly EVERY_MINUTE: "0 * * * * *";
+    readonly EVERY_5_MINUTES: "0 */5 * * * *";
+    readonly EVERY_10_MINUTES: "0 */10 * * * *";
+    readonly EVERY_30_MINUTES: "0 */30 * * * *";
+    readonly EVERY_HOUR: "0 0 * * * *";
+    readonly EVERY_DAY_AT_MIDNIGHT: "0 0 0 * * *";
+};
+//# sourceMappingURL=expressions.d.ts.map

package/dist/expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../src/expressions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc;;;;;;;;;;;CAWjB,CAAC"}

package/dist/expressions.js

@@ -0,0 +1,12 @@
+export const CronExpression = {
+  EVERY_SECOND: '* * * * * *',
+  EVERY_5_SECONDS: '*/5 * * * * *',
+  EVERY_10_SECONDS: '*/10 * * * * *',
+  EVERY_30_SECONDS: '*/30 * * * * *',
+  EVERY_MINUTE: '0 * * * * *',
+  EVERY_5_MINUTES: '0 */5 * * * *',
+  EVERY_10_MINUTES: '0 */10 * * * *',
+  EVERY_30_MINUTES: '0 */30 * * * *',
+  EVERY_HOUR: '0 0 * * * *',
+  EVERY_DAY_AT_MIDNIGHT: '0 0 0 * * *'
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './decorators.js';
+export * from './expressions.js';
+export * from './metadata.js';
+export * from './module.js';
+export * from './status.js';
+export { SCHEDULING_REGISTRY } from './tokens.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './decorators.js';
+export * from './expressions.js';
+export * from './metadata.js';
+export * from './module.js';
+export * from './status.js';
+export { SCHEDULING_REGISTRY } from './tokens.js';
+export * from './types.js';

package/dist/metadata.d.ts

@@ -0,0 +1,17 @@
+import { type MetadataPropertyKey } from '@fluojs/core';
+import type { CronTaskMetadata, SchedulingTaskMetadata } from './types.js';
+export declare function defineSchedulingTaskMetadata(target: object, propertyKey: MetadataPropertyKey, metadata: SchedulingTaskMetadata): void;
+export declare function defineCronTaskMetadata(target: object, propertyKey: MetadataPropertyKey, metadata: CronTaskMetadata): void;
+export declare function getSchedulingTaskMetadata(target: object, propertyKey: MetadataPropertyKey): SchedulingTaskMetadata | undefined;
+export declare function getCronTaskMetadata(target: object, propertyKey: MetadataPropertyKey): CronTaskMetadata | undefined;
+export declare function getSchedulingTaskMetadataEntries(target: object): Array<{
+    metadata: SchedulingTaskMetadata;
+    propertyKey: MetadataPropertyKey;
+}>;
+export declare function getCronTaskMetadataEntries(target: object): Array<{
+    metadata: CronTaskMetadata;
+    propertyKey: MetadataPropertyKey;
+}>;
+export declare const schedulingMetadataSymbol: symbol;
+export declare const cronMetadataSymbol: symbol;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAwD3E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,mBAAmB,EAChC,QAAQ,EAAE,sBAAsB,GAC/B,IAAI,CAEN;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAEzH;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,GAAG,sBAAsB,GAAG,SAAS,CAS9H;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,SAAS,CAIlH;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,MAAM,GACb,KAAK,CAAC;IAAE,QAAQ,EAAE,sBAAsB,CAAC;IAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAW/E;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAIlI;AAED,eAAO,MAAM,wBAAwB,QAAgC,CAAC;AACtE,eAAO,MAAM,kBAAkB,QAAgC,CAAC"}

package/dist/metadata.js

@@ -0,0 +1,78 @@
+import { ensureSymbolMetadataPolyfill, metadataSymbol } from '@fluojs/core/internal';
+void ensureSymbolMetadataPolyfill();
+const standardSchedulingMetadataKey = Symbol.for('fluo.cron.standard.task');
+const schedulingMetadataStore = new WeakMap();
+function cloneTaskMetadata(metadata) {
+  if (metadata.kind === 'cron') {
+    return {
+      expression: metadata.expression,
+      kind: 'cron',
+      options: {
+        ...metadata.options
+      }
+    };
+  }
+  if (metadata.kind === 'interval') {
+    return {
+      kind: 'interval',
+      ms: metadata.ms,
+      options: {
+        ...metadata.options
+      }
+    };
+  }
+  return {
+    kind: 'timeout',
+    ms: metadata.ms,
+    options: {
+      ...metadata.options
+    }
+  };
+}
+function getStandardMetadataBag(target) {
+  return target[metadataSymbol];
+}
+function getStandardSchedulingMap(target) {
+  const constructor = target.constructor;
+  return constructor ? getStandardMetadataBag(constructor)?.[standardSchedulingMetadataKey] : undefined;
+}
+function getOrCreateSchedulingMap(target) {
+  let map = schedulingMetadataStore.get(target);
+  if (!map) {
+    map = new Map();
+    schedulingMetadataStore.set(target, map);
+  }
+  return map;
+}
+export function defineSchedulingTaskMetadata(target, propertyKey, metadata) {
+  getOrCreateSchedulingMap(target).set(propertyKey, cloneTaskMetadata(metadata));
+}
+export function defineCronTaskMetadata(target, propertyKey, metadata) {
+  defineSchedulingTaskMetadata(target, propertyKey, metadata);
+}
+export function getSchedulingTaskMetadata(target, propertyKey) {
+  const stored = schedulingMetadataStore.get(target)?.get(propertyKey);
+  const standard = getStandardSchedulingMap(target)?.get(propertyKey);
+  if (!stored && !standard) {
+    return undefined;
+  }
+  return cloneTaskMetadata(stored ?? standard);
+}
+export function getCronTaskMetadata(target, propertyKey) {
+  const metadata = getSchedulingTaskMetadata(target, propertyKey);
+  return metadata?.kind === 'cron' ? metadata : undefined;
+}
+export function getSchedulingTaskMetadataEntries(target) {
+  const stored = schedulingMetadataStore.get(target) ?? new Map();
+  const standard = getStandardSchedulingMap(target) ?? new Map();
+  const keys = new Set([...stored.keys(), ...standard.keys()]);
+  return Array.from(keys).map(propertyKey => ({
+    metadata: getSchedulingTaskMetadata(target, propertyKey),
+    propertyKey
+  })).filter(entry => entry.metadata !== undefined);
+}
+export function getCronTaskMetadataEntries(target) {
+  return getSchedulingTaskMetadataEntries(target).filter(entry => entry.metadata.kind === 'cron');
+}
+export const schedulingMetadataSymbol = standardSchedulingMetadataKey;
+export const cronMetadataSymbol = standardSchedulingMetadataKey;

package/dist/module.d.ts

@@ -0,0 +1,31 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { CronModuleOptions, NormalizedCronModuleOptions } from './types.js';
+/**
+ * Normalizes module options so the runtime can rely on concrete scheduler and lock settings.
+ *
+ * @param options Raw cron module options supplied by the application.
+ * @returns A normalized options object with concrete distributed defaults and scheduler implementation.
+ */
+export declare function normalizeCronModuleOptions(options?: CronModuleOptions): NormalizedCronModuleOptions;
+/** Runtime module entrypoint for decorator-driven scheduling. */
+export declare class CronModule {
+    /**
+     * Registers the scheduling registry and optional distributed locking defaults.
+     *
+     * @param options Scheduler and distributed-lock options for discovered and dynamic tasks.
+     * @returns A module definition that exports the {@link SCHEDULING_REGISTRY} token.
+     *
+     * @example
+     * ```ts
+     * import { Module } from '@fluojs/core';
+     * import { CronModule } from '@fluojs/cron';
+     *
+     * @Module({
+     *   imports: [CronModule.forRoot({ distributed: true })],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRoot(options?: CronModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAkDjF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,iBAAsB,GAAG,2BAA2B,CAMvG;AAeD,iEAAiE;AACjE,qBAAa,UAAU;IACrB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU;CAQ5D"}

package/dist/module.js

@@ -0,0 +1,95 @@
+import { defineModule } from '@fluojs/runtime';
+import { CronLifecycleService } from './service.js';
+import { defaultCronScheduler } from './scheduler.js';
+import { CRON_OPTIONS, SCHEDULING_REGISTRY } from './tokens.js';
+const DEFAULT_CRON_SHUTDOWN_TIMEOUT_MS = 10_000;
+function randomId() {
+  return `${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function normalizeDistributedOptions(distributed) {
+  if (distributed === undefined || distributed === false) {
+    return {
+      clientName: undefined,
+      enabled: false,
+      keyPrefix: 'fluo:cron:lock',
+      lockTtlMs: 30_000,
+      ownerId: randomId()
+    };
+  }
+  if (distributed === true) {
+    return {
+      clientName: undefined,
+      enabled: true,
+      keyPrefix: 'fluo:cron:lock',
+      lockTtlMs: 30_000,
+      ownerId: randomId()
+    };
+  }
+  return {
+    clientName: distributed.clientName,
+    enabled: distributed.enabled ?? true,
+    keyPrefix: distributed.keyPrefix ?? 'fluo:cron:lock',
+    lockTtlMs: distributed.lockTtlMs ?? 30_000,
+    ownerId: distributed.ownerId ?? randomId()
+  };
+}
+function normalizeShutdownOptions(shutdown) {
+  const timeoutMs = shutdown?.timeoutMs ?? DEFAULT_CRON_SHUTDOWN_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || !Number.isInteger(timeoutMs) || timeoutMs < 0) {
+    throw new Error('Cron shutdown timeoutMs must be a non-negative integer.');
+  }
+  return {
+    timeoutMs
+  };
+}
+
+/**
+ * Normalizes module options so the runtime can rely on concrete scheduler and lock settings.
+ *
+ * @param options Raw cron module options supplied by the application.
+ * @returns A normalized options object with concrete distributed defaults and scheduler implementation.
+ */
+export function normalizeCronModuleOptions(options = {}) {
+  return {
+    distributed: normalizeDistributedOptions(options.distributed),
+    scheduler: options.scheduler ?? defaultCronScheduler,
+    shutdown: normalizeShutdownOptions(options.shutdown)
+  };
+}
+function createCronProviders(options = {}) {
+  return [{
+    provide: CRON_OPTIONS,
+    useValue: normalizeCronModuleOptions(options)
+  }, {
+    provide: SCHEDULING_REGISTRY,
+    useClass: CronLifecycleService
+  }];
+}
+
+/** Runtime module entrypoint for decorator-driven scheduling. */
+export class CronModule {
+  /**
+   * Registers the scheduling registry and optional distributed locking defaults.
+   *
+   * @param options Scheduler and distributed-lock options for discovered and dynamic tasks.
+   * @returns A module definition that exports the {@link SCHEDULING_REGISTRY} token.
+   *
+   * @example
+   * ```ts
+   * import { Module } from '@fluojs/core';
+   * import { CronModule } from '@fluojs/cron';
+   *
+   * @Module({
+   *   imports: [CronModule.forRoot({ distributed: true })],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRoot(options = {}) {
+    class CronModuleDefinition {}
+    return defineModule(CronModuleDefinition, {
+      exports: [SCHEDULING_REGISTRY],
+      providers: createCronProviders(options)
+    });
+  }
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,3 @@
+import type { CronScheduler } from './types.js';
+export declare const defaultCronScheduler: CronScheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,oBAAoB,EAAE,aAMlC,CAAC"}

package/dist/scheduler.js

@@ -0,0 +1,8 @@
+import { Cron as Croner } from 'croner';
+export const defaultCronScheduler = (expression, options, callback) => {
+  return new Croner(expression, {
+    name: options.name,
+    protect: options.protect,
+    timezone: options.timezone
+  }, callback);
+};

package/dist/service.d.ts

@@ -0,0 +1,118 @@
+import type { Container } from '@fluojs/di';
+import { type ApplicationLogger, type CompiledModule, type OnApplicationBootstrap, type OnApplicationShutdown, type OnModuleDestroy } from '@fluojs/runtime';
+import type { CronTaskOptions, IntervalTaskOptions, NormalizedCronModuleOptions, SchedulingRegistry, SchedulingTaskCallback, SchedulingTaskDescriptor, TimeoutTaskOptions } from './types.js';
+/**
+ * Lifecycle-managed scheduler runtime for decorator-discovered and dynamic tasks.
+ *
+ * The service discovers scheduling decorators during bootstrap, coordinates
+ * optional distributed locks through Redis, and exposes runtime task management
+ * through {@link SchedulingRegistry}.
+ */
+export declare class CronLifecycleService implements SchedulingRegistry, OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy {
+    private readonly options;
+    private readonly runtimeContainer;
+    private readonly compiledModules;
+    private readonly logger;
+    private readonly tasks;
+    private readonly activeTasks;
+    private readonly distributedLocks;
+    private readonly taskRunner;
+    private lifecycleState;
+    private started;
+    private shutdownPromise;
+    constructor(options: NormalizedCronModuleOptions, runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger);
+    /**
+     * Registers a cron task at runtime.
+     *
+     * @param name Stable task name used for lookup and distributed lock derivation.
+     * @param expression Cron expression validated before registration.
+     * @param callback Task body executed on matching cron ticks.
+     * @param options Optional hooks, distributed lock overrides, and timezone.
+     */
+    addCron(name: string, expression: string, callback: SchedulingTaskCallback, options?: CronTaskOptions): void;
+    /**
+     * Registers a fixed-interval task at runtime.
+     *
+     * @param name Stable task name used for lookup and distributed lock derivation.
+     * @param ms Positive interval in milliseconds.
+     * @param callback Task body executed on each interval.
+     * @param options Optional hooks and distributed lock overrides.
+     */
+    addInterval(name: string, ms: number, callback: SchedulingTaskCallback, options?: IntervalTaskOptions): void;
+    /**
+     * Registers a one-shot delayed task at runtime.
+     *
+     * @param name Stable task name used for lookup and distributed lock derivation.
+     * @param ms Positive delay in milliseconds before execution.
+     * @param callback Task body executed once after the delay.
+     * @param options Optional hooks and distributed lock overrides.
+     */
+    addTimeout(name: string, ms: number, callback: SchedulingTaskCallback, options?: TimeoutTaskOptions): void;
+    /**
+     * Removes a registered task by name.
+     *
+     * @param name Task name to remove.
+     * @returns `true` when a task existed and was removed.
+     */
+    remove(name: string): boolean;
+    /**
+     * Enables a task that was previously disabled.
+     *
+     * @param name Task name to enable.
+     * @returns `true` when the task exists after the operation.
+     */
+    enable(name: string): boolean;
+    /**
+     * Disables a task without removing its descriptor.
+     *
+     * @param name Task name to disable.
+     * @returns `true` when the task exists after the operation.
+     */
+    disable(name: string): boolean;
+    /**
+     * Looks up one task descriptor.
+     *
+     * @param name Task name to inspect.
+     * @returns The task descriptor, or `undefined` when not found.
+     */
+    get(name: string): SchedulingTaskDescriptor | undefined;
+    /**
+     * Lists every known task descriptor.
+     *
+     * @returns All decorator-discovered and dynamically registered task descriptors.
+     */
+    getAll(): SchedulingTaskDescriptor[];
+    /**
+     * Replaces the cron expression of one existing cron task.
+     *
+     * @param name Name of the cron task to update.
+     * @param expression New cron expression to validate and schedule.
+     */
+    updateCronExpression(name: string, expression: string): void;
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    createPlatformStatusSnapshot(): import("./status.js").CronPlatformStatusSnapshot;
+    private toSchedulingTaskDescriptor;
+    private shutdown;
+    private startLifecycle;
+    private validateDistributedLockConfiguration;
+    private handleStartupFailure;
+    private runShutdownLifecycle;
+    private registerDecoratorTasks;
+    private registerTask;
+    private assertTaskNameAvailable;
+    private scheduleEnabledTasks;
+    private scheduleTask;
+    private completeTimeoutTask;
+    private unscheduleTask;
+    private handleTaskTick;
+    private runTaskTick;
+    private shouldUseDistributedExecution;
+    private runDistributedTaskTick;
+    private waitForActiveTasks;
+    private drainActiveTasks;
+    private executeTask;
+    private stopAllScheduledTasks;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAQzB,OAAO,KAAK,EAEV,eAAe,EACf,mBAAmB,EACnB,2BAA2B,EAC3B,kBAAkB,EAClB,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAwCpB;;;;;;GAMG;AACH,qBACa,oBACX,YAAW,kBAAkB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe;IAW3F,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,cAAc,CAAmF;IACzG,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,eAAe,CAA4B;gBAGhC,OAAO,EAAE,2BAA2B,EACpC,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB;IAM5C;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI;IAuBhH;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI;IAsBhH;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,EAAE,OAAO,GAAE,kBAAuB,GAAG,IAAI;IAsB9G;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAY7B;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAoB7B;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAgB9B;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,SAAS;IAMvD;;;;OAIG;IACH,MAAM,IAAI,wBAAwB,EAAE;IAIpC;;;;;OAKG;IACH,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAuBtD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBvC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,4BAA4B;IA6B5B,OAAO,CAAC,0BAA0B;YAkBpB,QAAQ;YAWR,cAAc;IAQ5B,OAAO,CAAC,oCAAoC;IAQ5C,OAAO,CAAC,oBAAoB;YAOd,oBAAoB;IAiBlC,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,uBAAuB;IAM/B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,YAAY;IA4DpB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,cAAc;YAcR,cAAc;YAmBd,WAAW;IASzB,OAAO,CAAC,6BAA6B;YAIvB,sBAAsB;YAoBtB,kBAAkB;YA2BlB,gBAAgB;YAMhB,WAAW;IAYzB,OAAO,CAAC,qBAAqB;CAK9B"}