@veloxts/scheduler 0.6.57 → 0.6.59

package/README.md

@@ -1,36 +1,8 @@
 # @veloxts/scheduler
 
-> **Early Preview** - APIs may change before v1.0.
+> **Early Preview (v0.6.x)** - APIs are stabilizing but may still change. Use with caution in production.
 
-Cron-based task scheduling with a fluent API and overlap prevention.
-
-## Installation
-
-```bash
-npm install @veloxts/scheduler
-```
-
-## Quick Start
-
-```typescript
-import { createScheduler, task } from '@veloxts/scheduler';
-
-const scheduler = createScheduler([
-  task('cleanup', () => db.token.deleteExpired())
-    .daily()
-    .at('02:00')
-    .build(),
-
-  task('digest', () => sendDailyDigest())
-    .weekdays()
-    .at('09:00')
-    .build(),
-]);
-
-scheduler.start();
-```
-
-See [GUIDE.md](./GUIDE.md) for detailed documentation.
+Cron-based task scheduling for VeloxTS Framework - provides a fluent API for defining recurring tasks with overlap prevention and timezone support. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
 
 ## License
 

package/dist/index.d.ts

@@ -6,11 +6,11 @@
  *
  * @example
  * ```typescript
- * import { schedulerPlugin, task, defineSchedule } from '@veloxts/scheduler';
+ * import { schedulerPlugin, defineTask, defineSchedule } from '@veloxts/scheduler';
  *
- * // Define scheduled tasks with fluent API
+ * // Define scheduled tasks with fluent API - .build() is auto-called
  * const schedule = defineSchedule([
- *   task('cleanup-expired-tokens', async () => {
+ *   defineTask('cleanup-expired-tokens', async () => {
  *     await db.token.deleteMany({
  *       where: { expiresAt: { lt: new Date() } }
  *     });
@@ -21,26 +21,23 @@
  *     .withoutOverlapping()
  *     .onSuccess((ctx, duration) => {
  *       console.log(`Cleanup completed in ${duration}ms`);
- *     })
- *     .build(),
+ *     }),
  *
- *   task('send-daily-digest', async () => {
+ *   defineTask('send-daily-digest', async () => {
  *     await sendDailyDigest();
  *   })
  *     .daily()
  *     .at('09:00')
- *     .weekdays()
- *     .build(),
+ *     .weekdays(),
  *
- *   task('backup-database', async () => {
+ *   defineTask('backup-database', async () => {
  *     await runDatabaseBackup();
  *   })
  *     .weekly()
  *     .sundays()
  *     .at('03:00')
  *     .onSuccess(() => notifySlack('Backup complete'))
- *     .onFailure((ctx, error) => notifyPagerDuty(error))
- *     .build(),
+ *     .onFailure((ctx, error) => notifyPagerDuty(error)),
  * ]);
  *
  * // Register plugin
@@ -59,7 +56,8 @@
  */
 export { createScheduler, scheduler } from './manager.js';
 export { _resetStandaloneScheduler, getScheduler, getSchedulerFromInstance, schedulerPlugin, } from './plugin.js';
-export { defineSchedule, task } from './task.js';
+export type { ScheduleInput } from './task.js';
+export { defineSchedule, defineTask, schedule, task } from './task.js';
 export type { DayOfWeek, DayOfWeekNumber, ScheduleConstraint, ScheduledTask, SchedulerManager, SchedulerOptions, SchedulerPluginOptions, TaskBuilder, TaskContext, TaskExecution, TaskFailureCallback, TaskHandler, TaskSkipCallback, TaskSuccessCallback, } from './types.js';
 /**
  * DI tokens and providers for @veloxts/scheduler
@@ -69,13 +67,13 @@ export type { DayOfWeek, DayOfWeekNumber, ScheduleConstraint, ScheduledTask, Sch
  * @example
  * ```typescript
  * import { Container } from '@veloxts/core';
- * import { registerSchedulerProviders, SCHEDULER_MANAGER, task } from '@veloxts/scheduler';
+ * import { registerSchedulerProviders, SCHEDULER_MANAGER, defineTask, defineSchedule } from '@veloxts/scheduler';
  *
  * const container = new Container();
  * registerSchedulerProviders(container, {
- *   tasks: [
- *     task('cleanup', () => db.cleanup()).daily().build(),
- *   ],
+ *   tasks: defineSchedule([
+ *     defineTask('cleanup', () => db.cleanup()).daily(),
+ *   ]),
  * });
  *
  * const scheduler = container.resolve(SCHEDULER_MANAGER);

package/dist/index.js

