better-supabase 0.5.1 → 0.6.1

package/dist/workflows-B0j9WKPu.d.ts

@@ -0,0 +1,185 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+import { r as RunState } from "./run-state-CPo-1X2B.js";
+//#region src/blocks/workflows/workflows.d.ts
+/** A workflow run's state, in the words ai-chat and ai-tasks runs share. */
+type WorkflowRunStatus = Exclude<RunState, "cancel_requested">;
+/** A run of any engine, as the `workflows` module records it. */
+interface WorkflowRun {
+  readonly id: string;
+  /** The engine that runs it, e.g. `workflow-sdk`. */
+  readonly engine: string;
+  /** The engine's id for the run. */
+  readonly externalId: string;
+  /** The workflow it runs. */
+  readonly definition: string;
+  readonly tenant: string | undefined;
+  readonly actor: string | undefined;
+  readonly status: WorkflowRunStatus;
+  readonly attributes: Readonly<Record<string, unknown>>;
+  readonly error: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly startedAt: Temporal.Instant | undefined;
+  readonly completedAt: Temporal.Instant | undefined;
+  readonly cancelRequestedAt: Temporal.Instant | undefined;
+}
+interface WorkflowSchedule {
+  readonly id: string;
+  readonly tenant: string | undefined;
+  readonly name: string;
+  readonly workflow: string;
+  readonly input: unknown;
+  readonly cron: string;
+  readonly timezone: string;
+  readonly nextRunAt: Temporal.Instant;
+  readonly lastRunAt: Temporal.Instant | undefined;
+  readonly paused: boolean;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface WorkflowRunsQuery extends CursorPageOptions<Temporal.Instant> {
+  readonly tenant?: string;
+  readonly definition?: string;
+  readonly status?: WorkflowRunStatus;
+  /** At most this many runs, newest first (default 50, at most 500). */
+  readonly limit?: number;
+  /** Runs created before this instant, for the next page. */
+  readonly cursor?: Temporal.Instant;
+}
+/** What an engine reports about a run (service role). */
+interface WorkflowRunRecord {
+  readonly engine: string;
+  readonly externalId: string;
+  readonly definition: string;
+  readonly status: WorkflowRunStatus;
+  readonly tenant?: string;
+  readonly actor?: string;
+  readonly attributes?: Readonly<Record<string, unknown>>;
+  readonly error?: string;
+  readonly startedAt?: Temporal.Instant;
+  readonly completedAt?: Temporal.Instant;
+}
+interface WorkflowScheduleInput {
+  /** Unique per tenant: creating it again replaces it. */
+  readonly name: string;
+  readonly workflow: string;
+  /** Five cron fields, a macro such as `@daily`, or an interval such as `30 seconds`. */
+  readonly cron: string;
+  /** IANA time zone the cron fields are read in (default `UTC`). */
+  readonly timezone?: string;
+  /** The workflow's arguments. */
+  readonly input?: unknown;
+  readonly tenant?: string;
+}
+/** One start the tick asks the engine for. */
+interface WorkflowStartCall {
+  readonly workflow: string;
+  readonly input: unknown;
+  readonly tenant: string | undefined;
+  readonly actor: string | undefined;
+  /** Pass to the engine so a repeated tick doesn't start the run twice. */
+  readonly idempotencyKey: string;
+}
+/** Starts a run and returns the engine's run id. */
+type WorkflowStarter = (call: WorkflowStartCall) => Promise<string>;
+interface WorkflowTickOptions {
+  readonly start: WorkflowStarter;
+  /** Seconds a claimed row stays leased (default 60). */
+  readonly lease?: number;
+  readonly batch?: number;
+}
+interface WorkflowTickResult {
+  readonly started: number;
+  /** The rows whose start threw; they run again once their lease ends. */
+  readonly failed: readonly {
+    readonly id: string;
+    readonly error: string;
+  }[];
+}
+interface WorkflowStartRequest {
+  /** The admission key: runs with the same key share the limits below. */
+  readonly key: string;
+  readonly workflow: string;
+  readonly input?: unknown;
+  readonly tenant?: string;
+  readonly actor?: string;
+  /** At most this many runs with the key at once. */
+  readonly concurrency?: number;
+  /** Waits this many seconds and replaces a request with the key still waiting. */
+  readonly debounce?: number;
+  /** Drops the request while a run with the key is waiting or active. */
+  readonly singleton?: boolean;
+}
+interface WorkflowStartTicket {
+  readonly id: string | undefined;
+  readonly status: "pending" | "dropped";
+}
+interface WorkflowsOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /** The module schema (`sql.modules.workflows.schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface Workflows {
+  readonly runs: {
+    /** The runs the caller may read, newest first. */
+    list(query?: WorkflowRunsQuery): AsyncResult<readonly WorkflowRun[]>;
+    /** A run by its id or its engine's id. */
+    get(run: string): AsyncResult<WorkflowRun | undefined>;
+    /**
+     * Marks a run for cancellation: the actor, `workflow.admin` in its
+     * tenant, or the service role. The engine does the cancelling.
+     */
+    requestCancel(run: string): AsyncResult<WorkflowRun | undefined>;
+    /** Creates or updates a run (service role; engines call it). */
+    record(run: WorkflowRunRecord): AsyncResult<string>;
+    /** Deletes finished runs older than `olderThan` seconds (default 30 days). */
+    purge(options?: {
+      readonly olderThan?: number;
+      readonly batch?: number;
+    }): AsyncResult<number>;
+  };
+  readonly schedules: {
+    /** Creates or replaces a schedule: the service role, or `workflow.admin` in its tenant. */
+    create(input: WorkflowScheduleInput): AsyncResult<WorkflowSchedule>;
+    list(tenant?: string): AsyncResult<readonly WorkflowSchedule[]>;
+    pause(id: string, paused?: boolean): AsyncResult<boolean>;
+    remove(id: string): AsyncResult<boolean>;
+    /**
+     * Starts every due schedule once (service role), with the idempotency
+     * key `schedule:<id>:<fire time>`, then moves it to its next cron time
+     * after now. Call it from a cron route or a job.
+     */
+    tick(options: WorkflowTickOptions): AsyncResult<WorkflowTickResult>;
+  };
+  readonly semaphores: {
+    /** Takes one of `max` slots of `key` for `holder`, for `ttl` seconds (default 300). */
+    acquire(key: string, holder: string, options: {
+      readonly max: number;
+      readonly ttl?: number;
+    }): AsyncResult<boolean>;
+    release(key: string, holder: string): AsyncResult<boolean>;
+  };
+  readonly admission: {
+    /** Queues a start under its key's concurrency, debounce and singleton rules. */
+    request(input: WorkflowStartRequest): AsyncResult<WorkflowStartTicket>;
+    /** Starts the queued requests whose key has room (service role). */
+    tick(options: WorkflowTickOptions): AsyncResult<WorkflowTickResult>;
+  };
+}
+/**
+ * The `workflows` module's runs, schedules, semaphores and start admission,
+ * for any engine. Run with the user's transport to read what RLS allows;
+ * the ticks and `record` need the service role.
+ *
+ * ```ts
+ * const workflows = createWorkflows({ transport: rpcTransport(supabase) });
+ * const runs = await workflows.runs.list({ tenant: orgId }).orThrow();
+ * ```
+ */
+declare function createWorkflows(options: WorkflowsOptions): Workflows;
+//#endregion
+export { WorkflowSchedule as a, WorkflowStartRequest as c, WorkflowTickOptions as d, WorkflowTickResult as f, createWorkflows as h, WorkflowRunsQuery as i, WorkflowStartTicket as l, WorkflowsOptions as m, WorkflowRunRecord as n, WorkflowScheduleInput as o, Workflows as p, WorkflowRunStatus as r, WorkflowStartCall as s, WorkflowRun as t, WorkflowStarter as u };

