@lunora/scheduler 1.0.0-alpha.46 → 1.0.0-alpha.47

package/dist/index.d.mts

@@ -1,21 +1,46 @@
 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
- * direct dependency to keep this package usable from the codegen pipeline
- * itself.
+ * The generated function-reference type, shared by every package that needs to
+ * infer a call's args or return from `api.<file>.<fn>`.
  *
- * The runtime identifier lives in `__lunoraRef` — this MUST stay in lockstep
- * with the codegen emit + `@lunora/client`'s `FunctionReference`.
+ * This lives in `shared/` rather than in one package because the consumers span
+ * a dependency boundary they must not cross: `@lunora/scheduler` and
+ * `@lunora/workflow` accept a reference in `runAfter`/`runAt`/`step.run*` but
+ * cannot depend on `@lunora/client`, which is a browser package. Each of them
+ * previously hand-copied this declaration, and both copies silently rotted when
+ * the phantom carrier was renamed — the conditional matched an OPTIONAL property
+ * that no longer existed, so `ArgsOf<F>` quietly resolved to `unknown` and every
+ * `step.run(ref, args)` in the repo lost its arg checking without a single error.
+ *
+ * `shared/` is the repo's answer to exactly that shape: bundler-inlined,
+ * zero-dependency source imported by relative path, so it creates no runtime
+ * edge between the packages that inline it. Being ONE declaration, there is
+ * nothing to keep in lockstep and no drift test to write.
  */
-interface FunctionReference {
+/** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
+type FunctionKind = "action" | "mutation" | "query" | "stream";
+/**
+ * Opaque reference to a registered function emitted by `@lunora/codegen`.
+ *
+ * At runtime it carries the `<file>:<function>` identifier in `__lunoraRef`.
+ * Generated declarations decorate this with phantom type parameters so callers
+ * can infer args / return values per call site.
+ */
+interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unknown, Return = unknown> {
+  /**
+   * Phantom marker carrying the `Kind`/`Args`/`Return` type parameters for
+   * inference. Never present at runtime; declared as a covariant (output)
+   * position so a concrete reference stays assignable to a widened one.
+   */
+  readonly __lunoraPhantom?: {
+    args: Args;
+    kind: Kind;
+    returns: Return;
+  };
   readonly __lunoraRef: string;
-  /** Marker phantom type — discriminates queries / mutations / actions. */
-  readonly _kind?: "query" | "mutation" | "action";
 }
-type ArgsOf<F extends FunctionReference> = F extends {
-  _args?: infer A;
-} ? A : Record<string, unknown>;
+/** Extract the args type from a {@link FunctionReference}. */
+type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
 /**
  * Typed reference to a Lunora durable workflow — either the generated
  * `workflows.<name>` reference object (`_generated/api.ts`, which carries the
@@ -42,19 +67,30 @@ interface WorkflowReference<Params = Record<string, unknown>> {
   /** The workflow's export/stable name (present on a generated ref; a `defineWorkflow({ name })` override otherwise). */
   readonly name?: string;
 }
+/**
+ * A function reference a scheduler or workpool may target.
+ *
+ * `stream` is excluded deliberately, and the exclusion is load-bearing rather
+ * than tidiness: a scheduled job is dispatched as an ordinary `/rpc` call, and
+ * the function runner cannot execute a stream function (see
+ * `create-worker.ts`'s registry note). Accepting one compiles a job that is
+ * guaranteed to fail when its alarm fires, long after the call site that
+ * scheduled it.
+ */
+type SchedulableReference<Args = unknown, Return = unknown> = FunctionReference<Exclude<FunctionKind, "stream">, Args, Return>;
 /** A cron job's target: either a one-shot function dispatch or a durable workflow start. */
