@outloud/adonis-scheduler 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present, Outloud
+
+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,190 @@
+<div align="center">
+  <h2><b>Adonis Scheduler</b></h2>
+  
+  <p>
+
+`@outloud/adonis-scheduler` is a cron job scheduler for [AdonisJS](https://adonisjs.com/).
+
+  </p>
+</div>
+
+
+<div align="center">
+
+[![npm-image]][npm-url] [![license-image]][license-url]
+
+</div>
+
+---
+## Features
+- Define tasks with cron-like scheduling.
+- Run tasks as standalone processes or as part of the HTTP server.
+- Locking mechanism to prevent concurrent task execution.
+- Cancellation support for long-running tasks.
+- Graceful shutdown.
+- Global and task-level error handling.
+
+## Getting Started
+
+Install the package from the npm registry and configure it.
+
+```bash
+node ace add @outloud/adonis-scheduler
+```
+
+See `config/scheduler.ts` for available configuration options.
+
+## Usage
+
+To make scheduler work, you must define and register tasks.
+
+### Define a task
+
+You can create a task using `node ace make:task <task-name>` command. This will create a new task file in the `app/tasks` directory.
+
+```ts
+import { Task, type TaskOptions } from '@outloud/adonis-scheduler'
+
+export default class TestTask extends Task {
+  static options: TaskOptions = {
+    schedule: '* * * * *'
+  }
+
+  async run(): Promise<void> {
+    // Your task logic here
+  }
+}
+```
+
+### Register a task
+
+For task to run it must be registered in the scheduler. You can register tasks in two ways: using the `start/scheduler.ts` preloaded file or in a provider's `start` method.
+
+Using `start/scheduler.ts` file.
+
+```ts
+import scheduler from '@outloud/adonis-scheduler/services/main'
+
+scheduler.register(() => import('../app/tasks/test.task.js'))
+```
+
+Or using a provider.
+
+```ts
+import type { ApplicationService } from '@adonisjs/core/types'
+import scheduler from '@outloud/adonis-scheduler/services/main'
+
+export default class AppProvider {
+  constructor(protected app: ApplicationService) {}
+
+  start() {
+    scheduler.register(() => import('../app/tasks/test.task.js'))
+  }
+}
+
+```
+
+You can also run other commands using scheduler without defining custom Task class.
+
+```ts
+import scheduler from '@outloud/adonis-scheduler/services/main'
+
+scheduler.register({
+  command: '<command-name>',
+  schedule: '* * * * *',
+})
+```
+
+### Running the scheduler
+
+The scheduler can be run as standalone process or as part of the HTTP server.
+
+To run it as a **standalone process**, you can use the following command:
+
+```bash
+node ace scheduler:run
+```
+
+To run it as part of the **HTTP server**, set following env variable:
+
+```bash
+SCHEDULER_HTTP_SERVER=true
+```
+
+## Locking
+
+> [!NOTE]
+> This requires [@adonisjs/lock](https://docs.adonisjs.com/guides/digging-deeper/locks) package to be installed and configured.
+
+The scheduler supports locking to prevent multiple instances of the same task from running concurrently. You can enable locking by setting the `lock` option in the task options.
+
+```ts
+import { Task, type TaskOptions } from '@outloud/adonis-scheduler'
+
+export default class TestTask extends Task {
+  static options: TaskOptions = {
+    schedule: '* * * * *',
+    lock: true // or value for lock ttl
+  }
+
+  async run(): Promise<void> {
+    // Your task logic here
+  }
+}
+```
+
+## Cancellation
+
+The package supports cancellation and graceful shutdown. You can add `onCancel` handler in your task or watch for `isCanceled` property.
+
+```ts
+import { Task } from '@outloud/adonis-scheduler'
+
+export default class TestTask extends Task {
+  async run(): Promise<void> {
+    while (!this.isCanceled) {
+      // Your task logic here
+    }
+  }
+
+  async onCancel(): Promise<void> {
+    // teardown running logic
+  }
+}
+```
+
+## Error handling
+
+It's possible to globally handle errors for all your tasks or define custom error handler for each task.
+
+To register global error handler, you can use the `onError` method of the scheduler service. You can define it in `start/scheduler.ts` preloaded file.
+This handler will run only if custom error handler is not defined in the task itself.
+
+```ts
+import logger from '@adonisjs/core/services/logger'
+import scheduler from '@outloud/adonis-scheduler/services/main'
+import { Sentry } from '@rlanz/sentry'
+
+scheduler.onError((error, task) => {
+  logger.error(error)
+  Sentry.captureException(error)
+})
+```
+
+Custom error handler can be defined in the task itself by implementing `onError` method.
+
+```ts
+import { Task } from '@outloud/adonis-scheduler'
+
+export default class TestTask extends Task {
+  async onError(error: Error): Promise<void> {
+    // handle error
+  }
+}
+```
+
+[npm-image]: https://img.shields.io/npm/v/@outloud/adonis-scheduler.svg?style=for-the-badge&logo=**npm**
+[npm-url]: https://npmjs.org/package/@outloud/adonis-scheduler "npm"
+
+[license-image]: https://img.shields.io/npm/l/@outloud/adonis-scheduler?color=blueviolet&style=for-the-badge
+[license-url]: LICENSE "license"

package/build/chunk-7P6J5U6O.js

@@ -0,0 +1,25 @@
+import { __name } from './chunk-SHUYVCID.js';
+
+// src/task.ts
+var Task = class {
+  static {
+    __name(this, "Task");
+  }
+  isCanceled = false;
+  promise;
+  static options;
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+  constructor(..._) {
+  }
+  get name() {
+    const Ctor = this.constructor;
+    return Ctor.options.name ?? Ctor.name;
+  }
+  async $cancel() {
+    this.isCanceled = true;
+    await this.onCancel?.();
+    await this.promise;
+  }
+};
+
+export { Task };

package/build/chunk-BBI2I5B5.js

@@ -0,0 +1,183 @@
+import { __name } from './chunk-SHUYVCID.js';
+import { Cron } from 'croner';
+import timers from 'timers/promises';
+
+async function waitUntil(callback, interval = 50) {
+  while (!callback()) {
+    await timers.setTimeout(interval);
+  }
+}
+__name(waitUntil, "waitUntil");
+
+// src/scheduler.ts
+var Scheduler = class {
+  static {
+    __name(this, "Scheduler");
+  }
+  config;
+  resolver;
+  logger;
+  locks;
+  definitions = [];
+  state = "created";
+  errorHandler;
+  constructor(config, resolver, logger, locks) {
+    this.config = config;
+    this.resolver = resolver;
+    this.logger = logger;
+    this.locks = locks;
+  }
+  register(options) {
+    const definition = {
+      schedule: "* * * * *",
+      state: "created",
+      jobs: []
+    };
+    if (typeof options === "object") {
+      const command = Array.isArray(options.command) ? options.command : [
+        options.command
+      ];
+      Object.assign(definition, options);
+      definition.loader = () => import('./command.task-GUNK3QFY.js').then((module) => {
+        return class extends module.CommandTask {
+          static command = command;
+        };
+      });
+    } else {
+      definition.loader = options;
+    }
+    if (!definition.loader) {
+      throw new Error("Task definition must have either a command or a task defined.");
+    }
+    this.definitions.push(definition);
+    if (this.hasState([
+      "starting",
+      "running"
+    ])) {
+      this.schedule(definition);
+    }
+    return this;
+  }
+  async start(wait = false) {
+    if (!this.hasState([
+      "created",
+      "stopped"
+    ])) {
+      this.logger.warn("Scheduler is already running");
+      return;
+    }
+    this.setState("starting");
+    await Promise.all(this.definitions.map((definition) => this.schedule(definition)));
+    if (!this.definitions.length) {
+      this.logger.warn("No tasks registered, scheduler will not run any jobs.");
+    }
+    this.setState("running");
+    if (wait) {
+      return waitUntil(() => this.state === "stopped");
+    }
+  }
+  async stop() {
+    if (this.state === "starting") {
+      await waitUntil(() => this.state !== "starting");
+    }
+    if (this.state !== "running") {
+      this.logger.warn("Scheduler is not running");
+      return;
+    }
+    this.setState("stopping");
+    await Promise.all(this.definitions.map((definition) => this.terminate(definition)));
+    this.setState("stopped");
+  }
+  onError(callback) {
+    this.errorHandler = callback;
+    return this;
+  }
+  async load(definition) {
+    if (definition.loader) {
+      const module = await definition.loader();
+      definition.task = "default" in module ? module.default : module;
+    }
+    if (!definition.task) {
+      throw new Error("Failed to load task, no loader or task provided.");
+    }
+    Object.assign(definition, definition.task.options ?? {});
+  }
+  async make(definition) {
+    return await this.resolver.make(definition.task);
+  }
+  async run(definition) {
+    const task = await this.make(definition);
+    const lockDuration = definition.lock && typeof definition.lock !== "boolean" ? definition.lock : this.config.lockDuration;
+    const lock = definition.lock ? this.locks?.createLock(`scheduler:${task.name}`, lockDuration) : void 0;
+    if (definition.lock && !this.locks) {
+      this.logger.warn("Lock is not available, install @adonisjs/lock to use task locking.");
+    }
+    if (lock) {
+      const acquired = await lock.acquireImmediately();
+      if (!acquired) {
+        this.config.warnWhenLocked && this.logger.warn(`Task "${definition.task?.name}" is locked and cannot be run.`);
+        return;
+      }
+    }
+    try {
+      definition.jobs.push(task);
+      const promise = this.resolver.call(task, "run").finally(() => lock?.release());
+      task.promise = promise.catch(() => {
+      });
+      await promise;
+    } catch (error) {
+      await this.handleError(error, definition, task);
+    } finally {
+      definition.jobs.splice(definition.jobs.indexOf(task), 1);
+    }
+  }
+  hasState(state) {
+    const states = Array.isArray(state) ? state : [
+      state
+    ];
+    return states.includes(this.state);
+  }
+  setState(state) {
+    if (this.state === state) {
+      return;
+    }
+    this.state = state;
+    this.logger.info(`Scheduler: ${state}`);
+  }
+  async handleError(error, _, task) {
+    if (task && task.onError) {
+      await task.onError(error);
+      return;
+    }
+    if (this.errorHandler) {
+      await this.errorHandler(error, task);
+      return;
+    }
+    throw error;
+  }
+  async cancel(job) {
+    await job.$cancel();
+  }
+  async terminate(definition) {
+    definition.cron?.stop();
+    definition.cron = void 0;
+    await Promise.all(definition.jobs.map((job) => this.cancel(job)));
+    definition.state = "created";
+  }
+  async schedule(definition) {
+    if (definition.state !== "created") {
+      return;
+    }
+    definition.state = "preparing";
+    if (!definition.task) {
+      await this.load(definition);
+    }
+    definition.cron = new Cron(definition.schedule, {
+      timezone: definition.timeZone
+    }, () => this.run(definition));
+    definition.state = "ready";
+    this.logger.debug(`Scheduler: Task "${definition.task?.name}" scheduled with "${definition.schedule}"`);
+  }
+};
+
+export { Scheduler };

package/build/chunk-SHUYVCID.js

@@ -0,0 +1,4 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export { __name };

package/build/command.task-GUNK3QFY.js

@@ -0,0 +1,22 @@
+import { Task } from './chunk-7P6J5U6O.js';
+import { __name } from './chunk-SHUYVCID.js';
+import ace from '@adonisjs/core/services/ace';
+
+var CommandTask = class extends Task {
+  static {
+    __name(this, "CommandTask");
+  }
+  static command = [];
+  get name() {
+    return this.constructor.command.join(",");
+  }
+  async run() {
+    const [name, ...args] = this.constructor.command;
+    if (!name) {
+      throw new Error("No command name provided.");
+    }
+    await ace.exec(name, args);
+  }
+};
+
+export { CommandTask };

package/build/commands/commands.json

@@ -0,0 +1 @@
+{"commands":[{"commandName":"make:task","description":"Make a new task class","help":"","namespace":"make","aliases":[],"flags":[],"args":[{"name":"name","argumentName":"name","required":true,"description":"Name of the task","type":"string"}],"options":{"allowUnknownFlags":true},"filePath":"make_task.js"},{"commandName":"scheduler:run","description":"Run a scheduler","help":"","namespace":"scheduler","aliases":[],"flags":[],"args":[],"options":{"startApp":true,"staysAlive":true},"filePath":"scheduler_run.js"}],"version":1}

package/build/commands/main.d.ts

@@ -0,0 +1,4 @@
+import { CommandMetaData, Command } from '@adonisjs/ace/types';
+
+export function getMetaData(): Promise<CommandMetaData[]>
+export function getCommand(metaData: CommandMetaData): Promise<Command | null>

package/build/commands/main.js

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises'
+
+/**
+ * In-memory cache of commands after they have been loaded
+ */
+let commandsMetaData
+
+/**
+ * Reads the commands from the "./commands.json" file. Since, the commands.json
+ * file is generated automatically, we do not have to validate its contents
+ */
+export async function getMetaData() {
+  if (commandsMetaData) {
+    return commandsMetaData
+  }
+
+  const commandsIndex = await readFile(new URL('./commands.json', import.meta.url), 'utf-8')
+  commandsMetaData = JSON.parse(commandsIndex).commands
+
+  return commandsMetaData
+}
+
+/**
+ * Imports the command by lookingup its path from the commands
+ * metadata
+ */
+export async function getCommand(metaData) {
+  const commands = await getMetaData()
+  const command = commands.find(({ commandName }) => metaData.commandName === commandName)
+  if (!command) {
+    return null
+  }
+
+  const { default: commandConstructor } = await import(new URL(command.filePath, import.meta.url).href)
+  return commandConstructor
+}

package/build/commands/make_task.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import { CommandOptions } from '@adonisjs/core/types/ace';
+
+declare class MakeTask extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    /**
+     * The name of the job file.
+     */
+    name: string;
+    /**
+     * Execute command
+     */
+    run(): Promise<void>;
+}
+
+export { MakeTask as default };

package/build/commands/make_task.js

@@ -0,0 +1,42 @@
+import { __name } from '../chunk-SHUYVCID.js';
+import 'reflect-metadata';
+import { BaseCommand, args } from '@adonisjs/core/ace';
+
+function _ts_decorate(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;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var MakeTask = class extends BaseCommand {
+  static {
+    __name(this, "MakeTask");
+  }
+  static commandName = "make:task";
+  static description = "Make a new task class";
+  static options = {
+    allowUnknownFlags: true
+  };
+  /**
+  * Execute command
+  */
+  async run() {
+    const codemods = await this.createCodemods();
+    await codemods.makeUsingStub(import.meta.dirname + "/../stubs", "command/task.stub", {
+      entity: this.app.generators.createEntity(this.name)
+    });
+  }
+};
+_ts_decorate([
+  args.string({
+    description: "Name of the task"
+  }),
+  _ts_metadata("design:type", String)
+], MakeTask.prototype, "name", void 0);
+
+export { MakeTask as default };

package/build/commands/scheduler_run.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import { CommandOptions } from '@adonisjs/core/types/ace';
+import { a as Scheduler } from '../scheduler-BWT0Iqko.js';
+import '@adonisjs/core/container';
+import '@adonisjs/core/types';
+import '@adonisjs/lock/types';
+import '@adonisjs/core/logger';
+
+declare class SchedulerRun extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    private scheduler?;
+    prepare(): void;
+    run(scheduler: Scheduler): Promise<void>;
+}
+
+export { SchedulerRun as default };

package/build/commands/scheduler_run.js

@@ -0,0 +1,46 @@
+import { Scheduler } from '../chunk-BBI2I5B5.js';
+import { __name } from '../chunk-SHUYVCID.js';
+import 'reflect-metadata';
+import { inject } from '@adonisjs/core';
+import { BaseCommand } from '@adonisjs/core/ace';
+
+function _ts_decorate(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;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var SchedulerRun = class extends BaseCommand {
+  static {
+    __name(this, "SchedulerRun");
+  }
+  static commandName = "scheduler:run";
+  static description = "Run a scheduler";
+  static options = {
+    startApp: true,
+    staysAlive: true
+  };
+  scheduler;
+  prepare() {
+    this.app.terminating(() => this.scheduler?.stop());
+  }
+  async run(scheduler) {
+    this.scheduler = scheduler;
+    await this.scheduler.start(true);
+  }
+};
+_ts_decorate([
+  inject(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof Scheduler === "undefined" ? Object : Scheduler
+  ]),
+  _ts_metadata("design:returntype", Promise)
+], SchedulerRun.prototype, "run", null);
+
+export { SchedulerRun as default };

package/build/index.d.ts

@@ -0,0 +1,13 @@
+import { S as SchedulerConfig } from './scheduler-BWT0Iqko.js';
+export { a as Scheduler, T as Task, b as TaskOptions } from './scheduler-BWT0Iqko.js';
+import Configure from '@adonisjs/core/commands/configure';
+import '@adonisjs/core/container';
+import '@adonisjs/core/types';
+import '@adonisjs/lock/types';
+import '@adonisjs/core/logger';
+
+declare function configure(command: Configure): Promise<void>;
+
+declare function defineConfig<T extends SchedulerConfig>(config: T): T;
+
+export { SchedulerConfig, configure, defineConfig };

package/build/index.js

@@ -0,0 +1,29 @@
+export { Scheduler } from './chunk-BBI2I5B5.js';
+export { Task } from './chunk-7P6J5U6O.js';
+import { __name } from './chunk-SHUYVCID.js';
+
+// configure.ts
+async function configure(command) {
+  const codemods = await command.createCodemods();
+  await codemods.makeUsingStub(import.meta.dirname + "/stubs", "config/scheduler.stub", {});
+  await codemods.defineEnvVariables({
+    SCHEDULER_HTTP_SERVER: false
+  });
+  await codemods.defineEnvValidations({
+    variables: {
+      SCHEDULER_HTTP_SERVER: `Env.schema.boolean.optional()`
+    }
+  });
+  await codemods.updateRcFile((rcFile) => {
+    rcFile.addProvider("@outloud/adonis-scheduler/provider").addCommand("@outloud/adonis-scheduler/commands");
+  });
+}
+__name(configure, "configure");
+
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+__name(defineConfig, "defineConfig");
+
+export { configure, defineConfig };

package/build/providers/scheduler.provider.d.ts

@@ -0,0 +1,23 @@
+import { ApplicationService } from '@adonisjs/core/types';
+import { a as Scheduler } from '../scheduler-BWT0Iqko.js';
+import '@adonisjs/core/container';
+import '@adonisjs/lock/types';
+import '@adonisjs/core/logger';
+
+declare class SchedulerProvider {
+    protected app: ApplicationService;
+    private scheduler?;
+    constructor(app: ApplicationService);
+    private getConfig;
+    private getLocks;
+    register(): void;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+declare module '@adonisjs/core/types' {
+    interface ContainerBindings {
+        scheduler: Scheduler;
+    }
+}
+
+export { SchedulerProvider as default };

package/build/providers/scheduler.provider.js

@@ -0,0 +1,40 @@
+import { Scheduler } from '../chunk-BBI2I5B5.js';
+import { __name } from '../chunk-SHUYVCID.js';
+
+// providers/scheduler.provider.ts
+var SchedulerProvider = class {
+  static {
+    __name(this, "SchedulerProvider");
+  }
+  app;
+  scheduler;
+  constructor(app) {
+    this.app = app;
+  }
+  getConfig() {
+    return this.app.config.get("scheduler", {});
+  }
+  async getLocks() {
+    if (this.app.container.hasBinding("lock.manager")) {
+      return await this.app.container.make("lock.manager");
+    }
+  }
+  register() {
+    this.app.container.singleton(Scheduler, async () => {
+      return new Scheduler(this.getConfig(), this.app.container.createResolver(), await this.app.container.make("logger"), await this.getLocks());
+    });
+    this.app.container.alias("scheduler", Scheduler);
+  }
+  async ready() {
+    const config = this.getConfig();
+    if (this.app.getEnvironment() === "web" && config.httpServer) {
+      this.scheduler = await this.app.container.make(Scheduler);
+      await this.scheduler.start();
+    }
+  }
+  async shutdown() {
+    await this.scheduler?.stop();
+  }
+};
+
+export { SchedulerProvider as default };

package/build/scheduler-BWT0Iqko.d.ts

@@ -0,0 +1,91 @@
+import { ContainerResolver } from '@adonisjs/core/container';
+import { ContainerBindings } from '@adonisjs/core/types';
+import { LockService } from '@adonisjs/lock/types';
+import { Logger } from '@adonisjs/core/logger';
+
+interface SchedulerConfig {
+    /**
+     * Should the scheduler start with HTTP server?
+     */
+    httpServer: boolean;
+    /**
+     * Warn when a task is locked and cannot be run
+     */
+    warnWhenLocked: boolean;
+    /**
+     * The default ttl for the lock.
+     */
+    lockDuration: number | string;
+}
+interface TaskOptions {
+    /**
+     * A unique name for the task.
+     */
+    name?: string;
+    /**
+     * The pattern to when the task should run.
+     *
+     * See https://croner.56k.guru/usage/pattern/ for more information.
+     */
+    schedule: string;
+    /**
+     * Time zone to use for the task.
+     */
+    timeZone?: string;
+    /**
+     * Lock the task to prevent it from running concurrently.
+     *
+     * If a string or number is provided, it will be as ttl.
+     *
+     * @default false
+     */
+    lock?: boolean | number | string;
+}
+interface TaskRegisterOptions extends TaskOptions {
+    command: string | string[];
+}
+type ErrorHandler = (error: Error, task: Task) => (void | Promise<void>);
+type MaybePromise<T> = T | Promise<T>;
+type Factory<T> = () => MaybePromise<{
+    default: T;
+} | T>;
+
+declare abstract class Task {
+    isCanceled: boolean;
+    promise?: Promise<any>;
+    static options: TaskOptions;
+    constructor(..._: any[]);
+    get name(): string;
+    abstract run(...args: any[]): Promise<void>;
+    $cancel(): Promise<void>;
+}
+interface Task {
+    onCancel?(): Promise<void>;
+    onError?(error: Error): Promise<void>;
+}
+
+declare class Scheduler {
+    private config;
+    private resolver;
+    private logger;
+    private locks?;
+    private definitions;
+    private state;
+    private errorHandler?;
+    constructor(config: SchedulerConfig, resolver: ContainerResolver<ContainerBindings>, logger: Logger, locks?: LockService | undefined);
+    register(options: TaskRegisterOptions | Factory<typeof Task>): this;
+    start(wait?: boolean): Promise<void>;
+    stop(): Promise<void>;
+    onError(callback: ErrorHandler): this;
+    private load;
+    private make;
+    private run;
+    private hasState;
+    private setState;
+    private handleError;
+    private cancel;
+    private terminate;
+    private schedule;
+}
+
+export { type SchedulerConfig as S, Task as T, Scheduler as a, type TaskOptions as b };

package/build/services/main.d.ts

@@ -0,0 +1,9 @@
+import { a as Scheduler } from '../scheduler-BWT0Iqko.js';
+import '@adonisjs/core/container';
+import '@adonisjs/core/types';
+import '@adonisjs/lock/types';
+import '@adonisjs/core/logger';
+
+declare let scheduler: Scheduler;
+
+export { scheduler as default };

package/build/services/main.js

@@ -0,0 +1,9 @@
+import '../chunk-SHUYVCID.js';
+import app from '@adonisjs/core/services/app';
+
+var scheduler;
+await app?.booted(async () => {
+  scheduler = await app.container.make("scheduler");
+});
+
+export { scheduler as default };

package/build/stubs/command/task.stub

@@ -0,0 +1,16 @@
+{{#var name = string(entity.name).removeSuffix('task').suffix('Task').pascalCase().toString()}}
+{{#var fileName = string(entity.name).removeSuffix('task').suffix('.task').snakeCase().removeExtension().ext('.ts').toString()}}
+{{{
+  exports({ to: app.makePath('app/tasks', entity.path, fileName) })
+}}}
+import { Task, type TaskOptions } from '@outloud/adonis-scheduler'
+
+export default class {{ name }} extends Task {
+  static options: TaskOptions = {
+    schedule: '* * * * *'
+  }
+
+  async run(): Promise<void> {
+
+  }
+}

package/build/stubs/config/scheduler.stub

@@ -0,0 +1,14 @@
+{{{
+  exports({ to: app.configPath('scheduler.ts') })
+}}}
+
+import { defineConfig } from '@outloud/adonis-scheduler'
+import env from '#start/env'
+
+const schedulerConfig = defineConfig({
+  httpServer: env.get('SCHEDULER_HTTP_SERVER', false),
+  warnWhenLocked: false,
+  lockDuration: '10m',
+})
+
+export default schedulerConfig

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@outloud/adonis-scheduler",
+  "type": "module",
+  "version": "1.0.5",
+  "description": "Schedule cron jobs in AdonisJS.",
+  "author": "Outloud <hello@outloud.co>",
+  "contributors": [
+    "Andrej Adamcik"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/madebyoutloud/adonis-scheduler#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madebyoutloud/adonis-scheduler.git"
+  },
+  "publishConfig": {
+    "tag": "latest",
+    "access": "public"
+  },
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./provider": "./build/providers/scheduler.provider.js",
+    "./commands": "./build/commands/main.js",
+    "./services/*": "./build/services/*.js"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^6",
+    "@adonisjs/lock": "^1"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/lock": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "^7.8.2",
+    "@adonisjs/core": "~6.19.0",
+    "@adonisjs/lock": "^1.1.1",
+    "@adonisjs/tsconfig": "^1.4.1",
+    "@outloud/eslint-config": "^2.0.5",
+    "@swc/core": "^1.13.3",
+    "@types/node": "^24.2.1",
+    "copyfiles": "^2.4.1",
+    "eslint": "^9.33.0",
+    "reflect-metadata": "^0.2.2",
+    "release-it": "^19.0.4",
+    "tsup": "~8.5.0",
+    "typescript": "~5.9.2"
+  },
+  "dependencies": {
+    "croner": "^9"
+  },
+  "scripts": {
+    "copy:templates": "copyfiles \"stubs/**/*.stub\" build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . ",
+    "lint:fix": "eslint --fix .",
+    "quick:test": "node --import=./tsnode.esm.js --enable-source-maps bin/test.ts",
+    "pretest": "pnpm run lint",
+    "test": "c8 pnpm run quick:test",
+    "precompile": "pnpm run lint && rm -rf build",
+    "compile": "tsup-node",
+    "postcompile": "pnpm run copy:templates && pnpm run index:commands",
+    "build": "rm -rf build && pnpm run compile",
+    "release": "release-it",
+    "index:commands": "adonis-kit index build/commands",
+    "version": "pnpm run build"
+  }
+}