@fluojs/cron 1.0.0 → 1.0.1

package/README.ko.md

@@ -23,6 +23,8 @@ fluo 애플리케이션을 위한 데코레이터 기반 스케줄링 패키지
 npm install @fluojs/cron croner
 ```
 
+`croner`는 `@fluojs/cron`이 사용하는 scheduler engine입니다. 애플리케이션과 배포 감사에서 runtime scheduler dependency ownership이 명확히 보이도록 패키지와 함께 설치하세요.
+
 ## 사용 시점
 
 - 정기적인 백그라운드 작업(예: 데이터베이스 정리, 리포트 생성)이 필요할 때 사용합니다.
@@ -141,6 +143,8 @@ class TaskManager {
 
 Registry는 `addCron`, `addInterval`, `addTimeout`, `remove`, `enable`, `disable`, `get`, `getAll`, `updateCronExpression`을 제공합니다. Timeout task는 한 번 실행된 뒤 비활성화되지만 registry에는 남아 있어 의도적으로 다시 활성화할 수 있습니다.
 
+Dynamic cron 등록은 scheduler startup과 원자적으로 처리됩니다. Scheduler가 새 cron job을 거부하면 registry는 half-registered task를 남기지 않습니다. 실행 중인 cron expression update도 rollback-safe합니다. Rescheduling이 실패하면 이전 expression과 scheduled job이 그대로 유지됩니다. Cron task는 scheduler-level no-overlap protection과 fluo의 in-process running guard를 함께 사용하므로 같은 task instance가 overlapping tick으로 실행되지 않습니다.
+
 ### 제한된 종료
 
 `CronModule`은 애플리케이션 종료 시 실행 중인 작업을 제한된 타임아웃 안에서 drain합니다. 따라서 하나의 hung task 때문에 프로세스 종료가 영원히 막히지 않습니다.
@@ -177,6 +181,7 @@ singleton provider/controller만 스케줄링됩니다. Request-scoped 및 trans
 - `SCHEDULING_REGISTRY`: `SchedulingRegistry` 서비스를 위한 주입 토큰입니다.
 - `normalizeCronModuleOptions(...)`: module option과 기본값을 정규화합니다.
 - `createCronPlatformStatusSnapshot(...)`: health/readiness 통합을 위한 status snapshot을 생성합니다.
+- 공개 타입: `CronModuleOptions`, `CronDistributedOptions`, `CronShutdownOptions`, `CronScheduleOptions`, `CronScheduler`, `CronScheduledJob`, `SchedulingRegistry`, `SchedulingTaskDescriptor`, `SchedulingTaskCallback`, `SchedulingTaskOptions`, `CronTaskOptions`, `IntervalTaskOptions`, `TimeoutTaskOptions`.
 - 메타데이터 헬퍼와 심볼: `defineSchedulingTaskMetadata`, `defineCronTaskMetadata`, `getSchedulingTaskMetadata`, `getCronTaskMetadata`, `getSchedulingTaskMetadataEntries`, `getCronTaskMetadataEntries`, `schedulingMetadataSymbol`, `cronMetadataSymbol`.
 
 

package/README.md

@@ -23,6 +23,8 @@ Decorator-based scheduling for fluo applications with lifecycle-managed startup/
 npm install @fluojs/cron croner
 ```
 
+`croner` is the scheduler engine used by `@fluojs/cron`. Install it alongside the package so lockfiles make the runtime scheduler dependency explicit for applications and deployment audits.
+
 ## When to Use
 
 - When you need to run periodic background tasks (e.g., database cleanup, report generation).
