@basaltkit/scheduler 1.0.0 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -184,11 +184,23 @@ console.log(runs) // 1
 
 In tests with the plugin, pass `autostart: false` so the timer doesn't start.
 
+## CLI commands (`basalt schedule:*`)
+
+```bash
+basalt schedule:list                 # every scheduled task + its cron (from metadata)
+basalt schedule:run reconcile-billing  # run one task NOW, ignoring its cron
+basalt schedule:run --due            # run everything due at this instant (a manual tick)
+```
+
+`schedule:list` reads the `schedule:entries` metadata bucket; `schedule:run` is
+registered by `schedulerPlugin` and executes against the live `Scheduler`, so it
+respects each entry's overlap guard and `onFailure` handler.
+
 ## API reference
 
 ### `schedulerPlugin(options?: SchedulerPluginOptions)`
 
-Registers a `Scheduler` (singleton) under the `SCHEDULER` token; on `boot` it calls `define`, publishes the entries to the container's metadata (key `schedule:entries`, consumed by the `basalt schedule:list` CLI) and starts the timer; on `shutdown` it calls `stop()`.
+Registers a `Scheduler` (singleton) under the `SCHEDULER` token; on `boot` it calls `define`, publishes the entries to the container's metadata (key `schedule:entries`, consumed by `basalt schedule:list`), registers the `schedule:run` command, and starts the timer; on `shutdown` it calls `stop()`.
 
 | Option | Type | Required? | Default | Description |
 |---|---|---|---|---|

package/dist/index.d.ts

@@ -89,6 +89,14 @@ declare class Scheduler {
         cron: string;
         timezone: string;
     }[];
+    /** Names of every scheduled entry — for CLI validation/listing. */
+    names(): string[];
+    /**
+     * Runs a single entry by name on demand, ignoring its cron (for `schedule:run`
+     * and manual triggers). Returns false if no entry has that name. The entry's
+     * own overlap guard and failure handler still apply.
+     */
+    runNow(name: string): Promise<boolean>;
     /**
      * Runs the entries due at the given instant. Deterministic — this is what
      * the tests call directly and what the timer calls every minute.

package/dist/index.js

@@ -205,6 +205,21 @@ var Scheduler = class {
   list() {
     return this.entries.map((entry) => entry.describe());
   }
+  /** Names of every scheduled entry — for CLI validation/listing. */
+  names() {
+    return this.entries.map((entry) => entry.name);
+  }
+  /**
+   * Runs a single entry by name on demand, ignoring its cron (for `schedule:run`
+   * and manual triggers). Returns false if no entry has that name. The entry's
+   * own overlap guard and failure handler still apply.
+   */
+  async runNow(name) {
+    const entry = this.entries.find((candidate) => candidate.name === name);
+    if (!entry) return false;
+    await entry.run();
+    return true;
+  }
   /**
    * Runs the entries due at the given instant. Deterministic — this is what
    * the tests call directly and what the timer calls every minute.
@@ -260,6 +275,7 @@ function schedulerPlugin(options = {}) {
     name: "basalt:scheduler",
     register({ container }) {
       container.singleton(SCHEDULER, () => new Scheduler());
+      registerScheduleRunCommand(container);
     },
     boot({ container }) {
       const scheduler = container.get(SCHEDULER);
@@ -273,6 +289,36 @@ function schedulerPlugin(options = {}) {
     }
   });
 }
+function registerScheduleRunCommand(container) {
+  ensureMetadata(container).add("commands", {
+    name: "schedule:run",
+    description: "Run a scheduled task on demand (by name), or --due for all due now",
+    async handle({
+      io,
+      args,
+      flags
+    }) {
+      const scheduler = container.get(SCHEDULER);
+      if (flags["due"] === true) {
+        await scheduler.tick();
+        io.log("Ran all due scheduled tasks.");
+        return;
+      }
+      const name = args[0];
+      if (!name) {
+        io.error("Usage: basalt schedule:run <name> | --due");
+        return 1;
+      }
+      const ran = await scheduler.runNow(name);
+      if (!ran) {
+        const available = scheduler.names().join(", ") || "(none)";
+        io.error(`Unknown scheduled task "${name}". Available: ${available}.`);
+        return 1;
+      }
+      io.log(`Ran scheduled task "${name}".`);
+    }
+  });
+}
 export {
   CronParseError,
   SCHEDULER,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/scheduler",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Fluent Basalt scheduler: schedule.job(X).daily().at('03:00'), timezones, withoutOverlapping and @basaltkit/queue integration.",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,7 @@
   ],
   "dependencies": {
     "@basaltkit/core": "^1.0.0",
-    "@basaltkit/queue": "^1.0.0"
+    "@basaltkit/queue": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",