@gencow/core 0.1.23 → 0.1.24

package/src/workflow-types.ts

@@ -0,0 +1,111 @@
+import type { GencowCtx } from "./reactive.js";
+import type { InferArgs } from "./v.js";
+
+export type WorkflowStatus = "pending" | "running" | "completed" | "failed";
+export type WorkflowDuration = number | string;
+export type WorkflowDerivedStatus = WorkflowStatus | "queued" | "waiting" | "sleeping";
+
+export function deriveWorkflowStatus(
+    status: WorkflowStatus,
+    currentStep: string | null | undefined
+): WorkflowDerivedStatus {
+    if (status !== "pending") {
+        return status;
+    }
+    if (currentStep?.startsWith("sleep#")) {
+        return "sleeping";
+    }
+    if (currentStep?.startsWith("wait:")) {
+        return "waiting";
+    }
+    return "queued";
+}
+
+export interface WorkflowSummary {
+    id: string;
+    name: string;
+    status: WorkflowStatus;
+    derivedStatus: WorkflowDerivedStatus;
+    currentStep: string | null;
+    error: string | null;
+    retryCount: number;
+    maxRetries: number;
+    maxDurationMs: number;
+    startedAt: string;
+    updatedAt: string;
+    completedAt: string | null;
+}
+
+export interface WorkflowStepSnapshot {
+    name: string;
+    status: WorkflowStatus;
+    output: unknown;
+    error: string | null;
+    startedAt: string | null;
+    updatedAt: string;
+    completedAt: string | null;
+}
+
+export interface WorkflowSnapshot extends WorkflowSummary {
+    args: unknown;
+    result: unknown;
+    steps: WorkflowStepSnapshot[];
+    /** Opaque realtime channel for exact-id workflow updates. */
+    realtimeKey: string;
+}
+
+export interface WorkflowListArgs {
+    limit?: number;
+    status?: WorkflowDerivedStatus;
+}
+
+export interface WorkflowStartResult {
+    id: string;
+    name: string;
+    status: "pending";
+    scheduledJobId: string;
+}
+
+export interface WorkflowSignalResult {
+    ok: boolean;
+    workflowId: string;
+    event: string;
+    scheduledJobId: string | null;
+}
+
+export interface WorkflowResumePayload {
+    workflowId: string;
+}
+
+export interface WorkflowCtx extends GencowCtx {
+    workflowId: string;
+    workflowName: string;
+    step<TResult>(name: string, run: () => Promise<TResult>): Promise<TResult>;
+    sleep(duration: WorkflowDuration): Promise<void>;
+    waitForEvent<TPayload = unknown>(name: string, timeout?: WorkflowDuration): Promise<TPayload>;
+    parallel<TTasks extends ReadonlyArray<() => Promise<any>>>(
+        tasks: TTasks
+    ): Promise<{ [K in keyof TTasks]: Awaited<ReturnType<TTasks[K]>> }>;
+}
+
+export type WorkflowHandler<TArgs, TReturn> = (
+    wf: WorkflowCtx,
+    args: TArgs
+) => Promise<TReturn>;
+
+export interface WorkflowOptions<TSchema = any, TReturn = any> {
+    args?: TSchema;
+    public?: boolean;
+    maxDuration?: WorkflowDuration;
+    retries?: number;
+    handler: WorkflowHandler<InferArgs<TSchema>, TReturn>;
+}
+
+export interface WorkflowDef<TSchema = any, TReturn = any> {
+    name: string;
+    argsSchema?: TSchema;
+    isPublic: boolean;
+    maxDurationMs: number;
+    maxRetries: number;
+    handler: WorkflowHandler<InferArgs<TSchema>, TReturn>;
+}

package/src/workflow.ts

