@lunora/scheduler 1.0.0-alpha.13 → 1.0.0-alpha.14

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { SchedulerHost } from '@lunora/platform';
 /**
  * Opaque reference to a Lunora function. Mirrors the `FunctionReference` shape
  * emitted by `@lunora/codegen` (and consumed by `@lunora/client`). We avoid a
@@ -140,6 +141,19 @@ interface Scheduler {
   cancel: (id: string) => Promise<{
     cancelled: boolean;
   }>;
+  /**
+   * Jobs that exhausted their retry budget and were parked under `dead:`
+   * (the DO's `/dead` view). Deliberately absent from {@link Scheduler.list} —
+   * the park deletes the `id:` header — so this is the only view of a job
+   * that failed permanently rather than being silently dropped.
+   */
+  dead: () => Promise<ScheduleRecord[]>;
+  /**
+   * Resurrect a parked job with a fresh attempt budget (the DO's
+   * `POST /dead/retry`). `false` when the id is not parked; a racing double
+   * recover is a no-op rather than an error.
+   */
+  deadRetry: (id: string) => Promise<boolean>;
   /** Resolve a single pending job by id, or `null` when absent (derived from {@link Scheduler.list}). */
   get: (id: string) => Promise<ScheduleRecord | null>;
   /** All pending scheduled jobs (the DO's `/list` view). */
@@ -842,6 +856,33 @@ declare class SchedulerDO {
   private armAlarmIfEarlier;
   private rescheduleAlarm;
 }
+/** What the Cloudflare scheduler host needs from the Worker's environment. */
+interface SchedulerHostOptions {
+  /**
+   * Named scheduler instance — one `SchedulerDO` per name, useful for tenant
+   * isolation. Defaults to `"default"`.
+   */
+  instanceName?: string;
+  /**
+   * Data-residency jurisdiction for the `SchedulerDO`. Pass the same value as
+   * the worker's own jurisdiction so scheduled state co-resides with app data.
+   */
+  jurisdiction?: "eu" | "fedramp" | "us";
+  /** The `SchedulerDO` namespace binding. */
+  namespace: Parameters<typeof createScheduler>[0]["namespace"];
+  /**
+   * Public origin the Worker is mounted at. `SchedulerDO` dispatches back to
+   * this base URL when an alarm fires, so a wrong value means jobs fire into
+   * nothing.
+   */
+  originUrl: string;
+}
+/**
+ * Build the Cloudflare {@link SchedulerHost}.
+ *
+ * The returned host has no `cron` member — see the module docstring.
+ */
+declare const createSchedulerHost: (options: SchedulerHostOptions) => SchedulerHost;
 /** Standard cron expression (5- or 6-field) or a supported `@macro`, per `cron-parser`. */
 declare const isValidCronExpression: (schedule: string) => boolean;
 /**
@@ -850,4 +891,4 @@ declare const isValidCronExpression: (schedule: string) => boolean;
  * job (`cron job "send digest"`) vs. the bare trigger.
  */
 declare const assertValidCronExpression: (schedule: string, context?: string) => void;
-export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectJurisdiction, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, type RetryPolicy, type RunOptions, type ScheduleRecord, type Scheduler, SchedulerDO, type SchedulerDOState, type SchedulerEnv, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference };
+export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectJurisdiction, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, type RetryPolicy, type RunOptions, type ScheduleRecord, type Scheduler, SchedulerDO, type SchedulerDOState, type SchedulerEnv, type SchedulerHostOptions, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createSchedulerHost, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { SchedulerHost } from '@lunora/platform';
 /**
  * Opaque reference to a Lunora function. Mirrors the `FunctionReference` shape
  * emitted by `@lunora/codegen` (and consumed by `@lunora/client`). We avoid a
@@ -140,6 +141,19 @@ interface Scheduler {
   cancel: (id: string) => Promise<{
     cancelled: boolean;
   }>;
+  /**
+   * Jobs that exhausted their retry budget and were parked under `dead:`
+   * (the DO's `/dead` view). Deliberately absent from {@link Scheduler.list} —
+   * the park deletes the `id:` header — so this is the only view of a job
+   * that failed permanently rather than being silently dropped.
+   */
+  dead: () => Promise<ScheduleRecord[]>;
+  /**
+   * Resurrect a parked job with a fresh attempt budget (the DO's
+   * `POST /dead/retry`). `false` when the id is not parked; a racing double
+   * recover is a no-op rather than an error.
+   */
+  deadRetry: (id: string) => Promise<boolean>;
   /** Resolve a single pending job by id, or `null` when absent (derived from {@link Scheduler.list}). */
   get: (id: string) => Promise<ScheduleRecord | null>;
   /** All pending scheduled jobs (the DO's `/list` view). */
@@ -842,6 +856,33 @@ declare class SchedulerDO {
   private armAlarmIfEarlier;
   private rescheduleAlarm;
 }
