@commandkit/tasks 0.0.0-dev.20250724145623

package/dist/plugin.d.ts

@@ -0,0 +1,79 @@
+import { CommandKitPluginRuntime, RuntimePlugin, Collection, CommandKitHMREvent } from 'commandkit';
+import { Task } from './task';
+/**
+ * Configuration options for the tasks plugin.
+ *
+ * Currently, the plugin uses default settings for task loading and HMR.
+ * Future versions may support customizing the tasks directory path and HMR behavior.
+ */
+export interface TasksPluginOptions {
+}
+/**
+ * CommandKit plugin that provides task management capabilities.
+ *
+ * This plugin automatically loads task definitions from the `src/app/tasks` directory
+ * and manages their execution through configured drivers. It supports hot module
+ * replacement (HMR) for development workflows.
+ *
+ * @example
+ * ```ts
+ * import { tasks } from '@commandkit/tasks';
+ *
+ * export default {
+ *   plugins: [
+ *     tasks(),
+ *   ],
+ * };
+ * ```
+ */
+export declare class TasksPlugin extends RuntimePlugin<TasksPluginOptions> {
+    /** The plugin name identifier */
+    readonly name = "tasks";
+    /** Collection of loaded task instances indexed by task name */
+    readonly tasks: Collection<string, Task<Record<string, any>>>;
+    /**
+     * Activates the tasks plugin.
+     *
+     * This method:
+     * 1. Sets up the task execution runner
+     * 2. Loads all task definitions from the tasks directory
+     * 3. Schedules tasks that have defined schedules
+     *
+     * @param ctx - The CommandKit plugin runtime context
+     */
+    activate(ctx: CommandKitPluginRuntime): Promise<void>;
+    /**
+     * Deactivates the tasks plugin.
+     *
+     * Clears all loaded tasks from memory.
+     *
+     * @param ctx - The CommandKit plugin runtime context
+     */
+    deactivate(ctx: CommandKitPluginRuntime): Promise<void>;
+    /**
+     * Gets the default tasks directory path.
+     *
+     * @returns The absolute path to the tasks directory
+     */
+    private getTaskDirectory;
+    /**
+     * Loads all task definitions from the tasks directory.
+     *
+     * This method scans the tasks directory for TypeScript/JavaScript files and
+     * imports them as task definitions. It validates that each export is a valid
+     * Task instance and schedules tasks that have defined schedules.
+     *
+     * @param commandkit - The CommandKit instance
+     */
+    private loadTasks;
+    /**
+     * Handles hot module replacement (HMR) for task files.
+     *
+     * When a task file is modified during development, this method reloads the
+     * task definition and updates the scheduler accordingly.
+     *
+     * @param ctx - The CommandKit plugin runtime context
+     * @param event - The HMR event containing file change information
+     */
+    performHMR(ctx: CommandKitPluginRuntime, event: CommandKitHMREvent): Promise<void>;
+}

package/dist/plugin.js

