@commandkit/tasks 0.0.0-dev.20250724145623

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2025 Avraj Sahota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the “Software”), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# @commandkit/tasks
+
+Task management plugin for CommandKit. Provides on-demand task creation and management with support for both static and dynamic tasks.
+
+## Features
+
+- **Static Tasks**: Define tasks in your codebase that run on schedules
+- **Dynamic Tasks**: Create tasks on-demand from commands or events
+- **Multiple Drivers**: Support for in-memory, SQLite, and BullMQ persistence
+- **HMR Support**: Hot reload tasks during development
+- **Flexible Scheduling**: Support for cron expressions, dates, and dynamic schedules
+
+## Installation
+
+```bash
+npm install @commandkit/tasks
+```
+
+## Quick Start
+
+### 1. Add the plugin to your CommandKit configuration
+
+```ts
+import { tasks } from '@commandkit/tasks';
+
+export default {
+  plugins: [
+    tasks({
+      tasksPath: 'app/tasks', // optional, defaults to 'app/tasks'
+      enableHMR: true, // optional, defaults to true in development
+    }),
+  ],
+};
+```
+
+### 2. Create static tasks
+
+Create a file in `src/app/tasks/`:
+
+```ts
+import { task } from '@commandkit/tasks';
+
+export const refreshExchangeRate = task({
+  name: 'refresh-exchange-rate',
+  schedule: '0 0 * * *', // cron expression - daily at midnight
+  async execute(ctx) {
+    // Fetch latest exchange rates
+    const rates = await fetchExchangeRates();
+    await updateDatabase(rates);
+  },
+});
+
+export const cleanupOldData = task({
+  name: 'cleanup-old-data',
+  schedule: () => new Date(Date.now() + 24 * 60 * 60 * 1000), // tomorrow
+  async prepare(ctx) {
+    // Only run if there's old data to clean
+    return await hasOldData();
+  },
+  async execute(ctx) {
+    await cleanupOldRecords();
+  },
+});
+```
+
+### 3. Create dynamic tasks from commands
+
+```ts
+import { createTask } from '@commandkit/tasks';
+
+export default {
+  name: 'remind-me',
+  description: 'Set a reminder',
+  async run(ctx) {
+    const time = ctx.interaction.options.getString('time');
+    const reason = ctx.interaction.options.getString('reason');
+    
+    await createTask({
+      name: 'reminder',
+      schedule: new Date(Date.now() + ms(time)),
+      data: {
+        userId: ctx.interaction.user.id,
+        reason,
+      },
+    });
+    
+    await ctx.interaction.reply('Reminder set!');
+  },
+};
+```
+
+## API Reference
+
+### Plugin Options
+
+```ts
+interface TasksPluginOptions {
+  tasksPath?: string; // Path to tasks directory, defaults to 'app/tasks'
+  enableHMR?: boolean; // Enable HMR for tasks, defaults to true in development
+}
+```
+
+### Task Definition
+
+```ts
+interface TaskDefinition {
+  name: string;
+  schedule?: ScheduleType;
+  prepare?: (ctx: TaskContext) => Promise<boolean> | boolean;
+  execute: (ctx: TaskContext) => Promise<void> | void;
+}
+```
+
+### Schedule Types
+
+```ts
+type ScheduleType = 
+  | Date 
+  | number // unix timestamp
+  | string // cron expression or date string
+  | (() => Date | number | string); // dynamic schedule
+```
+
+**Cron Expressions**: The plugin supports standard cron expressions (e.g., `'0 0 * * *'` for daily at midnight). Cron parsing is handled by `cron-parser` for in-memory and SQLite drivers, while BullMQ uses its built-in cron support.
+
+### Task Context
+
+```ts
+interface TaskContext {
+  task: TaskData;
+  commandkit: CommandKit;
+  client: Client;
+}
+```
+
+### Functions
+
+#### `task(definition: TaskDefinition)`
+
+Creates a task definition.
+
+```ts
+import { task } from '@commandkit/tasks';
+
+export const myTask = task({
+  name: 'my-task',
+  schedule: '0 0 * * *',
+  async execute(ctx) {
+    // Task logic here
+  },
+});
+```
+
+#### `createTask(options: CreateTaskOptions)`
+
+Creates a dynamic task.
+
+```ts
+import { createTask } from '@commandkit/tasks';
+
+await createTask({
+  name: 'reminder',
+  schedule: new Date(Date.now() + 60000), // 1 minute from now
+  data: { userId: '123', message: 'Hello!' },
+});
+```
+
+#### `executeTask(taskOrName: TaskDefinition | string)`
+
+Executes a task immediately.
+
+```ts
+import { executeTask } from '@commandkit/tasks';
+
+await executeTask('my-task');
+// or
+await executeTask(myTask);
+```
+
+#### `cancelTask(taskOrName: TaskDefinition | string)`
+
+Cancels a scheduled task.
+
+```ts
+import { cancelTask } from '@commandkit/tasks';
+
+await cancelTask('my-task');
+```
+
+#### `pauseTask(taskOrName: TaskDefinition | string)`
+
+Pauses a task.
+
+```ts
+import { pauseTask } from '@commandkit/tasks';
+
+await pauseTask('my-task');
+```
+
+#### `resumeTask(taskOrName: TaskDefinition | string)`
+
+Resumes a paused task.
+
+```ts
+import { resumeTask } from '@commandkit/tasks';
+
+await resumeTask('my-task');
+```
+
+## Persistence Drivers
+
+The drivers handle all scheduling and timing internally. When a task is due for execution, the driver calls the plugin's execution handler.
+
+### In-Memory Driver (Default)
+
+```ts
+import { driver } from '@commandkit/tasks';
+import { InMemoryDriver } from '@commandkit/tasks/drivers';
+
+driver.use(new InMemoryDriver());
+```
+
+### SQLite Driver
+
+```ts
+import { driver } from '@commandkit/tasks';
+import { SQLiteDriver } from '@commandkit/tasks/drivers';
+
+driver.use(new SQLiteDriver('./tasks.db'));
+```
+
+**Note**: Requires `sqlite3`, `sqlite`, and `cron-parser` packages to be installed.
+
+### BullMQ Driver
+
+```ts
+import { driver } from '@commandkit/tasks';
+import { BullMQDriver } from '@commandkit/tasks/drivers';
+
+driver.use(new BullMQDriver({
+  host: 'localhost',
+  port: 6379,
+}));
+```
+
+**Note**: Requires `bullmq` package to be installed. BullMQ has built-in cron support, so no additional cron parsing is needed.
+
+## Examples
+
+### Scheduled Database Backup
+
+```ts
+import { task } from '@commandkit/tasks';
+
+export const databaseBackup = task({
+  name: 'database-backup',
+  schedule: '0 2 * * *', // Daily at 2 AM
+  async execute(ctx) {
+    const backup = await createBackup();
+    await uploadToCloud(backup);
+    await ctx.client.channels.cache.get('backup-log')?.send('Backup completed!');
+  },
+});
+```
+
+### User Reminder System
+
+```ts
+import { task } from '@commandkit/tasks';
+
+export const reminder = task({
+  name: 'reminder',
+  async execute(ctx) {
+    const { userId, message } = ctx.task.data;
+    const user = await ctx.client.users.fetch(userId);
+    await user.send(`Reminder: ${message}`);
+  },
+});
+```
+
+### Conditional Task
+
+```ts
+import { task } from '@commandkit/tasks';
+
+export const maintenanceCheck = task({
+  name: 'maintenance-check',
+  schedule: '0 */6 * * *', // Every 6 hours
+  async prepare(ctx) {
+    // Only run if maintenance mode is not enabled
+    return !ctx.commandkit.store.get('maintenance-mode');
+  },
+  async execute(ctx) {
+    await performMaintenanceChecks();
+  },
+});
+```
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,103 @@
+import type { CommandKit, Client } from 'commandkit';
+import { Task } from './task';
+/**
+ * Data structure for creating a task execution context.
+ *
+ * This interface contains all the necessary information to create a task context,
+ * including the task instance, custom data, and CommandKit instance.
+ */
+export interface TaskContextData<T extends Record<string, any> = Record<string, any>> {
+    /** The task instance that is being executed */
+    task: Task;
+    /** Custom data passed to the task execution */
+    data: T;
+    /** The CommandKit instance for accessing bot functionality */
+    commandkit: CommandKit;
+}
+/**
+ * Execution context provided to task functions.
+ *
+ * This class provides access to the task instance, custom data, CommandKit instance,
+ * and a temporary store for sharing data between prepare and execute functions.
+ *
+ * @example
+ * ```ts
+ * import { task } from '@commandkit/tasks';
+ *
+ * export const reminderTask = task({
+ *   name: 'reminder',
+ *   async execute(ctx) {
+ *     // Access custom data passed to the task
+ *     const { userId, message } = ctx.data;
+ *
+ *     // Access CommandKit and Discord.js client
+ *     const user = await ctx.commandkit.client.users.fetch(userId);
+ *     await user.send(`Reminder: ${message}`);
+ *
+ *     // Use the store to share data between prepare and execute
+ *     const processedCount = ctx.store.get('processedCount') || 0;
+ *     ctx.store.set('processedCount', processedCount + 1);
+ *   },
+ * });
+ * ```
+ */
+export declare class TaskContext<T extends Record<string, any> = Record<string, any>> {
+    private _data;
+    /**
+     * Temporary key-value store for sharing data between prepare and execute functions.
+     *
+     * This store is useful for passing computed values or state between the prepare
+     * and execute phases of task execution.
+     *
+     * @example
+     * ```ts
+     * export const conditionalTask = task({
+     *   name: 'conditional-task',
+     *   async prepare(ctx) {
+     *     const shouldRun = await checkConditions();
+     *     ctx.store.set('shouldRun', shouldRun);
+     *     return shouldRun;
+     *   },
+     *   async execute(ctx) {
+     *     const shouldRun = ctx.store.get('shouldRun');
+     *     if (shouldRun) {
+     *       await performAction();
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    readonly store: Map<string, any>;
+    /**
+     * Creates a new task execution context.
+     *
+     * @param _data - The task context data containing task, data, and CommandKit instance
+     */
+    constructor(_data: TaskContextData<T>);
+    /**
+     * Gets the task instance being executed.
+     *
+     * @returns The Task instance
+     */
+    get task(): Task;
+    /**
+     * Gets the Discord.js client.
+     * @returns The Discord.js client
+     */
+    get client(): Client;
+    /**
+     * Gets the custom data passed to the task execution.
+     *
+     * @returns The custom data object
+     */
+    get data(): T;
+    /**
+     * Gets the CommandKit instance for accessing bot functionality.
+     *
+     * This provides access to the Discord.js client, CommandKit store, and other
+     * bot-related functionality.
+     *
+     * @returns The CommandKit instance
+     */
+    get commandkit(): CommandKit;
+}

