@gencow/core 0.1.23 → 0.1.25

package/src/v.ts

@@ -11,106 +11,111 @@
  * without fragile string-matching on the error message.
  */
 export class GencowValidationError extends Error {
-    readonly statusCode = 400;
-    constructor(message: string) {
-        super(message);
-        this.name = "GencowValidationError";
-    }
+  readonly statusCode = 400;
+  constructor(message: string) {
+    super(message);
+    this.name = "GencowValidationError";
+  }
 }
 
 export type Validator<T = any> = {
-    parse(val: any): T;
-    _type: T; // Ghost property for TypeScript inference
+  parse(val: any): T;
+  _type: T; // Ghost property for TypeScript inference
 };
 
 export type Infer<T> = T extends Validator<infer U> ? U : never;
 
 export const v = {
-    string(): Validator<string> {
-        return {
-            parse: (val) => {
-                if (typeof val !== "string") throw new Error(`Expected string, got ${typeof val}`);
-                return val;
-            },
-            _type: "" as string,
-        };
-    },
-    number(): Validator<number> {
-        return {
-            parse: (val) => {
-                // Accept numeric strings (e.g. from URL params / form data)
-                const n = typeof val === "string" ? Number(val) : val;
-                if (typeof n !== "number" || isNaN(n)) throw new Error(`Expected number, got ${typeof val}`);
-                return n;
-            },
-            _type: 0 as number,
-        };
-    },
-    boolean(): Validator<boolean> {
-        return {
-            parse: (val) => {
-                if (typeof val !== "boolean") throw new Error(`Expected boolean, got ${typeof val}`);
-                return val;
-            },
-            _type: false as boolean,
-        };
-    },
-    any(): Validator<any> {
-        return {
-            parse: (val) => val,
-            _type: null as any,
-        };
-    },
-    optional<T>(inner: Validator<T>): Validator<T | undefined> {
-        return {
-            parse: (val) => {
-                if (val === undefined || val === null) return undefined;
-                return inner.parse(val);
-            },
-            _type: undefined as T | undefined,
-        };
-    },
-    object<T extends Record<string, Validator>>(fields: T): Validator<{ [K in keyof T]: Infer<T[K]> }> {
-        return {
-            parse: (val) => {
-                if (typeof val !== "object" || val === null) throw new Error("Expected object");
-                const result: any = {};
-                for (const key in fields) {
-                    result[key] = fields[key].parse((val as any)[key]);
-                }
-                return result;
-            },
-            _type: {} as any,
-        };
-    },
-    array<T>(inner: Validator<T>): Validator<T[]> {
-        return {
-            parse: (val) => {
-                if (!Array.isArray(val)) throw new Error("Expected array");
-                return val.map((item) => inner.parse(item));
-            },
-            _type: [] as T[],
-        };
-    },
+  string(): Validator<string> {
+    return {
+      parse: (val) => {
+        if (typeof val !== "string") throw new Error(`Expected string, got ${typeof val}`);
+        return val;
+      },
+      _type: "" as string,
+    };
+  },
+  number(): Validator<number> {
+    return {
+      parse: (val) => {
+        // Accept numeric strings (e.g. from URL params / form data)
+        const n = typeof val === "string" ? Number(val) : val;
+        if (typeof n !== "number" || isNaN(n)) throw new Error(`Expected number, got ${typeof val}`);
+        return n;
+      },
+      _type: 0 as number,
+    };
+  },
+  boolean(): Validator<boolean> {
+    return {
+      parse: (val) => {
+        if (typeof val !== "boolean") throw new Error(`Expected boolean, got ${typeof val}`);
+        return val;
+      },
+      _type: false as boolean,
+    };
+  },
+  any(): Validator<any> {
+    return {
+      parse: (val) => val,
+      _type: null as any,
+    };
+  },
+  optional<T>(inner: Validator<T>): Validator<T | undefined> {
+    return {
+      parse: (val) => {
+        if (val === undefined || val === null) return undefined;
+        return inner.parse(val);
+      },
+      _type: undefined as T | undefined,
+    };
+  },
+  object<T extends Record<string, Validator>>(fields: T): Validator<{ [K in keyof T]: Infer<T[K]> }> {
+    return {
+      parse: (val) => {
+        if (typeof val !== "object" || val === null) throw new Error("Expected object");
+        const result: any = {};
+        for (const key in fields) {
+          result[key] = fields[key].parse((val as any)[key]);
+        }
+        return result;
+      },
+      _type: {} as any,
+    };
+  },
+  array<T>(inner: Validator<T>): Validator<T[]> {
+    return {
+      parse: (val) => {
+        if (!Array.isArray(val)) throw new Error("Expected array");
+        return val.map((item) => inner.parse(item));
+      },
+      _type: [] as T[],
+    };
+  },
 };
 
 /**
  * Infer TypeScript type from a validator schema or a shorthand record of validators.
  * Correctly handles optional properties (Validator<T | undefined> → optional key).
  */