@@ -0,0 +1,223 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TasksPlugin = void 0;
+const commandkit_1 = require("commandkit");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importStar(require("node:path"));
+const task_1 = require("./task");
+const node_process_1 = require("node:process");
+const driver_manager_1 = require("./driver-manager");
+const context_1 = require("./context");
+const node_fs_1 = require("node:fs");
+/**
+ * CommandKit plugin that provides task management capabilities.
+ *
+ * This plugin automatically loads task definitions from the `src/app/tasks` directory
+ * and manages their execution through configured drivers. It supports hot module
+ * replacement (HMR) for development workflows.
+ *
+ * @example
+ * ```ts
+ * import { tasks } from '@commandkit/tasks';
+ *
+ * export default {
+ *   plugins: [
+ *     tasks(),
+ *   ],
+ * };
+ * ```
+ */
+class TasksPlugin extends commandkit_1.RuntimePlugin {
+    constructor() {
+        super(...arguments);
+        /** The plugin name identifier */
+        this.name = 'tasks';
+        /** Collection of loaded task instances indexed by task name */
+        this.tasks = new commandkit_1.Collection();
+    }
+    /**
+     * Activates the tasks plugin.
+     *
+     * This method:
+     * 1. Sets up the task execution runner
+     * 2. Loads all task definitions from the tasks directory
+     * 3. Schedules tasks that have defined schedules
+     *
+     * @param ctx - The CommandKit plugin runtime context
+     */
+    async activate(ctx) {
+        driver_manager_1.taskDriverManager.setTaskRunner(async (task) => {
+            try {
+                const taskInstance = this.tasks.get(task.name);
+                if (!taskInstance) {
+                    // task does not exist so we delete it
+                    await driver_manager_1.taskDriverManager.deleteTask(task.name);
+                    return;
+                }
+                const context = new context_1.TaskContext({
+                    task: taskInstance,
+                    data: task.data,
+                    commandkit: ctx.commandkit,
+                });
+                const prepared = await taskInstance.prepare(context);
+                if (!prepared)
+                    return;
+                await taskInstance.execute(context);
+            }
+            catch (e) {
+                commandkit_1.Logger.error(`Error executing task: ${e?.stack ?? e}`);
+            }
+        });
+        await this.loadTasks();
+        commandkit_1.Logger.info('Tasks plugin activated!');
+    }
+    /**
+     * Deactivates the tasks plugin.
+     *
+     * Clears all loaded tasks from memory.
+     *
+     * @param ctx - The CommandKit plugin runtime context
+     */
+    async deactivate(ctx) {
+        this.tasks.clear();
+        commandkit_1.Logger.info('Tasks plugin deactivated!');
+    }
+    /**
+     * Gets the default tasks directory path.
+     *
+     * @returns The absolute path to the tasks directory
+     */
+    getTaskDirectory() {
+        return node_path_1.default.join((0, commandkit_1.getCurrentDirectory)(), 'app', 'tasks');
+    }
+    /**
+     * Loads all task definitions from the tasks directory.
+     *
+     * This method scans the tasks directory for TypeScript/JavaScript files and
+     * imports them as task definitions. It validates that each export is a valid
+     * Task instance and schedules tasks that have defined schedules.
+     *
+     * @param commandkit - The CommandKit instance
+     */
+    async loadTasks() {
+        const taskDirectory = this.getTaskDirectory();
+        if (!(0, node_fs_1.existsSync)(taskDirectory))
+            return;
+        const files = await (0, promises_1.readdir)(taskDirectory, { withFileTypes: true });
+        for (const file of files) {
+            if (file.isDirectory() ||
+                file.name.startsWith('_') ||
+                !/\.(c|m)?(j|t)sx?$/.test(file.name)) {
+                continue;
+            }
+            const taskPath = node_path_1.default.join(file.parentPath, file.name);
+            const task = await import((0, commandkit_1.toFileURL)(taskPath, true))
+                .then((m) => m.default || m)
+                .catch((e) => {
+                commandkit_1.Logger.error(`Error loading task file: ${e?.stack ?? e}`);
+                return null;
+            });
+            if (!task || !(task instanceof task_1.Task)) {
+                continue;
+            }
+            if (this.tasks.has(task.name)) {
+                commandkit_1.Logger.error(`Duplicate task found: ${task.name} at src/app/tasks/${file.name}`);
+                continue;
+            }
+            if (task.schedule) {
+                await driver_manager_1.taskDriverManager.createTask({
+                    name: task.name,
+                    data: {},
+                    schedule: task.schedule,
+                });
+            }
+            this.tasks.set(task.name, task);
+            commandkit_1.Logger.info(`Loaded task: ${task.name}`);
+        }
+        commandkit_1.Logger.info(`Loaded ${this.tasks.size} tasks`);
+    }
+    /**
+     * Handles hot module replacement (HMR) for task files.
+     *
+     * When a task file is modified during development, this method reloads the
+     * task definition and updates the scheduler accordingly.
+     *
+     * @param ctx - The CommandKit plugin runtime context
+     * @param event - The HMR event containing file change information
+     */
+    async performHMR(ctx, event) {
+        if (event.event !== 'unknown')
+            return;
+        if (!event.path.startsWith((0, node_path_1.join)((0, node_process_1.cwd)(), 'src', 'app', 'tasks'))) {
+            return;
+        }
+        event.preventDefault();
+        event.accept();
+        const taskData = await import((0, commandkit_1.toFileURL)(event.path, true))
+            .then((t) => t.default || t)
+            .catch((e) => {
+            commandkit_1.Logger.error(`Error loading task file: ${e?.stack ?? e}`);
+            return null;
+        });
+        if (!taskData || !(taskData instanceof task_1.Task))
+            return;
+        if (this.tasks.has(taskData.name)) {
+            commandkit_1.Logger.info(`Reloading task: ${taskData.name}`);
+            await driver_manager_1.taskDriverManager.deleteTask(taskData.name);
+            this.tasks.set(taskData.name, taskData);
+            if (taskData.schedule) {
+                await driver_manager_1.taskDriverManager.createTask({
+                    name: taskData.name,
+                    data: {},
+                    schedule: taskData.schedule,
+                });
+            }
+        }
+        else {
+            commandkit_1.Logger.info(`Loading task: ${taskData.name}`);
+            this.tasks.set(taskData.name, taskData);
+            if (taskData.schedule) {
+                await driver_manager_1.taskDriverManager.createTask({
+                    name: taskData.name,
+                    data: {},
+                    schedule: taskData.schedule,
+                });
+            }
+        }
+    }
+}
+exports.TasksPlugin = TasksPlugin;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2luLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3BsdWdpbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSwyQ0FTb0I7QUFDcEIsK0NBQTJDO0FBQzNDLHVEQUF1QztBQUN2QyxpQ0FBOEI7QUFDOUIsK0NBQW1DO0FBQ25DLHFEQUFxRDtBQUNyRCx1Q0FBd0M7QUFDeEMscUNBQXFDO0FBY3JDOzs7Ozs7Ozs7Ozs7Ozs7OztHQWlCRztBQUNILE1BQWEsV0FBWSxTQUFRLDBCQUFpQztJQUFsRTs7UUFDRSxpQ0FBaUM7UUFDakIsU0FBSSxHQUFHLE9BQU8sQ0FBQztRQUUvQiwrREFBK0Q7UUFDL0MsVUFBSyxHQUFHLElBQUksdUJBQVUsRUFBZ0IsQ0FBQztJQWtMekQsQ0FBQztJQWhMQzs7Ozs7Ozs7O09BU0c7SUFDSSxLQUFLLENBQUMsUUFBUSxDQUFDLEdBQTRCO1FBQ2hELGtDQUFpQixDQUFDLGFBQWEsQ0FBQyxLQUFLLEVBQUUsSUFBSSxFQUFFLEVBQUU7WUFDN0MsSUFBSSxDQUFDO2dCQUNILE1BQU0sWUFBWSxHQUFHLElBQUksQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQztnQkFFL0MsSUFBSSxDQUFDLFlBQVksRUFBRSxDQUFDO29CQUNsQixzQ0FBc0M7b0JBQ3RDLE1BQU0sa0NBQWlCLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQztvQkFDOUMsT0FBTztnQkFDVCxDQUFDO2dCQUVELE1BQU0sT0FBTyxHQUFHLElBQUkscUJBQVcsQ0FBQztvQkFDOUIsSUFBSSxFQUFFLFlBQVk7b0JBQ2xCLElBQUksRUFBRSxJQUFJLENBQUMsSUFBSTtvQkFDZixVQUFVLEVBQUUsR0FBRyxDQUFDLFVBQVU7aUJBQzNCLENBQUMsQ0FBQztnQkFFSCxNQUFNLFFBQVEsR0FBRyxNQUFNLFlBQVksQ0FB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

