@tanstack/workflow-vercel 0.0.1

package/README.md

@@ -0,0 +1,70 @@
+# @tanstack/workflow-vercel
+
+Experimental Vercel host adapter for TanStack Workflow.
+
+See the main [Deployment guide](../../docs/guide/deployment.md) and
+[Host adapters API](../../docs/api/host-adapters.md).
+
+The adapter wires a `WorkflowRuntimeDefinition` into a Vercel Function. It
+materializes registered workflow schedules into the runtime store, then calls
+`runtime.sweep()` to run due scheduled workflows and resume due timers.
+
+```ts
+// app/api/workflow/sweep/route.ts
+import { createVercelWorkflowSweepHandler } from '@tanstack/workflow-vercel'
+import { workflowRuntime } from '../../../../src/workflows/runtime.server'
+
+export const runtime = 'nodejs'
+export const maxDuration = 60
+
+export const GET = createVercelWorkflowSweepHandler({
+  runtime: workflowRuntime,
+  cronSecret: process.env.CRON_SECRET,
+  maxDurationMs: 55_000,
+})
+```
+
+Configure the Vercel Cron Job in `vercel.json`:
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "crons": [
+    {
+      "path": "/api/workflow/sweep",
+      "schedule": "*/5 * * * *"
+    }
+  ]
+}
+```
+
+Vercel Cron Jobs invoke the configured path with an HTTP `GET` request. If the
+project defines `CRON_SECRET`, Vercel sends it in the `Authorization` header,
+and the handler can validate it with `cronSecret`.
+
+Workflow schedules stay in the runtime registration:
+
+```ts
+import { defineWorkflowRuntime, every } from '@tanstack/workflow-runtime'
+
+export const workflowRuntime = defineWorkflowRuntime({
+  store,
+  workflows: {
+    'intent-process': {
+      load: async () => intentProcessWorkflow,
+      schedules: [
+        {
+          id: 'intent-process-every-15m',
+          schedule: every.minutes(15),
+          overlapPolicy: 'skip',
+          input: { batchSize: 50 },
+        },
+      ],
+    },
+  },
+})
+```
+
+Vercel Hobby projects only support daily cron invocations. For minute-level
+sweeps, deploy on a plan that supports per-minute cron jobs or use a daily
+host cron as a coarse wake-up for schedules that tolerate that cadence.

package/dist/index.cjs

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_sweep_handler = require('./sweep-handler.cjs');
+let _tanstack_workflow_runtime = require("@tanstack/workflow-runtime");
+
+exports.createVercelWorkflowCronConfig = require_sweep_handler.createVercelWorkflowCronConfig;
+exports.createVercelWorkflowSweepHandler = require_sweep_handler.createVercelWorkflowSweepHandler;
+exports.materializeWorkflowSchedules = _tanstack_workflow_runtime.materializeWorkflowSchedules;
+exports.vercelWorkflowCronConfig = require_sweep_handler.vercelWorkflowCronConfig;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { MaterializeWorkflowSchedulesOptions, MaterializedWorkflowSchedule, VercelWorkflowCron, VercelWorkflowCronConfig, VercelWorkflowCronConfigOptions, VercelWorkflowSweepHandler, VercelWorkflowSweepHandlerOptions, VercelWorkflowSweepResponse, VercelWorkflowUnauthorizedResponse, createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig } from "./sweep-handler.cjs";
+export { type MaterializeWorkflowSchedulesOptions, type MaterializedWorkflowSchedule, type VercelWorkflowCron, type VercelWorkflowCronConfig, type VercelWorkflowCronConfigOptions, type VercelWorkflowSweepHandler, type VercelWorkflowSweepHandlerOptions, type VercelWorkflowSweepResponse, type VercelWorkflowUnauthorizedResponse, createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { MaterializeWorkflowSchedulesOptions, MaterializedWorkflowSchedule, VercelWorkflowCron, VercelWorkflowCronConfig, VercelWorkflowCronConfigOptions, VercelWorkflowSweepHandler, VercelWorkflowSweepHandlerOptions, VercelWorkflowSweepResponse, VercelWorkflowUnauthorizedResponse, createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig } from "./sweep-handler.js";
+export { type MaterializeWorkflowSchedulesOptions, type MaterializedWorkflowSchedule, type VercelWorkflowCron, type VercelWorkflowCronConfig, type VercelWorkflowCronConfigOptions, type VercelWorkflowSweepHandler, type VercelWorkflowSweepHandlerOptions, type VercelWorkflowSweepResponse, type VercelWorkflowUnauthorizedResponse, createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig } from "./sweep-handler.js";
+
+export { createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig };

package/dist/sweep-handler.cjs

@@ -0,0 +1,87 @@
+let _tanstack_workflow_runtime = require("@tanstack/workflow-runtime");
+
+//#region src/sweep-handler.ts
+const DEFAULT_SWEEP_INTERVAL_MINUTES = 5;
+const DEFAULT_SWEEP_PATH = "/api/workflow/sweep";
+const vercelWorkflowCronConfig = createVercelWorkflowCronConfig();
+function createVercelWorkflowCronConfig(options = {}) {
+	const path = options.path ?? DEFAULT_SWEEP_PATH;
+	if (!path.startsWith("/")) throw new Error("Vercel workflow cron path must start with \"/\".");
+	if (options.schedule) return {
+		$schema: "https://openapi.vercel.sh/vercel.json",
+		crons: [{
+			path,
+			schedule: options.schedule
+		}]
+	};
+	const everyMinutes = options.everyMinutes ?? DEFAULT_SWEEP_INTERVAL_MINUTES;
+	if (!Number.isInteger(everyMinutes) || everyMinutes <= 0) throw new Error("Vercel workflow sweep interval must be a positive integer.");
+	return {
+		$schema: "https://openapi.vercel.sh/vercel.json",
+		crons: [{
+			path,
+			schedule: everyMinutes === 1 ? "* * * * *" : `*/${everyMinutes} * * * *`
+		}]
+	};
+}
+function createVercelWorkflowSweepHandler(options) {
+	return async (request) => {
+		if (!isAuthorized(request, options.cronSecret)) return Response.json({
+			ok: false,
+			error: "Unauthorized"
+		}, { status: 401 });
+		const now = options.now?.() ?? Date.now();
+		const materialized = options.materializeSchedules === false ? [] : await (0, _tanstack_workflow_runtime.materializeWorkflowSchedules)(options.runtime, {
+			now,
+			cronLookbackMs: options.cronLookbackMs
+		});
+		const leaseOwner = resolveLeaseOwner(options.leaseOwner, request, now);
+		const sweepArgs = {
+			now,
+			leaseOwner,
+			limit: options.limit,
+			maxScheduledRuns: options.maxScheduledRuns,
+			maxTimers: options.maxTimers,
+			maxDurationMs: options.maxDurationMs,
+			leaseMs: options.leaseMs,
+			includeEvents: options.includeEvents ?? false,
+			maxEvents: options.maxEvents
+		};
+		const sweep = await options.runtime.sweep(sweepArgs);
+		const response = {
+			ok: true,
+			now,
+			leaseOwner,
+			materialized,
+			summary: {
+				materialized: materialized.length,
+				...sweep.summary
+			},
+			deadlineReached: sweep.deadlineReached,
+			remainingMayExist: sweep.remainingMayExist,
+			...options.includeSweepResult ? { sweep } : void 0
+		};
+		return Response.json(response);
+	};
+}
+function isAuthorized(request, cronSecret) {
+	if (!cronSecret) return true;
+	return request.headers.get("authorization") === `Bearer ${cronSecret}`;
+}
+function resolveLeaseOwner(leaseOwner, request, now) {
+	if (typeof leaseOwner === "string") return leaseOwner;
+	if (typeof leaseOwner === "function") return leaseOwner({
+		request,
+		now
+	}) ?? defaultLeaseOwner(request, now);
+	return defaultLeaseOwner(request, now);
+}
+function defaultLeaseOwner(request, now) {
+	return `vercel:${request.headers.get("x-vercel-id") ?? now}`;
+}
+
+//#endregion
+exports.createVercelWorkflowCronConfig = createVercelWorkflowCronConfig;
+exports.createVercelWorkflowSweepHandler = createVercelWorkflowSweepHandler;
+exports.vercelWorkflowCronConfig = vercelWorkflowCronConfig;
+//# sourceMappingURL=sweep-handler.cjs.map

package/dist/sweep-handler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep-handler.cjs","names":[],"sources":["../src/sweep-handler.ts"],"sourcesContent":["import { materializeWorkflowSchedules } from '@tanstack/workflow-runtime'\nimport type {\n  MaterializedWorkflowSchedule,\n  WorkflowRegistrationMap,\n  WorkflowRuntimeDefinition,\n  WorkflowRuntimeSweepArgs,\n  WorkflowRuntimeSweepResult,\n} from '@tanstack/workflow-runtime'\n\nconst DEFAULT_SWEEP_INTERVAL_MINUTES = 5\nconst DEFAULT_SWEEP_PATH = '/api/workflow/sweep'\n\nexport { materializeWorkflowSchedules }\nexport type {\n  MaterializedWorkflowSchedule,\n  MaterializeWorkflowSchedulesOptions,\n} from '@tanstack/workflow-runtime'\n\nexport interface VercelWorkflowCron {\n  path: string\n  schedule: string\n}\n\nexport interface VercelWorkflowCronConfig {\n  $schema: 'https://openapi.vercel.sh/vercel.json'\n  crons: ReadonlyArray<VercelWorkflowCron>\n}\n\nexport interface VercelWorkflowCronConfigOptions {\n  path?: string\n  schedule?: string\n  everyMinutes?: number\n}\n\nexport interface VercelWorkflowSweepResponse {\n  ok: true\n  now: number\n  leaseOwner: string\n  materialized: ReadonlyArray<MaterializedWorkflowSchedule>\n  summary: VercelWorkflowSweepSummary\n  deadlineReached: boolean\n  remainingMayExist: boolean\n  sweep?: WorkflowRuntimeSweepResult\n}\n\nexport interface VercelWorkflowUnauthorizedResponse {\n  ok: false\n  error: 'Unauthorized'\n}\n\nexport type VercelWorkflowSweepSummary =\n  WorkflowRuntimeSweepResult['summary'] & {\n    materialized: number\n  }\n\nexport type VercelWorkflowSweepHandler = (request: Request) => Promise<Response>\n\nexport interface VercelWorkflowSweepHandlerOptions<\n  TWorkflows extends WorkflowRegistrationMap = WorkflowRegistrationMap,\n> {\n  runtime: WorkflowRuntimeDefinition<TWorkflows>\n  now?: () => number\n  leaseOwner?:\n    | string\n    | ((args: { request: Request; now: number }) => string | undefined)\n  limit?: number\n  maxScheduledRuns?: number\n  maxTimers?: number\n  maxDurationMs?: number\n  leaseMs?: number\n  includeEvents?: boolean\n  maxEvents?: number\n  includeSweepResult?: boolean\n  materializeSchedules?: boolean\n  cronLookbackMs?: number\n  cronSecret?: string\n}\n\nexport const vercelWorkflowCronConfig = createVercelWorkflowCronConfig()\n\nexport function createVercelWorkflowCronConfig(\n  options: VercelWorkflowCronConfigOptions = {},\n): VercelWorkflowCronConfig {\n  const path = options.path ?? DEFAULT_SWEEP_PATH\n  if (!path.startsWith('/')) {\n    throw new Error('Vercel workflow cron path must start with \"/\".')\n  }\n  if (options.schedule) {\n    return {\n      $schema: 'https://openapi.vercel.sh/vercel.json',\n      crons: [{ path, schedule: options.schedule }],\n    }\n  }\n\n  const everyMinutes = options.everyMinutes ?? DEFAULT_SWEEP_INTERVAL_MINUTES\n  if (!Number.isInteger(everyMinutes) || everyMinutes <= 0) {\n    throw new Error(\n      'Vercel workflow sweep interval must be a positive integer.',\n    )\n  }\n\n  return {\n    $schema: 'https://openapi.vercel.sh/vercel.json',\n    crons: [\n      {\n        path,\n        schedule:\n          everyMinutes === 1 ? '* * * * *' : `*/${everyMinutes} * * * *`,\n      },\n    ],\n  }\n}\n\nexport function createVercelWorkflowSweepHandler<\n  TWorkflows extends WorkflowRegistrationMap,\n>(\n  options: VercelWorkflowSweepHandlerOptions<TWorkflows>,\n): VercelWorkflowSweepHandler {\n  return async (request) => {\n    if (!isAuthorized(request, options.cronSecret)) {\n      return Response.json(\n        {\n          ok: false,\n          error: 'Unauthorized',\n        } satisfies VercelWorkflowUnauthorizedResponse,\n        { status: 401 },\n      )\n    }\n\n    const now = options.now?.() ?? Date.now()\n    const materialized =\n      options.materializeSchedules === false\n        ? []\n        : await materializeWorkflowSchedules(options.runtime, {\n            now,\n            cronLookbackMs: options.cronLookbackMs,\n          })\n    const leaseOwner = resolveLeaseOwner(options.leaseOwner, request, now)\n    const sweepArgs: WorkflowRuntimeSweepArgs = {\n      now,\n      leaseOwner,\n      limit: options.limit,\n      maxScheduledRuns: options.maxScheduledRuns,\n      maxTimers: options.maxTimers,\n      maxDurationMs: options.maxDurationMs,\n      leaseMs: options.leaseMs,\n      includeEvents: options.includeEvents ?? false,\n      maxEvents: options.maxEvents,\n    }\n    const sweep = await options.runtime.sweep(sweepArgs)\n    const response: VercelWorkflowSweepResponse = {\n      ok: true,\n      now,\n      leaseOwner,\n      materialized,\n      summary: {\n        materialized: materialized.length,\n        ...sweep.summary,\n      },\n      deadlineReached: sweep.deadlineReached,\n      remainingMayExist: sweep.remainingMayExist,\n      ...(options.includeSweepResult ? { sweep } : undefined),\n    }\n\n    return Response.json(response)\n  }\n}\n\nfunction isAuthorized(request: Request, cronSecret: string | undefined) {\n  if (!cronSecret) return true\n  return request.headers.get('authorization') === `Bearer ${cronSecret}`\n}\n\nfunction resolveLeaseOwner(\n  leaseOwner: VercelWorkflowSweepHandlerOptions['leaseOwner'],\n  request: Request,\n  now: number,\n) {\n  if (typeof leaseOwner === 'string') return leaseOwner\n  if (typeof leaseOwner === 'function') {\n    return leaseOwner({ request, now }) ?? defaultLeaseOwner(request, now)\n  }\n  return defaultLeaseOwner(request, now)\n}\n\nfunction defaultLeaseOwner(request: Request, now: number) {\n  return `vercel:${request.headers.get('x-vercel-id') ?? now}`\n}\n"],"mappings":";;;AASA,MAAM,iCAAiC;AACvC,MAAM,qBAAqB;AAoE3B,MAAa,2BAA2B,gCAAgC;AAExE,SAAgB,+BACd,UAA2C,EAAE,EACnB;CAC1B,MAAM,OAAO,QAAQ,QAAQ;AAC7B,KAAI,CAAC,KAAK,WAAW,IAAI,CACvB,OAAM,IAAI,MAAM,mDAAiD;AAEnE,KAAI,QAAQ,SACV,QAAO;EACL,SAAS;EACT,OAAO,CAAC;GAAE;GAAM,UAAU,QAAQ;GAAU,CAAC;EAC9C;CAGH,MAAM,eAAe,QAAQ,gBAAgB;AAC7C,KAAI,CAAC,OAAO,UAAU,aAAa,IAAI,gBAAgB,EACrD,OAAM,IAAI,MACR,6DACD;AAGH,QAAO;EACL,SAAS;EACT,OAAO,CACL;GACE;GACA,UACE,iBAAiB,IAAI,cAAc,KAAK,aAAa;GACxD,CACF;EACF;;AAGH,SAAgB,iCAGd,SAC4B;AAC5B,QAAO,OAAO,YAAY;AACxB,MAAI,CAAC,aAAa,SAAS,QAAQ,WAAW,CAC5C,QAAO,SAAS,KACd;GACE,IAAI;GACJ,OAAO;GACR,EACD,EAAE,QAAQ,KAAK,CAChB;EAGH,MAAM,MAAM,QAAQ,OAAO,IAAI,KAAK,KAAK;EACzC,MAAM,eACJ,QAAQ,yBAAyB,QAC7B,EAAE,GACF,mEAAmC,QAAQ,SAAS;GAClD;GACA,gBAAgB,QAAQ;GACzB,CAAC;EACR,MAAM,aAAa,kBAAkB,QAAQ,YAAY,SAAS,IAAI;EACtE,MAAM,YAAsC;GAC1C;GACA;GACA,OAAO,QAAQ;GACf,kBAAkB,QAAQ;GAC1B,WAAW,QAAQ;GACnB,eAAe,QAAQ;GACvB,SAAS,QAAQ;GACjB,eAAe,QAAQ,iBAAiB;GACxC,WAAW,QAAQ;GACpB;EACD,MAAM,QAAQ,MAAM,QAAQ,QAAQ,MAAM,UAAU;EACpD,MAAM,WAAwC;GAC5C,IAAI;GACJ;GACA;GACA;GACA,SAAS;IACP,cAAc,aAAa;IAC3B,GAAG,MAAM;IACV;GACD,iBAAiB,MAAM;GACvB,mBAAmB,MAAM;GACzB,GAAI,QAAQ,qBAAqB,EAAE,OAAO,GAAG;GAC9C;AAED,SAAO,SAAS,KAAK,SAAS;;;AAIlC,SAAS,aAAa,SAAkB,YAAgC;AACtE,KAAI,CAAC,WAAY,QAAO;AACxB,QAAO,QAAQ,QAAQ,IAAI,gBAAgB,KAAK,UAAU;;AAG5D,SAAS,kBACP,YACA,SACA,KACA;AACA,KAAI,OAAO,eAAe,SAAU,QAAO;AAC3C,KAAI,OAAO,eAAe,WACxB,QAAO,WAAW;EAAE;EAAS;EAAK,CAAC,IAAI,kBAAkB,SAAS,IAAI;AAExE,QAAO,kBAAkB,SAAS,IAAI;;AAGxC,SAAS,kBAAkB,SAAkB,KAAa;AACxD,QAAO,UAAU,QAAQ,QAAQ,IAAI,cAAc,IAAI"}

package/dist/sweep-handler.d.cts

@@ -0,0 +1,59 @@
+import { MaterializeWorkflowSchedulesOptions, MaterializedWorkflowSchedule, MaterializedWorkflowSchedule as MaterializedWorkflowSchedule$1, WorkflowRegistrationMap, WorkflowRuntimeDefinition, WorkflowRuntimeSweepResult, materializeWorkflowSchedules } from "@tanstack/workflow-runtime";
+
+//#region src/sweep-handler.d.ts
+interface VercelWorkflowCron {
+  path: string;
+  schedule: string;
+}
+interface VercelWorkflowCronConfig {
+  $schema: 'https://openapi.vercel.sh/vercel.json';
+  crons: ReadonlyArray<VercelWorkflowCron>;
+}
+interface VercelWorkflowCronConfigOptions {
+  path?: string;
+  schedule?: string;
+  everyMinutes?: number;
+}
+interface VercelWorkflowSweepResponse {
+  ok: true;
+  now: number;
+  leaseOwner: string;
+  materialized: ReadonlyArray<MaterializedWorkflowSchedule>;
+  summary: VercelWorkflowSweepSummary;
+  deadlineReached: boolean;
+  remainingMayExist: boolean;
+  sweep?: WorkflowRuntimeSweepResult;
+}
+interface VercelWorkflowUnauthorizedResponse {
+  ok: false;
+  error: 'Unauthorized';
+}
+type VercelWorkflowSweepSummary = WorkflowRuntimeSweepResult['summary'] & {
+  materialized: number;
+};
+type VercelWorkflowSweepHandler = (request: Request) => Promise<Response>;
+interface VercelWorkflowSweepHandlerOptions<TWorkflows extends WorkflowRegistrationMap = WorkflowRegistrationMap> {
+  runtime: WorkflowRuntimeDefinition<TWorkflows>;
+  now?: () => number;
+  leaseOwner?: string | ((args: {
+    request: Request;
+    now: number;
+  }) => string | undefined);
+  limit?: number;
+  maxScheduledRuns?: number;
+  maxTimers?: number;
+  maxDurationMs?: number;
+  leaseMs?: number;
+  includeEvents?: boolean;
+  maxEvents?: number;
+  includeSweepResult?: boolean;
+  materializeSchedules?: boolean;
+  cronLookbackMs?: number;
+  cronSecret?: string;
+}
+declare const vercelWorkflowCronConfig: VercelWorkflowCronConfig;
+declare function createVercelWorkflowCronConfig(options?: VercelWorkflowCronConfigOptions): VercelWorkflowCronConfig;
+declare function createVercelWorkflowSweepHandler<TWorkflows extends WorkflowRegistrationMap>(options: VercelWorkflowSweepHandlerOptions<TWorkflows>): VercelWorkflowSweepHandler;
+//#endregion
+export { type MaterializeWorkflowSchedulesOptions, type MaterializedWorkflowSchedule$1 as MaterializedWorkflowSchedule, VercelWorkflowCron, VercelWorkflowCronConfig, VercelWorkflowCronConfigOptions, VercelWorkflowSweepHandler, VercelWorkflowSweepHandlerOptions, VercelWorkflowSweepResponse, VercelWorkflowUnauthorizedResponse, createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig };
+//# sourceMappingURL=sweep-handler.d.cts.map

package/dist/sweep-handler.d.ts

@@ -0,0 +1,59 @@
+import { MaterializeWorkflowSchedulesOptions, MaterializedWorkflowSchedule, MaterializedWorkflowSchedule as MaterializedWorkflowSchedule$1, WorkflowRegistrationMap, WorkflowRuntimeDefinition, WorkflowRuntimeSweepResult, materializeWorkflowSchedules } from "@tanstack/workflow-runtime";
+
+//#region src/sweep-handler.d.ts
+interface VercelWorkflowCron {
+  path: string;
+  schedule: string;
+}
+interface VercelWorkflowCronConfig {
+  $schema: 'https://openapi.vercel.sh/vercel.json';
+  crons: ReadonlyArray<VercelWorkflowCron>;
+}
+interface VercelWorkflowCronConfigOptions {
+  path?: string;
+  schedule?: string;
+  everyMinutes?: number;
+}
+interface VercelWorkflowSweepResponse {
+  ok: true;
+  now: number;
+  leaseOwner: string;
+  materialized: ReadonlyArray<MaterializedWorkflowSchedule>;
+  summary: VercelWorkflowSweepSummary;
+  deadlineReached: boolean;
+  remainingMayExist: boolean;
+  sweep?: WorkflowRuntimeSweepResult;
+}
+interface VercelWorkflowUnauthorizedResponse {
+  ok: false;
+  error: 'Unauthorized';
+}
+type VercelWorkflowSweepSummary = WorkflowRuntimeSweepResult['summary'] & {
+  materialized: number;
+};
+type VercelWorkflowSweepHandler = (request: Request) => Promise<Response>;
+interface VercelWorkflowSweepHandlerOptions<TWorkflows extends WorkflowRegistrationMap = WorkflowRegistrationMap> {
+  runtime: WorkflowRuntimeDefinition<TWorkflows>;
+  now?: () => number;
+  leaseOwner?: string | ((args: {
+    request: Request;
+    now: number;
+  }) => string | undefined);
+  limit?: number;
+  maxScheduledRuns?: number;
+  maxTimers?: number;
+  maxDurationMs?: number;
+  leaseMs?: number;
+  includeEvents?: boolean;
+  maxEvents?: number;
+  includeSweepResult?: boolean;
+  materializeSchedules?: boolean;
+  cronLookbackMs?: number;
+  cronSecret?: string;
+}
+declare const vercelWorkflowCronConfig: VercelWorkflowCronConfig;
+declare function createVercelWorkflowCronConfig(options?: VercelWorkflowCronConfigOptions): VercelWorkflowCronConfig;
+declare function createVercelWorkflowSweepHandler<TWorkflows extends WorkflowRegistrationMap>(options: VercelWorkflowSweepHandlerOptions<TWorkflows>): VercelWorkflowSweepHandler;
+//#endregion
+export { type MaterializeWorkflowSchedulesOptions, type MaterializedWorkflowSchedule$1 as MaterializedWorkflowSchedule, VercelWorkflowCron, VercelWorkflowCronConfig, VercelWorkflowCronConfigOptions, VercelWorkflowSweepHandler, VercelWorkflowSweepHandlerOptions, VercelWorkflowSweepResponse, VercelWorkflowUnauthorizedResponse, createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig };
+//# sourceMappingURL=sweep-handler.d.ts.map

package/dist/sweep-handler.js

@@ -0,0 +1,85 @@
+import { materializeWorkflowSchedules } from "@tanstack/workflow-runtime";
+
+//#region src/sweep-handler.ts
+const DEFAULT_SWEEP_INTERVAL_MINUTES = 5;
+const DEFAULT_SWEEP_PATH = "/api/workflow/sweep";
+const vercelWorkflowCronConfig = createVercelWorkflowCronConfig();
+function createVercelWorkflowCronConfig(options = {}) {
+	const path = options.path ?? DEFAULT_SWEEP_PATH;
+	if (!path.startsWith("/")) throw new Error("Vercel workflow cron path must start with \"/\".");
+	if (options.schedule) return {
+		$schema: "https://openapi.vercel.sh/vercel.json",
+		crons: [{
+			path,
+			schedule: options.schedule
+		}]
+	};
+	const everyMinutes = options.everyMinutes ?? DEFAULT_SWEEP_INTERVAL_MINUTES;
+	if (!Number.isInteger(everyMinutes) || everyMinutes <= 0) throw new Error("Vercel workflow sweep interval must be a positive integer.");
+	return {
+		$schema: "https://openapi.vercel.sh/vercel.json",
+		crons: [{
+			path,
+			schedule: everyMinutes === 1 ? "* * * * *" : `*/${everyMinutes} * * * *`
+		}]
+	};
+}
+function createVercelWorkflowSweepHandler(options) {
+	return async (request) => {
+		if (!isAuthorized(request, options.cronSecret)) return Response.json({
+			ok: false,
+			error: "Unauthorized"
+		}, { status: 401 });
+		const now = options.now?.() ?? Date.now();
+		const materialized = options.materializeSchedules === false ? [] : await materializeWorkflowSchedules(options.runtime, {
+			now,
+			cronLookbackMs: options.cronLookbackMs
+		});
+		const leaseOwner = resolveLeaseOwner(options.leaseOwner, request, now);
+		const sweepArgs = {
+			now,
+			leaseOwner,
+			limit: options.limit,
+			maxScheduledRuns: options.maxScheduledRuns,
+			maxTimers: options.maxTimers,
+			maxDurationMs: options.maxDurationMs,
+			leaseMs: options.leaseMs,
+			includeEvents: options.includeEvents ?? false,
+			maxEvents: options.maxEvents
+		};
+		const sweep = await options.runtime.sweep(sweepArgs);
+		const response = {
+			ok: true,
+			now,
+			leaseOwner,
+			materialized,
+			summary: {
+				materialized: materialized.length,
+				...sweep.summary
+			},
+			deadlineReached: sweep.deadlineReached,
+			remainingMayExist: sweep.remainingMayExist,
+			...options.includeSweepResult ? { sweep } : void 0
+		};
+		return Response.json(response);
+	};
+}
+function isAuthorized(request, cronSecret) {
+	if (!cronSecret) return true;
+	return request.headers.get("authorization") === `Bearer ${cronSecret}`;
+}
+function resolveLeaseOwner(leaseOwner, request, now) {
+	if (typeof leaseOwner === "string") return leaseOwner;
+	if (typeof leaseOwner === "function") return leaseOwner({
+		request,
+		now
+	}) ?? defaultLeaseOwner(request, now);
+	return defaultLeaseOwner(request, now);
+}
+function defaultLeaseOwner(request, now) {
+	return `vercel:${request.headers.get("x-vercel-id") ?? now}`;
+}
+
+//#endregion
+export { createVercelWorkflowCronConfig, createVercelWorkflowSweepHandler, materializeWorkflowSchedules, vercelWorkflowCronConfig };
+//# sourceMappingURL=sweep-handler.js.map

package/dist/sweep-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep-handler.js","names":[],"sources":["../src/sweep-handler.ts"],"sourcesContent":["import { materializeWorkflowSchedules } from '@tanstack/workflow-runtime'\nimport type {\n  MaterializedWorkflowSchedule,\n  WorkflowRegistrationMap,\n  WorkflowRuntimeDefinition,\n  WorkflowRuntimeSweepArgs,\n  WorkflowRuntimeSweepResult,\n} from '@tanstack/workflow-runtime'\n\nconst DEFAULT_SWEEP_INTERVAL_MINUTES = 5\nconst DEFAULT_SWEEP_PATH = '/api/workflow/sweep'\n\nexport { materializeWorkflowSchedules }\nexport type {\n  MaterializedWorkflowSchedule,\n  MaterializeWorkflowSchedulesOptions,\n} from '@tanstack/workflow-runtime'\n\nexport interface VercelWorkflowCron {\n  path: string\n  schedule: string\n}\n\nexport interface VercelWorkflowCronConfig {\n  $schema: 'https://openapi.vercel.sh/vercel.json'\n  crons: ReadonlyArray<VercelWorkflowCron>\n}\n\nexport interface VercelWorkflowCronConfigOptions {\n  path?: string\n  schedule?: string\n  everyMinutes?: number\n}\n\nexport interface VercelWorkflowSweepResponse {\n  ok: true\n  now: number\n  leaseOwner: string\n  materialized: ReadonlyArray<MaterializedWorkflowSchedule>\n  summary: VercelWorkflowSweepSummary\n  deadlineReached: boolean\n  remainingMayExist: boolean\n  sweep?: WorkflowRuntimeSweepResult\n}\n\nexport interface VercelWorkflowUnauthorizedResponse {\n  ok: false\n  error: 'Unauthorized'\n}\n\nexport type VercelWorkflowSweepSummary =\n  WorkflowRuntimeSweepResult['summary'] & {\n    materialized: number\n  }\n\nexport type VercelWorkflowSweepHandler = (request: Request) => Promise<Response>\n\nexport interface VercelWorkflowSweepHandlerOptions<\n  TWorkflows extends WorkflowRegistrationMap = WorkflowRegistrationMap,\n> {\n  runtime: WorkflowRuntimeDefinition<TWorkflows>\n  now?: () => number\n  leaseOwner?:\n    | string\n    | ((args: { request: Request; now: number }) => string | undefined)\n  limit?: number\n  maxScheduledRuns?: number\n  maxTimers?: number\n  maxDurationMs?: number\n  leaseMs?: number\n  includeEvents?: boolean\n  maxEvents?: number\n  includeSweepResult?: boolean\n  materializeSchedules?: boolean\n  cronLookbackMs?: number\n  cronSecret?: string\n}\n\nexport const vercelWorkflowCronConfig = createVercelWorkflowCronConfig()\n\nexport function createVercelWorkflowCronConfig(\n  options: VercelWorkflowCronConfigOptions = {},\n): VercelWorkflowCronConfig {\n  const path = options.path ?? DEFAULT_SWEEP_PATH\n  if (!path.startsWith('/')) {\n    throw new Error('Vercel workflow cron path must start with \"/\".')\n  }\n  if (options.schedule) {\n    return {\n      $schema: 'https://openapi.vercel.sh/vercel.json',\n      crons: [{ path, schedule: options.schedule }],\n    }\n  }\n\n  const everyMinutes = options.everyMinutes ?? DEFAULT_SWEEP_INTERVAL_MINUTES\n  if (!Number.isInteger(everyMinutes) || everyMinutes <= 0) {\n    throw new Error(\n      'Vercel workflow sweep interval must be a positive integer.',\n    )\n  }\n\n  return {\n    $schema: 'https://openapi.vercel.sh/vercel.json',\n    crons: [\n      {\n        path,\n        schedule:\n          everyMinutes === 1 ? '* * * * *' : `*/${everyMinutes} * * * *`,\n      },\n    ],\n  }\n}\n\nexport function createVercelWorkflowSweepHandler<\n  TWorkflows extends WorkflowRegistrationMap,\n>(\n  options: VercelWorkflowSweepHandlerOptions<TWorkflows>,\n): VercelWorkflowSweepHandler {\n  return async (request) => {\n    if (!isAuthorized(request, options.cronSecret)) {\n      return Response.json(\n        {\n          ok: false,\n          error: 'Unauthorized',\n        } satisfies VercelWorkflowUnauthorizedResponse,\n        { status: 401 },\n      )\n    }\n\n    const now = options.now?.() ?? Date.now()\n    const materialized =\n      options.materializeSchedules === false\n        ? []\n        : await materializeWorkflowSchedules(options.runtime, {\n            now,\n            cronLookbackMs: options.cronLookbackMs,\n          })\n    const leaseOwner = resolveLeaseOwner(options.leaseOwner, request, now)\n    const sweepArgs: WorkflowRuntimeSweepArgs = {\n      now,\n      leaseOwner,\n      limit: options.limit,\n      maxScheduledRuns: options.maxScheduledRuns,\n      maxTimers: options.maxTimers,\n      maxDurationMs: options.maxDurationMs,\n      leaseMs: options.leaseMs,\n      includeEvents: options.includeEvents ?? false,\n      maxEvents: options.maxEvents,\n    }\n    const sweep = await options.runtime.sweep(sweepArgs)\n    const response: VercelWorkflowSweepResponse = {\n      ok: true,\n      now,\n      leaseOwner,\n      materialized,\n      summary: {\n        materialized: materialized.length,\n        ...sweep.summary,\n      },\n      deadlineReached: sweep.deadlineReached,\n      remainingMayExist: sweep.remainingMayExist,\n      ...(options.includeSweepResult ? { sweep } : undefined),\n    }\n\n    return Response.json(response)\n  }\n}\n\nfunction isAuthorized(request: Request, cronSecret: string | undefined) {\n  if (!cronSecret) return true\n  return request.headers.get('authorization') === `Bearer ${cronSecret}`\n}\n\nfunction resolveLeaseOwner(\n  leaseOwner: VercelWorkflowSweepHandlerOptions['leaseOwner'],\n  request: Request,\n  now: number,\n) {\n  if (typeof leaseOwner === 'string') return leaseOwner\n  if (typeof leaseOwner === 'function') {\n    return leaseOwner({ request, now }) ?? defaultLeaseOwner(request, now)\n  }\n  return defaultLeaseOwner(request, now)\n}\n\nfunction defaultLeaseOwner(request: Request, now: number) {\n  return `vercel:${request.headers.get('x-vercel-id') ?? now}`\n}\n"],"mappings":";;;AASA,MAAM,iCAAiC;AACvC,MAAM,qBAAqB;AAoE3B,MAAa,2BAA2B,gCAAgC;AAExE,SAAgB,+BACd,UAA2C,EAAE,EACnB;CAC1B,MAAM,OAAO,QAAQ,QAAQ;AAC7B,KAAI,CAAC,KAAK,WAAW,IAAI,CACvB,OAAM,IAAI,MAAM,mDAAiD;AAEnE,KAAI,QAAQ,SACV,QAAO;EACL,SAAS;EACT,OAAO,CAAC;GAAE;GAAM,UAAU,QAAQ;GAAU,CAAC;EAC9C;CAGH,MAAM,eAAe,QAAQ,gBAAgB;AAC7C,KAAI,CAAC,OAAO,UAAU,aAAa,IAAI,gBAAgB,EACrD,OAAM,IAAI,MACR,6DACD;AAGH,QAAO;EACL,SAAS;EACT,OAAO,CACL;GACE;GACA,UACE,iBAAiB,IAAI,cAAc,KAAK,aAAa;GACxD,CACF;EACF;;AAGH,SAAgB,iCAGd,SAC4B;AAC5B,QAAO,OAAO,YAAY;AACxB,MAAI,CAAC,aAAa,SAAS,QAAQ,WAAW,CAC5C,QAAO,SAAS,KACd;GACE,IAAI;GACJ,OAAO;GACR,EACD,EAAE,QAAQ,KAAK,CAChB;EAGH,MAAM,MAAM,QAAQ,OAAO,IAAI,KAAK,KAAK;EACzC,MAAM,eACJ,QAAQ,yBAAyB,QAC7B,EAAE,GACF,MAAM,6BAA6B,QAAQ,SAAS;GAClD;GACA,gBAAgB,QAAQ;GACzB,CAAC;EACR,MAAM,aAAa,kBAAkB,QAAQ,YAAY,SAAS,IAAI;EACtE,MAAM,YAAsC;GAC1C;GACA;GACA,OAAO,QAAQ;GACf,kBAAkB,QAAQ;GAC1B,WAAW,QAAQ;GACnB,eAAe,QAAQ;GACvB,SAAS,QAAQ;GACjB,eAAe,QAAQ,iBAAiB;GACxC,WAAW,QAAQ;GACpB;EACD,MAAM,QAAQ,MAAM,QAAQ,QAAQ,MAAM,UAAU;EACpD,MAAM,WAAwC;GAC5C,IAAI;GACJ;GACA;GACA;GACA,SAAS;IACP,cAAc,aAAa;IAC3B,GAAG,MAAM;IACV;GACD,iBAAiB,MAAM;GACvB,mBAAmB,MAAM;GACzB,GAAI,QAAQ,qBAAqB,EAAE,OAAO,GAAG;GAC9C;AAED,SAAO,SAAS,KAAK,SAAS;;;AAIlC,SAAS,aAAa,SAAkB,YAAgC;AACtE,KAAI,CAAC,WAAY,QAAO;AACxB,QAAO,QAAQ,QAAQ,IAAI,gBAAgB,KAAK,UAAU;;AAG5D,SAAS,kBACP,YACA,SACA,KACA;AACA,KAAI,OAAO,eAAe,SAAU,QAAO;AAC3C,KAAI,OAAO,eAAe,WACxB,QAAO,WAAW;EAAE;EAAS;EAAK,CAAC,IAAI,kBAAkB,SAAS,IAAI;AAExE,QAAO,kBAAkB,SAAS,IAAI;;AAGxC,SAAS,kBAAkB,SAAkB,KAAa;AACxD,QAAO,UAAU,QAAQ,QAAQ,IAAI,cAAc,IAAI"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@tanstack/workflow-vercel",
+  "version": "0.0.1",
+  "description": "Vercel host adapter for TanStack Workflow runtimes.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/workflow.git",
+    "directory": "packages/workflow-vercel"
+  },
+  "homepage": "https://tanstack.com/workflow",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "tanstack",
+    "workflow",
+    "durable-execution",
+    "vercel",
+    "serverless"
+  ],
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "build": "tsdown"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/workflow-runtime": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  createVercelWorkflowCronConfig,
+  createVercelWorkflowSweepHandler,
+  materializeWorkflowSchedules,
+  vercelWorkflowCronConfig,
+} from './sweep-handler'
+export type {
+  MaterializedWorkflowSchedule,
+  MaterializeWorkflowSchedulesOptions,
+  VercelWorkflowCron,
+  VercelWorkflowCronConfig,
+  VercelWorkflowCronConfigOptions,
+  VercelWorkflowSweepHandler,
+  VercelWorkflowSweepHandlerOptions,
+  VercelWorkflowSweepResponse,
+  VercelWorkflowUnauthorizedResponse,
+} from './sweep-handler'

package/src/sweep-handler.ts

@@ -0,0 +1,188 @@
+import { materializeWorkflowSchedules } from '@tanstack/workflow-runtime'
+import type {
+  MaterializedWorkflowSchedule,
+  WorkflowRegistrationMap,
+  WorkflowRuntimeDefinition,
+  WorkflowRuntimeSweepArgs,
+  WorkflowRuntimeSweepResult,
+} from '@tanstack/workflow-runtime'
+
+const DEFAULT_SWEEP_INTERVAL_MINUTES = 5
+const DEFAULT_SWEEP_PATH = '/api/workflow/sweep'
+
+export { materializeWorkflowSchedules }
+export type {
+  MaterializedWorkflowSchedule,
+  MaterializeWorkflowSchedulesOptions,
+} from '@tanstack/workflow-runtime'
+
+export interface VercelWorkflowCron {
+  path: string
+  schedule: string
+}
+
+export interface VercelWorkflowCronConfig {
+  $schema: 'https://openapi.vercel.sh/vercel.json'
+  crons: ReadonlyArray<VercelWorkflowCron>
+}
+
+export interface VercelWorkflowCronConfigOptions {
+  path?: string
+  schedule?: string
+  everyMinutes?: number
+}
+
+export interface VercelWorkflowSweepResponse {
+  ok: true
+  now: number
+  leaseOwner: string
+  materialized: ReadonlyArray<MaterializedWorkflowSchedule>
+  summary: VercelWorkflowSweepSummary
+  deadlineReached: boolean
+  remainingMayExist: boolean
+  sweep?: WorkflowRuntimeSweepResult
+}
+
+export interface VercelWorkflowUnauthorizedResponse {
+  ok: false
+  error: 'Unauthorized'
+}
+
+export type VercelWorkflowSweepSummary =
+  WorkflowRuntimeSweepResult['summary'] & {
+    materialized: number
+  }
+
+export type VercelWorkflowSweepHandler = (request: Request) => Promise<Response>
+
+export interface VercelWorkflowSweepHandlerOptions<
+  TWorkflows extends WorkflowRegistrationMap = WorkflowRegistrationMap,
+> {
+  runtime: WorkflowRuntimeDefinition<TWorkflows>
+  now?: () => number
+  leaseOwner?:
+    | string
+    | ((args: { request: Request; now: number }) => string | undefined)
+  limit?: number
+  maxScheduledRuns?: number
+  maxTimers?: number
+  maxDurationMs?: number
+  leaseMs?: number
+  includeEvents?: boolean
+  maxEvents?: number
+  includeSweepResult?: boolean
+  materializeSchedules?: boolean
+  cronLookbackMs?: number
+  cronSecret?: string
+}
+
+export const vercelWorkflowCronConfig = createVercelWorkflowCronConfig()
+
+export function createVercelWorkflowCronConfig(
+  options: VercelWorkflowCronConfigOptions = {},
+): VercelWorkflowCronConfig {
+  const path = options.path ?? DEFAULT_SWEEP_PATH
+  if (!path.startsWith('/')) {
+    throw new Error('Vercel workflow cron path must start with "/".')
+  }
+  if (options.schedule) {
+    return {
+      $schema: 'https://openapi.vercel.sh/vercel.json',
+      crons: [{ path, schedule: options.schedule }],
+    }
+  }
+
+  const everyMinutes = options.everyMinutes ?? DEFAULT_SWEEP_INTERVAL_MINUTES
+  if (!Number.isInteger(everyMinutes) || everyMinutes <= 0) {
+    throw new Error(
+      'Vercel workflow sweep interval must be a positive integer.',
+    )
+  }
+
+  return {
+    $schema: 'https://openapi.vercel.sh/vercel.json',
+    crons: [
+      {
+        path,
+        schedule:
+          everyMinutes === 1 ? '* * * * *' : `*/${everyMinutes} * * * *`,
+      },
+    ],
+  }
+}
+
+export function createVercelWorkflowSweepHandler<
+  TWorkflows extends WorkflowRegistrationMap,
+>(
+  options: VercelWorkflowSweepHandlerOptions<TWorkflows>,
+): VercelWorkflowSweepHandler {
+  return async (request) => {
+    if (!isAuthorized(request, options.cronSecret)) {
+      return Response.json(
+        {
+          ok: false,
+          error: 'Unauthorized',
+        } satisfies VercelWorkflowUnauthorizedResponse,
+        { status: 401 },
+      )
+    }
+
+    const now = options.now?.() ?? Date.now()
+    const materialized =
+      options.materializeSchedules === false
+        ? []
+        : await materializeWorkflowSchedules(options.runtime, {
+            now,
+            cronLookbackMs: options.cronLookbackMs,
+          })
+    const leaseOwner = resolveLeaseOwner(options.leaseOwner, request, now)
+    const sweepArgs: WorkflowRuntimeSweepArgs = {
+      now,
+      leaseOwner,
+      limit: options.limit,
+      maxScheduledRuns: options.maxScheduledRuns,
+      maxTimers: options.maxTimers,
+      maxDurationMs: options.maxDurationMs,
+      leaseMs: options.leaseMs,
+      includeEvents: options.includeEvents ?? false,
+      maxEvents: options.maxEvents,
+    }
+    const sweep = await options.runtime.sweep(sweepArgs)
+    const response: VercelWorkflowSweepResponse = {
+      ok: true,
+      now,
+      leaseOwner,
+      materialized,
+      summary: {
+        materialized: materialized.length,
+        ...sweep.summary,
+      },
+      deadlineReached: sweep.deadlineReached,
+      remainingMayExist: sweep.remainingMayExist,
+      ...(options.includeSweepResult ? { sweep } : undefined),
+    }
+
+    return Response.json(response)
+  }
+}
+
+function isAuthorized(request: Request, cronSecret: string | undefined) {
+  if (!cronSecret) return true
+  return request.headers.get('authorization') === `Bearer ${cronSecret}`
+}
+
+function resolveLeaseOwner(
+  leaseOwner: VercelWorkflowSweepHandlerOptions['leaseOwner'],
+  request: Request,
+  now: number,
+) {
+  if (typeof leaseOwner === 'string') return leaseOwner
+  if (typeof leaseOwner === 'function') {
+    return leaseOwner({ request, now }) ?? defaultLeaseOwner(request, now)
+  }
+  return defaultLeaseOwner(request, now)
+}
+
+function defaultLeaseOwner(request: Request, now: number) {
+  return `vercel:${request.headers.get('x-vercel-id') ?? now}`
+}