@kingsworld/plugin-cron 1.5.2 → 2.0.0-next.023f779

package/README.md

@@ -1,122 +1,152 @@
+<div align="center">
+
 # @kingsworld/plugin-cron
 
-A simple [@sapphire/framework](https://www.npmjs.com/package/@sapphire/framework) plugin that aims to make use of the [cron](https://www.npmjs.com/package/cron) package and allow users to make cron jobs within their Sapphire discord bot.
+**Plugin for <a href="https://github.com/sapphiredev/framework">@sapphire/framework</a> to add support for cron tasks using <a href="https://github.com/kelektiv/node-cron">cron</a>.**
+
+[![GitHub](https://img.shields.io/github/license/Kings-World/sapphire-plugins)](https://github.com/Kings-World/sapphire-plugins/blob/main/LICENSE.md)
+[![npm bundle size](https://pkg-size.dev/badge/bundle/83411)](https://pkg-size.dev/@kingsworld/plugin-cron)
+[![npm](https://img.shields.io/npm/v/@kingsworld/plugin-cron?color=crimson&logo=npm&style=flat-square)](https://www.npmjs.com/package/@kingsworld/plugin-cron)
+
+</div>
+
+## Description
+
+This plugin adds support for cron tasks to the Sapphire framework. It uses the [cron](ttps://www.npmjs.com/package/@kingsworld/plugin-cron) package to create and manage cron tasks.
+
+## Features
+
+-   Full TypeScript support
+-   Includes ESM entrypoint
 
 ## Installation
 
+`@kingsworld/plugin-cron` depends on the following packages. Be sure to install these along with this package!
+
+-   [`@sapphire/framework`](https://www.npmjs.com/package/@sapphire/framework)
+
+You can use the following command to install this package along with `cron`, or replace `npm install` with your package manager of choice.
+
 ```sh
-yarn add @kingsworld/plugin-cron @sapphire/framework
+npm install @kingsworld/plugin-cron @sapphire/framework
 ```
 
 ## Usage
 
-Make sure to register the plugin before creating the client
+This registers the necessary options and methods in the Sapphire client to be able to use the cron plugin.
 
 ```ts
-import "@kingsworld/plugin-cron/register";
+// Main bot file
+// Be sure to register the plugin before instantiating the client.
+import '@kingsworld/plugin-cron/register';
 ```
 
-If you would like to set the default cron job timezone for all your cron jobs, you can do so within the client options. A list of TZ identifers can be found on [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+Then, you can configure the plugin in the configuration options in your SapphireClient extension class or initializer. This will either be located in your new SapphireClient constructor call, or super in your constructor method if you use an extension class.
 
 ```ts
-new SapphireClient({
-    ...otherClientOptions,
-    cron: {
-        // the cron object is optional
-        defaultTimezone: "Europe/London", // the cron package defaults to UTC
-    },
-});
+const options = {
+	...otherClientOptionsGoHere,
+	cron: {
+		/**
+		 * Whether to disable Sentry cron monitoring
+		 * @default false
+		 */
+		disableSentry: false,
+		/**
+		 * The timezone to use for the cron tasks
+		 * @default 'system'
+		 */
+		defaultTimezone: 'Europe/London'
+	}
+};
 ```
 
-However, if you would like to do so for a single task, you can do so in the cron task options
+-   The `disableSentry` option is used to disable Sentry's cron monitoring. By default, it is set to `false`, which means Sentry cron monitoring is enabled if the `@sentry/node` package is installed and configured. This makes using Sentry an opt-in feature - you first opt in by installing `@sentry/node`. The `disableSentry` option then allows you to opt out in specific situations. You can set this to `true` to disable cron monitoring, which can be useful during development or if you haven't provided a Sentry DSN. If you don't use Sentry at all (i.e., `@sentry/node` is not installed), this option has no effect and can be safely ignored.
 
-```js
-{
-    cronTime: "* * * * *", // every minute
-    timeZone: "Europe/London"
-}
-```
+In order to use the cron tasks anywhere other than a piece (commands, arguments, preconditions, etc.), you must first import the `container` property of `@sapphire/framework`. For pieces, you can simply use `this.container.cron` to access this plugin's methods.
 
-### Creating a task
+This is a simple example of how to start a task from a service.
 
-Cron Tasks come with their own store, just like Sapphire commands, listeners, and so on. They must be located within a `cron-tasks` directory that is located alongside your other stores.
+```typescript
+import { container } from '@sapphire/framework';
 
-```
-src
-├── listeners
-|   └── ready.ts
-└── cron-tasks
-    └── ping.ts
+export class MyAwesomeService {
+	public createAwesomeTask() {
+		const task = container.cron.store.get('my-awesome-task');
+
+		task.job.start();
+	}
+}
 ```
 
-Using decorators from [@sapphire/decorators](https://www.npmjs.com/package/@sapphire/decorators):
+This is a simple example of how to start all tasks from a service.
 
-```ts
-import { ApplyOptions } from "@sapphire/decorators";
-import { CronTask } from "@kingsworld/plugin-cron";
+```typescript
+import { container } from '@sapphire/framework';
 
-@ApplyOptions<CronTask.Options>({
-    cronTime: "* * * * *",
-})
-export class PingPong extends CronTask {
-    run() {
-        this.container.logger.info("Ping Pong! 🏓");
-    }
+export class MyAwesomeService {
+	public createAwesomeTask() {
+		container.cron.startAll();
+	}
 }
 ```
 
-Using the class constructor:
+It's important to note that the `startAll()` method is called automatically when the client is ready. Therefore, it's generally not necessary to call this method manually, unless you have a specific need to restart all cron tasks at some point after the client has been initialized.
 
-```ts
-import { CronTask } from "@kingsworld/plugin-cron";
+### Create a task handler
+
+Cron tasks use their own store, like other types of pieces. You can create a directory alongside your commands directory named `cron-tasks` and place your tasks there, but they must inherit from `CronTask`, like so.
+
+##### Creating the Piece:
+
+```typescript
+import { CronTask } from '@kingsworld/plugin-cron';
 
 export class PingPong extends CronTask {
-    constructor(context: CronTask.LoaderContext, options: CronTask.Options) {
-        super(context, {
-            ...options,
-            cronTime: "* * * * *",
-        });
-    }
-
-    run() {
-        this.container.logger.info("Ping Pong! 🏓");
-    }
+	public constructor(context: CronTask.LoaderContext, options: CronTask.Options) {
+		super(context, {
+			...options,
+			cronTime: '* * * * *'
+		});
+	}
+
+	public run() {
+		this.container.logger.info('Ping Pong! 🏓');
+	}
 }
 ```
 
-### Frequently Asked Questions
+### Logging Helpers
 
-##### What does the `this.info()`, `this.error()`, `this.warn()`, `this.debug()`, and `this.trace()` methods do in the CronTask class?
+The `CronTask` class provides logging helpers that are similar to the ones provided by the `Logger` class. These helpers are `info`, `error`, `warn`, `debug`, and `trace`. They all take a single string argument, which is the message to log.
 
-These methods are small helpers towards Sapphire's logger that prefixes logs with `CronTask[$name]`. The helpers are optional, however, I find them useful when using them in my own projects.
+This is an example of how to use the `info` helper:
+
+```typescript
+import { CronTask } from '@kingsworld/plugin-cron';
 
-```ts
 export class PingPong extends CronTask {
-    run() {
-        this.info("Ping Pong! 🏓"); // INFO - CronTask[ping] Ping Pong! 🏓
-        this.error("Ping Pong! 🏓"); // ERROR - CronTask[ping] Ping Pong! 🏓
-        this.warn("Ping Pong! 🏓"); // WARN - CronTask[ping] Ping Pong! 🏓
-        this.debug("Ping Pong! 🏓"); // DEBUG - CronTask[ping] Ping Pong! 🏓
-        this.trace("Ping Pong! 🏓"); // TRACE - CronTask[ping] Ping Pong! 🏓
-    }
+	public constructor(context: CronTask.LoaderContext, options: CronTask.Options) {
+		super(context, {
+			...options,
+			cronTime: '* * * * *'
+		});
+	}
+
+	public run() {
+		this.info('Ping Pong! 🏓'); // CronTask[ping] Ping Pong! 🏓
+	}
 }
 ```
 
-### Contributing
+## Contributors
 
-#### Getting started
+Please make sure to read the [Contributing Guide][contributing] before making a pull request.
 
-First, clone the repo using git SSH, the GitHub CLI, or HTTP
+Thank you to all the people who already contributed to Sapphire!
 
-```sh
-git clone git@github.com:Kings-World/sapphire-plugins.git # ssh
-git clone https://github.com/Kings-World/sapphire-plugins.git # http
-gh repo clone Kings-World/sapphire-plugins # github cli
-```
+<a href="https://github.com/Kings-World/sapphire-plugins/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Kings-World/sapphire-plugins" />
+</a>
 
-Finally, install the dependencies using Yarn
-
-```sh
-yarn # shorthand
-yarn install # full command
-```
+[contributing]: https://github.com/Kings-World/sapphire-plugins/blob/main/.github/CONTRIBUTING.md

package/dist/cjs/index.cjs

@@ -6,7 +6,7 @@ var CronTaskStore_cjs = require('./lib/structures/CronTaskStore.cjs');
 var CronTaskTypes_cjs = require('./lib/types/CronTaskTypes.cjs');
 
 // src/index.ts
-var version = "1.5.1";
+var version = "2.0.0-next.023f779";
 
 exports.version = version;
 Object.keys(CronTaskHandler_cjs).forEach(function (k) {

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;AA+BO,IAAM,OAAkB,GAAA","file":"index.cjs","sourcesContent":["import type { CronTaskStore } from \"./lib/structures/CronTaskStore\";\nimport type { CronTaskHandler } from \"./lib/CronTaskHandler\";\nimport type { CronTaskHandlerOptions } from \"./lib/types/CronTaskTypes\";\n\nexport * from \"./lib/CronTaskHandler\";\nexport * from \"./lib/structures/CronTask\";\nexport * from \"./lib/structures/CronTaskStore\";\nexport * from \"./lib/types/CronTaskTypes\";\n\ndeclare module \"@sapphire/pieces\" {\n    interface Container {\n        cron: CronTaskHandler;\n    }\n\n    interface StoreRegistryEntries {\n        \"cron-tasks\": CronTaskStore;\n    }\n}\n\ndeclare module \"discord.js\" {\n    export interface ClientOptions {\n        cron?: CronTaskHandlerOptions;\n    }\n}\n\n/**\n * The [@kingsworld/plugin-cron](https://github.com/Kings-World/sapphire-plugins/tree/main/packages/cron) version that you are currently using.\n * An example use of this is showing it of in a bot information command.\n *\n * Note to Sapphire developers: This needs to explicitly be `string` so it is not typed as the string that gets replaced by esbuild\n */\nexport const version: string = \"1.5.1\";\n"]}
+{"version":3,"sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;AA+BO,IAAM,OAAkB,GAAA","file":"index.cjs","sourcesContent":["import type { CronTaskStore } from './lib/structures/CronTaskStore';\nimport type { CronTaskHandler } from './lib/CronTaskHandler';\nimport type { CronTaskHandlerOptions } from './lib/types/CronTaskTypes';\n\nexport * from './lib/CronTaskHandler';\nexport * from './lib/structures/CronTask';\nexport * from './lib/structures/CronTaskStore';\nexport * from './lib/types/CronTaskTypes';\n\ndeclare module '@sapphire/pieces' {\n\tinterface Container {\n\t\tcron: CronTaskHandler;\n\t}\n\n\tinterface StoreRegistryEntries {\n\t\t'cron-tasks': CronTaskStore;\n\t}\n}\n\ndeclare module 'discord.js' {\n\texport interface ClientOptions {\n\t\tcron?: CronTaskHandlerOptions;\n\t}\n}\n\n/**\n * The [@kingsworld/plugin-cron](https://github.com/Kings-World/sapphire-plugins/tree/main/packages/cron) version that you are currently using.\n * An example use of this is showing it of in a bot information command.\n *\n * Note to Sapphire developers: This needs to explicitly be `string` so it is not typed as the string that gets replaced by esbuild\n */\nexport const version: string = '2.0.0-next.023f779';\n"]}

package/dist/cjs/index.d.cts

@@ -1,71 +1,167 @@
 import { Piece, Store } from '@sapphire/pieces';
-import { CronJobParams, CronJob } from 'cron';
 import { Awaitable } from '@sapphire/framework';
+import { CronJobParams, CronJob } from 'cron';
 import Sentry from '@sentry/node';
 
 interface CronTaskHandlerOptions {
     /**
      * The default timezone to use for all cron tasks.
      * You can override this per task, using the timeZone option.
-     * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-     * @default "UTC"
+     * @see https://github.com/moment/luxon/blob/master/docs/zones.md#specifying-a-zone
+     * @default 'system'
      */
-    defaultTimezone?: string;
+    defaultTimezone: string;
     /**
      * The ability to opt-out of instrumenting cron jobs with Sentry.
      * If you don't use Sentry, you can ignore this option.
      * @see https://docs.sentry.io/product/crons/
-     * @default undefined // technically false
+     * @default false
      */
-    disableSentry?: boolean;
+    disableSentry: boolean;
 }
-type CronJobOptions = Omit<CronJobParams<null, CronTask>, "onTick" | "onComplete" | "start" | "context" | "utcOffset">;
+type CronJobOptions = Omit<CronJobParams<null, CronTask>, 'onTick' | 'onComplete' | 'start' | 'context' | 'utcOffset'>;
 
-declare abstract class CronTask<Options extends CronTask.Options = CronTask.Options> extends Piece<Options, "cron-tasks"> {
+/**
+ * @example
+ *
+ * ```typescript
+ * // ping.ts
+ * import { CronTask } from '@kingsworld/plugin-cron';
+ *
+ * export class PingPong extends CronTask {
+ * 	public constructor(context: CronTask.LoaderContext, options: CronTask.Options) {
+ * 		super(context, {
+ * 			...options,
+ * 			cronTime: '* * * * *'
+ * 		});
+ * 	}
+ *
+ * 	public run() {
+ * 		this.info('Ping Pong! 🏓'); // CronTask[ping] Ping Pong! 🏓
+ * 	}
+ * }
+ * ```
+ */
+declare abstract class CronTask<Options extends CronTask.Options = CronTask.Options> extends Piece<Options, 'cron-tasks'> {
     job: CronJob<null, CronTask>;
     constructor(context: CronTask.LoaderContext, options: Options);
     abstract run(): Awaitable<unknown>;
+    /**
+     * A helper function to log messages with the `CronTask[${name}]` prefix.
+     * @param message The message to include after the prefix
+     * @param other Extra parameters to pass to the logger
+     * @example
+     * this.info('Hello world!'); // CronTask[my-task] Hello world!
+     */
     info(message: string, ...other: unknown[]): void;
+    /**
+     * A helper function to log messages with the `CronTask[${name}]` prefix.
+     * @param message The message to include after the prefix
+     * @param other Extra parameters to pass to the logger
+     * @example
+     * this.error('Something went wrong!'); // CronTask[my-task] Something went wrong!
+     */
     error(message: string, ...other: unknown[]): void;
+    /**
+     * A helper function to log messages with the `CronTask[${name}]` prefix.
+     * @param message The message to include after the prefix
+     * @param other Extra parameters to pass to the logger
+     * @example
+     * this.warn('Something is not right!'); // CronTask[my-task] Something is not right!
+     */
     warn(message: string, ...other: unknown[]): void;
+    /**
+     * A helper function to log messages with the `CronTask[${name}]` prefix.
+     * @param message The message to include after the prefix
+     * @param other Extra parameters to pass to the logger
+     * @example
+     * this.debug('Something is happening!'); // CronTask[my-task] Something is happening!
+     */
     debug(message: string, ...other: unknown[]): void;
+    /**
+     * A helper function to log messages with the `CronTask[${name}]` prefix.
+     * @param message The message to include after the prefix
+     * @param other Extra parameters to pass to the logger
+     * @example
+     * this.trace('Loaded the file.'); // CronTask[my-task] Loaded the file.
+     */
     trace(message: string, ...other: unknown[]): void;
 }
 declare namespace CronTask {
     type Options = Piece.Options & CronJobOptions;
     /** @deprecated Use {@linkcode LoaderContext} instead. */
     type Context = LoaderContext;
-    type LoaderContext = Piece.LoaderContext<"cron-tasks">;
+    type LoaderContext = Piece.LoaderContext<'cron-tasks'>;
 }
 
-declare class CronTaskStore extends Store<CronTask, "cron-tasks"> {
+declare class CronTaskStore extends Store<CronTask, 'cron-tasks'> {
     constructor();
+    /**
+     * Loops over all tasks and starts those that are enabled.
+     * This gets called automatically when the Client is ready.
+     * @returns CronTaskStore
+     */
     startAll(): this;
+    /**
+     * Loops over all tasks and stops those that are running.
+     * @returns CronTaskStore
+     */
     stopAll(): this;
     set(key: string, value: CronTask): this;
     delete(key: string): boolean;
+    /**
+     * Stops all running cron jobs and clears the store.
+     * @returns void
+     */
     clear(): void;
 }
 
 declare class CronTaskHandler {
-    defaultTimezone?: CronTaskHandlerOptions["defaultTimezone"];
-    disableSentry?: boolean;
+    /**
+     * The default timezone to use for all cron tasks.
+     * You can override this per task, using the timeZone option.
+     * @see https://github.com/moment/luxon/blob/master/docs/zones.md#specifying-a-zone
+     * @default 'system'
+     */
+    defaultTimezone: CronTaskHandlerOptions['defaultTimezone'];
+    /**
+     * The ability to opt-out of instrumenting cron jobs with Sentry.
+     * If you don't use Sentry, you can ignore this option.
+     * @see https://docs.sentry.io/product/crons/
+     * @default false
+     */
+    disableSentry: boolean;
+    /**
+     * The Sentry instance to use for instrumenting cron jobs.
+     * This is only available when [`@sentry/node`](https://www.npmjs.com/package/@sentry/node)
+     * is installed and the {@linkcode disableSentry} option is set to false.
+     */
     sentry?: typeof Sentry;
     constructor(options?: CronTaskHandlerOptions);
+    /**
+     * Start all enabled cron jobs.
+     * This gets called automatically when the Client is ready.
+     */
     startAll(): void;
+    /**
+     * Stop all running cron jobs.
+     */
     stopAll(): void;
+    /**
+     * Get the cron task store.
+     */
     private get store();
 }
 
-declare module "@sapphire/pieces" {
+declare module '@sapphire/pieces' {
     interface Container {
         cron: CronTaskHandler;
     }
     interface StoreRegistryEntries {
-        "cron-tasks": CronTaskStore;
+        'cron-tasks': CronTaskStore;
     }
 }
-declare module "discord.js" {
+declare module 'discord.js' {
     interface ClientOptions {
         cron?: CronTaskHandlerOptions;
     }

package/dist/cjs/lib/CronTaskHandler.cjs

@@ -8,18 +8,45 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 var _CronTaskHandler = class _CronTaskHandler {
   constructor(options) {
+    /**
+     * The default timezone to use for all cron tasks.
+     * You can override this per task, using the timeZone option.
+     * @see https://github.com/moment/luxon/blob/master/docs/zones.md#specifying-a-zone
+     * @default 'system'
+     */
     __publicField(this, "defaultTimezone");
+    /**
+     * The ability to opt-out of instrumenting cron jobs with Sentry.
+     * If you don't use Sentry, you can ignore this option.
+     * @see https://docs.sentry.io/product/crons/
+     * @default false
+     */
     __publicField(this, "disableSentry");
+    /**
+     * The Sentry instance to use for instrumenting cron jobs.
+     * This is only available when [`@sentry/node`](https://www.npmjs.com/package/@sentry/node)
+     * is installed and the {@linkcode disableSentry} option is set to false.
+     */
     __publicField(this, "sentry");
-    this.defaultTimezone = options?.defaultTimezone;
-    this.disableSentry = options?.disableSentry;
+    this.defaultTimezone = options?.defaultTimezone ?? "system";
+    this.disableSentry = options?.disableSentry ?? false;
   }
+  /**
+   * Start all enabled cron jobs.
+   * This gets called automatically when the Client is ready.
+   */
   startAll() {
     this.store.startAll();
   }
+  /**
+   * Stop all running cron jobs.
+   */
   stopAll() {
     this.store.stopAll();
   }
+  /**
+   * Get the cron task store.
+   */
   get store() {
     return framework.container.stores.get("cron-tasks");
   }

package/dist/cjs/lib/CronTaskHandler.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/CronTaskHandler.ts"],"names":["container"],"mappings":";;;;;;;;AAIO,IAAM,gBAAA,GAAN,MAAM,gBAAgB,CAAA;AAAA,EAKzB,YAAY,OAAkC,EAAA;AAJ9C,IAAA,aAAA,CAAA,IAAA,EAAA,iBAAA,CAAA,CAAA;AACA,IAAA,aAAA,CAAA,IAAA,EAAA,eAAA,CAAA,CAAA;AACA,IAAA,aAAA,CAAA,IAAA,EAAA,QAAA,CAAA,CAAA;AAGI,IAAA,IAAA,CAAK,kBAAkB,OAAS,EAAA,eAAA,CAAA;AAChC,IAAA,IAAA,CAAK,gBAAgB,OAAS,EAAA,aAAA,CAAA;AAAA,GAClC;AAAA,EAEA,QAAW,GAAA;AACP,IAAA,IAAA,CAAK,MAAM,QAAS,EAAA,CAAA;AAAA,GACxB;AAAA,EAEA,OAAU,GAAA;AACN,IAAA,IAAA,CAAK,MAAM,OAAQ,EAAA,CAAA;AAAA,GACvB;AAAA,EAEA,IAAY,KAAQ,GAAA;AAChB,IAAO,OAAAA,mBAAA,CAAU,MAAO,CAAA,GAAA,CAAI,YAAY,CAAA,CAAA;AAAA,GAC5C;AACJ,CAAA,CAAA;AArB6B,MAAA,CAAA,gBAAA,EAAA,iBAAA,CAAA,CAAA;AAAtB,IAAM,eAAN,GAAA","file":"CronTaskHandler.cjs","sourcesContent":["import { container } from \"@sapphire/framework\";\nimport type { CronTaskHandlerOptions } from \"./types/CronTaskTypes\";\nimport type Sentry from \"@sentry/node\";\n\nexport class CronTaskHandler {\n    defaultTimezone?: CronTaskHandlerOptions[\"defaultTimezone\"];\n    disableSentry?: boolean;\n    sentry?: typeof Sentry;\n\n    constructor(options?: CronTaskHandlerOptions) {\n        this.defaultTimezone = options?.defaultTimezone;\n        this.disableSentry = options?.disableSentry;\n    }\n\n    startAll() {\n        this.store.startAll();\n    }\n\n    stopAll() {\n        this.store.stopAll();\n    }\n\n    private get store() {\n        return container.stores.get(\"cron-tasks\");\n    }\n}\n"]}
+{"version":3,"sources":["../../../src/lib/CronTaskHandler.ts"],"names":["container"],"mappings":";;;;;;;;AAIO,IAAM,gBAAA,GAAN,MAAM,gBAAgB,CAAA;AAAA,EAwBrB,YAAY,OAAkC,EAAA;AAjBrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAO,aAAA,CAAA,IAAA,EAAA,iBAAA,CAAA,CAAA;AAQP;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAO,aAAA,CAAA,IAAA,EAAA,eAAA,CAAA,CAAA;AAOP;AAAA;AAAA;AAAA;AAAA;AAAA,IAAO,aAAA,CAAA,IAAA,EAAA,QAAA,CAAA,CAAA;AAGN,IAAK,IAAA,CAAA,eAAA,GAAkB,SAAS,eAAmB,IAAA,QAAA,CAAA;AACnD,IAAK,IAAA,CAAA,aAAA,GAAgB,SAAS,aAAiB,IAAA,KAAA,CAAA;AAAA,GAChD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,QAAW,GAAA;AACjB,IAAA,IAAA,CAAK,MAAM,QAAS,EAAA,CAAA;AAAA,GACrB;AAAA;AAAA;AAAA;AAAA,EAKO,OAAU,GAAA;AAChB,IAAA,IAAA,CAAK,MAAM,OAAQ,EAAA,CAAA;AAAA,GACpB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAY,KAAQ,GAAA;AACnB,IAAO,OAAAA,mBAAA,CAAU,MAAO,CAAA,GAAA,CAAI,YAAY,CAAA,CAAA;AAAA,GACzC;AACD,CAAA,CAAA;AAlD6B,MAAA,CAAA,gBAAA,EAAA,iBAAA,CAAA,CAAA;AAAtB,IAAM,eAAN,GAAA","file":"CronTaskHandler.cjs","sourcesContent":["import { container } from '@sapphire/framework';\nimport type Sentry from '@sentry/node';\nimport type { CronTaskHandlerOptions } from './types/CronTaskTypes';\n\nexport class CronTaskHandler {\n\t/**\n\t * The default timezone to use for all cron tasks.\n\t * You can override this per task, using the timeZone option.\n\t * @see https://github.com/moment/luxon/blob/master/docs/zones.md#specifying-a-zone\n\t * @default 'system'\n\t */\n\tpublic defaultTimezone: CronTaskHandlerOptions['defaultTimezone'];\n\n\t/**\n\t * The ability to opt-out of instrumenting cron jobs with Sentry.\n\t * If you don't use Sentry, you can ignore this option.\n\t * @see https://docs.sentry.io/product/crons/\n\t * @default false\n\t */\n\tpublic disableSentry: boolean;\n\n\t/**\n\t * The Sentry instance to use for instrumenting cron jobs.\n\t * This is only available when [`@sentry/node`](https://www.npmjs.com/package/@sentry/node)\n\t * is installed and the {@linkcode disableSentry} option is set to false.\n\t */\n\tpublic sentry?: typeof Sentry;\n\n\tpublic constructor(options?: CronTaskHandlerOptions) {\n\t\tthis.defaultTimezone = options?.defaultTimezone ?? 'system';\n\t\tthis.disableSentry = options?.disableSentry ?? false;\n\t}\n\n\t/**\n\t * Start all enabled cron jobs.\n\t * This gets called automatically when the Client is ready.\n\t */\n\tpublic startAll() {\n\t\tthis.store.startAll();\n\t}\n\n\t/**\n\t * Stop all running cron jobs.\n\t */\n\tpublic stopAll() {\n\t\tthis.store.stopAll();\n\t}\n\n\t/**\n\t * Get the cron task store.\n\t */\n\tprivate get store() {\n\t\treturn container.stores.get('cron-tasks');\n\t}\n}\n"]}

package/dist/cjs/lib/structures/CronTask.cjs

@@ -8,35 +8,55 @@ var _CronTask = class _CronTask extends pieces.Piece {
   constructor(context, options) {
     super(context, options);
   }
+  /**
+   * A helper function to log messages with the `CronTask[${name}]` prefix.
+   * @param message The message to include after the prefix
+   * @param other Extra parameters to pass to the logger
+   * @example
+   * this.info('Hello world!'); // CronTask[my-task] Hello world!
+   */
   info(message, ...other) {
-    this.container.logger.info(
-      `CronTask[${this.name}] ${message}`,
-      ...other
-    );
+    this.container.logger.info(`CronTask[${this.name}] ${message}`, ...other);
   }
+  /**
+   * A helper function to log messages with the `CronTask[${name}]` prefix.
+   * @param message The message to include after the prefix
+   * @param other Extra parameters to pass to the logger
+   * @example
+   * this.error('Something went wrong!'); // CronTask[my-task] Something went wrong!
+   */
   error(message, ...other) {
-    this.container.logger.error(
-      `CronTask[${this.name}] ${message}`,
-      ...other
-    );
+    this.container.logger.error(`CronTask[${this.name}] ${message}`, ...other);
   }
+  /**
+   * A helper function to log messages with the `CronTask[${name}]` prefix.
+   * @param message The message to include after the prefix
+   * @param other Extra parameters to pass to the logger
+   * @example
+   * this.warn('Something is not right!'); // CronTask[my-task] Something is not right!
+   */
   warn(message, ...other) {
-    this.container.logger.warn(
-      `CronTask[${this.name}] ${message}`,
-      ...other
-    );
+    this.container.logger.warn(`CronTask[${this.name}] ${message}`, ...other);
   }
+  /**
+   * A helper function to log messages with the `CronTask[${name}]` prefix.
+   * @param message The message to include after the prefix
+   * @param other Extra parameters to pass to the logger
+   * @example
+   * this.debug('Something is happening!'); // CronTask[my-task] Something is happening!
+   */
   debug(message, ...other) {
-    this.container.logger.debug(
-      `CronTask[${this.name}] ${message}`,
-      ...other
-    );
+    this.container.logger.debug(`CronTask[${this.name}] ${message}`, ...other);
   }
+  /**
+   * A helper function to log messages with the `CronTask[${name}]` prefix.
+   * @param message The message to include after the prefix
+   * @param other Extra parameters to pass to the logger
+   * @example
+   * this.trace('Loaded the file.'); // CronTask[my-task] Loaded the file.
+   */
   trace(message, ...other) {
-    this.container.logger.trace(
-      `CronTask[${this.name}] ${message}`,
-      ...other
-    );
+    this.container.logger.trace(`CronTask[${this.name}] ${message}`, ...other);
   }
 };
 __name(_CronTask, "CronTask");

package/dist/cjs/lib/structures/CronTask.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/lib/structures/CronTask.ts"],"names":["Piece"],"mappings":";;;;;;AAKO,IAAe,SAAA,GAAf,MAAe,SAAA,SAEZA,YAA6B,CAAA;AAAA,EAGnC,WAAA,CAAY,SAAiC,OAAkB,EAAA;AAC3D,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA,CAAA;AAAA,GAC1B;AAAA,EAIA,IAAA,CAAK,YAAoB,KAAkB,EAAA;AACvC,IAAA,IAAA,CAAK,UAAU,MAAO,CAAA,IAAA;AAAA,MAClB,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA;AAAA,MACjC,GAAG,KAAA;AAAA,KACP,CAAA;AAAA,GACJ;AAAA,EAEA,KAAA,CAAM,YAAoB,KAAkB,EAAA;AACxC,IAAA,IAAA,CAAK,UAAU,MAAO,CAAA,KAAA;AAAA,MAClB,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA;AAAA,MACjC,GAAG,KAAA;AAAA,KACP,CAAA;AAAA,GACJ;AAAA,EAEA,IAAA,CAAK,YAAoB,KAAkB,EAAA;AACvC,IAAA,IAAA,CAAK,UAAU,MAAO,CAAA,IAAA;AAAA,MAClB,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA;AAAA,MACjC,GAAG,KAAA;AAAA,KACP,CAAA;AAAA,GACJ;AAAA,EAEA,KAAA,CAAM,YAAoB,KAAkB,EAAA;AACxC,IAAA,IAAA,CAAK,UAAU,MAAO,CAAA,KAAA;AAAA,MAClB,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA;AAAA,MACjC,GAAG,KAAA;AAAA,KACP,CAAA;AAAA,GACJ;AAAA,EAEA,KAAA,CAAM,YAAoB,KAAkB,EAAA;AACxC,IAAA,IAAA,CAAK,UAAU,MAAO,CAAA,KAAA;AAAA,MAClB,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA;AAAA,MACjC,GAAG,KAAA;AAAA,KACP,CAAA;AAAA,GACJ;AACJ,CAAA,CAAA;AA3CuC,MAAA,CAAA,SAAA,EAAA,UAAA,CAAA,CAAA;AAFhC,IAAe,QAAf,GAAA","file":"CronTask.cjs","sourcesContent":["import { Piece } from \"@sapphire/pieces\";\nimport type { CronJob } from \"cron\";\nimport type { CronJobOptions } from \"../types/CronTaskTypes\";\nimport type { Awaitable } from \"@sapphire/framework\";\n\nexport abstract class CronTask<\n    Options extends CronTask.Options = CronTask.Options,\n> extends Piece<Options, \"cron-tasks\"> {\n    declare job: CronJob<null, CronTask>;\n\n    constructor(context: CronTask.LoaderContext, options: Options) {\n        super(context, options);\n    }\n\n    abstract run(): Awaitable<unknown>;\n\n    info(message: string, ...other: unknown[]) {\n        this.container.logger.info(\n            `CronTask[${this.name}] ${message}`,\n            ...other,\n        );\n    }\n\n    error(message: string, ...other: unknown[]) {\n        this.container.logger.error(\n            `CronTask[${this.name}] ${message}`,\n            ...other,\n        );\n    }\n\n    warn(message: string, ...other: unknown[]) {\n        this.container.logger.warn(\n            `CronTask[${this.name}] ${message}`,\n            ...other,\n        );\n    }\n\n    debug(message: string, ...other: unknown[]) {\n        this.container.logger.debug(\n            `CronTask[${this.name}] ${message}`,\n            ...other,\n        );\n    }\n\n    trace(message: string, ...other: unknown[]) {\n        this.container.logger.trace(\n            `CronTask[${this.name}] ${message}`,\n            ...other,\n        );\n    }\n}\n\nexport namespace CronTask {\n    export type Options = Piece.Options & CronJobOptions;\n    /** @deprecated Use {@linkcode LoaderContext} instead. */\n    export type Context = LoaderContext;\n    export type LoaderContext = Piece.LoaderContext<\"cron-tasks\">;\n}\n"]}
+{"version":3,"sources":["../../../../src/lib/structures/CronTask.ts"],"names":["Piece"],"mappings":";;;;;;AA0BO,IAAe,SAAA,GAAf,MAAe,SAAA,SAAsEA,YAA6B,CAAA;AAAA,EAGjH,WAAA,CAAY,SAAiC,OAAkB,EAAA;AACrE,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA,CAAA;AAAA,GACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWO,IAAA,CAAK,YAAoB,KAAkB,EAAA;AACjD,IAAK,IAAA,CAAA,SAAA,CAAU,MAAO,CAAA,IAAA,CAAK,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAK,EAAA,EAAA,OAAO,CAAI,CAAA,EAAA,GAAG,KAAK,CAAA,CAAA;AAAA,GACzE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASO,KAAA,CAAM,YAAoB,KAAkB,EAAA;AAClD,IAAK,IAAA,CAAA,SAAA,CAAU,MAAO,CAAA,KAAA,CAAM,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAK,EAAA,EAAA,OAAO,CAAI,CAAA,EAAA,GAAG,KAAK,CAAA,CAAA;AAAA,GAC1E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASO,IAAA,CAAK,YAAoB,KAAkB,EAAA;AACjD,IAAK,IAAA,CAAA,SAAA,CAAU,MAAO,CAAA,IAAA,CAAK,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAK,EAAA,EAAA,OAAO,CAAI,CAAA,EAAA,GAAG,KAAK,CAAA,CAAA;AAAA,GACzE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASO,KAAA,CAAM,YAAoB,KAAkB,EAAA;AAClD,IAAK,IAAA,CAAA,SAAA,CAAU,MAAO,CAAA,KAAA,CAAM,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAK,EAAA,EAAA,OAAO,CAAI,CAAA,EAAA,GAAG,KAAK,CAAA,CAAA;AAAA,GAC1E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASO,KAAA,CAAM,YAAoB,KAAkB,EAAA;AAClD,IAAK,IAAA,CAAA,SAAA,CAAU,MAAO,CAAA,KAAA,CAAM,CAAY,SAAA,EAAA,IAAA,CAAK,IAAI,CAAK,EAAA,EAAA,OAAO,CAAI,CAAA,EAAA,GAAG,KAAK,CAAA,CAAA;AAAA,GAC1E;AACD,CAAA,CAAA;AA/DyH,MAAA,CAAA,SAAA,EAAA,UAAA,CAAA,CAAA;AAAlH,IAAe,QAAf,GAAA","file":"CronTask.cjs","sourcesContent":["import type { Awaitable } from '@sapphire/framework';\nimport { Piece } from '@sapphire/pieces';\nimport type { CronJob } from 'cron';\nimport type { CronJobOptions } from '../types/CronTaskTypes';\n\n/**\n * @example\n *\n * ```typescript\n * // ping.ts\n * import { CronTask } from '@kingsworld/plugin-cron';\n *\n * export class PingPong extends CronTask {\n * \tpublic constructor(context: CronTask.LoaderContext, options: CronTask.Options) {\n * \t\tsuper(context, {\n * \t\t\t...options,\n * \t\t\tcronTime: '* * * * *'\n * \t\t});\n * \t}\n *\n * \tpublic run() {\n * \t\tthis.info('Ping Pong! 🏓'); // CronTask[ping] Ping Pong! 🏓\n * \t}\n * }\n * ```\n */\nexport abstract class CronTask<Options extends CronTask.Options = CronTask.Options> extends Piece<Options, 'cron-tasks'> {\n\tpublic declare job: CronJob<null, CronTask>;\n\n\tpublic constructor(context: CronTask.LoaderContext, options: Options) {\n\t\tsuper(context, options);\n\t}\n\n\tpublic abstract run(): Awaitable<unknown>;\n\n\t/**\n\t * A helper function to log messages with the `CronTask[${name}]` prefix.\n\t * @param message The message to include after the prefix\n\t * @param other Extra parameters to pass to the logger\n\t * @example\n\t * this.info('Hello world!'); // CronTask[my-task] Hello world!\n\t */\n\tpublic info(message: string, ...other: unknown[]) {\n\t\tthis.container.logger.info(`CronTask[${this.name}] ${message}`, ...other);\n\t}\n\n\t/**\n\t * A helper function to log messages with the `CronTask[${name}]` prefix.\n\t * @param message The message to include after the prefix\n\t * @param other Extra parameters to pass to the logger\n\t * @example\n\t * this.error('Something went wrong!'); // CronTask[my-task] Something went wrong!\n\t */\n\tpublic error(message: string, ...other: unknown[]) {\n\t\tthis.container.logger.error(`CronTask[${this.name}] ${message}`, ...other);\n\t}\n\n\t/**\n\t * A helper function to log messages with the `CronTask[${name}]` prefix.\n\t * @param message The message to include after the prefix\n\t * @param other Extra parameters to pass to the logger\n\t * @example\n\t * this.warn('Something is not right!'); // CronTask[my-task] Something is not right!\n\t */\n\tpublic warn(message: string, ...other: unknown[]) {\n\t\tthis.container.logger.warn(`CronTask[${this.name}] ${message}`, ...other);\n\t}\n\n\t/**\n\t * A helper function to log messages with the `CronTask[${name}]` prefix.\n\t * @param message The message to include after the prefix\n\t * @param other Extra parameters to pass to the logger\n\t * @example\n\t * this.debug('Something is happening!'); // CronTask[my-task] Something is happening!\n\t */\n\tpublic debug(message: string, ...other: unknown[]) {\n\t\tthis.container.logger.debug(`CronTask[${this.name}] ${message}`, ...other);\n\t}\n\n\t/**\n\t * A helper function to log messages with the `CronTask[${name}]` prefix.\n\t * @param message The message to include after the prefix\n\t * @param other Extra parameters to pass to the logger\n\t * @example\n\t * this.trace('Loaded the file.'); // CronTask[my-task] Loaded the file.\n\t */\n\tpublic trace(message: string, ...other: unknown[]) {\n\t\tthis.container.logger.trace(`CronTask[${this.name}] ${message}`, ...other);\n\t}\n}\n\nexport namespace CronTask {\n\texport type Options = Piece.Options & CronJobOptions;\n\t/** @deprecated Use {@linkcode LoaderContext} instead. */\n\texport type Context = LoaderContext;\n\texport type LoaderContext = Piece.LoaderContext<'cron-tasks'>;\n}\n"]}