@@ -141,6 +143,8 @@ class TaskManager {
 
 The registry exposes `addCron`, `addInterval`, `addTimeout`, `remove`, `enable`, `disable`, `get`, `getAll`, and `updateCronExpression`. Timeout tasks run once, then disable themselves while remaining in the registry so they can be re-enabled deliberately.
 
+Dynamic cron registration is atomic with scheduler startup: if the scheduler rejects a new cron job, the registry does not retain a half-registered task. Updating a running cron expression is also rollback-safe. If rescheduling fails, the previous expression and scheduled job remain active. Cron tasks use both scheduler-level no-overlap protection and fluo's in-process running guard, so the same task instance will not run overlapping ticks.
+
 ### Bounded Shutdown
 
 `CronModule` drains active task executions during application shutdown with a bounded timeout so one hung task cannot block process termination forever.
@@ -177,6 +181,7 @@ Only singleton providers/controllers are scheduled. Request-scoped and transient
 - `SCHEDULING_REGISTRY`: Injection token for the `SchedulingRegistry` service.
 - `normalizeCronModuleOptions(...)`: Normalizes module options and defaults.
 - `createCronPlatformStatusSnapshot(...)`: Creates a status snapshot for health/readiness integrations.
+- Public types: `CronModuleOptions`, `CronDistributedOptions`, `CronShutdownOptions`, `CronScheduleOptions`, `CronScheduler`, `CronScheduledJob`, `SchedulingRegistry`, `SchedulingTaskDescriptor`, `SchedulingTaskCallback`, `SchedulingTaskOptions`, `CronTaskOptions`, `IntervalTaskOptions`, and `TimeoutTaskOptions`.
 - Metadata helpers and symbols: `defineSchedulingTaskMetadata`, `defineCronTaskMetadata`, `getSchedulingTaskMetadata`, `getCronTaskMetadata`, `getSchedulingTaskMetadataEntries`, `getCronTaskMetadataEntries`, `schedulingMetadataSymbol`, `cronMetadataSymbol`.
 
 

package/dist/service.d.ts

@@ -1,5 +1,5 @@
 import type { Container } from '@fluojs/di';
-import { type ApplicationLogger, type CompiledModule, type OnApplicationBootstrap, type OnApplicationShutdown, type OnModuleDestroy } from '@fluojs/runtime';
+import type { ApplicationLogger, CompiledModule, OnApplicationBootstrap, OnApplicationShutdown, 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.
@@ -106,8 +106,10 @@ export declare class CronLifecycleService implements SchedulingRegistry, OnAppli
     private assertTaskNameAvailable;
     private scheduleEnabledTasks;
     private scheduleTask;
+    private createScheduledHandle;
     private completeTimeoutTask;
     private unscheduleTask;
+    private stopScheduledHandle;
     private handleTaskTick;
     private runTaskTick;
     private shouldUseDistributedExecution;

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -176,10 +176,17 @@ class CronLifecycleService {
     if (task.enabled) {
       return true;
     }
-    task.enabled = true;
     if (this.started) {
-      this.scheduleTask(task);
+      task.enabled = true;
+      try {
+        this.scheduleTask(task);
+      } catch (error) {
+        task.enabled = false;
+        throw error;
+      }
+      return true;
     }
+    task.enabled = true;
     return true;
   }
 
@@ -237,12 +244,24 @@ class CronLifecycleService {
     if (task.descriptor.kind !== 'cron') {
       throw new Error(`updateCronExpression() supports only cron tasks. Received ${task.descriptor.kind} task "${name}".`);
     }
-    task.descriptor.expression = expression;
     if (!task.enabled || !this.started) {
+      task.descriptor.expression = expression;
       return;
     }
-    this.unscheduleTask(task);
-    this.scheduleTask(task);
+    const previousExpression = task.descriptor.expression;
+    const previousHandle = task.scheduledHandle;
+    task.descriptor.expression = expression;
+    try {
+      const nextHandle = this.createScheduledHandle(task);
+      task.scheduledHandle = nextHandle;
+      if (previousHandle) {
+        this.stopScheduledHandle(previousHandle);
+      }
+    } catch (error) {
+      task.descriptor.expression = previousExpression;
+      task.scheduledHandle = previousHandle;
+      throw error;
+    }
   }
   async onApplicationBootstrap() {
     if (this.started) {
@@ -365,10 +384,10 @@ class CronLifecycleService {
       scheduledHandle: undefined,
       source
     };
-    this.tasks.set(descriptor.taskName, task);
     if (this.started) {
-      this.scheduleTask(task);
+      task.scheduledHandle = this.createScheduledHandle(task);
     }
+    this.tasks.set(descriptor.taskName, task);
   }
   assertTaskNameAvailable(taskName) {
     if (this.tasks.has(taskName)) {
@@ -386,42 +405,43 @@ class CronLifecycleService {
     if (!task.enabled || task.scheduledHandle) {
       return;
     }
+    task.scheduledHandle = this.createScheduledHandle(task);
+  }
+  createScheduledHandle(task) {
+    const taskName = task.descriptor.taskName;
     if (task.descriptor.kind === 'cron') {
       const expression = task.descriptor.expression;
       if (!expression) {
-        throw new Error(`Cron task "${task.descriptor.taskName}" is missing a cron expression.`);
+        throw new Error(`Cron task "${taskName}" is missing a cron expression.`);
       }
-      const scheduled = this.options.scheduler(expression, {
-        name: task.descriptor.taskName,
+      return this.options.scheduler(expression, {
+        name: taskName,
         protect: true,
         timezone: task.descriptor.timezone
       }, async () => {
-        await this.handleTaskTick(task.descriptor.taskName);
+        await this.handleTaskTick(taskName);
       });
-      task.scheduledHandle = scheduled;
-      return;
     }
     const ms = task.descriptor.ms;
     if (!ms) {
-      throw new Error(`${task.descriptor.kind} task "${task.descriptor.taskName}" is missing interval duration.`);
+      throw new Error(`${task.descriptor.kind} task "${taskName}" is missing interval duration.`);
     }
     if (task.descriptor.kind === 'interval') {
       const timer = setInterval(() => {
-        void this.handleTaskTick(task.descriptor.taskName);
+        void this.handleTaskTick(taskName);
       }, ms);
-      task.scheduledHandle = {
+      return {
         stop: () => {
           clearInterval(timer);
         }
       };
-      return;
     }
     const timer = setTimeout(() => {
-      void this.handleTaskTick(task.descriptor.taskName).finally(() => {
-        this.completeTimeoutTask(task.descriptor.taskName);
+      void this.handleTaskTick(taskName).finally(() => {
+        this.completeTimeoutTask(taskName);
       });
     }, ms);
-    task.scheduledHandle = {
+    return {
       stop: () => {
         clearTimeout(timer);
       }
@@ -439,17 +459,20 @@ class CronLifecycleService {
     if (!task.scheduledHandle) {
       return;
     }
+    const scheduledHandle = task.scheduledHandle;
+    task.scheduledHandle = undefined;
+    this.stopScheduledHandle(scheduledHandle);
+  }
+  stopScheduledHandle(scheduledHandle) {
     try {
-      task.scheduledHandle.stop();
+      scheduledHandle.stop();
     } catch (error) {
-      this.logger.error('Failed to stop scheduled task during shutdown.', error, 'CronLifecycleService');
-    } finally {
-      task.scheduledHandle = undefined;
+      this.logger.error('Failed to stop scheduled task.', error, 'CronLifecycleService');
     }
   }
   async handleTaskTick(taskName) {
     const taskState = this.tasks.get(taskName);
-    if (!taskState || !taskState.enabled || taskState.running) {
+    if (!taskState?.enabled || taskState.running) {
       return;
     }
     const task = this.runTaskTick(taskState.descriptor, taskState);

package/package.json

@@ -9,7 +9,7 @@
     "timeout",
     "distributed-lock"
   ],
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -37,10 +37,10 @@
   ],
   "dependencies": {
     "croner": "^8.1.2",
-    "@fluojs/core": "^1.0.0",
-    "@fluojs/di": "^1.0.0",
-    "@fluojs/runtime": "^1.0.0",
-    "@fluojs/redis": "^1.0.0"
+    "@fluojs/core": "^1.0.1",
+    "@fluojs/di": "^1.0.1",
+    "@fluojs/redis": "^1.0.0",
+    "@fluojs/runtime": "^1.0.1"
   },
   "devDependencies": {
     "vitest": "^3.2.4"