@valentinkolb/sync 2.1.1 → 2.1.2

package/README.md

@@ -351,6 +351,11 @@ await sched.register({
   misfire: "skip",         // default: do not replay backlog
   meta: { owner: "ops" },
 });
+
+await sched.triggerNow({
+  id: "cleanup-hourly",
+  key: "ops-manual-run-1", // optional but recommended for retry-safe manual triggers
+});
 ```
 
 ### Scheduler features
@@ -358,10 +363,16 @@ await sched.register({
 - **Idempotent upsert registration**: repeated `register({ id, ... })` creates once, then updates in place.
 - **No fixed leader pod**: leadership uses a renewable Redis lease (`mutex`) with epoch fencing.
 - **Durable dispatch**: each cron slot maps to deterministic job key (`scheduleId:slotTs`) to prevent duplicates.
+- **Durable manual trigger**: `triggerNow({ id, key? })` submits immediately through the same durable job path. Durability begins once `triggerNow()` returns a `jobId`.
 - **Misfire policies**: `skip` (default), `catch_up_one`, `catch_up_all` with cap (`maxCatchUpRuns`).
 - **Failure isolation**: submit retry + backoff, dispatch DLQ, configurable threshold for auto-advance after repeated failures.
 - **Handler safety**: optional `strictHandlers` mode (default `true`) relinquishes leadership when required handlers are missing.
 
+Manual trigger notes:
+- `triggerNow()` does not require `start()` and does not alter cron state (`nextRunAt`, misfire handling, due slots).
+- `triggerNow()` reuses the registered schedule input. If you need custom input per run, call the underlying `job.submit(...)` directly.
+- Pass `key` for retry-safe idempotent manual triggering. Without `key`, repeated calls create additional runs.
+
 ## Ephemeral
 
 Typed ephemeral key/value store with TTL semantics and stream events. Useful for short-lived state like presence, worker heartbeats, or temporary coordination hints.

package/index.d.ts

@@ -3,6 +3,6 @@ export { mutex, LockError, type Mutex, type Lock, type MutexConfig } from "./src
 export { queue, type Queue, type QueueConfig, type QueueReader, type QueueRecvConfig, type QueueSendConfig, type QueueReceived, } from "./src/queue";
 export { topic, type Topic, type TopicConfig, type TopicReader, type TopicRecvConfig, type TopicPubConfig, type TopicDelivery, type TopicLiveConfig, type TopicLiveEvent, } from "./src/topic";
 export { job, type JobId, type JobStatus, type JobTerminal, type SubmitOptions, type JoinOptions, type CancelOptions, type JobEvent, type JobEvents, type JobContext, type JobHandle, type JobDefinition, } from "./src/job";
-export { scheduler, type Scheduler, type SchedulerConfig, type SchedulerRegisterConfig, type SchedulerUnregisterConfig, type SchedulerGetConfig, type SchedulerInfo, type SchedulerMetric, type SchedulerMetricsSnapshot, } from "./src/scheduler";
+export { scheduler, type Scheduler, type SchedulerConfig, type SchedulerRegisterConfig, type SchedulerUnregisterConfig, type SchedulerTriggerNowConfig, type SchedulerGetConfig, type SchedulerInfo, type SchedulerMetric, type SchedulerMetricsSnapshot, } from "./src/scheduler";
 export { ephemeral, EphemeralCapacityError, EphemeralPayloadTooLargeError, type EphemeralConfig, type EphemeralUpsertConfig, type EphemeralTouchConfig, type EphemeralRemoveConfig, type EphemeralEntry, type EphemeralSnapshot, type EphemeralRecvConfig, type EphemeralEvent, type EphemeralReader, type EphemeralStore, } from "./src/ephemeral";
 export { retry, isRetryableTransportError, DEFAULT_RETRY_OPTIONS, type RetryOptions, } from "./src/retry";

package/index.js

@@ -15745,6 +15745,9 @@ var scheduler = (config2) => {
     dispatchRetried: 0,
     dispatchSkipped: 0,
     dispatchDlq: 0,
+    triggerSubmitted: 0,
+    triggerFailed: 0,
+    triggerRejected: 0,
     tickErrors: 0,
     lastTickAt: null
   };
@@ -15884,22 +15887,17 @@ var scheduler = (config2) => {
       message: cfg.message
     });
   };
-  const submitWithRetry = async (cfg) => {
-    await retry(async () => {
-      if (!await ensureLeadership({ forceRefresh: true })) {
+  const submitScheduledJob = async (cfg) => {
+    return await retry(async () => {
+      if (cfg.requireLeadership && !await ensureLeadership({ forceRefresh: true })) {
         throw new Error("leadership lost during dispatch");
       }
       return await cfg.jobHandle.submit({
         input: cfg.schedule.input,
-        key: `${cfg.schedule.id}:${cfg.slotTs}`,
+        key: cfg.key,
         keyTtlMs: scheduledJobKeyTtlMs,
-        at: cfg.slotTs,
-        meta: {
-          ...cfg.schedule.meta ?? {},
-          scheduleId: cfg.schedule.id,
-          scheduleSlotTs: cfg.slotTs,
-          schedulerId: config2.id
-        }
+        ...cfg.at !== undefined ? { at: cfg.at } : {},
+        meta: cfg.meta
       });
     }, {
       attempts: submitRetries + 1,
@@ -15911,9 +15909,9 @@ var scheduler = (config2) => {
         const err = asError4(error48);
         if (err.name === "ZodError")
           return false;
-        if (err.message === "leadership lost during dispatch")
+        if (cfg.requireLeadership && err.message === "leadership lost during dispatch")
           return false;
-        metricsState.dispatchRetried += 1;
+        cfg.onRetry?.();
         return true;
       }
     });
@@ -16000,10 +15998,21 @@ var scheduler = (config2) => {
           break;
         }
         try {
-          await submitWithRetry({
+          const jobId = await submitScheduledJob({
             jobHandle,
             schedule,
-            slotTs
+            key: `${schedule.id}:${slotTs}`,
+            at: slotTs,
+            meta: {
+              ...schedule.meta ?? {},
+              scheduleId: schedule.id,
+              scheduleSlotTs: slotTs,
+              schedulerId: config2.id
+            },
+            requireLeadership: true,
+            onRetry: () => {
+              metricsState.dispatchRetried += 1;
+            }
           });
           metricsState.dispatchSubmitted += 1;
           submitsRemaining -= 1;
@@ -16014,7 +16023,7 @@ var scheduler = (config2) => {
             ts: Date.now(),
             scheduleId: schedule.id,
             slotTs,
-            jobId: schedule.jobId
+            jobId
           });
         } catch (error48) {
           submitFailed = true;
@@ -16188,6 +16197,74 @@ var scheduler = (config2) => {
         jobsById.delete(jobId);
     }
   };
+  const triggerNow = async (cfg) => {
+    const raw = await redis6.get(scheduleKey(cfg.id));
+    if (!raw) {
+      metricsState.triggerRejected += 1;
+      safeMetric(config2.onMetric, {
+        type: "trigger_rejected",
+        ts: Date.now(),
+        scheduleId: cfg.id,
+        reason: "missing_schedule"
+      });
+      throw new Error(`scheduler trigger rejected: missing schedule ${cfg.id}`);
+    }
+    const schedule = parseSchedule(raw);
+    if (!schedule) {
+      metricsState.triggerRejected += 1;
+      safeMetric(config2.onMetric, {
+        type: "trigger_rejected",
+        ts: Date.now(),
+        scheduleId: cfg.id,
+        reason: "invalid_schedule"
+      });
+      throw new Error(`scheduler trigger rejected: invalid schedule ${cfg.id}`);
+    }
+    const jobHandle = jobsById.get(schedule.jobId);
+    if (!jobHandle) {
+      metricsState.triggerRejected += 1;
+      safeMetric(config2.onMetric, {
+        type: "trigger_rejected",
+        ts: Date.now(),
+        scheduleId: schedule.id,
+        reason: "missing_handler"
+      });
+      throw new Error(`scheduler trigger rejected: missing local handler for schedule ${schedule.id}`);
+    }
+    try {
+      const jobId = await submitScheduledJob({
+        jobHandle,
+        schedule,
+        key: cfg.key ? `manual:${schedule.id}:${cfg.key}` : undefined,
+        meta: {
+          ...schedule.meta ?? {},
+          scheduleId: schedule.id,
+          schedulerId: config2.id,
+          scheduleTrigger: "manual",
+          ...cfg.key ? { scheduleManualKey: cfg.key } : {}
+        },
+        requireLeadership: false
+      });
+      metricsState.triggerSubmitted += 1;
+      safeMetric(config2.onMetric, {
+        type: "trigger_submitted",
+        ts: Date.now(),
+        scheduleId: schedule.id,
+        jobId
+      });
+      return jobId;
+    } catch (error48) {
+      metricsState.triggerFailed += 1;
+      const err = asError4(error48);
+      safeMetric(config2.onMetric, {
+        type: "trigger_failed",
+        ts: Date.now(),
+        scheduleId: schedule.id,
+        message: err.message
+      });
+      throw err;
+    }
+  };
   const get = async (cfg) => {
     const raw = await redis6.get(scheduleKey(cfg.id));
     const parsed = parseSchedule(raw);
@@ -16241,6 +16318,7 @@ var scheduler = (config2) => {
     stop,
     register,
     unregister,
+    triggerNow,
     get,
     list,
     metrics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/sync",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Distributed synchronization primitives for Bun and TypeScript",
   "main": "index.js",
   "module": "index.js",

package/src/scheduler.d.ts

@@ -63,6 +63,21 @@ export type SchedulerMetric = {
     scheduleId: string;
     slotTs: number;
     failures: number;
+} | {
+    type: "trigger_submitted";
+    ts: number;
+    scheduleId: string;
+    jobId: string;
+} | {
+    type: "trigger_rejected";
+    ts: number;
+    scheduleId: string;
+    reason: "missing_schedule" | "missing_handler" | "invalid_schedule";
+} | {
+    type: "trigger_failed";
+    ts: number;
+    scheduleId: string;
+    message: string;
 };
 export type SchedulerConfig = {
     id: string;
@@ -98,6 +113,10 @@ export type SchedulerRegisterConfig = {
 export type SchedulerUnregisterConfig = {
     id: string;
 };
+export type SchedulerTriggerNowConfig = {
+    id: string;
+    key?: string;
+};
 export type SchedulerGetConfig = {
     id: string;
 };
@@ -121,6 +140,9 @@ export type SchedulerMetricsSnapshot = {
     dispatchRetried: number;
     dispatchSkipped: number;
     dispatchDlq: number;
+    triggerSubmitted: number;
+    triggerFailed: number;
+    triggerRejected: number;
     tickErrors: number;
     lastTickAt: number | null;
 };
@@ -133,6 +155,7 @@ export type Scheduler = {
         updated: boolean;
     }>;
     unregister(cfg: SchedulerUnregisterConfig): Promise<void>;
+    triggerNow(cfg: SchedulerTriggerNowConfig): Promise<string>;
     get(cfg: SchedulerGetConfig): Promise<SchedulerInfo | null>;
     list(): Promise<SchedulerInfo[]>;
     metrics(): SchedulerMetricsSnapshot;