+/** What the Cloudflare scheduler host needs from the Worker's environment. */
+interface SchedulerHostOptions {
+  /**
+   * Named scheduler instance — one `SchedulerDO` per name, useful for tenant
+   * isolation. Defaults to `"default"`.
+   */
+  instanceName?: string;
+  /**
+   * Data-residency jurisdiction for the `SchedulerDO`. Pass the same value as
+   * the worker's own jurisdiction so scheduled state co-resides with app data.
+   */
+  jurisdiction?: "eu" | "fedramp" | "us";
+  /** The `SchedulerDO` namespace binding. */
+  namespace: Parameters<typeof createScheduler>[0]["namespace"];
+  /**
+   * Public origin the Worker is mounted at. `SchedulerDO` dispatches back to
+   * this base URL when an alarm fires, so a wrong value means jobs fire into
+   * nothing.
+   */
+  originUrl: string;
+}
+/**
+ * Build the Cloudflare {@link SchedulerHost}.
+ *
+ * The returned host has no `cron` member — see the module docstring.
+ */
+declare const createSchedulerHost: (options: SchedulerHostOptions) => SchedulerHost;
 /** Standard cron expression (5- or 6-field) or a supported `@macro`, per `cron-parser`. */
 declare const isValidCronExpression: (schedule: string) => boolean;
 /**
@@ -850,4 +891,4 @@ declare const isValidCronExpression: (schedule: string) => boolean;
  * job (`cron job "send digest"`) vs. the bare trigger.
  */
 declare const assertValidCronExpression: (schedule: string, context?: string) => void;
-export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectJurisdiction, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, type RetryPolicy, type RunOptions, type ScheduleRecord, type Scheduler, SchedulerDO, type SchedulerDOState, type SchedulerEnv, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference };
+export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectJurisdiction, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, type RetryPolicy, type RunOptions, type ScheduleRecord, type Scheduler, SchedulerDO, type SchedulerDOState, type SchedulerEnv, type SchedulerHostOptions, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createSchedulerHost, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference };

package/dist/index.mjs

@@ -1 +1 @@
-import{default as o}from"./packem_shared/createScheduler-B2YOy_ph.mjs";import{default as p}from"./packem_shared/createWorkpool-DyVdhB6o.mjs";import{createCronTrigger as s}from"./packem_shared/createCronTrigger-CyPdVKNF.mjs";import{CRON_SCHEDULE_KINDS as f,compileCronSchedule as l,cronJobs as m}from"./packem_shared/CRON_SCHEDULE_KINDS-CZFw97XW.mjs";import{createQueueConsumer as x,createQueueWorkpool as i,httpDispatcher as n}from"./packem_shared/createQueueConsumer-B0qNXRUJ.mjs";import{SchedulerDO as C}from"./packem_shared/SchedulerDO-DGgeZ-uI.mjs";import{isWorkflowReference as S}from"./packem_shared/isWorkflowReference-CT3tdefh.mjs";import{assertValidCronExpression as E,isValidCronExpression as k}from"./packem_shared/assertValidCronExpression-DHvO7Vm9.mjs";export{f as CRON_SCHEDULE_KINDS,C as SchedulerDO,E as assertValidCronExpression,l as compileCronSchedule,s as createCronTrigger,x as createQueueConsumer,i as createQueueWorkpool,o as createScheduler,p as createWorkpool,m as cronJobs,n as httpDispatcher,k as isValidCronExpression,S as isWorkflowReference};
+import{default as o}from"./packem_shared/createScheduler-CsRAEtdb.mjs";import{default as p}from"./packem_shared/createWorkpool-DyVdhB6o.mjs";import{createCronTrigger as c}from"./packem_shared/createCronTrigger-CyPdVKNF.mjs";import{CRON_SCHEDULE_KINDS as f,compileCronSchedule as l,cronJobs as m}from"./packem_shared/CRON_SCHEDULE_KINDS-CZFw97XW.mjs";import{createQueueConsumer as x,createQueueWorkpool as i,httpDispatcher as n}from"./packem_shared/createQueueConsumer-B0qNXRUJ.mjs";import{SchedulerDO as C}from"./packem_shared/SchedulerDO-DGgeZ-uI.mjs";import{createSchedulerHost as S}from"./packem_shared/createSchedulerHost-C5XacwXv.mjs";import{isWorkflowReference as E}from"./packem_shared/isWorkflowReference-CT3tdefh.mjs";import{assertValidCronExpression as W,isValidCronExpression as g}from"./packem_shared/assertValidCronExpression-DHvO7Vm9.mjs";export{f as CRON_SCHEDULE_KINDS,C as SchedulerDO,W as assertValidCronExpression,l as compileCronSchedule,c as createCronTrigger,x as createQueueConsumer,i as createQueueWorkpool,o as createScheduler,S as createSchedulerHost,p as createWorkpool,m as cronJobs,n as httpDispatcher,g as isValidCronExpression,E as isWorkflowReference};

package/dist/packem_shared/createScheduler-CsRAEtdb.mjs

