@qodalis/cli-server-jobs 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodalis/cli-server-jobs",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Background job management",
   "author": "Qodalis Solutions",
   "license": "MIT",
@@ -18,7 +18,7 @@
   "umd": "./umd/index.global.js",
   "unpkg": "./umd/index.global.js",
   "dependencies": {
-    "@qodalis/cli-core": "2.3.0"
+    "@qodalis/cli-core": "2.4.0"
   },
   "sideEffects": false,
   "main": "./public-api.js",

package/public-api.d.mts

@@ -1,52 +1,5 @@
 import { ICliCommandProcessor, ICliCommandAuthor, CliProcessorMetadata, CliProcessCommand, ICliExecutionContext, ICliCompletionProvider, ICliServiceProvider, ICliCompletionContext, ICliModule } from '@qodalis/cli-core';
 
-declare class CliJobsCommandProcessor implements ICliCommandProcessor {
-    command: string;
-    extendsProcessor: boolean;
-    description: string;
-    author: ICliCommandAuthor;
-    metadata: CliProcessorMetadata;
-    processors?: ICliCommandProcessor[];
-    processCommand(_cmd: CliProcessCommand, _context: ICliExecutionContext): Promise<void>;
-    private handleList;
-    private handleInfo;
-    /**
-     * Without --server the action applies to every connected server that has
-     * the job, each reported on its own line. When several servers have it,
-     * a note says so (and how to target one).
-     */
-    private handleAction;
-    private handleHistory;
-    private handleLogs;
-    /**
-     * Prompt for each setting; Enter keeps the current value. Ctrl+C or
-     * Escape at any prompt (the reader resolves null) cancels the whole edit
-     * and nothing is sent. A job on several servers needs --server.
-     */
-    private handleEdit;
-    /**
-     * Stream job events until Ctrl+C (context.onAbort / context.signal) or
-     * until every watched server has closed its connection. On exit the
-     * sockets are closed and every subscription and listener is removed.
-     */
-    private handleWatch;
-}
-
-/**
- * Provides tab-completion for job names when typing
- * `server jobs <subcommand> <name>`.
- *
- * Priority 50 — checked before command and parameter completion so that
- * job names are suggested instead of treating the value position as
- * a sub-command or flag.
- */
-declare class CliJobNameCompletionProvider implements ICliCompletionProvider {
-    priority: number;
-    private services;
-    setServices(services: ICliServiceProvider): void;
-    getCompletions(context: ICliCompletionContext): Promise<string[]>;
-}
-
 interface JobDto {
     id: string;
     name: string;
@@ -54,11 +7,20 @@ interface JobDto {
     group?: string;
     status: 'active' | 'paused' | 'stopped';
     schedule?: string;
-    interval?: number;
+    /** Milliseconds (.NET, Node) or a span such as `30s` (Python). */
+    interval?: number | string;
     maxRetries: number;
-    timeout?: number;
+    /** Milliseconds (.NET, Node) or a span such as `5m` (Python). */
+    timeout?: number | string;
     overlapPolicy: string;
+    /** Runs of the job that may go at the same time (servers 1.0.0-beta.23; 1 before). */
+    maxConcurrentRuns?: number;
+    /** The newest running run. */
     currentExecutionId?: string;
+    /** Every running run, oldest first (servers 1.0.0-beta.23). */
+    runningExecutionIds?: string[];
+    /** A run waits for a free slot (overlap policy `queue`). */
+    queued?: boolean;
     nextRunAt?: string;
     lastRunAt?: string;
     lastRunStatus?: string;
@@ -96,6 +58,61 @@ interface UpdateJobRequest {
     maxRetries?: number;
     timeout?: string;
     overlapPolicy?: string;
+    maxConcurrentRuns?: number;
+}
+
+/**
+ * An interval or timeout as servers send it: milliseconds (.NET, Node) or a
+ * span such as `30s` (Python), shown as `30s`, `5m`, `1h`.
+ */
+declare function formatSpan(value?: number | string | null): string | null;
+/** Runs going now, when more than one may run: `2/3 running`, `1/3 running, 1 queued`. */
+declare function formatRunning(job: JobDto): string | null;
+declare class CliJobsCommandProcessor implements ICliCommandProcessor {
+    command: string;
+    extendsProcessor: boolean;
+    description: string;
+    author: ICliCommandAuthor;
+    metadata: CliProcessorMetadata;
+    processors?: ICliCommandProcessor[];
+    processCommand(_cmd: CliProcessCommand, _context: ICliExecutionContext): Promise<void>;
+    private handleList;
+    private handleInfo;
+    /**
+     * Without --server the action applies to every connected server that has
+     * the job, each reported on its own line. When several servers have it,
+     * a note says so (and how to target one).
+     */
+    private handleAction;
+    private handleHistory;
+    private handleLogs;
+    /**
+     * Prompt for each setting; Enter keeps the current value. Ctrl+C or
+     * Escape at any prompt (the reader resolves null) cancels the whole edit
+     * and nothing is sent. A job on several servers needs --server.
+     */
+    private handleEdit;
+    /**
+     * Stream job events until Ctrl+C (context.onAbort / context.signal) or
+     * until every watched server has closed its connection. On exit the
+     * sockets are closed and every subscription and listener is removed.
+     */
+    private handleWatch;
+}
+
+/**
+ * Provides tab-completion for job names when typing
+ * `server jobs <subcommand> <name>`.
+ *
+ * Priority 50 — checked before command and parameter completion so that
+ * job names are suggested instead of treating the value position as
+ * a sub-command or flag.
+ */
+declare class CliJobNameCompletionProvider implements ICliCompletionProvider {
+    priority: number;
+    private services;
+    setServices(services: ICliServiceProvider): void;
+    getCompletions(context: ICliCompletionContext): Promise<string[]>;
 }
 
 declare class CliJobsService {
@@ -119,10 +136,10 @@ declare class CliJobsService {
     getExecution(jobId: string, execId: string): Promise<JobExecutionDto>;
 }
 
-declare const LIBRARY_VERSION = "2.3.0";
+declare const LIBRARY_VERSION = "2.4.0";
 declare const API_VERSION = 2;
 
 declare const jobsModule: ICliModule;
 
-export { API_VERSION, CliJobNameCompletionProvider, CliJobsCommandProcessor, CliJobsService, LIBRARY_VERSION, jobsModule };
+export { API_VERSION, CliJobNameCompletionProvider, CliJobsCommandProcessor, CliJobsService, LIBRARY_VERSION, formatRunning, formatSpan, jobsModule };
 export type { JobDto, JobExecutionDto, JobHistoryResponse, JobLogEntryDto, UpdateJobRequest };

package/public-api.d.ts

@@ -1,52 +1,5 @@
 import { ICliCommandProcessor, ICliCommandAuthor, CliProcessorMetadata, CliProcessCommand, ICliExecutionContext, ICliCompletionProvider, ICliServiceProvider, ICliCompletionContext, ICliModule } from '@qodalis/cli-core';
 
-declare class CliJobsCommandProcessor implements ICliCommandProcessor {
-    command: string;
-    extendsProcessor: boolean;
-    description: string;
-    author: ICliCommandAuthor;
-    metadata: CliProcessorMetadata;
-    processors?: ICliCommandProcessor[];
-    processCommand(_cmd: CliProcessCommand, _context: ICliExecutionContext): Promise<void>;
-    private handleList;
-    private handleInfo;
-    /**
-     * Without --server the action applies to every connected server that has
-     * the job, each reported on its own line. When several servers have it,
-     * a note says so (and how to target one).
-     */
-    private handleAction;
-    private handleHistory;
-    private handleLogs;
-    /**
-     * Prompt for each setting; Enter keeps the current value. Ctrl+C or
-     * Escape at any prompt (the reader resolves null) cancels the whole edit
-     * and nothing is sent. A job on several servers needs --server.
-     */
-    private handleEdit;
-    /**
-     * Stream job events until Ctrl+C (context.onAbort / context.signal) or
-     * until every watched server has closed its connection. On exit the
-     * sockets are closed and every subscription and listener is removed.
-     */
-    private handleWatch;
-}
-
-/**
- * Provides tab-completion for job names when typing
- * `server jobs <subcommand> <name>`.
- *
- * Priority 50 — checked before command and parameter completion so that
- * job names are suggested instead of treating the value position as
- * a sub-command or flag.
- */
-declare class CliJobNameCompletionProvider implements ICliCompletionProvider {
-    priority: number;
-    private services;
-    setServices(services: ICliServiceProvider): void;
-    getCompletions(context: ICliCompletionContext): Promise<string[]>;
-}
-
 interface JobDto {
     id: string;
     name: string;
@@ -54,11 +7,20 @@ interface JobDto {
     group?: string;
     status: 'active' | 'paused' | 'stopped';
     schedule?: string;
-    interval?: number;
+    /** Milliseconds (.NET, Node) or a span such as `30s` (Python). */
+    interval?: number | string;
     maxRetries: number;
-    timeout?: number;
+    /** Milliseconds (.NET, Node) or a span such as `5m` (Python). */
+    timeout?: number | string;
     overlapPolicy: string;
+    /** Runs of the job that may go at the same time (servers 1.0.0-beta.23; 1 before). */
+    maxConcurrentRuns?: number;
+    /** The newest running run. */
     currentExecutionId?: string;
+    /** Every running run, oldest first (servers 1.0.0-beta.23). */
+    runningExecutionIds?: string[];
+    /** A run waits for a free slot (overlap policy `queue`). */
+    queued?: boolean;
     nextRunAt?: string;
     lastRunAt?: string;
     lastRunStatus?: string;
@@ -96,6 +58,61 @@ interface UpdateJobRequest {
     maxRetries?: number;
     timeout?: string;
     overlapPolicy?: string;
+    maxConcurrentRuns?: number;
+}
+
+/**
+ * An interval or timeout as servers send it: milliseconds (.NET, Node) or a
+ * span such as `30s` (Python), shown as `30s`, `5m`, `1h`.
+ */
+declare function formatSpan(value?: number | string | null): string | null;
+/** Runs going now, when more than one may run: `2/3 running`, `1/3 running, 1 queued`. */
+declare function formatRunning(job: JobDto): string | null;
+declare class CliJobsCommandProcessor implements ICliCommandProcessor {
+    command: string;
+    extendsProcessor: boolean;
+    description: string;
+    author: ICliCommandAuthor;
+    metadata: CliProcessorMetadata;
+    processors?: ICliCommandProcessor[];
+    processCommand(_cmd: CliProcessCommand, _context: ICliExecutionContext): Promise<void>;
+    private handleList;
+    private handleInfo;
+    /**
+     * Without --server the action applies to every connected server that has
+     * the job, each reported on its own line. When several servers have it,
+     * a note says so (and how to target one).
+     */
+    private handleAction;
+    private handleHistory;
+    private handleLogs;
+    /**
+     * Prompt for each setting; Enter keeps the current value. Ctrl+C or
+     * Escape at any prompt (the reader resolves null) cancels the whole edit
+     * and nothing is sent. A job on several servers needs --server.
+     */
+    private handleEdit;
+    /**
+     * Stream job events until Ctrl+C (context.onAbort / context.signal) or
+     * until every watched server has closed its connection. On exit the
+     * sockets are closed and every subscription and listener is removed.
+     */
+    private handleWatch;
+}
+
+/**
+ * Provides tab-completion for job names when typing
+ * `server jobs <subcommand> <name>`.
+ *
+ * Priority 50 — checked before command and parameter completion so that
+ * job names are suggested instead of treating the value position as
+ * a sub-command or flag.
+ */
+declare class CliJobNameCompletionProvider implements ICliCompletionProvider {
+    priority: number;
+    private services;
+    setServices(services: ICliServiceProvider): void;
+    getCompletions(context: ICliCompletionContext): Promise<string[]>;
 }
 
 declare class CliJobsService {
@@ -119,10 +136,10 @@ declare class CliJobsService {
     getExecution(jobId: string, execId: string): Promise<JobExecutionDto>;
 }
 
-declare const LIBRARY_VERSION = "2.3.0";
+declare const LIBRARY_VERSION = "2.4.0";
 declare const API_VERSION = 2;
 
 declare const jobsModule: ICliModule;
 
-export { API_VERSION, CliJobNameCompletionProvider, CliJobsCommandProcessor, CliJobsService, LIBRARY_VERSION, jobsModule };
+export { API_VERSION, CliJobNameCompletionProvider, CliJobsCommandProcessor, CliJobsService, LIBRARY_VERSION, formatRunning, formatSpan, jobsModule };
 export type { JobDto, JobExecutionDto, JobHistoryResponse, JobLogEntryDto, UpdateJobRequest };

package/public-api.js

@@ -168,6 +168,24 @@ function formatRelativeTime(isoString) {
   if (diff < 864e5) return `${Math.round(diff / 36e5)}h ago`;
   return `${Math.round(diff / 864e5)}d ago`;
 }
+function formatSpan(value) {
+  if (value === null || value === void 0 || value === "") return null;
+  if (typeof value === "string") return value;
+  if (!Number.isFinite(value) || value < 0) return null;
+  const units = [[864e5, "d"], [36e5, "h"], [6e4, "m"], [1e3, "s"]];
+  for (const [size, unit] of units) {
+    if (value >= size && value % size === 0) return `${value / size}${unit}`;
+  }
+  return value >= 1e3 ? `${(value / 1e3).toFixed(1)}s` : `${value}ms`;
+}
+function formatRunning(job) {
+  const running = job.runningExecutionIds?.length ?? (job.currentExecutionId ? 1 : 0);
+  const max = job.maxConcurrentRuns ?? 1;
+  if (running === 0 && !job.queued) return null;
+  const parts = [max > 1 ? `${running}/${max} running` : `${running} running`];
+  if (job.queued) parts.push("1 queued");
+  return parts.join(", ");
+}
 function formatDuration(ms) {
   if (ms == null) return "-";
   if (ms < 1e3) return `${ms}ms`;
@@ -533,6 +551,11 @@ var CliJobsCommandProcessor = class {
                 t.t("cli.server.jobs.edit.help.change_job_step_step", "Change a job step by step: description, group, cron schedule or interval, max retries, timeout and overlap policy (skip, queue or cancel). Press Enter to keep a value and Ctrl+C or Escape to cancel; nothing changes until you confirm. A job on several servers needs --server.")
               );
               context.writer.writeln();
+              cliCore.writeWrapped(
+                context,
+                t.t("cli.server.jobs.edit.help.max_concurrent_runs", "Max concurrent runs: how many runs of the job may go at the same time (1 by default). When that many are running, the overlap policy decides what happens to the next one.")
+              );
+              context.writer.writeln();
               cliCore.writeUsage(context, [
                 ["server jobs edit <name|id>", ""]
               ]);
@@ -624,7 +647,7 @@ var CliJobsCommandProcessor = class {
           j.name,
           j.group ?? "-",
           statusColor(j.status, context.writer),
-          j.schedule ?? (j.interval ? `every ${j.interval}ms` : "-"),
+          j.schedule ?? (formatSpan(j.interval) ? `every ${formatSpan(j.interval)}` : "-"),
           formatRelativeTime(j.lastRunAt),
           formatRelativeTime(j.nextRunAt),
           formatDuration(j.lastRunDuration)
@@ -662,12 +685,16 @@ var CliJobsCommandProcessor = class {
         ["Status", statusColor(job.status, context.writer)],
         [
           "Schedule",
-          job.schedule ?? (job.interval ? `every ${job.interval}ms` : "-")
+          job.schedule ?? (formatSpan(job.interval) ? `every ${formatSpan(job.interval)}` : "-")
         ],
         ["Max Retries", String(job.maxRetries)],
-        ["Timeout", job.timeout ? `${job.timeout}ms` : "none"],
+        ["Timeout", formatSpan(job.timeout) ?? "none"],
         ["Overlap Policy", job.overlapPolicy],
-        ["Current Execution", job.currentExecutionId ?? "none"],
+        ["Max Concurrent Runs", String(job.maxConcurrentRuns ?? 1)],
+        [
+          "Running",
+          job.runningExecutionIds && job.runningExecutionIds.length > 1 ? `${formatRunning(job)}: ${job.runningExecutionIds.join(", ")}` : formatRunning(job) && job.currentExecutionId ? `${formatRunning(job)} (${job.currentExecutionId})` : formatRunning(job) ?? "none"
+        ],
         ["Next Run", formatRelativeTime(job.nextRunAt)],
         ["Last Run", formatRelativeTime(job.lastRunAt)],
         [
@@ -911,7 +938,7 @@ var CliJobsCommandProcessor = class {
       const newGroup = await ask(`Group [${job.group ?? "none"}]: `);
       if (newGroup == null) return cancelled();
       if (newGroup) update.group = newGroup;
-      const currentSchedule = job.schedule ?? (job.interval ? `interval: ${job.interval}ms` : "none");
+      const currentSchedule = job.schedule ?? (formatSpan(job.interval) ? `interval: ${formatSpan(job.interval)}` : "none");
       const newSchedule = await ask(
         `Cron schedule [${currentSchedule}]: `
       );
@@ -919,7 +946,7 @@ var CliJobsCommandProcessor = class {
       if (newSchedule) update.schedule = newSchedule;
       if (!newSchedule) {
         const newInterval = await ask(
-          `Interval (e.g. 30s, 5m) [${job.interval ? `${job.interval}ms` : "none"}]: `
+          `Interval (e.g. 30s, 5m) [${formatSpan(job.interval) ?? "none"}]: `
         );
         if (newInterval == null) return cancelled();
         if (newInterval) update.interval = newInterval;
@@ -933,7 +960,7 @@ var CliJobsCommandProcessor = class {
         }
       }
       const newTimeout = await ask(
-        `Timeout (e.g. 5m, 1h) [${job.timeout ? `${job.timeout}ms` : "none"}]: `
+        `Timeout (e.g. 5m, 1h) [${formatSpan(job.timeout) ?? "none"}]: `
       );
       if (newTimeout == null) return cancelled();
       if (newTimeout) update.timeout = newTimeout;
@@ -944,6 +971,20 @@ var CliJobsCommandProcessor = class {
       if (newOverlap && ["skip", "queue", "cancel"].includes(newOverlap.toLowerCase())) {
         update.overlapPolicy = newOverlap.toLowerCase();
       }
+      const newMax = await ask(
+        `Max concurrent runs [${job.maxConcurrentRuns ?? 1}]: `
+      );
+      if (newMax == null) return cancelled();
+      if (newMax) {
+        const parsed = Number(newMax);
+        if (Number.isInteger(parsed) && parsed >= 1) {
+          update.maxConcurrentRuns = parsed;
+        } else {
+          context.writer.writeWarning(
+            "Max concurrent runs must be a whole number of at least 1; kept as it was."
+          );
+        }
+      }
       if (Object.keys(update).length === 0) {
         context.writer.writeInfo("No changes made.");
         return;
@@ -1177,7 +1218,7 @@ var CliJobNameCompletionProvider = class {
 };
 
 // src/lib/version.ts
-var LIBRARY_VERSION = "2.3.0";
+var LIBRARY_VERSION = "2.4.0";
 var API_VERSION = 2;
 var completionProvider = new CliJobNameCompletionProvider();
 var jobsModule = {
@@ -1201,6 +1242,8 @@ exports.CliJobNameCompletionProvider = CliJobNameCompletionProvider;
 exports.CliJobsCommandProcessor = CliJobsCommandProcessor;
 exports.CliJobsService = CliJobsService;
 exports.LIBRARY_VERSION = LIBRARY_VERSION;
+exports.formatRunning = formatRunning;
+exports.formatSpan = formatSpan;
 exports.jobsModule = jobsModule;
 //# sourceMappingURL=public-api.js.map
 //# sourceMappingURL=public-api.js.map