package/dist/task.d.ts

@@ -0,0 +1,108 @@
+import { TaskContext } from './context';
+import { TaskDefinition, TaskSchedule } from './types';
+/**
+ * Represents a task instance with execution logic and metadata.
+ *
+ * Tasks can be scheduled to run at specific times or intervals using cron expressions
+ * or date-based scheduling. They support preparation logic to conditionally execute
+ * and provide a context for accessing CommandKit and Discord.js functionality.
+ *
+ * @example
+ * ```ts
+ * import { task } from '@commandkit/tasks';
+ *
+ * export const cleanupTask = task({
+ *   name: 'cleanup-old-data',
+ *   schedule: { type: 'cron', value: '0 2 * * *' }, // Daily at 2 AM
+ *   async prepare(ctx) {
+ *     // Only run if there's old data to clean
+ *     return await hasOldData();
+ *   },
+ *   async execute(ctx) {
+ *     await cleanupOldRecords();
+ *     await ctx.commandkit.client.channels.cache
+ *       .get('log-channel')?.send('Cleanup completed!');
+ *   },
+ * });
+ * ```
+ */
+export declare class Task<T extends Record<string, any> = Record<string, any>> {
+    private data;
+    /**
+     * Creates a new task instance.
+     *
+     * @param data - The task definition containing name, schedule, and execution logic
+     */
+    constructor(data: TaskDefinition<T>);
+    /**
+     * Whether this task should run immediately when created.
+     * Only applicable to cron tasks, defaults to false.
+     */
+    get immediate(): boolean;
+    /**
+     * The unique identifier for this task.
+     */
+    get name(): string;
+    /**
+     * The schedule configuration for this task.
+     * Returns null if no schedule is defined (manual execution only).
+     */
+    get schedule(): TaskSchedule | null;
+    /**
+     * Checks if this task uses cron-based scheduling.
+     *
+     * @returns true if the task has a cron schedule
+     */
+    isCron(): boolean;
+    /**
+     * Checks if this task uses date-based scheduling.
+     *
+     * @returns true if the task has a date schedule
+     */
+    isDate(): boolean;
+    /**
+     * Determines if the task is ready to be executed.
+     *
+     * This method calls the optional prepare function if defined. If no prepare
+     * function is provided, the task is always ready to execute.
+     *
+     * @param ctx - The task execution context
+     * @returns true if the task should execute, false to skip this run
+     */
+    prepare(ctx: TaskContext<T>): Promise<boolean>;
+    /**
+     * Executes the task's main logic.
+     *
+     * This method calls the execute function defined in the task definition.
+     * It provides access to the CommandKit instance, Discord.js client, and
+     * any custom data passed to the task.
+     *
+     * @param ctx - The task execution context containing CommandKit, client, and data
+     */
+    execute(ctx: TaskContext<T>): Promise<void>;
+}
+/**
+ * Creates a new task definition.
+ *
+ * This is the main function for defining tasks in your application. Tasks can be
+ * scheduled using cron expressions or specific dates, and can include preparation
+ * logic to conditionally execute based on runtime conditions.
+ *
+ * @example
+ * ```ts
+ * import { task } from '@commandkit/tasks';
+ *
+ * // Simple scheduled task
+ * export const dailyBackup = task({
+ *   name: 'daily-backup',
+ *   schedule: { type: 'cron', value: '0 0 * * *' },
+ *   async execute(ctx) {
+ *     await performBackup();
+ *   },
+ * });
+ * ```
+ *
+ * @param data - The task definition containing name, schedule, and execution logic
+ * @returns A configured Task instance
+ */
+export declare function task<T extends Record<string, any> = Record<string, any>>(data: TaskDefinition<T>): Task<T>;

