@athenna/cron 4.0.0

package/src/cron/CronImpl.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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 { ScheduledTask } from '#src/types';
+import { CronBuilder } from '#src/cron/CronBuilder';
+export declare class CronImpl {
+    /**
+     * Creates a new instance of CronBuilder to register
+     * your scheduler.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('59 * * * *')
+     *    .handler((ctx) => console.log(`my cron pattern is ${ctx.pattern}`))
+     *    .register()
+     * ```
+     */
+    schedule(): CronBuilder;
+    /**
+     * Validate if CRON pattern is correct.
+     *
+     * @example
+     * ```ts
+     * const valid = Cron.validate('59 * * * *')
+     * const invalid = Cron.validate('60 * * * *')
+     * ```
+     */
+    validate(pattern: string): boolean;
+    /**
+     * Register the error handler for all tasks.
+     *
+     * @example
+     * ```ts
+     * Cron.setErrorHandler((err) => console.error(err))
+     * ```
+     */
+    setErrorHandler(handler: any): this;
+    /**
+     * Returns a map with all tasks that has been scheduled.
+     *
+     * @example
+     * ```ts
+     * const tasks = Cron.getTasks()
+     *
+     * task.map(task => task.stop())
+     * ```
+     */
+    getTasks(): Map<string, ScheduledTask>;
+    /**
+     * Close all scheduled tasks.
+     *
+     * @example
+     * ```ts
+     * Cron.close()
+     * ```
+     */
+    close(): this;
+    /**
+     * Delete all scheduled tasks.
+     *
+     * @example
+     * ```ts
+     * Cron.truncate()
+     * ```
+     */
+    truncate(): this;
+}

package/src/cron/CronImpl.js

@@ -0,0 +1,92 @@
+/**
+ * @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 { getTasks, validate } from 'node-cron';
+import { CronBuilder } from '#src/cron/CronBuilder';
+export class CronImpl {
+    /**
+     * Creates a new instance of CronBuilder to register
+     * your scheduler.
+     *
+     * @example
+     * ```ts
+     * Cron.schedule().pattern('59 * * * *')
+     *    .handler((ctx) => console.log(`my cron pattern is ${ctx.pattern}`))
+     *    .register()
+     * ```
+     */
+    schedule() {
+        return new CronBuilder();
+    }
+    /**
+     * Validate if CRON pattern is correct.
+     *
+     * @example
+     * ```ts
+     * const valid = Cron.validate('59 * * * *')
+     * const invalid = Cron.validate('60 * * * *')
+     * ```
+     */
+    validate(pattern) {
+        return validate(pattern);
+    }
+    /**
+     * Register the error handler for all tasks.
+     *
+     * @example
+     * ```ts
+     * Cron.setErrorHandler((err) => console.error(err))
+     * ```
+     */
+    setErrorHandler(handler) {
+        CronBuilder.exceptionHandler = handler;
+        return this;
+    }
+    /**
+     * Returns a map with all tasks that has been scheduled.
+     *
+     * @example
+     * ```ts
+     * const tasks = Cron.getTasks()
+     *
+     * task.map(task => task.stop())
+     * ```
+     */
+    getTasks() {
+        return getTasks();
+    }
+    /**
+     * Close all scheduled tasks.
+     *
+     * @example
+     * ```ts
+     * Cron.close()
+     * ```
+     */
+    close() {
+        for (const task of this.getTasks().values()) {
+            task.stop();
+        }
+        return this;
+    }
+    /**
+     * Delete all scheduled tasks.
+     *
+     * @example
+     * ```ts
+     * Cron.truncate()
+     * ```
+     */
+    truncate() {
+        const tasks = this.getTasks();
+        for (const task of tasks.keys()) {
+            tasks.delete(task);
+        }
+        return this;
+    }
+}

package/src/debug/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export declare const debug: import("util").DebugLogger;

package/src/debug/index.js