@@ -0,0 +1,205 @@
+import { sql } from "drizzle-orm";
+import { mutation } from "./reactive.js";
+import type { MutationDef } from "./reactive.js";
+import type {
+    WorkflowDef,
+    WorkflowDuration,
+    WorkflowOptions,
+    WorkflowStartResult,
+} from "./workflow-types.js";
+import { registerWorkflowsApi } from "./workflows-api.js";
+
+declare global {
+    // eslint-disable-next-line no-var
+    var __gencow_workflowRegistry: Map<string, WorkflowDef<any, any>>;
+}
+
+const workflowRegistry =
+    globalThis.__gencow_workflowRegistry ??= new Map<string, WorkflowDef<any, any>>();
+
+export const DEFAULT_WORKFLOW_MAX_DURATION_MS = 30 * 60 * 1000;
+export const DEFAULT_WORKFLOW_MAX_RETRIES = 3;
+export const WORKFLOW_RESUME_ACTION_PREFIX = "__gencow.workflow.resume";
+export const WORKFLOW_REALTIME_KEY_PREFIX = "__gencow.workflow.state";
+
+type SerializedWorkflowValue =
+    | { __gencowUndefined: true }
+    | { value: unknown };
+
+function isSerializedWorkflowValue(value: unknown): value is SerializedWorkflowValue {
+    return !!value && typeof value === "object" && (
+        "__gencowUndefined" in value ||
+        "value" in value
+    );
+}
+
+export function serializeWorkflowValue(value: unknown): SerializedWorkflowValue {
+    const payload = value === undefined
+        ? { __gencowUndefined: true as const }
+        : { value };
+
+    try {
+        return JSON.parse(JSON.stringify(payload)) as SerializedWorkflowValue;
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(
+            `workflow() only persists JSON-serializable values. Failed to serialize workflow payload: ${reason}`
+        );
+    }
+}
+
+export function deserializeWorkflowValue(value: unknown): unknown {
+    if (!isSerializedWorkflowValue(value)) return value;
+    if ("__gencowUndefined" in value) return undefined;
+    return value.value;
+}
+
+function clampRetries(retries: number | undefined): number {
+    if (retries == null) return DEFAULT_WORKFLOW_MAX_RETRIES;
+    if (!Number.isFinite(retries) || retries < 0) {
+        throw new Error(`workflow() retries must be a non-negative finite number, got "${retries}"`);
+    }
+    return Math.floor(retries);
+}
+
+function parseDurationString(raw: string, label: string): number {
+    const normalized = raw.trim().toLowerCase();
+    const match = normalized.match(/^(\d+)(ms|s|m|h|d)$/);
+    if (!match) {
+        throw new Error(
+            `${label} must be a number of ms or a string like "30m", "90s", "1h" — got "${raw}"`
+        );
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const unitMs =
+        unit === "ms" ? 1 :
+            unit === "s" ? 1_000 :
+                unit === "m" ? 60_000 :
+                    unit === "h" ? 3_600_000 :
+                        86_400_000;
+    return value * unitMs;
+}
+
+export function parseWorkflowDurationMs(
+    raw: WorkflowDuration,
+    label = "workflow duration"
+): number {
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw) || raw <= 0) {
+            throw new Error(`${label} must be a positive finite number, got "${raw}"`);
+        }
+        return Math.floor(raw);
+    }
+    if (typeof raw !== "string") {
+        throw new Error(
+            `${label} must be a positive finite number or a string like "30m", "90s", "1h" — got "${String(raw)}"`
+        );
+    }
+    return parseDurationString(raw, label);
+}
+
+function normalizeMaxDurationMs(maxDuration: WorkflowDuration | undefined): number {
+    if (maxDuration == null) return DEFAULT_WORKFLOW_MAX_DURATION_MS;
+    return parseWorkflowDurationMs(maxDuration, "workflow() maxDuration");
+}
+
+export function getWorkflowResumeActionName(name: string): string {
+    return `${WORKFLOW_RESUME_ACTION_PREFIX}.${name}`;
+}
+
+export function createWorkflowRealtimeToken(): string {
+    return crypto.randomUUID().replace(/-/g, "");
+}
+
+export function getWorkflowRealtimeKey(workflowId: string, realtimeToken: string): string {
+    return `${WORKFLOW_REALTIME_KEY_PREFIX}.${workflowId}.${realtimeToken}`;
+}
+
+export function getWorkflowDef(name: string): WorkflowDef | undefined {
+    return workflowRegistry.get(name);
+}
+
+export function getRegisteredWorkflows(): WorkflowDef[] {
+    return Array.from(workflowRegistry.values());
+}
+
+/**
+ * workflow() — durable multi-step execution with step memoization.
+ *
+ * The returned value is still a mutation definition, so existing API codegen and
+ * frontend hooks keep working without extra workflow-specific tooling.
+ */
+export function workflow<TSchema = any, TReturn = any>(
+    name: string,
+    options: WorkflowOptions<TSchema, TReturn>
+): MutationDef<TSchema, WorkflowStartResult> {
+    registerWorkflowsApi();
+
+    const maxDurationMs = normalizeMaxDurationMs(options.maxDuration);
+    const maxRetries = clampRetries(options.retries);
+
+    const def: WorkflowDef<TSchema, TReturn> = {
+        name,
+        argsSchema: options.args,
+        isPublic: options.public === true,
+        maxDurationMs,
+        maxRetries,
+        handler: options.handler,
+    };
+
+    workflowRegistry.set(name, def);
+
+    return mutation<TSchema, WorkflowStartResult>(name, {
+        args: options.args,
+        public: options.public,
+        handler: async (ctx, args) => {
+            const workflowId = crypto.randomUUID();
+            const resumeAction = getWorkflowResumeActionName(name);
+            const ownerId = ctx.auth.getUserIdentity()?.id ?? null;
+            const persistedArgs = serializeWorkflowValue(args ?? {});
+            const realtimeToken = createWorkflowRealtimeToken();
+
+            await ctx.unsafeDb.execute(sql`
+                INSERT INTO _gencow_workflows (
+                    id,
+                    name,
+                    args,
+                    realtime_token,
+                    status,
+                    retry_count,
+                    max_retries,
+                    max_duration_ms,
+                    user_id
+                )
+                VALUES (
+                    ${workflowId},
+                    ${name},
+                    ${JSON.stringify(persistedArgs)}::jsonb,
+                    ${realtimeToken},
+                    'pending',
+                    0,
+                    ${maxRetries},
+                    ${maxDurationMs},
+                    ${ownerId}
+                )
+            `);
+
+            try {
+                const scheduledJobId = ctx.scheduler.runAfter(0, resumeAction, { workflowId });
+                return {
+                    id: workflowId,
+                    name,
+                    status: "pending",
+                    scheduledJobId,
+                };
+            } catch (error) {
+                await ctx.unsafeDb.execute(sql`
+                    DELETE FROM _gencow_workflows
+                    WHERE id = ${workflowId}
+                `);
+                throw error;
+            }
+        },
+    });
+}