@@ -6,11 +6,11 @@
  *
  * @example
  * ```typescript
- * import { schedulerPlugin, task, defineSchedule } from '@veloxts/scheduler';
+ * import { schedulerPlugin, defineTask, defineSchedule } from '@veloxts/scheduler';
  *
- * // Define scheduled tasks with fluent API
+ * // Define scheduled tasks with fluent API - .build() is auto-called
  * const schedule = defineSchedule([
- *   task('cleanup-expired-tokens', async () => {
+ *   defineTask('cleanup-expired-tokens', async () => {
  *     await db.token.deleteMany({
  *       where: { expiresAt: { lt: new Date() } }
  *     });
@@ -21,26 +21,23 @@
  *     .withoutOverlapping()
  *     .onSuccess((ctx, duration) => {
  *       console.log(`Cleanup completed in ${duration}ms`);
- *     })
- *     .build(),
+ *     }),
  *
- *   task('send-daily-digest', async () => {
+ *   defineTask('send-daily-digest', async () => {
  *     await sendDailyDigest();
  *   })
  *     .daily()
  *     .at('09:00')
- *     .weekdays()
- *     .build(),
+ *     .weekdays(),
  *
- *   task('backup-database', async () => {
+ *   defineTask('backup-database', async () => {
  *     await runDatabaseBackup();
  *   })
  *     .weekly()
  *     .sundays()
  *     .at('03:00')
  *     .onSuccess(() => notifySlack('Backup complete'))
- *     .onFailure((ctx, error) => notifyPagerDuty(error))
- *     .build(),
+ *     .onFailure((ctx, error) => notifyPagerDuty(error)),
  * ]);
  *
  * // Register plugin
@@ -62,7 +59,7 @@ export { createScheduler, scheduler } from './manager.js';
 // Plugin
 export { _resetStandaloneScheduler, getScheduler, getSchedulerFromInstance, schedulerPlugin, } from './plugin.js';
 // Task builder
-export { defineSchedule, task } from './task.js';
+export { defineSchedule, defineTask, schedule, task } from './task.js';
 // ============================================================================
 // Dependency Injection
 // ============================================================================
@@ -74,13 +71,13 @@ export { defineSchedule, task } from './task.js';
  * @example
  * ```typescript
  * import { Container } from '@veloxts/core';
- * import { registerSchedulerProviders, SCHEDULER_MANAGER, task } from '@veloxts/scheduler';
+ * import { registerSchedulerProviders, SCHEDULER_MANAGER, defineTask, defineSchedule } from '@veloxts/scheduler';
  *
  * const container = new Container();
  * registerSchedulerProviders(container, {
- *   tasks: [
- *     task('cleanup', () => db.cleanup()).daily().build(),
- *   ],
+ *   tasks: defineSchedule([
+ *     defineTask('cleanup', () => db.cleanup()).daily(),
+ *   ]),
  * });
  *
  * const scheduler = container.resolve(SCHEDULER_MANAGER);

package/dist/task.d.ts

@@ -29,19 +29,65 @@ import type { ScheduledTask, TaskBuilder, TaskHandler } from './types.js';
  * ```
  */
 export declare function task(name: string, handler: TaskHandler): TaskBuilder;
+/**
+ * Alias for task() - provides consistency with defineJob() and defineMail().
+ *
+ * @example
+ * ```typescript
+ * import { defineTask, defineSchedule } from '@veloxts/scheduler';
+ *
+ * const cleanup = defineTask('cleanup-expired-tokens', async () => {
+ *   await db.token.deleteMany({
+ *     where: { expiresAt: { lt: new Date() } }
+ *   });
+ * })
+ *   .daily()
+ *   .at('02:00')
+ *   .build();
+ * ```
+ */
+export declare const defineTask: typeof task;
+/**
+ * Input type for defineSchedule - accepts either built tasks or builders.
+ */
+export type ScheduleInput = ScheduledTask | TaskBuilder;
 /**
  * Define a schedule with multiple tasks.
  *
- * @param tasks - Array of scheduled tasks
+ * Auto-calls `.build()` on TaskBuilder instances, allowing either:
+ * - Pre-built ScheduledTask objects
+ * - TaskBuilder instances (build() called automatically)
+ *
+ * @param tasks - Array of scheduled tasks or task builders
  * @returns Array of scheduled tasks
  *
  * @example
  * ```typescript