package/dist/task.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Task = void 0;
+exports.task = task;
+/**
+ * Represents a task instance with execution logic and metadata.
+ *
+ * Tasks can be scheduled to run at specific times or intervals using cron expressions
+ * or date-based scheduling. They support preparation logic to conditionally execute
+ * and provide a context for accessing CommandKit and Discord.js functionality.
+ *
+ * @example
+ * ```ts
+ * import { task } from '@commandkit/tasks';
+ *
+ * export const cleanupTask = task({
+ *   name: 'cleanup-old-data',
+ *   schedule: { type: 'cron', value: '0 2 * * *' }, // Daily at 2 AM
+ *   async prepare(ctx) {
+ *     // Only run if there's old data to clean
+ *     return await hasOldData();
+ *   },
+ *   async execute(ctx) {
+ *     await cleanupOldRecords();
+ *     await ctx.commandkit.client.channels.cache
+ *       .get('log-channel')?.send('Cleanup completed!');
+ *   },
+ * });
+ * ```
+ */
+class Task {
+    /**
+     * Creates a new task instance.
+     *
+     * @param data - The task definition containing name, schedule, and execution logic
+     */
+    constructor(data) {
+        this.data = data;
+    }
+    /**
+     * Whether this task should run immediately when created.
+     * Only applicable to cron tasks, defaults to false.
+     */
+    get immediate() {
+        return this.data.immediate ?? false;
+    }
+    /**
+     * The unique identifier for this task.
+     */
+    get name() {
+        return this.data.name;
+    }
+    /**
+     * The schedule configuration for this task.
+     * Returns null if no schedule is defined (manual execution only).
+     */
+    get schedule() {
+        return this.data.schedule ?? null;
+    }
+    /**
+     * Checks if this task uses cron-based scheduling.
+     *
+     * @returns true if the task has a cron schedule
+     */
+    isCron() {
+        return this.schedule?.type === 'cron';
+    }
+    /**
+     * Checks if this task uses date-based scheduling.
+     *
+     * @returns true if the task has a date schedule
+     */
+    isDate() {
+        return this.schedule?.type === 'date';
+    }
+    /**
+     * Determines if the task is ready to be executed.
+     *
+     * This method calls the optional prepare function if defined. If no prepare
+     * function is provided, the task is always ready to execute.
+     *
+     * @param ctx - The task execution context
+     * @returns true if the task should execute, false to skip this run
+     */
+    async prepare(ctx) {
+        return this.data.prepare?.(ctx) ?? true;
+    }
+    /**
+     * Executes the task's main logic.
+     *
+     * This method calls the execute function defined in the task definition.
+     * It provides access to the CommandKit instance, Discord.js client, and
+     * any custom data passed to the task.
+     *
+     * @param ctx - The task execution context containing CommandKit, client, and data
+     */
+    async execute(ctx) {
+        await this.data.execute(ctx);
+    }
+}
+exports.Task = Task;
+/**
+ * Creates a new task definition.
+ *
+ * This is the main function for defining tasks in your application. Tasks can be
+ * scheduled using cron expressions or specific dates, and can include preparation
+ * logic to conditionally execute based on runtime conditions.
+ *
+ * @example
+ * ```ts
+ * import { task } from '@commandkit/tasks';
+ *
+ * // Simple scheduled task
+ * export const dailyBackup = task({
+ *   name: 'daily-backup',
+ *   schedule: { type: 'cron', value: '0 0 * * *' },
+ *   async execute(ctx) {
+ *     await performBackup();
+ *   },
+ * });
+ * ```
+ *
+ * @param data - The task definition containing name, schedule, and execution logic
+ * @returns A configured Task instance
+ */
+function task(data) {
+    return new Task(data);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGFzay5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy90YXNrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQWlJQSxvQkFJQztBQWxJRDs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXlCRztBQUNILE1BQWEsSUFBSTtJQUNmOzs7O09BSUc7SUFDSCxZQUEyQixJQUF1QjtRQUF2QixTQUFJLEdBQUosSUFBSSxDQUFtQjtJQUFHLENBQUM7SUFFdEQ7OztPQUdHO0lBQ0gsSUFBVyxTQUFTO1FBQ2xCLE9BQU8sSUFBSSxDQUFDLElBQUksQ0FBQyxTQUFTLElBQUksS0FBSyxDQUFDO0lBQ3RDLENBQUM7SUFFRDs7T0FFRztJQUNILElBQVcsSUFBSTtRQUNiLE9BQU8sSUFBSSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUM7SUFDeEIsQ0FBQztJQUVEOzs7T0FHRztJQUNILElBQVcsUUFBUTtRQUNqQixPQUFPLElBQUksQ0FBQyxJQUFJLENBQUMsUUFBUSxJQUFJLElBQUksQ0FBQztJQUNwQyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNJLE1BQU07UUFDWCxPQUFPLElBQUksQ0FBQyxRQUFRLEVBQUUsSUFBSSxLQUFLLE1BQU0sQ0FBQztJQUN4QyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNJLE1BQU07UUFDWCxPQUFPLElBQUksQ0FBQyxRQUFRLEVBQUUsSUFBSSxLQUFLLE1BQU0sQ0FBQztJQUN4QyxDQUFDO0lBRUQ7Ozs7Ozs7O09BUUc7SUFDSSxLQUFLLENBQUMsT0FBTyxDQUFDLEdBQW1CO1FBQ3RDLE9BQU8sSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsQ0FBQyxHQUFHLENBQUMsSUFBSSxJQUFJLENBQUM7SUFDMUMsQ0FBQztJQUVEOzs7Ozs7OztPQVFHO0lBQ0ksS0FBSyxDQUFDLE9BQU8sQ0FBQyxHQUFtQjtRQUN0QyxNQUFNLElBQUksQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQy9CLENBQUM7Q0FDRjtBQTFFRCxvQkEwRUM7QUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0F1Qkc7QUFDSCxTQUFnQixJQUFJLENBQ2xCLElBQXVCO0lBRXZCLE9BQU8sSUFBSSxJQUFJLENBQUksSUFBSSxDQUFDLENBQUM7QUFDM0IsQ0FBQyJ9

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+import { TaskContext } from './context';
+/**
+ * Represents a task schedule configuration.
+ *
+ * Tasks can be scheduled using either cron expressions or specific dates/timestamps.
+ * The timezone is optional and defaults to the system timezone.
+ */
+export type TaskSchedule = {
+    /** Schedule type using cron expressions */
+    type: 'cron';
+    /** Optional timezone for the cron schedule (e.g., 'UTC', 'America/New_York') */
+    timezone?: string;
+    /** Cron expression (e.g., '0 0 * * *' for daily at midnight) */
+    value: string;
+} | {
+    /** Schedule type using a specific date or timestamp */
+    type: 'date';
+    /** Optional timezone for the date schedule */
+    timezone?: string;
+    /** Date object or Unix timestamp in milliseconds */
+    value: Date | number;
+};
+/**
+ * Defines a task with its execution logic and scheduling.
+ *
+ * Tasks can have optional preparation logic that determines whether the task should run,
+ * and required execution logic that performs the actual task work.
+ */
+export interface TaskDefinition<T extends Record<string, any> = Record<string, any>> {
+    /** Unique identifier for the task */
+    name: string;
+    /** Optional schedule configuration for recurring or delayed execution */
+    schedule?: TaskSchedule;
+    /** Whether the task should run immediately when created (only for cron tasks) */
+    immediate?: boolean;
+    /**
+     * Optional preparation function that determines if the task should execute.
+     * Return false to skip execution for this run.
+     */
+    prepare?: (ctx: TaskContext<T>) => Promise<boolean>;
+    /**
+     * The main execution function that performs the task work.
+     * This is called when the task is scheduled to run.
+     */
+    execute: (ctx: TaskContext<T>) => Promise<void>;
+}
+/**
+ * Represents the data structure for a task instance.
+ *
+ * This includes the task metadata and any custom data passed to the task.
+ */
+export interface TaskData<T extends Record<string, any> = Record<string, any>> {
+    /** The name of the task definition to execute */
+    name: string;
+    /** Custom data passed to the task execution context */
+    data: T;
+    /** Schedule configuration for when the task should run */
+    schedule: TaskSchedule;
+    /** Whether the task should run immediately when created */
+    immediate?: boolean;
+}
+/**
+ * Partial task data for creating tasks with optional fields.
+ *
+ * Useful when you want to create a task with only some fields specified.
+ */
+export type PartialTaskData<T extends Record<string, any> = Record<string, any>> = Partial<TaskData<T>>;
+/**
+ * Data structure passed to task execution handlers.
+ *
+ * This includes the task metadata and execution timestamp, but excludes
+ * scheduling information since the task is already being executed.
+ */
+export type TaskExecutionData = Omit<TaskData, 'schedule' | 'immediate'> & {
+    /** Unix timestamp when the task execution started */
+    timestamp: number;
+};

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9