better-supabase 0.8.0 → 0.9.0

package/dist/workflows-C-OvZpeg.js

@@ -0,0 +1,282 @@
+import { t as temporal } from "./temporal-required-DqRzr7i0.js";
+import { a as ok, r as err } from "./result-BlgnMB0H.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { A as requiredInstant, C as optionalText, D as recordOf, I as textOf, M as seconds, S as optionalInstant, f as errorText, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall, w as pageOf } from "./block-helpers-CfG_MvDR.js";
+import { n as nextCronRun, t as assertCron } from "./cron-CUaKTjWC.js";
+import { r as withBlockHooks } from "./block-hooks-BsXncUlZ.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";
+}
+const PRINCIPAL_KINDS = /* @__PURE__ */ new Set([
+	"user",
+	"service_principal",
+	"system",
+	"external"
+]);
+function isPrincipalKind(text) {
+	return PRINCIPAL_KINDS.has(text);
+}
+/** The subject in `subjectType` and `subjectId`, when both are set. */
+function workflowSubjectOf(row) {
+	const type = optionalText(row["subjectType"]);
+	const id = optionalText(row["subjectId"]);
+	return type === void 0 || id === void 0 ? void 0 : {
+		type,
+		id
+	};
+}
+function principalOf(row) {
+	const kind = textOf(row["principalKind"]);
+	return isPrincipalKind(kind) ? {
+		kind,
+		id: optionalText(row["principalId"])
+	} : void 0;
+}
+/** 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"]),
+		subject: workflowSubjectOf(row),
+		principal: principalOf(row),
+		mode: row["mode"] === "test" ? "test" : "live",
+		triggerNode: optionalText(row["triggerNode"])
+	};
+}
+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 subjectField = (subject) => subject === void 0 ? {} : { subject };
+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
+		});
+	});
+	const client = {
+		runs: {
+			list: (query = {}) => call("workflow_runs_list", {
+				tenant: query.tenant,
+				definition: query.definition,
+				status: query.status,
+				max: query.limit,
+				before: instantArg(pageOf(query).cursor),
+				subject_type: query.subject?.type,
+				subject_id: query.subject?.id,
+				mode: query.mode === "all" ? null : query.mode ?? "live"
+			}, (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),
+				subject_type: run.subject?.type,
+				subject_id: run.subject?.id,
+				principal_kind: run.principal?.kind,
+				principal_id: run.principal?.id,
+				mode: run.mode,
+				trigger_node: run.triggerNode
+			}, 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: {
+						source: "schedule",
+						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,
+				subject_type: input.subject?.type,
+				subject_id: input.subject?.id
+			}, (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: {
+						source: "admission",
+						workflow: textOf(row["workflow"]),
+						input: row["input"],
+						tenant: optionalText(row["tenant"]),
+						actor: optionalText(row["actor"]),
+						...subjectField(workflowSubjectOf(row)),
+						idempotencyKey: `admission:${id}`
+					},
+					done: (run) => call("mark_workflow_start_request", {
+						request: id,
+						run
+					}, (value) => value === true)
+				};
+			})
+		}
+	};
+	const hooks = options.hooks ?? {};
+	const logger = options.logger ? { logger: options.logger } : {};
+	return {
+		runs: withBlockHooks(client.runs, hooks.runs, {
+			block: "workflows.runs",
+			...logger
+		}),
+		schedules: withBlockHooks(client.schedules, hooks.schedules, {
+			block: "workflows.schedules",
+			...logger
+		}),
+		semaphores: withBlockHooks(client.semaphores, hooks.semaphores, {
+			block: "workflows.semaphores",
+			...logger
+		}),
+		admission: withBlockHooks(client.admission, hooks.admission, {
+			block: "workflows.admission",
+			...logger
+		})
+	};
+}
+//#endregion
+export { createWorkflows as t };

package/dist/workflows-DFQeXDAI.d.ts

@@ -0,0 +1,243 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.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">;
+/** The record a run belongs to: a subject type from `config.subjects` and its id. */
+interface WorkflowSubject {
+  readonly type: string;
+  readonly id: string;
+}
+/** Who a run's steps act as. */
+type WorkflowPrincipalKind = "user" | "service_principal" | "system" | "external";
+interface WorkflowPrincipal {
+  readonly kind: WorkflowPrincipalKind;
+  /** The user's or service principal's id; absent for `system`. */
+  readonly id: string | undefined;
+}
+/** `test` runs come from the builder's test button: no outbox events, no alerts. */
+type WorkflowRunMode = "live" | "test";
+/** 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;
+  /** The record it was started on. */
+  readonly subject: WorkflowSubject | undefined;
+  /** Who its steps act as, when the engine reported it. */
+  readonly principal: WorkflowPrincipal | undefined;
+  readonly mode: WorkflowRunMode;
+  /** The trigger node it started from, in a graph with several. */
+  readonly triggerNode: string | 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;
+  /** One record's runs. */
+  readonly subject?: WorkflowSubject;
+  /** `live` (the default), `test`, or `all`. */
+  readonly mode?: WorkflowRunMode | "all";
+  /** 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;
+  /** Kept from the first report that names one. */
+  readonly subject?: WorkflowSubject;
+  /** Kept from the first report that names one. */
+  readonly principal?: WorkflowPrincipal;
+  /** Set by the first report (default `live`). */
+  readonly mode?: WorkflowRunMode;
+  readonly triggerNode?: string;
+}
+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 {
+  /** A due schedule or a queued admission request. */
+  readonly source: "schedule" | "admission";
+  readonly workflow: string;
+  readonly input: unknown;
+  readonly tenant: string | undefined;
+  /**
+   * The schedule's creator or the request's actor. For a schedule it is the
+   * trigger, recorded for audit; the run needs a `runAs` publisher.
+   */
+  readonly actor: string | undefined;
+  /** The record a queued request named. */
+  readonly subject?: WorkflowSubject;
+  /** 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;
+  /** The record the run belongs to. */
+  readonly subject?: WorkflowSubject;
+  /** 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, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * `withBlockHooks` hooks around the methods of each group, such as a rule
+   * on who may create a schedule: `{ schedules: { create: { before } } }`.
+   */
+  readonly hooks?: WorkflowsHooks;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** Hooks for the methods of each group of `Workflows`. */
+interface WorkflowsHooks {
+  readonly runs?: BlockHooks<Workflows["runs"]>;
+  readonly schedules?: BlockHooks<Workflows["schedules"]>;
+  readonly semaphores?: BlockHooks<Workflows["semaphores"]>;
+  readonly admission?: BlockHooks<Workflows["admission"]>;
+}
+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 { WorkflowsHooks as _, WorkflowRunStatus as a, WorkflowScheduleInput as c, WorkflowStartTicket as d, WorkflowStarter as f, Workflows as g, WorkflowTickResult as h, WorkflowRunRecord as i, WorkflowStartCall as l, WorkflowTickOptions as m, WorkflowRun as n, WorkflowRunsQuery as o, WorkflowSubject as p, WorkflowRunMode as r, WorkflowSchedule as s, WorkflowPrincipalKind as t, WorkflowStartRequest as u, WorkflowsOptions as v, createWorkflows as y };

package/dist/yjs/index.d.ts

@@ -0,0 +1,67 @@
+import { t as AsyncResult } from "../result-Cj3yWhjH.js";
+import { c as RealtimeClient, r as PresenceMember } from "../topic-cMS7UtM1.js";
+import { c as OpenedDocument, n as DocumentRef, o as Documents } from "../documents-CWn2mtYf.js";
+//#region src/yjs/yjs.d.ts
+type PresenceState = Readonly<Record<string, unknown>>;
+/** The part of a `Y.Doc` the provider uses. */
+interface YDocLike {
+  on(event: "update", handler: (update: Uint8Array, origin: unknown) => void): void;
+  off(event: "update", handler: (update: Uint8Array, origin: unknown) => void): void;
+}
+/** The functions the provider calls from the `yjs` package. */
+interface YjsLike {
+  applyUpdate(doc: never, update: Uint8Array, origin?: unknown): void;
+  mergeUpdates(updates: readonly Uint8Array[]): Uint8Array;
+}
+interface DocumentProviderOptions<P extends PresenceState> {
+  /** The `better-supabase/blocks/documents` client. */
+  readonly documents: Documents;
+  /** A Supabase client signed in as the editor, for the private topic. */
+  readonly client: RealtimeClient;
+  readonly doc: YDocLike;
+  readonly ref: DocumentRef;
+  /** The `yjs` module. Default: imported on first connect. */
+  readonly yjs?: YjsLike;
+  /** Called with everyone on the document after each presence sync. */
+  readonly onPresence?: (members: readonly PresenceMember<P>[]) => void;
+  readonly onStatus?: (status: DocumentProviderStatus) => void;
+  /** Called when a push, pull or broadcast fails; the provider retries on reconnect. */
+  readonly onError?: (error: unknown) => void;
+}
+type DocumentProviderStatus = "connecting" | "synced" | "offline" | "closed";
+interface DocumentProvider<P extends PresenceState> extends AsyncDisposable {
+  /** The opened document, once `connect` resolves. */
+  readonly document: OpenedDocument | undefined;
+  readonly status: DocumentProviderStatus;
+  /** Loads the stored state, joins the topic and starts sending edits. */
+  connect(): AsyncResult<OpenedDocument>;
+  /** Shares a presence state (a cursor, a name) with the other editors. */
+  track(state: P): AsyncResult<void>;
+  /** Everyone from the last presence sync. */
+  members(): readonly PresenceMember<P>[];
+  /** Waits for local edits that are still being stored. */
+  flush(): Promise<void>;
+  /** Stops listening to the document and leaves the topic. */
+  destroy(): Promise<void>;
+}
+/**
+ * Syncs a `Y.Doc` with the documents module: it loads the snapshot and
+ * updates, stores each local edit, broadcasts it on the document's private
+ * topic, and pulls what it missed when the channel reconnects.
+ */
+export declare function createDocumentProvider<P extends PresenceState = PresenceState>(options: DocumentProviderOptions<P>): DocumentProvider<P>;
+interface CompactDocumentOptions {
+  readonly documents: Documents;
+  readonly documentId: string;
+  /** The `yjs` module. Default: imported on first use. */
+  readonly yjs?: YjsLike;
+}
+/**
+ * Merges a document's snapshot and updates into one state and stores it,
+ * for the `documents.compact` job or a sweep over `documents.toCompact()`.
+ * Needs the service role or `documents.manage`. Resolves false when there
+ * was nothing to compact or a newer snapshot won.
+ */
+export declare function compactDocument(options: CompactDocumentOptions): AsyncResult<boolean>;
+//#endregion
+export type { CompactDocumentOptions, DocumentProvider, DocumentProviderOptions, DocumentProviderStatus, YDocLike, YjsLike };