+ * // .build() is now optional - defineSchedule calls it automatically
  * export const schedule = defineSchedule([
- *   task('cleanup', () => db.cleanup()).daily().at('02:00').build(),
- *   task('digest', () => sendDigest()).daily().at('09:00').build(),
- *   task('backup', () => runBackup()).weekly().sundays().at('03:00').build(),
+ *   defineTask('cleanup', () => db.cleanup()).daily().at('02:00'),
+ *   defineTask('digest', () => sendDigest()).daily().at('09:00'),
+ *   defineTask('backup', () => runBackup()).weekly().sundays().at('03:00'),
+ * ]);
+ *
+ * // Explicit .build() still works for backward compatibility
+ * export const schedule = defineSchedule([
+ *   defineTask('cleanup', () => db.cleanup()).daily().at('02:00').build(),
+ * ]);
+ * ```
+ */
+export declare function defineSchedule(tasks: ScheduleInput[]): ScheduledTask[];
+/**
+ * Alias for defineSchedule() - matches pattern of job/mail/task short aliases.
+ *
+ * @example
+ * ```typescript
+ * import { schedule, task } from '@veloxts/scheduler';
+ *
+ * const tasks = schedule([
+ *   task('cleanup', () => db.cleanup()).daily().at('02:00'),
+ *   task('digest', () => sendDigest()).daily().at('09:00'),
  * ]);
  * ```
  */
-export declare function defineSchedule(tasks: ScheduledTask[]): ScheduledTask[];
+export declare const schedule: typeof defineSchedule;

package/dist/task.js

@@ -414,29 +414,82 @@ class TaskBuilderImpl {
 export function task(name, handler) {
     return new TaskBuilderImpl(name, handler);
 }
+/**
+ * Alias for task() - provides consistency with defineJob() and defineMail().
+ *
+ * @example
+ * ```typescript
+ * import { defineTask, defineSchedule } from '@veloxts/scheduler';
+ *
+ * const cleanup = defineTask('cleanup-expired-tokens', async () => {
+ *   await db.token.deleteMany({
+ *     where: { expiresAt: { lt: new Date() } }
+ *   });
+ * })
+ *   .daily()
+ *   .at('02:00')
+ *   .build();
+ * ```
+ */
+export const defineTask = task;
+/**
+ * Type guard to check if value is a TaskBuilder (has build method).
+ */
+function isTaskBuilder(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        'build' in value &&
+        typeof value.build === 'function');
+}
 /**
  * Define a schedule with multiple tasks.
  *
- * @param tasks - Array of scheduled tasks
+ * Auto-calls `.build()` on TaskBuilder instances, allowing either:
+ * - Pre-built ScheduledTask objects
+ * - TaskBuilder instances (build() called automatically)
+ *
+ * @param tasks - Array of scheduled tasks or task builders
  * @returns Array of scheduled tasks
  *
  * @example
  * ```typescript
+ * // .build() is now optional - defineSchedule calls it automatically
  * export const schedule = defineSchedule([
- *   task('cleanup', () => db.cleanup()).daily().at('02:00').build(),
- *   task('digest', () => sendDigest()).daily().at('09:00').build(),
- *   task('backup', () => runBackup()).weekly().sundays().at('03:00').build(),
+ *   defineTask('cleanup', () => db.cleanup()).daily().at('02:00'),
+ *   defineTask('digest', () => sendDigest()).daily().at('09:00'),
+ *   defineTask('backup', () => runBackup()).weekly().sundays().at('03:00'),
+ * ]);
+ *
+ * // Explicit .build() still works for backward compatibility
+ * export const schedule = defineSchedule([
+ *   defineTask('cleanup', () => db.cleanup()).daily().at('02:00').build(),
  * ]);
  * ```
  */
 export function defineSchedule(tasks) {
+    // Normalize: call build() on TaskBuilders, pass through ScheduledTasks
+    const builtTasks = tasks.map((t) => (isTaskBuilder(t) ? t.build() : t));
     // Validate unique names
     const names = new Set();
-    for (const t of tasks) {
+    for (const t of builtTasks) {
         if (names.has(t.name)) {
             throw new Error(`Duplicate task name: "${t.name}". Task names must be unique.`);
         }
         names.add(t.name);
     }
-    return tasks;
+    return builtTasks;
 }
+/**
+ * Alias for defineSchedule() - matches pattern of job/mail/task short aliases.
+ *
+ * @example
+ * ```typescript
+ * import { schedule, task } from '@veloxts/scheduler';
+ *
+ * const tasks = schedule([
+ *   task('cleanup', () => db.cleanup()).daily().at('02:00'),
+ *   task('digest', () => sendDigest()).daily().at('09:00'),
+ * ]);
+ * ```
+ */
+export const schedule = defineSchedule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/scheduler",
-  "version": "0.6.57",
+  "version": "0.6.59",
   "description": "Task scheduling for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   "dependencies": {
     "cron": "3.5.0",
     "fastify-plugin": "5.1.0",
-    "@veloxts/core": "0.6.57"
+    "@veloxts/core": "0.6.59"
   },
   "peerDependencies": {
     "fastify": "^5.0.0"