-export type InferArgs<T> = T extends Validator<infer U>
+export type InferArgs<T> =
+  T extends Validator<infer U>
     ? U
     : T extends Record<string, Validator>
-    ? {
-        [K in keyof T as T[K] extends Validator<infer U>
-        ? (undefined extends U ? never : K)
-        : K]: T[K] extends Validator<infer U> ? U : any;
-    } & {
-        [K in keyof T as T[K] extends Validator<infer U>
-        ? (undefined extends U ? K : never)
-        : never]?: T[K] extends Validator<infer U> ? U : any;
-    }
-    : T;
+      ? {
+          [K in keyof T as T[K] extends Validator<infer U>
+            ? undefined extends U
+              ? never
+              : K
+            : K]: T[K] extends Validator<infer U> ? U : any;
+        } & {
+          [K in keyof T as T[K] extends Validator<infer U>
+            ? undefined extends U
+              ? K
+              : never
+            : never]?: T[K] extends Validator<infer U> ? U : any;
+        }
+      : T;
 
 /**
  * Validates and parses arguments against a schema at runtime.
@@ -122,41 +127,41 @@ export type InferArgs<T> = T extends Validator<infer U>
  * Throws `GencowValidationError` (HTTP 400) on validation failure.
  */
 export function parseArgs(schema: any, args: any): any {
-    if (!schema) return args;
+  if (!schema) return args;
 
-    // Direct Validator (has a .parse method)
-    if (typeof schema.parse === "function") {
-        try {
-            return schema.parse(args);
-        } catch (e: any) {
-            throw new GencowValidationError(e.message);
-        }
+  // Direct Validator (has a .parse method)
+  if (typeof schema.parse === "function") {
+    try {
+      return schema.parse(args);
+    } catch (e: any) {
+      throw new GencowValidationError(e.message);
     }
+  }
 
-    // Shorthand object — e.g. { id: v.number(), title: v.optional(v.string()) }
-    if (typeof schema === "object" && schema !== null) {
-        // Empty schema {} → passthrough all args (e.g. FormData with file field)
-        const schemaKeys = Object.keys(schema);
-        if (schemaKeys.length === 0) return args;
+  // Shorthand object — e.g. { id: v.number(), title: v.optional(v.string()) }
+  if (typeof schema === "object" && schema !== null) {
+    // Empty schema {} → passthrough all args (e.g. FormData with file field)
+    const schemaKeys = Object.keys(schema);
+    if (schemaKeys.length === 0) return args;
 
-        if (typeof args !== "object" || args === null) {
-            throw new GencowValidationError("Expected an object for arguments");
-        }
-        const result: any = {};
-        for (const key of schemaKeys) {
-            const validator = schema[key];
-            if (validator && typeof validator.parse === "function") {
-                try {
-                    result[key] = validator.parse(args[key]);
-                } catch (e: any) {
-                    throw new GencowValidationError(`Argument "${key}": ${e.message}`);
-                }
-            } else {
-                result[key] = args[key];
-            }
+    if (typeof args !== "object" || args === null) {
+      throw new GencowValidationError("Expected an object for arguments");
+    }
+    const result: any = {};
+    for (const key of schemaKeys) {
+      const validator = schema[key];
+      if (validator && typeof validator.parse === "function") {
+        try {
+          result[key] = validator.parse(args[key]);
+        } catch (e: any) {
+          throw new GencowValidationError(`Argument "${key}": ${e.message}`);
         }
-        return result;
+      } else {
+        result[key] = args[key];
+      }
     }
+    return result;
+  }
 
-    return args;
+  return args;
 }

package/src/workflow-types.ts

@@ -0,0 +1,108 @@
+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,188 @@
+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;
+      }
+    },
+  });
+}