@vite-hub/workflow 0.0.0 → 0.0.1

package/README.md

@@ -1,3 +1,62 @@
 # @vite-hub/workflow
 
-Reserved package name for ViteHub.
+<p>
+  <a href="https://vitehub.dev"><img alt="ViteHub" src="https://img.shields.io/badge/ViteHub-vitehub.dev-646cff?style=flat-square"></a>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-3178c6?style=flat-square">
+  <img alt="Vite" src="https://img.shields.io/badge/Vite-discovery-646cff?style=flat-square">
+  <img alt="Workflow" src="https://img.shields.io/badge/Workflow-durable%20steps-7c3aed?style=flat-square">
+</p>
+
+`@vite-hub/workflow` defines long-running work once and starts it through one `runWorkflow()` API.
+
+## Install
+
+```sh
+pnpm add @vite-hub/workflow
+```
+
+Add the provider dependency for the workflow provider you configure.
+
+## Minimal API
+
+```ts
+// server/workflows/welcome.ts
+import { defineWorkflow } from "@vite-hub/workflow"
+
+export default defineWorkflow<{ email: string }>(async ({ id, payload, step }) => {
+  const email = await step?.do?.("send-email", {}, async () => {
+    return { sentTo: payload.email }
+  })
+
+  return { id, email }
+})
+```
+
+```ts
+// server/api/welcome.post.ts
+import { getWorkflowRun, runWorkflow } from "@vite-hub/workflow"
+import { defineEventHandler, readBody } from "h3"
+
+export default defineEventHandler(async (event) => {
+  const run = await runWorkflow("welcome", await readBody<{ email: string }>(event))
+  return getWorkflowRun("welcome", run.id)
+})
+```
+
+```ts
+// nitro.config.ts
+import { defineNitroConfig } from "nitro/config"
+
+export default defineNitroConfig({
+  modules: ["@vite-hub/workflow/nitro"],
+  workflow: { provider: "openworkflow" },
+})
+```
+
+## Vite and Nitro
+
+Nitro discovers `server/workflows/<name>.ts` and folder workflows such as `server/workflows/welcome/index.ts` with numbered step files. Vite also supports `src/<name>.workflow.ts` through `hubWorkflow()`.
+
+Providers map to [OpenWorkflow](https://openworkflow.dev/docs/overview), [Cloudflare Workflows](https://developers.cloudflare.com/workflows/), or [Vercel Workflow](https://vercel.com/docs/workflow).
+
+Learn more at [vitehub.dev](https://vitehub.dev).

package/dist/_app-BVWpnNHo.d.ts

@@ -0,0 +1,11 @@
+//#region ../internal/src/runtime/app.d.ts
+type AppHandler = (request: Request, context?: Record<string, unknown>) => Response | Promise<Response>;
+type VitehubApp = AppHandler | {
+  fetch?: AppHandler;
+  request?: (request: Request, options?: RequestInit, context?: Record<string, unknown>) => Response | Promise<Response>;
+};
+//#endregion
+//#region src/runtime/_app.d.ts
+type WorkflowApp = VitehubApp;
+//#endregion
+export { WorkflowApp as t };

package/dist/app-BE3EYOWn.js

@@ -0,0 +1,10 @@
+//#region ../internal/src/runtime/app.ts
+function resolveAppFetch(label, app) {
+	if (!app) return;
+	if (typeof app === "function") return app;
+	if (typeof app.request === "function") return (request, context) => app.request(request, void 0, context);
+	if (typeof app.fetch === "function") return app.fetch.bind(app);
+	throw new TypeError(`Invalid ${label} app. Expected an h3 app or a fetch-compatible handler.`);
+}
+//#endregion
+export { resolveAppFetch as t };

package/dist/cloudflare-CeHVSHoN.js

@@ -0,0 +1,42 @@
+//#region ../internal/src/integrations/hex.ts
+const textEncoder = new TextEncoder();
+new TextDecoder();
+function encodeNameHex(name) {
+	return [...textEncoder.encode(name)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+//#region src/integrations/cloudflare.ts
+const cloudflareWorkflowNameMaxLength = 64;
+function shortHash(value) {
+	let hash = 2166136261;
+	for (const char of value) {
+		hash ^= char.codePointAt(0) || 0;
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function getCloudflareWorkflowBindingName(name) {
+	return `WORKFLOW_${encodeNameHex(name).toUpperCase()}`;
+}
+function getCloudflareWorkflowName(name) {
+	const encoded = encodeNameHex(name);
+	const fullName = `workflow--${encoded}`;
+	if (fullName.length <= cloudflareWorkflowNameMaxLength) return fullName;
+	const hash = shortHash(name);
+	const prefixLength = cloudflareWorkflowNameMaxLength - 10 - 1 - hash.length;
+	return `workflow--${encoded.slice(0, prefixLength)}-${hash}`;
+}
+function getCloudflareWorkflowClassName(name) {
+	return `ViteHub${name.split(/[^a-z0-9]+/i).filter(Boolean).map((segment) => `${segment.charAt(0).toUpperCase()}${segment.slice(1)}`).join("") || "Default"}${shortHash(name)}Workflow`;
+}
+function createCloudflareWorkflowBindings(definitions, options) {
+	if (!definitions.length) return;
+	if (definitions.length > 1 && options && (options.binding || options.name)) throw new TypeError("Cloudflare workflow binding and name overrides are only supported when one workflow is discovered.");
+	return definitions.map((definition) => ({
+		binding: definitions.length === 1 && options ? options.binding || getCloudflareWorkflowBindingName(definition.name) : getCloudflareWorkflowBindingName(definition.name),
+		class_name: getCloudflareWorkflowClassName(definition.name),
+		name: definitions.length === 1 && options ? options.name || getCloudflareWorkflowName(definition.name) : getCloudflareWorkflowName(definition.name)
+	}));
+}
+//#endregion
+export { encodeNameHex as a, getCloudflareWorkflowName as i, getCloudflareWorkflowBindingName as n, getCloudflareWorkflowClassName as r, createCloudflareWorkflowBindings as t };

package/dist/cloudflare-env-BVUMOgFK.d.ts

@@ -0,0 +1,21 @@
+//#region ../internal/src/runtime/cloudflare-env.d.ts
+type CloudflareWorkerEnv = Record<string, unknown>;
+interface CloudflareWorkerExecutionContext {
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+declare function setActiveCloudflareEnv(env: CloudflareWorkerEnv | undefined): void;
+type WaitUntilFn = (promise: Promise<unknown>) => void;
+interface CloudflareRuntimeEvent {
+  context: {
+    cloudflare: {
+      context: CloudflareWorkerExecutionContext | undefined;
+      env: CloudflareWorkerEnv;
+    };
+    waitUntil?: WaitUntilFn;
+  };
+  env: CloudflareWorkerEnv;
+  waitUntil?: WaitUntilFn;
+}
+declare function createCloudflareRuntimeEvent(env: CloudflareWorkerEnv, context: CloudflareWorkerExecutionContext | undefined): CloudflareRuntimeEvent;
+//#endregion
+export { setActiveCloudflareEnv as i, CloudflareWorkerExecutionContext as n, createCloudflareRuntimeEvent as r, CloudflareWorkerEnv as t };

package/dist/cloudflare-env-g0Rf3ClH.js

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region ../internal/src/runtime/cloudflare-env.ts
+let activeEnv;
+const activeEnvStorage = new AsyncLocalStorage();
+function setActiveCloudflareEnv(env) {
+	activeEnv = env;
+	globalThis.__env__ = env;
+	try {
+		activeEnvStorage.enterWith(env);
+	} catch {}
+}
+function getActiveCloudflareEnv() {
+	return activeEnvStorage.getStore() ?? activeEnv ?? globalThis.__env__;
+}
+function getCloudflareEnv(event) {
+	const target = event;
+	return target?.env || target?.context?.cloudflare?.env || target?.context?._platform?.cloudflare?.env || target?.req?.runtime?.cloudflare?.env || getActiveCloudflareEnv();
+}
+function resolveWaitUntil(event) {
+	const target = event;
+	const owners = [
+		target,
+		target?.context,
+		target?.context?.cloudflare,
+		target?.context?.cloudflare?.context,
+		target?.context?._platform?.cloudflare,
+		target?.context?._platform?.cloudflare?.context,
+		target?.req,
+		target?.req?.runtime?.cloudflare,
+		target?.req?.runtime?.cloudflare?.context
+	];
+	for (const owner of owners) if (typeof owner?.waitUntil === "function") return owner.waitUntil.bind(owner);
+}
+function createCloudflareRuntimeEvent(env, context) {
+	const waitUntil = typeof context?.waitUntil === "function" ? context.waitUntil.bind(context) : void 0;
+	return {
+		context: {
+			cloudflare: {
+				env,
+				context
+			},
+			waitUntil
+		},
+		env,
+		waitUntil
+	};
+}
+//#endregion
+export { setActiveCloudflareEnv as i, getCloudflareEnv as n, resolveWaitUntil as r, createCloudflareRuntimeEvent as t };

package/dist/cloudflare-shared-BIeY2kak.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cloudflare-vite-DcM5YVTP.js

@@ -0,0 +1,40 @@
+import { t as normalizeWorkflowOptions } from "./config-DkgsQuXz.js";
+import { i as setActiveCloudflareEnv, t as createCloudflareRuntimeEvent } from "./cloudflare-env-g0Rf3ClH.js";
+import { runWithWorkflowRuntimeEvent, setWorkflowRuntimeConfig, setWorkflowRuntimeRegistry } from "./runtime/state.js";
+import { t as resolveAppFetch } from "./app-BE3EYOWn.js";
+import { H3, toWebHandler } from "h3/cloudflare";
+//#region ../internal/src/runtime/cloudflare-hosted.ts
+function createWebRequestHandler(appHandler) {
+	const defaultHandler = toWebHandler(new H3());
+	return async (request, context) => await Promise.resolve(appHandler ? appHandler(request, context) : defaultHandler(request, context));
+}
+function createCloudflareHostedWorker(adapter) {
+	const requestHandler = createWebRequestHandler(resolveAppFetch(adapter.label, adapter.app));
+	return { async fetch(request, env, context) {
+		const handle = async (handlerContext) => await Promise.resolve(requestHandler(request, handlerContext));
+		if (adapter.onRequest) return await adapter.onRequest({
+			env,
+			executionContext: context,
+			handle
+		});
+		return await handle();
+	} };
+}
+//#endregion
+//#region src/runtime/cloudflare-vite.ts
+function createWorkflowCloudflareWorker(options = {}) {
+	const workflowConfig = options.workflow === false ? false : normalizeWorkflowOptions(options.workflow, { hosting: "cloudflare" });
+	return createCloudflareHostedWorker({
+		app: options.app,
+		label: "workflow",
+		async onRequest({ env, executionContext, handle }) {
+			setWorkflowRuntimeConfig(workflowConfig);
+			setWorkflowRuntimeRegistry(options.registry);
+			setActiveCloudflareEnv(env);
+			const runtimeEvent = createCloudflareRuntimeEvent(env, executionContext);
+			return await runWithWorkflowRuntimeEvent(runtimeEvent, () => handle(runtimeEvent.context));
+		}
+	});
+}
+//#endregion
+export { createWorkflowCloudflareWorker as t };

package/dist/config-DkgsQuXz.js

@@ -0,0 +1,92 @@
+import { defu } from "defu";
+//#region ../internal/src/feature-bridge/hosting.ts
+function normalizeHosting(hosting) {
+	const normalized = hosting?.trim().toLowerCase().replaceAll("_", "-") || "";
+	if (normalized === "cloudflare") return "cloudflare-module";
+	return normalized;
+}
+//#endregion
+//#region ../internal/src/object.ts
+function isPlainObject(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#region src/config.ts
+const knownProviders = new Set([
+	"cloudflare",
+	"openworkflow",
+	"vercel"
+]);
+function readString(value, label) {
+	if (typeof value === "undefined") return;
+	if (typeof value !== "string" || !value.trim()) throw new TypeError(`\`${label}\` must be a non-empty string when provided.`);
+	return value.trim();
+}
+function readBoolean(value, label) {
+	if (typeof value === "undefined") return;
+	if (typeof value !== "boolean") throw new TypeError(`\`${label}\` must be a boolean when provided.`);
+	return value;
+}
+function readPositiveInteger(value, label) {
+	if (typeof value === "undefined") return;
+	if (!Number.isInteger(value) || value <= 0) throw new TypeError(`\`${label}\` must be a positive integer when provided.`);
+	return value;
+}
+function normalizeOpenWorkflowPostgresOptions(value) {
+	if (typeof value === "undefined") return;
+	if (!isPlainObject(value)) throw new TypeError("`workflow.postgres` must be a plain object.");
+	const namespaceId = readString(value.namespaceId, "workflow.postgres.namespaceId");
+	const runMigrations = readBoolean(value.runMigrations, "workflow.postgres.runMigrations");
+	const schema = readString(value.schema, "workflow.postgres.schema");
+	const url = readString(value.url, "workflow.postgres.url");
+	return {
+		...namespaceId ? { namespaceId } : {},
+		...typeof runMigrations === "boolean" ? { runMigrations } : {},
+		...schema ? { schema } : {},
+		...url ? { url } : {}
+	};
+}
+function normalizeOpenWorkflowWorkerOptions(value) {
+	if (typeof value === "undefined") return;
+	if (!isPlainObject(value)) throw new TypeError("`workflow.worker` must be a plain object.");
+	const concurrency = readPositiveInteger(value.concurrency, "workflow.worker.concurrency");
+	return typeof concurrency === "number" ? { concurrency } : {};
+}
+function hasOpenWorkflowPostgresConfig(options) {
+	return isPlainObject(options.postgres) && typeof options.postgres.url === "string" && !!options.postgres.url.trim();
+}
+function inferProvider(provider, hosting) {
+	if (provider === "cloudflare" || provider === "openworkflow" || provider === "vercel") return provider;
+	if (hosting.includes("cloudflare")) return "cloudflare";
+	return "vercel";
+}
+function inferProviderFromOptions(options, hosting) {
+	if (typeof options.provider === "undefined" && (hosting.includes("node") || hosting.includes("docker")) && hasOpenWorkflowPostgresConfig(options)) return "openworkflow";
+	return inferProvider(options.provider, hosting);
+}
+function resolveProvider(options, hosting) {
+	const shared = {
+		...typeof options.binding === "string" ? { binding: options.binding } : {},
+		...typeof options.name === "string" ? { name: options.name } : {}
+	};
+	const provider = options.provider;
+	if (typeof provider === "string" && !knownProviders.has(provider)) throw new TypeError(`Unknown \`workflow.provider\`: ${JSON.stringify(provider)}. Expected "cloudflare", "openworkflow", or "vercel".`);
+	const resolved = inferProviderFromOptions(options, hosting);
+	if (resolved === "cloudflare") return defu(shared, { provider: "cloudflare" });
+	if (resolved === "openworkflow") {
+		const postgres = normalizeOpenWorkflowPostgresOptions(options.postgres);
+		const worker = normalizeOpenWorkflowWorkerOptions(options.worker);
+		return defu({
+			...postgres ? { postgres } : {},
+			...worker ? { worker } : {}
+		}, shared, { provider: "openworkflow" });
+	}
+	return defu(shared, { provider: "vercel" });
+}
+function normalizeWorkflowOptions(options, input = {}) {
+	if (options === false) return void 0;
+	if (typeof options !== "undefined" && !isPlainObject(options)) throw new TypeError("`workflow` must be a plain object.");
+	return resolveProvider(options || {}, normalizeHosting(input.hosting));
+}
+//#endregion
+export { normalizeWorkflowOptions as t };

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import { A as WorkflowStepRunner, C as WorkflowProviderStep, D as WorkflowStartOptions, E as WorkflowSharedOptions, O as WorkflowStepFunction, S as WorkflowProviderOptions, T as WorkflowRunStatus, _ as WorkflowHandle, a as InferredWorkflowProviderOptions, b as WorkflowModuleProviderOptions, c as OpenWorkflowWorkerOptions, d as WorkflowCreateOptions, f as WorkflowDeferOptions, g as WorkflowExecutionContext, h as WorkflowDefinitionRegistry, i as DiscoveredWorkflowDefinition, k as WorkflowStepOptions, l as ResolvedWorkflowOptions, m as WorkflowDefinitionOptions, n as CloudflareWorkflowInstance, o as OpenWorkflowPostgresOptions, p as WorkflowDefinition, r as CloudflareWorkflowProviderOptions, s as OpenWorkflowProviderOptions, t as CloudflareWorkflowBinding, u as VercelWorkflowProviderOptions, v as WorkflowHandler, w as WorkflowRun, x as WorkflowProvider, y as WorkflowModuleOptions } from "./types-ThDitg7Z.js";
+import { createWorkflowCloudflareWorker } from "./runtime/cloudflare-vite.js";
+import { createOpenWorkflowWorker, startOpenWorkflowWorker } from "./runtime/openworkflow-worker.js";
+
+//#region src/config.d.ts
+interface WorkflowResolutionInput {
+  hosting?: string;
+}
+declare function normalizeWorkflowOptions(options: WorkflowModuleOptions | undefined, input?: WorkflowResolutionInput): ResolvedWorkflowOptions | undefined;
+//#endregion
+//#region src/definition.d.ts
+declare function defineWorkflow<TPayload = unknown, TResult = unknown>(handler: WorkflowHandler<TPayload, TResult>, options?: WorkflowDefinitionOptions): WorkflowDefinition<TPayload, TResult>;
+//#endregion
+//#region src/errors.d.ts
+interface WorkflowErrorOptions {
+  cause?: unknown;
+  code?: string;
+  details?: Record<string, unknown>;
+  httpStatus?: number;
+  provider?: string;
+}
+declare class WorkflowError extends Error {
+  readonly code?: string;
+  readonly details?: Record<string, unknown>;
+  readonly httpStatus?: number;
+  readonly provider?: string;
+  constructor(message: string, options?: WorkflowErrorOptions);
+}
+//#endregion
+//#region src/integrations/cloudflare.d.ts
+declare function getCloudflareWorkflowBindingName(name: string): string;
+declare function getCloudflareWorkflowName(name: string): string;
+declare function getCloudflareWorkflowClassName(name: string): string;
+//#endregion
+//#region src/integrations/vercel.d.ts
+declare function getVercelWorkflowName(name: string): string;
+//#endregion
+//#region src/runtime/client.d.ts
+declare function createWorkflow<TPayload = unknown, TResult = unknown>(options: WorkflowCreateOptions<TPayload, TResult> & {
+  handler: WorkflowHandler<TPayload, TResult>;
+  name: string;
+}): WorkflowHandle<TPayload, TResult>;
+declare function createWorkflow<TPayload = unknown, TResult = unknown>(name: string, options?: WorkflowCreateOptions<TPayload, TResult>): WorkflowHandle<TPayload, TResult>;
+declare function createWorkflow<TPayload = unknown, TResult = unknown>(name: string, handler: WorkflowHandler<TPayload, TResult>, options?: WorkflowCreateOptions<TPayload, TResult>): WorkflowHandle<TPayload, TResult>;
+declare function runWorkflow<TPayload = unknown, TResult = unknown>(name: string, payload?: TPayload, options?: WorkflowDeferOptions): Promise<WorkflowRun<TPayload, TResult>>;
+declare function getWorkflowRun<TPayload = unknown, TResult = unknown>(name: string, id: string): Promise<WorkflowRun<TPayload, TResult>>;
+declare function deferWorkflow<TPayload = unknown>(name: string, payload?: TPayload, options?: WorkflowStartOptions): Promise<WorkflowRun<TPayload>>;
+//#endregion
+//#region src/runtime/payload.d.ts
+interface PayloadSchema<T> {
+  safeParse: (payload: unknown) => {
+    success: boolean;
+    data?: T;
+    error?: unknown;
+  };
+}
+interface ParsePayloadSchema<T> {
+  parse: (payload: unknown) => T;
+}
+type PayloadValidator<T> = PayloadSchema<T> | ParsePayloadSchema<T> | ((payload: unknown) => T | Promise<T>);
+declare function readRequestPayload<T = unknown>(request: Request): Promise<T>;
+declare function validatePayload<T>(payload: unknown, schema: PayloadValidator<T>): Promise<T>;
+declare function readValidatedPayload<T>(request: Request, schema: PayloadValidator<T>): Promise<T>;
+//#endregion
+export { type CloudflareWorkflowBinding, type CloudflareWorkflowInstance, type CloudflareWorkflowProviderOptions, type DiscoveredWorkflowDefinition, type InferredWorkflowProviderOptions, type OpenWorkflowPostgresOptions, type OpenWorkflowProviderOptions, type OpenWorkflowWorkerOptions, type ResolvedWorkflowOptions, type VercelWorkflowProviderOptions, type WorkflowCreateOptions, type WorkflowDeferOptions, type WorkflowDefinition, type WorkflowDefinitionOptions, type WorkflowDefinitionRegistry, WorkflowError, type WorkflowExecutionContext, type WorkflowHandle, type WorkflowHandler, type WorkflowModuleOptions, type WorkflowModuleProviderOptions, type WorkflowProvider, type WorkflowProviderOptions, type WorkflowProviderStep, type WorkflowRun, type WorkflowRunStatus, type WorkflowSharedOptions, type WorkflowStartOptions, type WorkflowStepFunction, type WorkflowStepOptions, type WorkflowStepRunner, createOpenWorkflowWorker, createWorkflow, createWorkflowCloudflareWorker, deferWorkflow, defineWorkflow, getCloudflareWorkflowBindingName, getCloudflareWorkflowClassName, getCloudflareWorkflowName, getVercelWorkflowName, getWorkflowRun, normalizeWorkflowOptions, readRequestPayload, readValidatedPayload, runWorkflow, startOpenWorkflowWorker, validatePayload };