@apisurf/ngn-core 0.3.1 → 0.4.0

package/dist/core.d.ts

@@ -774,6 +774,13 @@ type Options$1 = {
     /** Called when a scheduled run throws, with the run it was recorded as when there is one. */
     onRunError?: (path: string, error: unknown, runId: number | null) => void;
 };
+/** What `runNow()` did: started a run, or why it did not. */
+type RunNowOutcome = {
+    started: true;
+} | {
+    started: false;
+    reason: string;
+};
 /** What `start()` did with each task: scheduled on its pattern, or left out and why. */
 interface ScheduleReport {
     scheduled: {
@@ -793,6 +800,17 @@ declare class TaskLibraryScheduler {
     start(): Promise<ScheduleReport>;
     stop(): Promise<void>;
     scheduleTask(task: Task): Promise<void>;
+    /**
+     * Start one run of a scheduled task now, outside its schedule, the way a tick
+     * would: retries, budget, locks and hooks all apply, and errors go where a
+     * tick's go. It is not a tick, so the breaker does not hold it back. Resolves
+     * once the run is under way, not when it ends: a run can take longer than
+     * anyone waits on a button.
+     *
+     * A run still going is reported rather than recorded as a skip, since nothing
+     * was due: the person asking can simply wait.
+     */
+    runNow(taskPath: string): RunNowOutcome;
     unscheduleTask(task: Task): void;
     isCronPatternValid(cronPattern: string): boolean;
 }
@@ -824,4 +842,4 @@ declare function createControlsGenerator({ dbClient, env, report, }: {
     report?: (problem: RunProblem) => void;
 }): BuildCompiledTaskConfigFn;
 
-export { type AddJob, type Backoff, type ClaimOptions, Compiler, type DBInstance, type Duration, type InitDBOptions, type Job, type JobFilter, type JobStatus, LockBusyError, type LockOptions, type Migration, type OverlapPolicy, Queue, type QueueOptions, type QueueStats, type RunProblem, type ScheduleReport, Task, type TaskContext, TaskLibrary, TaskLibraryScheduler, TaskOnceRunner, type TaskRun, type TaskSqlite, type WorkHandler, type WorkOptions, type WorkSummary, type WorkerHandle, closeTaskDatabases, createControlsGenerator, executeEsm, failedRunId, getDbClient, isCronPatternValid, releaseTaskDatabases, runFailure, scheduleTask, setupDbClient };
+export { type AddJob, type Backoff, type ClaimOptions, Compiler, type DBInstance, type Duration, type InitDBOptions, type Job, type JobFilter, type JobStatus, LockBusyError, type LockOptions, type Migration, type OverlapPolicy, Queue, type QueueOptions, type QueueStats, type RunNowOutcome, type RunProblem, type ScheduleReport, Task, type TaskContext, TaskLibrary, TaskLibraryScheduler, TaskOnceRunner, type TaskRun, type TaskSqlite, type WorkHandler, type WorkOptions, type WorkSummary, type WorkerHandle, closeTaskDatabases, createControlsGenerator, executeEsm, failedRunId, getDbClient, isCronPatternValid, releaseTaskDatabases, runFailure, scheduleTask, setupDbClient };

package/dist/core.js

@@ -385,10 +385,17 @@ function deadlineSignal(deadline) {
     return { signal: controller.signal, dispose: () => {
     } };
   }
-  const timer = setTimeout(abort, delay);
-  timer.unref();
+  let timer;
+  const arm = () => {
+    const left = deadline - Date.now();
+    if (left <= 0) return abort();
+    timer = setTimeout(arm, Math.min(left, MAX_TIMER_MS));
+    timer.unref();
+  };
+  arm();
   return { signal: controller.signal, dispose: () => clearTimeout(timer) };
 }
+var MAX_TIMER_MS = 2 ** 31 - 1;
 
 // src/runtime/locks.ts
 var LockBusyError = class extends Error {
@@ -1664,6 +1671,36 @@ var TaskLibraryScheduler = class {
     this.scheduledTasks.set(task.taskPath, scheduledTask);
     logTaskLibraryScheduler(`Scheduled: ${task.taskPath}`);
   }
+  /**
+   * Start one run of a scheduled task now, outside its schedule, the way a tick
+   * would: retries, budget, locks and hooks all apply, and errors go where a
+   * tick's go. It is not a tick, so the breaker does not hold it back. Resolves
+   * once the run is under way, not when it ends: a run can take longer than
+   * anyone waits on a button.
+   *
+   * A run still going is reported rather than recorded as a skip, since nothing
+   * was due: the person asking can simply wait.
+   */
+  runNow(taskPath) {
+    const task = this.taskLibrary.getTasks().find((t) => t.taskPath === taskPath);
+    const cron = this.scheduledTasks.get(taskPath);
+    if (!task || !cron) {
+      return { started: false, reason: `${taskPath} is not scheduled by this ngn run` };
+    }
+    if (task.isRunning && task.overlapPolicy === "skip") {
+      return { started: false, reason: "a run of it is still going" };
+    }
+    void tick(
+      task,
+      (error) => {
+        logTaskLibrarySchedulerError(`Run failed: ${task.taskPath}`);
+        logTaskLibrarySchedulerError(error);
+        this.onRunError?.(task.taskPath, error, failedRunId(error));
+      },
+      { scheduledAt: null, nextAt: cron.nextRun()?.getTime() ?? null }
+    );
+    return { started: true };
+  }
   unscheduleTask(task) {
     const existingTask = this.scheduledTasks.get(task.taskPath);
     if (!existingTask) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apisurf/ngn-core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "ngn runtime: task compilation, scheduling and the run/log/timing services.",
   "type": "module",
   "author": "Luka Vidakovic",
@@ -38,9 +38,9 @@
     "esbuild": "^0.27.1",
     "tiny-invariant": "^1.3.3",
     "zod": "^3.24.2",
-    "@apisurf/ngn-os": "0.3.1",
-    "@apisurf/ngn-schema": "0.3.1",
-    "@apisurf/ngn-persistence": "0.3.1"
+    "@apisurf/ngn-os": "0.4.0",
+    "@apisurf/ngn-persistence": "0.4.0",
+    "@apisurf/ngn-schema": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.8.1",