package/dist/workflows-wu1WWBn7.js

@@ -0,0 +1,216 @@
+import { t as temporal } from "./temporal-required-BVvW7SYJ.js";
+import { a as ok, r as err } from "./result-DzUbqgdW.js";
+import { n as nextCronRun, t as assertCron } from "./cron-DVPUg5k3.js";
+import { O as textOf, S as requiredInstant, c as errorText, d as isRecord, g as pageOf, h as optionalText, i as blockCall, m as optionalInstant, n as applyTemporal, u as instantArg, w as seconds, x as recordsOf, y as recordOf } from "./block-helpers-DWHxHsEQ.js";
+//#region src/blocks/workflows/workflows.ts
+const STATUSES = /* @__PURE__ */ new Set([
+	"queued",
+	"running",
+	"waiting",
+	"completed",
+	"failed",
+	"cancelled"
+]);
+function isStatus(text) {
+	return STATUSES.has(text);
+}
+/** An engine may add statuses: an unknown one reads as `running`, never as finished. */
+function statusOf(value) {
+	const text = textOf(value);
+	return isStatus(text) ? text : "running";
+}
+/** A run from the jsonb the module returns. */
+function workflowRunOf(row) {
+	const attributes = row["attributes"];
+	return {
+		id: textOf(row["id"]),
+		engine: textOf(row["engine"]),
+		externalId: textOf(row["externalId"]),
+		definition: textOf(row["definition"]),
+		tenant: optionalText(row["tenant"]),
+		actor: optionalText(row["actor"]),
+		status: statusOf(row["status"]),
+		attributes: isRecord(attributes) ? attributes : {},
+		error: optionalText(row["error"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		updatedAt: requiredInstant(row["updatedAt"], "updatedAt"),
+		startedAt: optionalInstant(row["startedAt"]),
+		completedAt: optionalInstant(row["completedAt"]),
+		cancelRequestedAt: optionalInstant(row["cancelRequestedAt"])
+	};
+}
+function scheduleOf(row) {
+	return {
+		id: textOf(row["id"]),
+		tenant: optionalText(row["tenant"]),
+		name: textOf(row["name"]),
+		workflow: textOf(row["workflow"]),
+		input: row["input"],
+		cron: textOf(row["cron"]),
+		timezone: textOf(row["timezone"]),
+		nextRunAt: requiredInstant(row["nextRunAt"], "nextRunAt"),
+		lastRunAt: optionalInstant(row["lastRunAt"]),
+		paused: row["paused"] === true,
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt")
+	};
+}
+const optionalRun = (value) => isRecord(value) ? workflowRunOf(value) : void 0;
+/**
+* The `workflows` module's runs, schedules, semaphores and start admission,
+* for any engine. Run with the user's transport to read what RLS allows;
+* the ticks and `record` need the service role.
+*
+* ```ts
+* const workflows = createWorkflows({ transport: rpcTransport(supabase) });
+* const runs = await workflows.runs.list({ tenant: orgId }).orThrow();
+* ```
+*/
+function createWorkflows(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const now = () => temporal().Now.instant();
+	const tick = (claimFn, options, each) => call(claimFn, {
+		lease: options.lease ?? 60,
+		batch: options.batch ?? 50
+	}, (value) => recordsOf(value, claimFn)).andThen(async (rows) => {
+		let started = 0;
+		const failed = [];
+		for (const row of rows) {
+			const id = textOf(row["id"]);
+			const step = each(row);
+			try {
+				const run = await options.start(step.call);
+				const done = await step.done(run);
+				if (!done.ok) return err(done.error);
+				started += 1;
+			} catch (cause) {
+				failed.push({
+					id,
+					error: errorText(cause)
+				});
+			}
+		}
+		return ok({
+			started,
+			failed
+		});
+	});
+	return {
+		runs: {
+			list: (query = {}) => call("workflow_runs_list", {
+				tenant: query.tenant,
+				definition: query.definition,
+				status: query.status,
+				max: query.limit,
+				before: instantArg(pageOf(query).cursor)
+			}, (value) => recordsOf(value, "workflow_runs_list").map(workflowRunOf)),
+			get: (run) => call("workflow_run_get", { run }, optionalRun),
+			requestCancel: (run) => call("request_workflow_cancel", { run }, optionalRun),
+			record: (run) => call("record_workflow_run", {
+				engine: run.engine,
+				external_id: run.externalId,
+				definition: run.definition,
+				status: run.status,
+				tenant: run.tenant,
+				actor: run.actor,
+				attributes: run.attributes,
+				error: run.error,
+				started_at: instantArg(run.startedAt),
+				completed_at: instantArg(run.completedAt)
+			}, textOf),
+			purge: (purge = {}) => call("purge_workflow_runs", {
+				older_than: purge.olderThan === void 0 ? void 0 : seconds(purge.olderThan),
+				batch: purge.batch
+			}, Number)
+		},
+		schedules: {
+			create: (input) => {
+				const timezone = input.timezone ?? "UTC";
+				assertCron(input.cron);
+				return call("create_workflow_schedule", {
+					name: input.name,
+					workflow: input.workflow,
+					cron: input.cron,
+					next_run: nextCronRun(input.cron, timezone, now()).toString(),
+					payload: { input: input.input ?? [] },
+					timezone,
+					tenant: input.tenant
+				}, (value) => scheduleOf(recordOf(value, "create_workflow_schedule")));
+			},
+			list: (tenant) => call("workflow_schedules_list", { tenant }, (value) => recordsOf(value, "workflow_schedules_list").map(scheduleOf)),
+			pause: (id, paused = true) => call("pause_workflow_schedule", {
+				schedule: id,
+				paused
+			}, (value) => value === true),
+			remove: (id) => call("remove_workflow_schedule", { schedule: id }, (value) => value === true),
+			tick: (tickOptions) => tick("claim_due_workflow_schedules", tickOptions, (row) => {
+				const schedule = scheduleOf(row);
+				const fireAt = requiredInstant(row["fireAt"], "fireAt");
+				const after = temporal().Instant.compare(fireAt, now()) > 0 ? fireAt : now();
+				return {
+					call: {
+						workflow: schedule.workflow,
+						input: schedule.input,
+						tenant: schedule.tenant,
+						actor: schedule.createdBy,
+						idempotencyKey: `schedule:${schedule.id}:${fireAt.toString()}`
+					},
+					done: () => call("advance_workflow_schedule", {
+						schedule: schedule.id,
+						fired: fireAt.toString(),
+						next_run: nextCronRun(schedule.cron, schedule.timezone, after).toString()
+					}, (value) => value === true)
+				};
+			})
+		},
+		semaphores: {
+			acquire: (key, holder, semaphore) => call("acquire_workflow_semaphore", {
+				key,
+				holder,
+				max: semaphore.max,
+				ttl: seconds(semaphore.ttl ?? 300)
+			}, (value) => value === true),
+			release: (key, holder) => call("release_workflow_semaphore", {
+				key,
+				holder
+			}, (value) => value === true)
+		},
+		admission: {
+			request: (input) => call("request_workflow_start", {
+				key: input.key,
+				workflow: input.workflow,
+				payload: { input: input.input ?? [] },
+				tenant: input.tenant,
+				actor: input.actor,
+				concurrency: input.concurrency,
+				debounce: input.debounce === void 0 ? void 0 : seconds(input.debounce),
+				singleton: input.singleton
+			}, (value) => {
+				const row = recordOf(value, "request_workflow_start");
+				return {
+					id: optionalText(row["id"]),
+					status: row["status"] === "dropped" ? "dropped" : "pending"
+				};
+			}),
+			tick: (tickOptions) => tick("claim_workflow_start_requests", tickOptions, (row) => {
+				const id = textOf(row["id"]);
+				return {
+					call: {
+						workflow: textOf(row["workflow"]),
+						input: row["input"],
+						tenant: optionalText(row["tenant"]),
+						actor: optionalText(row["actor"]),
+						idempotencyKey: `admission:${id}`
+					},
+					done: (run) => call("mark_workflow_start_request", {
+						request: id,
+						run
+					}, (value) => value === true)
+				};
+			})
+		}
+	};
+}
+//#endregion
+export { createWorkflows as t };