@lunora/scheduler 1.0.0-alpha.8 → 1.0.0-alpha.9

package/dist/index.d.mts

@@ -45,6 +45,15 @@ interface WorkflowReference<Params = Record<string, unknown>> {
 type CronTarget = FunctionReference | WorkflowReference;
 /** The arguments a cron's target accepts: a workflow's inferred `params`, else an open record (function args aren't inferred). */
 type CronTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : Record<string, unknown>;
+/**
+* The arguments a one-shot schedule target ({@link Scheduler.runAfter} /
+* {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it preserves a
+* {@link FunctionReference}'s inferred `args` (via {@link ArgsOf}) as well as a
+* {@link WorkflowReference}'s inferred `params`, so scheduling a plain function
+* keeps its today's arg checking while scheduling a workflow/agent infers its
+* `params`.
+*/
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : Record<string, unknown>;
 /** Narrow a {@link CronTarget} to a {@link WorkflowReference} by its runtime brand. */
 declare const isWorkflowReference: (target: unknown) => target is WorkflowReference;
 /**
@@ -93,7 +102,12 @@ interface ScheduleRecord {
   */
   attempts?: number;
   enqueuedAt: number;
-  functionPath: string;
+  /**
+  * The `ns:fn` path of the function to dispatch on fire. Absent when the job
+  * targets a durable workflow/agent instead — see {@link ScheduleRecord.workflow}.
+  * Exactly one of `functionPath` / `workflow` is set.
+  */
+  functionPath?: string;
   id: string;
   /**
   * Scheduler/workpool instance name the job was enqueued through. Echoed in
@@ -113,6 +127,14 @@ interface ScheduleRecord {
   retry?: RetryPolicy;
   scheduledFor: number;
   shardKey?: string;
+  /**
+  * The `WORKFLOW_*`/`AGENT_*` binding name to start a fresh durable instance
+  * of on fire (the {@link ScheduleRecord.args} become its `params`). Set
+  * instead of {@link ScheduleRecord.functionPath} when the job targets a
+  * workflow/agent {@link WorkflowReference}. The runtime — not the DO — owns
+  * the binding, so the dispatch payload carries this through to the Worker.
+  */
+  workflow?: string;
 }
 interface Scheduler {
   cancel: (id: string) => Promise<{
@@ -122,11 +144,20 @@ interface Scheduler {
   get: (id: string) => Promise<ScheduleRecord | null>;
   /** All pending scheduled jobs (the DO's `/list` view). */
   list: () => Promise<ScheduleRecord[]>;
-  runAfter: <F extends FunctionReference>(delayMs: number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /**
+  * Schedule `target` to run once, `delayMs` from now. `target` is a function
+  * {@link FunctionReference} (dispatched as a one-shot) or a durable
+  * {@link WorkflowReference} — the generated `workflows.&lt;name>` /
+  * `agents.&lt;name>` ref — which starts a fresh instance on fire (args become
+  * its `params`). {@link ScheduleTargetArgs} infers the accepted args from
+  * whichever target was passed.
+  */
+  runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
-  runAt: <F extends FunctionReference>(date: Date | number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. */
+  runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
@@ -617,6 +648,13 @@ declare class SchedulerDO {
   * compatibility shim, not the hot path.
   */
   private static releaseFirstSlot;
+  /**
+  * Normalize the mutually-exclusive dispatch target off an untrusted body: a
+  * one-shot function path (`functionPath`) or a durable workflow/agent
+  * instance (`workflow`, a `WORKFLOW_*`/`AGENT_*` binding). Returns `undefined`
+  * when neither is present so the caller can reject the schedule.
+  */
+  private static resolveScheduleTarget;
   protected readonly state: SchedulerDOState;
   protected readonly env: SchedulerEnv;
   constructor(state: SchedulerDOState, env: SchedulerEnv);

package/dist/index.d.ts

@@ -45,6 +45,15 @@ interface WorkflowReference<Params = Record<string, unknown>> {
 type CronTarget = FunctionReference | WorkflowReference;
 /** The arguments a cron's target accepts: a workflow's inferred `params`, else an open record (function args aren't inferred). */
 type CronTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : Record<string, unknown>;
+/**
+* The arguments a one-shot schedule target ({@link Scheduler.runAfter} /
+* {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it preserves a
+* {@link FunctionReference}'s inferred `args` (via {@link ArgsOf}) as well as a
+* {@link WorkflowReference}'s inferred `params`, so scheduling a plain function
+* keeps its today's arg checking while scheduling a workflow/agent infers its
+* `params`.
+*/
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : Record<string, unknown>;
 /** Narrow a {@link CronTarget} to a {@link WorkflowReference} by its runtime brand. */
 declare const isWorkflowReference: (target: unknown) => target is WorkflowReference;
 /**
@@ -93,7 +102,12 @@ interface ScheduleRecord {
   */
   attempts?: number;
   enqueuedAt: number;
-  functionPath: string;
+  /**
+  * The `ns:fn` path of the function to dispatch on fire. Absent when the job
+  * targets a durable workflow/agent instead — see {@link ScheduleRecord.workflow}.
+  * Exactly one of `functionPath` / `workflow` is set.
+  */
+  functionPath?: string;
   id: string;
   /**
   * Scheduler/workpool instance name the job was enqueued through. Echoed in
@@ -113,6 +127,14 @@ interface ScheduleRecord {
   retry?: RetryPolicy;
   scheduledFor: number;
   shardKey?: string;
+  /**
+  * The `WORKFLOW_*`/`AGENT_*` binding name to start a fresh durable instance
+  * of on fire (the {@link ScheduleRecord.args} become its `params`). Set
+  * instead of {@link ScheduleRecord.functionPath} when the job targets a
+  * workflow/agent {@link WorkflowReference}. The runtime — not the DO — owns
+  * the binding, so the dispatch payload carries this through to the Worker.
+  */
+  workflow?: string;
 }
 interface Scheduler {
   cancel: (id: string) => Promise<{
@@ -122,11 +144,20 @@ interface Scheduler {
   get: (id: string) => Promise<ScheduleRecord | null>;
   /** All pending scheduled jobs (the DO's `/list` view). */
   list: () => Promise<ScheduleRecord[]>;
-  runAfter: <F extends FunctionReference>(delayMs: number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /**
+  * Schedule `target` to run once, `delayMs` from now. `target` is a function
+  * {@link FunctionReference} (dispatched as a one-shot) or a durable
+  * {@link WorkflowReference} — the generated `workflows.&lt;name>` /
+  * `agents.&lt;name>` ref — which starts a fresh instance on fire (args become
+  * its `params`). {@link ScheduleTargetArgs} infers the accepted args from
+  * whichever target was passed.
+  */
+  runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
-  runAt: <F extends FunctionReference>(date: Date | number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. */
+  runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
@@ -617,6 +648,13 @@ declare class SchedulerDO {
   * compatibility shim, not the hot path.
   */
   private static releaseFirstSlot;
+  /**
+  * Normalize the mutually-exclusive dispatch target off an untrusted body: a
+  * one-shot function path (`functionPath`) or a durable workflow/agent
+  * instance (`workflow`, a `WORKFLOW_*`/`AGENT_*` binding). Returns `undefined`
+  * when neither is present so the caller can reject the schedule.
+  */
+  private static resolveScheduleTarget;
   protected readonly state: SchedulerDOState;
   protected readonly env: SchedulerEnv;
   constructor(state: SchedulerDOState, env: SchedulerEnv);

package/dist/index.mjs

@@ -1,8 +1,8 @@
-export { default as createScheduler } from './packem_shared/createScheduler-DGVqs2Ft.mjs';
+export { default as createScheduler } from './packem_shared/createScheduler-Df9JUjQb.mjs';
 export { default as createWorkpool } from './packem_shared/createWorkpool-Ce0kNM2p.mjs';
 export { createCronTrigger } from './packem_shared/createCronTrigger-Dh4VLxD9.mjs';
 export { CRON_SCHEDULE_KINDS, compileCronSchedule, cronJobs } from './packem_shared/CRON_SCHEDULE_KINDS-C2FflEnq.mjs';
 export { createQueueConsumer, createQueueWorkpool, httpDispatcher } from './packem_shared/createQueueConsumer-Cy-Mp-El.mjs';
-export { SchedulerDO } from './packem_shared/SchedulerDO-DbXUK1Qa.mjs';
+export { SchedulerDO } from './packem_shared/SchedulerDO-DeJHI379.mjs';
 export { isWorkflowReference } from './packem_shared/isWorkflowReference-C9mQkMXt.mjs';
 export { assertValidCronExpression, isValidCronExpression } from './packem_shared/assertValidCronExpression-B9m75qU0.mjs';

package/dist/packem_shared/{SchedulerDO-DbXUK1Qa.mjs → SchedulerDO-DeJHI379.mjs}

@@ -102,6 +102,20 @@ class SchedulerDO {
     const next = pool.inFlightIds.slice(0, Math.max(0, pool.inFlightIds.length - 1));
     return { ...pool, inFlight: next.length, inFlightIds: next };
   }
+  /**
+   * Normalize the mutually-exclusive dispatch target off an untrusted body: a
+   * one-shot function path (`functionPath`) or a durable workflow/agent
+   * instance (`workflow`, a `WORKFLOW_*`/`AGENT_*` binding). Returns `undefined`
+   * when neither is present so the caller can reject the schedule.
+   */
+  static resolveScheduleTarget(body) {
+    const functionPath = typeof body?.functionPath === "string" && body.functionPath.length > 0 ? body.functionPath : void 0;
+    const workflow = typeof body?.workflow === "string" && body.workflow.length > 0 ? body.workflow : void 0;
+    if (functionPath === void 0 && workflow === void 0) {
+      return void 0;
+    }
+    return { functionPath, workflow };
+  }
   state;
   env;
   constructor(state, env) {
@@ -211,7 +225,12 @@ class SchedulerDO {
       // so the pool's concurrency slot is released — see handleComplete().
       pool: record.pool,
       scheduledFor: record.scheduledFor,
-      shardKey: record.shardKey
+      shardKey: record.shardKey,
+      // Present instead of `functionPath` for a workflow/agent target; the
+      // runtime starts a fresh instance of this binding. `undefined` when
+      // absent, so JSON.stringify drops it and the payload is unchanged for
+      // ordinary function dispatches.
+      workflow: record.workflow
     });
     try {
       const headers = { "content-type": "application/json" };
@@ -408,7 +427,9 @@ class SchedulerDO {
     if (attempts > maxAttempts) {
       await this.state.storage.put(`${DEAD_PREFIX}${record.id}`, { ...record, attempts });
       await this.state.storage.delete([`${RETRY_PREFIX}${record.id}`, `${HEADER_PREFIX}${record.id}`]);
-      console.warn(`@lunora/scheduler: job "${record.id}" (${record.functionPath}) parked in dead-letter after ${String(attempts)} attempts`);
+      console.warn(
+        `@lunora/scheduler: job "${record.id}" (${record.functionPath ?? record.workflow ?? "unknown"}) parked in dead-letter after ${String(attempts)} attempts`
+      );
       return;
     }
     const rawDelay = backoff === "linear" ? baseMs * attempts : baseMs * 2 ** (attempts - 1);
@@ -524,9 +545,11 @@ class SchedulerDO {
   }
   async handleSchedule(request) {
     const body = await request.json().catch(() => void 0);
-    if (!body || typeof body.functionPath !== "string") {
-      return SchedulerDO.error(400, "INVALID_INPUT", "functionPath is required");
+    const target = SchedulerDO.resolveScheduleTarget(body);
+    if (!body || target === void 0) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "functionPath or workflow is required");
     }
+    const { functionPath, workflow } = target;
     if (typeof body.scheduledFor !== "number" || !Number.isInteger(body.scheduledFor) || body.scheduledFor <= 0 || body.scheduledFor > MAX_SCHEDULED_FOR_MS) {
       return SchedulerDO.error(400, "INVALID_INPUT", "scheduledFor must be a positive integer epoch-millisecond number no greater than 999999999999999");
     }
@@ -543,13 +566,14 @@ class SchedulerDO {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- parsed wire data can omit args
       args: body.args ?? {},
       enqueuedAt: Date.now(),
-      functionPath: body.functionPath,
       id,
+      ...functionPath === void 0 ? {} : { functionPath },
       ...instanceName === void 0 ? {} : { instanceName },
       ...pool === void 0 ? {} : { pool },
       ...retry === void 0 ? {} : { retry },
       scheduledFor: body.scheduledFor,
-      shardKey: body.shardKey
+      shardKey: body.shardKey,
+      ...workflow === void 0 ? {} : { workflow }
     };
     if (pool !== void 0) {
       const current = await this.loadPool(pool, body.maxConcurrency);

package/dist/packem_shared/{createScheduler-DGVqs2Ft.mjs → createScheduler-Df9JUjQb.mjs}

@@ -1,5 +1,6 @@
 import { LunoraError } from '@lunora/errors';
 import { c as callDO, g as getDO } from './do-client-CMJtLoHO.mjs';
+import { isWorkflowReference } from './isWorkflowReference-C9mQkMXt.mjs';
 
 const createScheduler = (options) => {
   if (!options.namespace) {
@@ -8,26 +9,33 @@ const createScheduler = (options) => {
   if (!options.originUrl) {
     throw new LunoraError("INTERNAL", "@lunora/scheduler: `originUrl` is required so the DO can dispatch back to the Worker");
   }
-  const runAt = async (date, function_, args, options_ = {}) => {
+  const runAt = async (date, target, args, options_ = {}) => {
     const scheduledFor = date instanceof Date ? date.getTime() : date;
-    return callDO(options, "/schedule", {
+    const base = {
       args,
-      functionPath: function_.__lunoraRef,
       originUrl: options.originUrl,
-      // Optional workpool / retry-policy passthrough. Absent for ordinary
-      // `runAfter`/`runAt` calls, which keeps the wire payload (and the
-      // DO's behaviour) identical to before this feature.
       pool: options_.pool,
       retry: options_.retry,
       scheduledFor,
       shardKey: options_.shardKey
-    });
+    };
+    if (isWorkflowReference(target)) {
+      if (typeof target.binding !== "string" || target.binding.length === 0) {
+        throw new LunoraError(
+          "INTERNAL",
+          "@lunora/scheduler: workflow/agent schedule target is missing its `binding` — pass the generated `workflows.<name>` / `agents.<name>` reference"
+        );
+      }
+      return callDO(options, "/schedule", { ...base, workflow: target.binding });
+    }
+    const functionPath = typeof target === "string" ? target : target.__lunoraRef;
+    return callDO(options, "/schedule", { ...base, functionPath });
   };
-  const runAfter = async (delayMs, function_, args, options_ = {}) => {
+  const runAfter = async (delayMs, target, args, options_ = {}) => {
     if (!Number.isFinite(delayMs) || delayMs < 0) {
       throw new LunoraError("INTERNAL", "@lunora/scheduler: `delayMs` must be a non-negative finite number");
     }
-    return runAt(Date.now() + delayMs, function_, args, options_);
+    return runAt(Date.now() + delayMs, target, args, options_);
   };
   const cancel = async (id) => callDO(options, "/cancel", { id });
   const list = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/scheduler",
-  "version": "1.0.0-alpha.8",
+  "version": "1.0.0-alpha.9",
   "description": "Scheduling for Lunora: runAfter / runAt and Cron Triggers via SchedulerDO",
   "keywords": [
     "cloudflare",