package/dist/context.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskContext = void 0;
+/**
+ * Execution context provided to task functions.
+ *
+ * This class provides access to the task instance, custom data, CommandKit instance,
+ * and a temporary store for sharing data between prepare and execute functions.
+ *
+ * @example
+ * ```ts
+ * import { task } from '@commandkit/tasks';
+ *
+ * export const reminderTask = task({
+ *   name: 'reminder',
+ *   async execute(ctx) {
+ *     // Access custom data passed to the task
+ *     const { userId, message } = ctx.data;
+ *
+ *     // Access CommandKit and Discord.js client
+ *     const user = await ctx.commandkit.client.users.fetch(userId);
+ *     await user.send(`Reminder: ${message}`);
+ *
+ *     // Use the store to share data between prepare and execute
+ *     const processedCount = ctx.store.get('processedCount') || 0;
+ *     ctx.store.set('processedCount', processedCount + 1);
+ *   },
+ * });
+ * ```
+ */
+class TaskContext {
+    /**
+     * Creates a new task execution context.
+     *
+     * @param _data - The task context data containing task, data, and CommandKit instance
+     */
+    constructor(_data) {
+        this._data = _data;
+        /**
+         * Temporary key-value store for sharing data between prepare and execute functions.
+         *
+         * This store is useful for passing computed values or state between the prepare
+         * and execute phases of task execution.
+         *
+         * @example
+         * ```ts
+         * export const conditionalTask = task({
+         *   name: 'conditional-task',
+         *   async prepare(ctx) {
+         *     const shouldRun = await checkConditions();
+         *     ctx.store.set('shouldRun', shouldRun);
+         *     return shouldRun;
+         *   },
+         *   async execute(ctx) {
+         *     const shouldRun = ctx.store.get('shouldRun');
+         *     if (shouldRun) {
+         *       await performAction();
+         *     }
+         *   },
+         * });
+         * ```
+         */
+        this.store = new Map();
+    }
+    /**
+     * Gets the task instance being executed.
+     *
+     * @returns The Task instance
+     */
+    get task() {
+        return this._data.task;
+    }
+    /**
+     * Gets the Discord.js client.
+     * @returns The Discord.js client
+     */
+    get client() {
+        return this._data.commandkit.client;
+    }
+    /**
+     * Gets the custom data passed to the task execution.
+     *
+     * @returns The custom data object
+     */
+    get data() {
+        return this._data.data;
+    }
+    /**
+     * Gets the CommandKit instance for accessing bot functionality.
+     *
+     * This provides access to the Discord.js client, CommandKit store, and other
+     * bot-related functionality.
+     *
+     * @returns The CommandKit instance
+     */
+    get commandkit() {
+        return this._data.commandkit;
+    }
+}
+exports.TaskContext = TaskContext;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udGV4dC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9jb250ZXh0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQW9CQTs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0EwQkc7QUFDSCxNQUFhLFdBQVc7SUEyQnRCOzs7O09BSUc7SUFDSCxZQUEyQixLQUF5QjtRQUF6QixVQUFLLEdBQUwsS0FBSyxDQUFvQjtRQS9CcEQ7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O1dBdUJHO1FBQ2EsVUFBSyxHQUFHLElBQUksR0FBRyxFQUFlLENBQUM7SUFPUSxDQUFDO0lBRXhEOzs7O09BSUc7SUFDSCxJQUFXLElBQUk7UUFDYixPQUFPLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDO0lBQ3pCLENBQUM7SUFFRDs7O09BR0c7SUFDSCxJQUFXLE1BQU07UUFDZixPQUFPLElBQUksQ0FBQyxLQUFLLENBQUMsVUFBVSxDQUFDLE1BQU0sQ0FBQztJQUN0QyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILElBQVcsSUFBSTtRQUNiLE9BQU8sSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUM7SUFDekIsQ0FBQztJQUVEOzs7Ozs7O09BT0c7SUFDSCxJQUFXLFVBQVU7UUFDbkIsT0FBTyxJQUFJLENBQUMsS0FBSyxDQUFDLFVBQVUsQ0FBQztJQUMvQixDQUFDO0NBQ0Y7QUF2RUQsa0NBdUVDIn0=