@@ -0,0 +1 @@
+import{LunoraError as i}from"@lunora/errors";import{l as s,u as a}from"./do-client-BFps7NIj.mjs";import{isWorkflowReference as g}from"./isWorkflowReference-CT3tdefh.mjs";const y=n=>{if(!n.namespace)throw new i("INTERNAL","@lunora/scheduler: `namespace` (SchedulerDO binding) is required");if(!n.originUrl)throw new i("INTERNAL","@lunora/scheduler: `originUrl` is required so the DO can dispatch back to the Worker");const c=async(e,r,o,t={})=>{const l=e instanceof Date?e.getTime():e,d={args:o,originUrl:n.originUrl,pool:t.pool,retry:t.retry,scheduledFor:l,shardKey:t.shardKey};if(g(r)){if(typeof r.binding!="string"||r.binding.length===0)throw new i("INTERNAL","@lunora/scheduler: workflow/agent schedule target is missing its `binding` — pass the generated `workflows.<name>` / `agents.<name>` reference");return a(n,"/schedule",{...d,workflow:r.binding})}const u=typeof r=="string"?r:r.__lunoraRef;return a(n,"/schedule",{...d,functionPath:u})};return{cancel:async e=>a(n,"/cancel",{id:e}),dead:async()=>{const e=await s(n,"/dead");return Array.isArray(e.records)?e.records:[]},deadRetry:async e=>{const{retried:r}=await a(n,"/dead/retry",{id:e});return r===!0},get:async e=>(await s(n,`/get?id=${encodeURIComponent(e)}`)).record??null,list:async()=>{const e=await s(n,"/list");return Array.isArray(e.records)?e.records:[]},runAfter:async(e,r,o,t={})=>{if(!Number.isFinite(e)||e<0)throw new i("INTERNAL","@lunora/scheduler: `delayMs` must be a non-negative finite number");return c(Date.now()+e,r,o,t)},runAt:c}};export{y as default};

package/dist/packem_shared/createSchedulerHost-C5XacwXv.mjs

@@ -0,0 +1 @@
+import i from"./createScheduler-CsRAEtdb.mjs";const o=a=>a?.at!==void 0?typeof a.at=="number"?a.at:a.at.getTime():Date.now()+(a?.delayMs??0),u=a=>{const t=i({instanceName:a.instanceName,jurisdiction:a.jurisdiction,namespace:a.namespace,originUrl:a.originUrl}),c=e=>({attempts:e.attempts??0,functionPath:e.functionPath??e.workflow??"",id:e.id,scheduledFor:e.scheduledFor});return{cancel:async e=>{const{cancelled:r}=await t.cancel(e);return r},deadLetter:{list:async()=>(await t.dead()).map(e=>c(e)),requeue:async e=>t.deadRetry(e)},list:async()=>(await t.list()).map(e=>c(e)),schedule:async(e,r,n)=>{const s=t.runAt;return s(o(n),e,r,{retry:n?.retry,shardKey:n?.shardKey})}}};export{u as createSchedulerHost};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/scheduler",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.14",
   "description": "Scheduling for Lunora: runAfter / runAt and Cron Triggers via SchedulerDO",
   "keywords": [
     "cloudflare",
@@ -47,6 +47,7 @@
   },
   "dependencies": {
     "@lunora/errors": "1.0.0-alpha.9",
+    "@lunora/platform": "1.0.0-alpha.1",
     "cron-parser": "5.6.2"
   },
   "engines": {

package/dist/packem_shared/createScheduler-B2YOy_ph.mjs

@@ -1 +0,0 @@
-import{LunoraError as i}from"@lunora/errors";import{l,u as s}from"./do-client-BFps7NIj.mjs";import{isWorkflowReference as g}from"./isWorkflowReference-CT3tdefh.mjs";const m=n=>{if(!n.namespace)throw new i("INTERNAL","@lunora/scheduler: `namespace` (SchedulerDO binding) is required");if(!n.originUrl)throw new i("INTERNAL","@lunora/scheduler: `originUrl` is required so the DO can dispatch back to the Worker");const a=async(e,r,o,t={})=>{const u=e instanceof Date?e.getTime():e,c={args:o,originUrl:n.originUrl,pool:t.pool,retry:t.retry,scheduledFor:u,shardKey:t.shardKey};if(g(r)){if(typeof r.binding!="string"||r.binding.length===0)throw new i("INTERNAL","@lunora/scheduler: workflow/agent schedule target is missing its `binding` — pass the generated `workflows.<name>` / `agents.<name>` reference");return s(n,"/schedule",{...c,workflow:r.binding})}const d=typeof r=="string"?r:r.__lunoraRef;return s(n,"/schedule",{...c,functionPath:d})};return{cancel:async e=>s(n,"/cancel",{id:e}),get:async e=>(await l(n,`/get?id=${encodeURIComponent(e)}`)).record??null,list:async()=>{const e=await l(n,"/list");return Array.isArray(e.records)?e.records:[]},runAfter:async(e,r,o,t={})=>{if(!Number.isFinite(e)||e<0)throw new i("INTERNAL","@lunora/scheduler: `delayMs` must be a non-negative finite number");return a(Date.now()+e,r,o,t)},runAt:a}};export{m as default};