@athenna/cron 4.0.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2022 The Athenna Framework
+
+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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+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,42 @@
+# Cron ⏱️
+
+> Athenna scheduler application. Built on top of node-cron.
+
+[![GitHub followers](https://img.shields.io/github/followers/athennaio.svg?style=social&label=Follow&maxAge=2592000)](https://github.com/athennaio?tab=followers)
+[![GitHub stars](https://img.shields.io/github/stars/AthennaIO/Cron.svg?style=social&label=Star&maxAge=2592000)](https://github.com/AthennaIO/Cron/stargazers/)
+
+<p>
+    <a href="https://www.buymeacoffee.com/athenna" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>
+</p>
+
+<p>
+  <img alt="GitHub language count" src="https://img.shields.io/github/languages/count/AthennaIO/Cron?style=for-the-badge&logo=appveyor">
+
+  <img alt="Repository size" src="https://img.shields.io/github/repo-size/AthennaIO/Cron?style=for-the-badge&logo=appveyor">
+
+  <img alt="License" src="https://img.shields.io/badge/license-MIT-brightgreen?style=for-the-badge&logo=appveyor">
+
+  <img alt="Commitizen" src="https://img.shields.io/badge/commitizen-friendly-brightgreen?style=for-the-badge&logo=appveyor">
+</p>
+
+<img src=".github/logo.svg" width="200px" align="right" hspace="30px" vspace="100px">
+
+## Links
+
+> For project documentation [click here](https://athenna.io). If something is not clear in the documentation please open an issue in the [documentation repository](https://github.com/athennaio/docs)
+
+## Contributing
+
+> If you want to contribute to this project, first read the [CONTRIBUTING.MD](https://github.com/AthennaIO/Cron/blob/develop/CONTRIBUTING.md) file. It will be a pleasure to receive your help.
+
+---
+
+<p align='center'>
+  With 💜 by <a href='https://github.com/AthennaIO'>Athenna community</a>
+</p>
+
+<p align='center'>
+  <a href='https://github.com/AthennaIO/Cron/graphs/contributors'>
+    <img src='https://contrib.rocks/image?repo=AthennaIO/Cron'/>
+  </a>
+</p>

package/package.json

@@ -0,0 +1,187 @@
+{
+  "name": "@athenna/cron",
+  "version": "4.0.0",
+  "description": "Athenna scheduler application. Built on top of node-cron.",
+  "license": "MIT",
+  "author": "João Lenon <lenon@athenna.io>",
+  "bugs": "https://github.com/AthennaIO/Cron/issues",
+  "repository": "https://github.com/AthennaIO/Cron.git",
+  "homepage": "https://github.com/AthennaIO/Cron#readme",
+  "keywords": [
+    "esm",
+    "athenna"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "node node_modules/@athenna/tsconfig/src/build.js",
+    "lint:fix": "eslint \"{bin,src,configurer,tests}/**/*.ts\" --fix",
+    "test": "npm run --silent lint:fix && node --enable-source-maps --import=@athenna/tsconfig bin/test.ts",
+    "test:debug": "cross-env NODE_DEBUG=athenna:* node --inspect --enable-source-maps --import=@athenna/tsconfig bin/test.ts",
+    "test:coverage": "c8 npm run --silent test"
+  },
+  "files": [
+    "src/*.js",
+    "src/*.d.ts",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "templates",
+    "configurer"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./types": "./src/types/index.js",
+    "./package": "./package.json",
+    "./package.json": "./package.json",
+    "./testing/plugins": "./src/testing/plugins/index.js",
+    "./kernels/CronKernel": "./src/kernels/CronKernel.js",
+    "./handlers/CronExceptionHandler": "./src/handlers/CronExceptionHandler.js",
+    "./providers/CronProvider": "./src/providers/CronProvider.js",
+    "./commands/MakeSchedulerCommand": "./src/commands/MakeSchedulerCommand.js"
+  },
+  "imports": {
+    "#bin/*": "./bin/*.js",
+    "#bin": "./bin/index.js",
+    "#src/*": "./src/*.js",
+    "#src": "./src/index.js",
+    "#src/types": "./src/types/index.js",
+    "#src/debug": "./src/debug/index.js",
+    "#tests/*": "./tests/*.js",
+    "#tests": "./tests/index.js"
+  },
+  "dependencies": {
+    "node-cron": "^3.0.3"
+  },
+  "devDependencies": {
+    "@athenna/artisan": "^4.45.0",
+    "@athenna/common": "^4.46.0",
+    "@athenna/config": "^4.27.0",
+    "@athenna/ioc": "^4.27.0",
+    "@athenna/logger": "^4.29.0",
+    "@athenna/test": "^4.30.0",
+    "@athenna/tsconfig": "^4.19.0",
+    "@athenna/view": "^4.33.0",
+    "@types/node-cron": "^3.0.11",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "cls-rtracer": "^2.6.3",
+    "commitizen": "^4.3.0",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^8.10.0",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-n": "^15.7.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "eslint-plugin-promise": "^6.6.0",
+    "husky": "^3.1.0",
+    "lint-staged": "^12.5.0",
+    "prettier": "^2.8.8"
+  },
+  "c8": {
+    "all": true,
+    "include": [
+      "src/**/*.ts"
+    ],
+    "exclude": [
+      "src/types"
+    ],
+    "reporter": [
+      "text-summary",
+      "html"
+    ],
+    "report-dir": "./tests/coverage",
+    "check-coverage": true
+  },
+  "husky": {
+    "hooks": {
+      "prepare-commit-msg": "lint-staged && exec < /dev/tty && git cz --hook || true"
+    }
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "git add"
+    ],
+    "*.json": [
+      "prettier --write",
+      "git add"
+    ]
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "prettier": {
+    "singleQuote": true,
+    "trailingComma": "none",
+    "arrowParens": "avoid",
+    "endOfLine": "lf",
+    "semi": false,
+    "printWidth": 80,
+    "overrides": [
+      {
+        "files": "tests/**/*",
+        "options": {
+          "printWidth": 120
+        }
+      }
+    ]
+  },
+  "eslintIgnore": [],
+  "eslintConfig": {
+    "env": {
+      "es2021": true,
+      "node": true
+    },
+    "globals": {
+      "ioc": true,
+      "Env": true,
+      "Path": true,
+      "Config": true,
+      "container": true
+    },
+    "plugins": [
+      "prettier",
+      "@typescript-eslint"
+    ],
+    "extends": [
+      "standard",
+      "eslint:recommended",
+      "plugin:prettier/recommended",
+      "plugin:@typescript-eslint/recommended",
+      "plugin:@typescript-eslint/eslint-recommended"
+    ],
+    "parser": "@typescript-eslint/parser",
+    "rules": {
+      "camelcase": "off",
+      "dot-notation": "off",
+      "prettier/prettier": "error",
+      "no-useless-constructor": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-empty-function": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          "argsIgnorePattern": "^_",
+          "varsIgnorePattern": "^_",
+          "caughtErrorsIgnorePattern": "^_"
+        }
+      ]
+    }
+  },
+  "athenna": {
+    "templates": {
+      "scheduler": "./templates/scheduler.edge"
+    },
+    "schedulers": [
+      "#tests/fixtures/schedulers/AnnotatedScheduler",
+      "#tests/fixtures/schedulers/HelloScheduler"
+    ]
+  }
+}

package/src/annotations/Scheduler.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @athenna/cron
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import 'reflect-metadata';
+import type { SchedulerOptions } from '#src/types/schedulers/SchedulerOptions';
+/**
+ * Create a scheduler inside the service provider.
+ */
+export declare function Scheduler(options: SchedulerOptions): ClassDecorator;

package/src/annotations/Scheduler.js

@@ -0,0 +1,38 @@
+/**
+ * @athenna/cron
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import 'reflect-metadata';
+import { debug } from '#src/debug';
+import { Options } from '@athenna/common';
+import { Annotation } from '@athenna/ioc';
+/**
+ * Create a scheduler inside the service provider.
+ */
+export function Scheduler(options) {
+    return (target) => {
+        options = Options.create(options, {
+            name: target.name,
+            scheduled: true,
+            runOnInit: false,
+            recoverMissedExecutions: false,
+            alias: `App/Cron/Schedulers/${target.name}`,
+            type: 'transient'
+        });
+        debug('Registering scheduler metadata for the service container %o', {
+            name: target.name,
+            ...options
+        });
+        if (ioc.has(options.alias) ||
+            ioc.has(options.camelAlias) ||
+            ioc.has(options.name)) {
+            debug('Skipping registration, scheduler is already registered.');
+            return;
+        }
+        Annotation.defineMeta(target, options);
+    };
+}

package/src/commands/MakeSchedulerCommand.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @athenna/cron
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { BaseCommand } from '@athenna/artisan';
+export declare class MakeSchedulerCommand extends BaseCommand {
+    name: string;
+    static signature(): string;
+    static description(): string;
+    handle(): Promise<void>;
+}

package/src/commands/MakeSchedulerCommand.js

@@ -0,0 +1,47 @@
+/**
+ * @athenna/cron
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Path } from '@athenna/common';
+import { BaseCommand, Argument } from '@athenna/artisan';
+export class MakeSchedulerCommand extends BaseCommand {
+    static signature() {
+        return 'make:scheduler';
+    }
+    static description() {
+        return 'Make a new scheduler file.';
+    }
+    async handle() {
+        this.logger.simple('({bold,green} [ MAKING SCHEDULER ])\n');
+        const destination = Config.get('rc.commands.make:scheduler.destination', Path.schedulers());
+        const file = await this.generator
+            .fileName(this.name)
+            .destination(destination)
+            .template('scheduler')
+            .setNameProperties(true)
+            .make();
+        this.logger.success(`Scheduler ({yellow} "${file.name}") successfully created.`);
+        const importPath = this.generator.getImportPath();
+        await this.rc.pushTo('schedulers', importPath).save();
+        this.logger.success(`Athenna RC updated: ({dim,yellow} [ schedulers += "${importPath}" ])`);
+    }
+}
+__decorate([
+    Argument({
+        description: 'The scheduler name.'
+    }),
+    __metadata("design:type", String)
+], MakeSchedulerCommand.prototype, "name", void 0);

package/src/cron/CronBuilder.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @athenna/cron
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import type { CronHandler } from '#src/types';
+import type { CronExceptionHandler } from '#src/handlers/CronExceptionHandler';
+export declare class CronBuilder {
+    static rTracerPlugin: any;
+    static exceptionHandler: CronExceptionHandler;
+    /**
+     * Register the cls-rtracer plugin into cron handlers.
+     */
+    static registerRTracer(plugin: any): void;
+    private cron;
+    /**
+     * Defines the CRON expression that will determine when
+     * the task will run.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule()
+     *    .pattern('* * * * *')
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    pattern(pattern: string): this;
+    /**
+     * Register a scheduler handler for a dependency that exists
+     * inside "rc.schedulers".
+     *
+     * @example
+     * ```ts
+     * const task = Cron.schedule()
+     *    .pattern('* * * * *')
+     *    .scheduler('MyCustomSchedulerClass')
+     *
+     * task.stop()
+     * ```
+     */
+    scheduler(name: string): import("node-cron").ScheduledTask;
+    /**
+     * Defines what operation the scheduler will run and
+     * register your scheduler with all options defined.
+     * This method also return an instance of your scheduler,
+     * you can use this instance to stop your scheduler.
+     *
+     * @example
+     * ```ts
+     * const task = Cron.schedule()
+     *    .pattern('* * * * *')
+     *    .handler(() => console.log('hey'))
+     *
+     * task.stop()
+     * ```
+     */
+    handler(handler: CronHandler): import("node-cron").ScheduledTask;
+    /**
+     * Defines if the task needs to be scheduled to run
+     * after registering it.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .scheduled(true)
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    scheduled(scheduled: boolean): this;
+    /**
+     * Defines a name to your scheduler.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .name('myScheduler')
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    name(name: string): this;
+    /**
+     * Defines the timezone that is used for the job
+     * scheduling.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .timezone('America/Sao_Paulo')
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    timezone(timezone: string): this;
+    /**
+     * Runs the task immediately after registering, no matter
+     * the CRON pattern defined.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .runOnInit(true)
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    runOnInit(runOnInit: boolean): this;
+    /**
+     * Specifies whether to recover missed executions instead
+     * of skipping them.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .recoverMissingExecutions(true)
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    recoverMissedExecutions(recoverMissedExecutions?: boolean): this;
+}

package/src/cron/CronBuilder.js

@@ -0,0 +1,185 @@
+/**
+ * @athenna/cron
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { schedule } from 'node-cron';
+import { Options } from '@athenna/common';
+export class CronBuilder {
+    constructor() {
+        this.cron = {};
+    }
+    /**
+     * Register the cls-rtracer plugin into cron handlers.
+     */
+    static registerRTracer(plugin) {
+        this.rTracerPlugin = plugin;
+    }
+    /**
+     * Defines the CRON expression that will determine when
+     * the task will run.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule()
+     *    .pattern('* * * * *')
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    pattern(pattern) {
+        this.cron.pattern = pattern;
+        return this;
+    }
+    /**
+     * Register a scheduler handler for a dependency that exists
+     * inside "rc.schedulers".
+     *
+     * @example
+     * ```ts
+     * const task = Cron.schedule()
+     *    .pattern('* * * * *')
+     *    .scheduler('MyCustomSchedulerClass')
+     *
+     * task.stop()
+     * ```
+     */
+    scheduler(name) {
+        return this.handler(ctx => {
+            const scheduler = ioc.use(name) || ioc.safeUse(`App/Cron/Schedulers/${name}`);
+            return scheduler.handle(ctx);
+        });
+    }
+    /**
+     * Defines what operation the scheduler will run and
+     * register your scheduler with all options defined.
+     * This method also return an instance of your scheduler,
+     * you can use this instance to stop your scheduler.
+     *
+     * @example
+     * ```ts
+     * const task = Cron.schedule()
+     *    .pattern('* * * * *')
+     *    .handler(() => console.log('hey'))
+     *
+     * task.stop()
+     * ```
+     */
+    handler(handler) {
+        const register = () => {
+            const getCtx = () => ({
+                name: this.cron.name,
+                traceId: CronBuilder.rTracerPlugin
+                    ? CronBuilder.rTracerPlugin.id()
+                    : null,
+                pattern: this.cron.pattern,
+                timezone: this.cron.timezone,
+                runOnInit: this.cron.runOnInit,
+                recoverMissedExecutions: this.cron.recoverMissedExecutions
+            });
+            const options = Options.create({
+                name: this.cron.name,
+                timezone: this.cron.timezone,
+                runOnInit: this.cron.runOnInit,
+                scheduled: this.cron.scheduled,
+                recoverMissedExecutions: this.cron.recoverMissedExecutions
+            });
+            if (CronBuilder.rTracerPlugin) {
+                return schedule(this.cron.pattern, () => CronBuilder.rTracerPlugin.runWithId(() => this.cron.handler(getCtx())), options);
+            }
+            return schedule(this.cron.pattern, () => this.cron.handler(getCtx()), options);
+        };
+        if (!CronBuilder.exceptionHandler) {
+            this.cron.handler = handler;
+            return register();
+        }
+        this.cron.handler = async (...args) => {
+            try {
+                await handler(...args);
+            }
+            catch (err) {
+                CronBuilder.exceptionHandler.handle(err);
+            }
+        };
+        return register();
+    }
+    /**
+     * Defines if the task needs to be scheduled to run
+     * after registering it.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .scheduled(true)
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    scheduled(scheduled) {
+        this.cron.scheduled = scheduled;
+        return this;
+    }
+    /**
+     * Defines a name to your scheduler.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .name('myScheduler')
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    name(name) {
+        this.cron.name = name;
+        return this;
+    }
+    /**
+     * Defines the timezone that is used for the job
+     * scheduling.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .timezone('America/Sao_Paulo')
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    timezone(timezone) {
+        this.cron.timezone = timezone;
+        return this;
+    }
+    /**
+     * Runs the task immediately after registering, no matter
+     * the CRON pattern defined.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .runOnInit(true)
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    runOnInit(runOnInit) {
+        this.cron.runOnInit = runOnInit;
+        return this;
+    }
+    /**
+     * Specifies whether to recover missed executions instead
+     * of skipping them.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('* * * * *')
+     *    .recoverMissingExecutions(true)
+     *    .handler(() => console.log('hey'))
+     * ```
+     */
+    recoverMissedExecutions(recoverMissedExecutions) {
+        this.cron.recoverMissedExecutions = recoverMissedExecutions;
+        return this;
+    }
+}