package/dist/driver-manager.d.ts

@@ -0,0 +1,126 @@
+import { TaskDriver, TaskRunner } from './driver';
+import { TaskData } from './types';
+/**
+ * Manages the active task driver and provides a unified interface for task operations.
+ *
+ * This class acts as a facade for the underlying task driver, providing methods
+ * to create, delete, and manage tasks. It ensures that a driver is set before
+ * any operations are performed.
+ *
+ * @example
+ * ```ts
+ * import { TaskDriverManager } from '@commandkit/tasks';
+ * import { HyperCronDriver } from '@commandkit/tasks/hypercron';
+ *
+ * const manager = new TaskDriverManager();
+ * manager.setDriver(new HyperCronDriver());
+ *
+ * // Now you can create and manage tasks
+ * const taskId = await manager.createTask({
+ *   name: 'my-task',
+ *   data: { userId: '123' },
+ *   schedule: { type: 'date', value: Date.now() + 60000 },
+ * });
+ * ```
+ */
+export declare class TaskDriverManager {
+    private driver;
+    /**
+     * Sets the active task driver.
+     *
+     * This method must be called before any task operations can be performed.
+     * The driver handles all scheduling, persistence, and execution timing.
+     *
+     * @param driver - The task driver to use for all operations
+     */
+    setDriver(driver: TaskDriver): void;
+    /**
+     * Creates a new scheduled task.
+     *
+     * This method delegates to the active driver to schedule the task according
+     * to its configuration. The task will be executed when its schedule is due.
+     *
+     * @param task - The task data containing name, schedule, and custom data
+     * @returns A unique identifier for the created task
+     * @throws {Error} If no driver has been set
+     */
+    createTask(task: TaskData): Promise<string>;
+    /**
+     * Deletes a scheduled task by its identifier.
+     *
+     * This method delegates to the active driver to remove the task from the
+     * scheduling system and cancel any pending executions.
+     *
+     * @param identifier - The unique identifier of the task to delete
+     * @throws {Error} If no driver has been set
+     */
+    deleteTask(identifier: string): Promise<void>;
+    /**
+     * Sets the task execution runner function.
+     *
+     * This method delegates to the active driver to set up the execution handler
+     * that will be called when tasks are due to run.
+     *
+     * @param runner - The function to call when a task should be executed
+     * @throws {Error} If no driver has been set
+     */
+    setTaskRunner(runner: TaskRunner): Promise<void>;
+}
+/**
+ * Global task driver manager instance.
+ *
+ * This is the default instance used by the tasks plugin for managing task operations.
+ * You can use this instance directly or create your own TaskDriverManager instance.
+ */
+export declare const taskDriverManager: TaskDriverManager;
+/**
+ * Sets the global task driver.
+ *
+ * This is a convenience function that sets the driver on the global task driver manager.
+ *
+ * @param driver - The task driver to use for all operations
+ *
+ * @example
+ * ```ts
+ * import { setDriver } from '@commandkit/tasks';
+ * import { HyperCronDriver } from '@commandkit/tasks/hypercron';
+ *
+ * setDriver(new HyperCronDriver());
+ * ```
+ */
+export declare function setDriver(driver: TaskDriver): void;
+/**
+ * Creates a new scheduled task using the global driver manager.
+ *
+ * This is a convenience function that creates a task using the global task driver manager.
+ *
+ * @param task - The task data containing name, schedule, and custom data
+ * @returns A unique identifier for the created task
+ *
+ * @example
+ * ```ts
+ * import { createTask } from '@commandkit/tasks';
+ *
+ * const taskId = await createTask({
+ *   name: 'reminder',
+ *   data: { userId: '123', message: 'Hello!' },
+ *   schedule: { type: 'date', value: Date.now() + 60000 },
+ * });
+ * ```
+ */
+export declare function createTask(task: TaskData): Promise<string>;
+/**
+ * Deletes a scheduled task using the global driver manager.
+ *
+ * This is a convenience function that deletes a task using the global task driver manager.
+ *
+ * @param identifier - The unique identifier of the task to delete
+ *
+ * @example
+ * ```ts
+ * import { deleteTask } from '@commandkit/tasks';
+ *
+ * await deleteTask('task-123');
+ * ```
+ */
+export declare function deleteTask(identifier: string): Promise<void>;