-type CronTarget = FunctionReference | WorkflowReference;
+type CronTarget = SchedulableReference | 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`.
+ * {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it resolves a
+ * {@link FunctionReference}'s `args` through {@link ArgsOf} as well as a
+ * {@link WorkflowReference}'s `params`, so scheduling a generated function
+ * reference is arg-checked against that function's validator while scheduling a
+ * workflow/agent is checked against its `params`.
  */
-type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : Record<string, unknown>;
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends SchedulableReference ? 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;
 /**
@@ -276,7 +312,7 @@ interface Workpool {
    * and the time it was scheduled for (it may not run immediately if the pool
    * is at capacity).
    */
-  enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
+  enqueue: <F extends SchedulableReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
@@ -356,7 +392,7 @@ interface QueueWorkpoolOptions {
  */
 interface QueueWorkpool {
   /** Enqueue a single `fn(args)` dispatch. */
-  enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: QueueEnqueueOptions) => Promise<void>;
+  enqueue: <F extends SchedulableReference>(function_: F, args: ArgsOf<F>, options?: QueueEnqueueOptions) => Promise<void>;
   /** Enqueue many dispatches in one `sendBatch`. Each job names its function `ref`. */
   enqueueBatch: (jobs: ReadonlyArray<{
     args?: Record<string, unknown>;
@@ -1013,4 +1049,4 @@ declare const warnIfSecondsLeading: (schedule: string, context: string) => void;
  * {@link warnIfSecondsLeading}.
  */
 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 HourlySchedule, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, MAX_RETRY_ATTEMPTS, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, RETRY_BASE_DELAY_MS, 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, warnIfSecondsLeading };
+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 FunctionKind, type FunctionReference, type HourlySchedule, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, MAX_RETRY_ATTEMPTS, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, RETRY_BASE_DELAY_MS, 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, warnIfSecondsLeading };

package/dist/index.d.ts

@@ -1,21 +1,46 @@
 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
- * direct dependency to keep this package usable from the codegen pipeline
- * itself.
+ * The generated function-reference type, shared by every package that needs to
+ * infer a call's args or return from `api.<file>.<fn>`.
  *
- * The runtime identifier lives in `__lunoraRef` — this MUST stay in lockstep
- * with the codegen emit + `@lunora/client`'s `FunctionReference`.
+ * This lives in `shared/` rather than in one package because the consumers span
+ * a dependency boundary they must not cross: `@lunora/scheduler` and
+ * `@lunora/workflow` accept a reference in `runAfter`/`runAt`/`step.run*` but
+ * cannot depend on `@lunora/client`, which is a browser package. Each of them
+ * previously hand-copied this declaration, and both copies silently rotted when
+ * the phantom carrier was renamed — the conditional matched an OPTIONAL property
+ * that no longer existed, so `ArgsOf<F>` quietly resolved to `unknown` and every
+ * `step.run(ref, args)` in the repo lost its arg checking without a single error.
+ *
+ * `shared/` is the repo's answer to exactly that shape: bundler-inlined,
+ * zero-dependency source imported by relative path, so it creates no runtime
+ * edge between the packages that inline it. Being ONE declaration, there is
+ * nothing to keep in lockstep and no drift test to write.
  */
-interface FunctionReference {
+/** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
+type FunctionKind = "action" | "mutation" | "query" | "stream";
+/**
+ * Opaque reference to a registered function emitted by `@lunora/codegen`.
+ *
+ * At runtime it carries the `<file>:<function>` identifier in `__lunoraRef`.
+ * Generated declarations decorate this with phantom type parameters so callers
+ * can infer args / return values per call site.
+ */
+interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unknown, Return = unknown> {
+  /**
+   * Phantom marker carrying the `Kind`/`Args`/`Return` type parameters for
+   * inference. Never present at runtime; declared as a covariant (output)
+   * position so a concrete reference stays assignable to a widened one.
+   */
+  readonly __lunoraPhantom?: {
+    args: Args;
+    kind: Kind;
+    returns: Return;
+  };
   readonly __lunoraRef: string;
-  /** Marker phantom type — discriminates queries / mutations / actions. */
-  readonly _kind?: "query" | "mutation" | "action";
 }
-type ArgsOf<F extends FunctionReference> = F extends {
-  _args?: infer A;
-} ? A : Record<string, unknown>;
+/** Extract the args type from a {@link FunctionReference}. */
+type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
 /**
  * Typed reference to a Lunora durable workflow — either the generated
  * `workflows.<name>` reference object (`_generated/api.ts`, which carries the
@@ -42,19 +67,30 @@ interface WorkflowReference<Params = Record<string, unknown>> {
   /** The workflow's export/stable name (present on a generated ref; a `defineWorkflow({ name })` override otherwise). */
   readonly name?: string;
 }
+/**
+ * A function reference a scheduler or workpool may target.
+ *
+ * `stream` is excluded deliberately, and the exclusion is load-bearing rather
+ * than tidiness: a scheduled job is dispatched as an ordinary `/rpc` call, and
+ * the function runner cannot execute a stream function (see
+ * `create-worker.ts`'s registry note). Accepting one compiles a job that is
+ * guaranteed to fail when its alarm fires, long after the call site that
+ * scheduled it.
+ */
+type SchedulableReference<Args = unknown, Return = unknown> = FunctionReference<Exclude<FunctionKind, "stream">, Args, Return>;
 /** A cron job's target: either a one-shot function dispatch or a durable workflow start. */
-type CronTarget = FunctionReference | WorkflowReference;
+type CronTarget = SchedulableReference | 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`.
+ * {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it resolves a
+ * {@link FunctionReference}'s `args` through {@link ArgsOf} as well as a
+ * {@link WorkflowReference}'s `params`, so scheduling a generated function
+ * reference is arg-checked against that function's validator while scheduling a
+ * workflow/agent is checked against its `params`.
  */
-type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : Record<string, unknown>;
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends SchedulableReference ? 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;
 /**
@@ -276,7 +312,7 @@ interface Workpool {
    * and the time it was scheduled for (it may not run immediately if the pool
    * is at capacity).
    */
-  enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
+  enqueue: <F extends SchedulableReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
@@ -356,7 +392,7 @@ interface QueueWorkpoolOptions {
  */
 interface QueueWorkpool {
   /** Enqueue a single `fn(args)` dispatch. */
-  enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: QueueEnqueueOptions) => Promise<void>;
+  enqueue: <F extends SchedulableReference>(function_: F, args: ArgsOf<F>, options?: QueueEnqueueOptions) => Promise<void>;
   /** Enqueue many dispatches in one `sendBatch`. Each job names its function `ref`. */
   enqueueBatch: (jobs: ReadonlyArray<{
     args?: Record<string, unknown>;
@@ -1013,4 +1049,4 @@ declare const warnIfSecondsLeading: (schedule: string, context: string) => void;
  * {@link warnIfSecondsLeading}.
  */
 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 HourlySchedule, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, MAX_RETRY_ATTEMPTS, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, RETRY_BASE_DELAY_MS, 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, warnIfSecondsLeading };
+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 FunctionKind, type FunctionReference, type HourlySchedule, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, MAX_RETRY_ATTEMPTS, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, RETRY_BASE_DELAY_MS, 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, warnIfSecondsLeading };

package/package.json

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