@@ -0,0 +1,10 @@
+/**
+ * @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 { debuglog } from 'node:util';
+export const debug = debuglog('athenna:cron');

package/src/facades/Cron.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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 { CronImpl } from '#src/cron/CronImpl';
+export declare const Cron: import("@athenna/ioc").FacadeType<CronImpl>;

package/src/facades/Cron.js

@@ -0,0 +1,10 @@
+/**
+ * @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 { Facade } from '@athenna/ioc';
+export const Cron = Facade.createFor('Athenna/Core/Cron');

package/src/handlers/CronExceptionHandler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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.
+ */
+export declare class CronExceptionHandler {
+    /**
+     * Error codes that should be ignored from logging.
+     */
+    get ignoreCodes(): string[];
+    /**
+     * Error statuses that should be ignored from logging.
+     */
+    get ignoreStatuses(): number[];
+    /**
+     * The exception handler of all Artisan commands.
+     */
+    handle(error: any): Promise<void>;
+    /**
+     * Return a boolean indicating if the error can be logged or not.
+     */
+    private canBeLogged;
+}

package/src/handlers/CronExceptionHandler.js

@@ -0,0 +1,59 @@
+/**
+ * @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 { Log } from '@athenna/logger';
+import { Config } from '@athenna/config';
+import { Is, String } from '@athenna/common';
+export class CronExceptionHandler {
+    /**
+     * Error codes that should be ignored from logging.
+     */
+    get ignoreCodes() {
+        return Config.get('cron.logger.ignoreCodes', []);
+    }
+    /**
+     * Error statuses that should be ignored from logging.
+     */
+    get ignoreStatuses() {
+        return Config.get('cron.logger.ignoreStatuses', []);
+    }
+    /**
+     * The exception handler of all Artisan commands.
+     */
+    async handle(error) {
+        error.code = String.toSnakeCase(error.code || error.name).toUpperCase();
+        const isException = Is.Exception(error);
+        const isDebugMode = Config.get('app.debug', true);
+        const isInternalServerError = Is.Error(error) && !isException;
+        if (!isException) {
+            error = error.toAthennaException();
+        }
+        if (isInternalServerError && !isDebugMode) {
+            error.name = 'Internal error';
+            error.code = 'E_INTERNAL_ERROR';
+            error.message = 'An internal error has occurred.';
+            delete error.stack;
+        }
+        if (!this.canBeLogged(error)) {
+            return;
+        }
+        Log.channelOrVanilla('exception').error(await error.prettify());
+    }
+    /**
+     * Return a boolean indicating if the error can be logged or not.
+     */
+    canBeLogged(error) {
+        if (this.ignoreCodes.includes(error.code)) {
+            return false;
+        }
+        if (this.ignoreStatuses.includes(error.status || error.statusCode)) {
+            return false;
+        }
+        return true;
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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.
+ */
+export * from '#src/types';
+export * from '#src/cron/CronImpl';
+export * from '#src/cron/CronBuilder';
+export * from '#src/facades/Cron';
+export * from '#src/annotations/Scheduler';
+export * from '#src/kernels/CronKernel';
+export * from '#src/handlers/CronExceptionHandler';
+export * from '#src/providers/CronProvider';

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * @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.
+ */
+export * from '#src/types';
+export * from '#src/cron/CronImpl';
+export * from '#src/cron/CronBuilder';
+export * from '#src/facades/Cron';
+export * from '#src/annotations/Scheduler';
+export * from '#src/kernels/CronKernel';
+export * from '#src/handlers/CronExceptionHandler';
+export * from '#src/providers/CronProvider';

package/src/kernels/CronKernel.d.ts

@@ -0,0 +1,28 @@
+export declare class CronKernel {
+    /**
+     * Register the cls-rtracer plugin in the Cron.
+     */
+    registerRTracer(trace?: boolean): Promise<void>;
+    /**
+     * Register the exception handler for all Cron tasks.
+     */
+    registerExceptionHandler(path?: string): Promise<void>;
+    /**
+     * Register all the schedulers found inside "rc.schedulers" config
+     * inside the service provider.
+     */
+    registerSchedulers(): Promise<void>;
+    /**
+     * Register the route file by importing the file.
+     */
+    registerRoutes(path: string): Promise<void>;
+    /**
+     * Register the schedulers using the meta information
+     * defined by annotations.
+     */
+    private registerUsingMeta;
+    /**
+     * Get the parent URL of the project.
+     */
+    private getParentURL;
+}

package/src/kernels/CronKernel.js

@@ -0,0 +1,95 @@
+import { sep } from 'node:path';
+import { debug } from '#src/debug';
+import { Cron } from '#src/facades/Cron';
+import { CronBuilder } from '#src/cron/CronBuilder';
+import { Exec, Module, Path } from '@athenna/common';
+import { Annotation } from '@athenna/ioc';
+import { CronExceptionHandler } from '#src/handlers/CronExceptionHandler';
+const rTracerPlugin = await Module.safeImport('cls-rtracer');
+export class CronKernel {
+    /**
+     * Register the cls-rtracer plugin in the Cron.
+     */
+    async registerRTracer(trace) {
+        if (trace === false) {
+            debug('Not able to register rTracer plugin. Set the trace option as true in your cron options.');
+            return;
+        }
+        if (trace === undefined && Config.is('cron.rTracer.enabled', false)) {
+            debug('Not able to register rTracer plugin. Set the cron.rTracer.enabled configuration as true.');
+            return;
+        }
+        if (!rTracerPlugin) {
+            debug('Not able to register tracer plugin. Install cls-rtracer package.');
+            return;
+        }
+        CronBuilder.registerRTracer(rTracerPlugin);
+    }
+    /**
+     * Register the exception handler for all Cron tasks.
+     */
+    async registerExceptionHandler(path) {
+        if (!path) {
+            CronBuilder.exceptionHandler = new CronExceptionHandler();
+            return;
+        }
+        const Handler = await Module.resolve(path, this.getParentURL());
+        CronBuilder.exceptionHandler = new Handler();
+    }
+    /**
+     * Register all the schedulers found inside "rc.schedulers" config
+     * inside the service provider.
+     */
+    async registerSchedulers() {
+        const schedulers = Config.get('rc.schedulers', []);
+        await Exec.concurrently(schedulers, async (path) => {
+            const Scheduler = await Module.resolve(path, this.getParentURL());
+            if (Annotation.isAnnotated(Scheduler)) {
+                this.registerUsingMeta(Scheduler);
+                return;
+            }
+            ioc.transient(`App/Cron/Schedulers/${Scheduler.name}`, Scheduler);
+        });
+    }
+    /**
+     * Register the route file by importing the file.
+     */
+    async registerRoutes(path) {
+        await Module.resolve(path, this.getParentURL());
+    }
+    /**
+     * Register the schedulers using the meta information
+     * defined by annotations.
+     */
+    registerUsingMeta(target) {
+        const meta = Annotation.getMeta(target);
+        const builder = Cron.schedule();
+        ioc[meta.type](meta.alias, target);
+        if (meta.name) {
+            builder.name(meta.name);
+            ioc.alias(meta.name, meta.alias);
+        }
+        if (meta.camelAlias) {
+            ioc.alias(meta.camelAlias, meta.alias);
+        }
+        builder
+            .pattern(meta.pattern)
+            .timezone(meta.timezone)
+            .scheduled(meta.scheduled)
+            .runOnInit(meta.runOnInit)
+            .recoverMissedExecutions(meta.recoverMissedExecutions)
+            .handler(ctx => {
+            const scheduler = ioc.use(meta.name) ||
+                ioc.use(meta.camelAlias) ||
+                ioc.safeUse(meta.alias);
+            return scheduler.handler(ctx);
+        });
+        return meta;
+    }
+    /**
+     * Get the parent URL of the project.
+     */
+    getParentURL() {
+        return Config.get('rc.parentURL', Path.toHref(Path.pwd() + sep));
+    }
+}

package/src/providers/CronProvider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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 { ServiceProvider } from '@athenna/ioc';
+export declare class CronProvider extends ServiceProvider {
+    register(): void;
+    shutdown(): Promise<void>;
+}

package/src/providers/CronProvider.js

@@ -0,0 +1,22 @@
+/**
+ * @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 { CronImpl } from '#src/cron/CronImpl';
+import { ServiceProvider } from '@athenna/ioc';
+export class CronProvider extends ServiceProvider {
+    register() {
+        this.container.instance('Athenna/Core/Cron', new CronImpl());
+    }
+    async shutdown() {
+        const Cron = this.container.use('Athenna/Core/Cron');
+        if (!Cron) {
+            return;
+        }
+        Cron.close().truncate();
+    }
+}

package/src/types/Context.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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.
+ */
+export interface Context {
+    name?: string;
+    traceId?: string;
+    pattern?: string;
+    timezone?: string;
+    runOnInit?: boolean;
+    recoverMissedExecutions?: boolean;
+}

package/src/types/Context.js

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export {};

package/src/types/CronHandler.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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 { Context } from '#src/types/Context';
+export type CronHandler = (ctx?: Context) => any | Promise<any>;

package/src/types/CronHandler.js

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export {};

package/src/types/ScheduledTask.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 { ScheduledTask as NodeCronScheduledTask } from 'node-cron';
+export type ScheduledTask = NodeCronScheduledTask & {
+    options: {
+        name?: string;
+        timezone?: string;
+        runOnInit?: boolean;
+        scheduled?: boolean;
+        recoverMissedExecutions?: boolean;
+    };
+};

package/src/types/ScheduledTask.js

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export {};

package/src/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @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.
+ */
+export * from '#src/types/Context';
+export * from '#src/types/CronHandler';
+export * from '#src/types/ScheduledTask';
+export * from '#src/types/schedulers/SchedulerOptions';

package/src/types/index.js

@@ -0,0 +1,12 @@
+/**
+ * @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.
+ */
+export * from '#src/types/Context';
+export * from '#src/types/CronHandler';
+export * from '#src/types/ScheduledTask';
+export * from '#src/types/schedulers/SchedulerOptions';

package/src/types/schedulers/SchedulerOptions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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.
+ */
+export type SchedulerOptions = {
+    /**
+     * The CRON expression that will determined when the scheduler
+     * will run.
+     *
+     * @example '* * * * *'
+     */
+    pattern: string;
+    /**
+     * The timezone that the CRON expression needs to respect when
+     * running the scheduler.
+     */
+    timezone?: string;
+    /**
+     * Defines if the scheduler should run when initiating the application,
+     * not matter the CRON expression, it will always run on boot.
+     *
+     * @default false
+     */
+    runOnInit?: boolean;
+    /**
+     * Defines if the scheduler should already be registered when booting
+     * the application. This option is not like `runOnInit`, if you set it
+     * as `false`, it will basically register your CRON but disabled, meaning
+     * you need to manually start it using `Cron` facade.
+     *
+     * @default true
+     */
+    scheduled?: boolean;
+    /**
+     * If this option is `true`, when the main thread froze for any reason,
+     * the elapsed time since last execution will be considered an all the
+     * missed executions will be triggered.
+     *
+     * @default false
+     */
+    recoverMissedExecutions?: boolean;
+    /**
+     * The name that will be used to register the scheduler node-cron
+     * and also inside the service container as an alias.
+     *
+     * @default YourSchedulerClassName
+     */
+    name?: string;
+    /**
+     * The alias that will be used to register the scheduler inside
+     * the service container.
+     *
+     * @default App/Cron/Schedulers/YourSchedulerClassName
+     */
+    alias?: string;
+    /**
+     * The camel alias that will be used as an alias of the real
+     * scheduler alias. Camel alias is important when you want to
+     * work with constructor injection. By default, Athenna doesn't
+     * create camel alias for schedulers.
+     *
+     * @default undefined
+     */
+    camelAlias?: string;
+    /**
+     * The registration type that will be used to register your scheduler
+     * inside the service container.
+     *
+     * @default 'transient'
+     */
+    type?: 'fake' | 'scoped' | 'singleton' | 'transient';
+};