@lunora/bindings 0.0.0 → 1.0.0-alpha.10

package/dist/kv/index.d.ts

@@ -0,0 +1,271 @@
+/**
+ * The value types Workers KV can store / return. Mirrors Cloudflare's
+ * `KVNamespace` `get`/`put` body unions; declared here so the package stays
+ * runtime-agnostic and the `*Like` interfaces don't pull in
+ * `@cloudflare/workers-types` at runtime.
+ */
+type KvValue = ReadableStream | ArrayBuffer | ArrayBufferView | string;
+/** How a raw KV read should decode the stored value. Mirrors KV's `type` option. */
+type KvValueType = "text" | "json" | "arrayBuffer" | "stream";
+/**
+ * Per-read options forwarded to the binding. `cacheTtl` is KV's edge-cache TTL
+ * (seconds, min 60); `type` selects the decode mode for {@link Kv.getRaw}.
+ */
+interface KvGetOptions {
+  /** KV edge-cache TTL in seconds (minimum 60). Forwarded verbatim. */
+  cacheTtl?: number;
+  /** Decode mode for a raw read. {@link Kv.get} always uses `"json"`. */
+  type?: KvValueType;
+}
+/**
+ * Minimal projection of Cloudflare's `KVNamespace`. Declared structurally so
+ * unit tests can pass a plain `Map`-backed double; the real binding satisfies
+ * the same shape. Mirrors `R2BucketLike` in `@lunora/storage`.
+ */
+interface KVNamespaceLike {
+  /** Delete a key. No-op if the key is absent. */
+  delete: (key: string) => Promise<void>;
+  /**
+   * Read a value. The real binding overloads on `options.type`; declared here
+   * as the broad union so a structural double need only return the value (or
+   * `null` when absent).
+   */
+  get: (key: string, options?: KvGetOptions | KvValueType) => Promise<unknown>;
+  /**
+   * Read a value together with its associated metadata. Returns
+   * `{ value: null, metadata: null }` when the key is absent.
+   */
+  getWithMetadata: (key: string, options?: KvGetOptions | KvValueType) => Promise<{
+    metadata: unknown;
+    value: unknown;
+  }>;
+  /** List keys, optionally filtered by `prefix` and paginated via `cursor`. */
+  list: (options?: {
+    cursor?: string;
+    limit?: number;
+    prefix?: string;
+  }) => Promise<KvNamespaceListResult>;
+  /** Write a value, optionally with TTL/expiration and metadata. */
+  put: (key: string, value: KvValue, options?: KvNamespacePutOptions) => Promise<void>;
+}
+/** The raw put options the KV binding accepts (mirrors `KVNamespacePutOptions`). */
+interface KvNamespacePutOptions {
+  /** Absolute expiration as a Unix timestamp (seconds). Mutually exclusive with `expirationTtl`. */
+  expiration?: number;
+  /** Relative expiration in seconds from now (minimum 60). Mutually exclusive with `expiration`. */
+  expirationTtl?: number;
+  /** Arbitrary JSON metadata stored alongside the value, returned by `getWithMetadata`/`list`. */
+  metadata?: unknown;
+}
+/** One key entry as returned by the KV binding's `list`. */
+interface KvListKey<Metadata = unknown> {
+  /** Absolute expiration (Unix seconds), when the key has one. */
+  expiration?: number;
+  /** The key's metadata, when set at write time. */
+  metadata?: Metadata;
+  /** The key name. */
+  name: string;
+}
+/** The raw `list` result shape returned by the KV binding. */
+type KvNamespaceListResult<Metadata = unknown> = {
+  cacheStatus?: string | null;
+  cursor: string;
+  keys: KvListKey<Metadata>[];
+  list_complete: false;
+} | {
+  cacheStatus?: string | null;
+  keys: KvListKey<Metadata>[];
+  list_complete: true;
+};
+/** Construction options for the `createKv` factory. */
+interface LunoraKvOptions {
+  /**
+   * Optional per-instance key prefix applied to every operation (get/put/
+   * delete/list). Use for multi-tenant key namespacing — equivalent to
+   * calling the `scopeKey` helper on every key. Combined via `scopeKey`, so a
+   * `..` or NUL in the prefix is rejected.
+   */
+  keyPrefix?: string;
+  /** The bound KV namespace (`env.&lt;BINDING>`). */
+  namespace: KVNamespaceLike;
+}
+/** Options for {@link Kv.put}. JSON-stringifies the value unless `raw` is set. */
+interface KvPutOptions {
+  /** Absolute expiration as a Unix timestamp (seconds). Mutually exclusive with `expirationTtl`. */
+  expiration?: number;
+  /** Relative expiration in seconds from now (minimum 60). Mutually exclusive with `expiration`. */
+  expirationTtl?: number;
+  /** Arbitrary metadata stored alongside the value (returned by `getWithMetadata`/`list`). */
+  metadata?: unknown;
+  /**
+   * When true, write `value` to KV verbatim (no `JSON.stringify`). `value`
+   * must already be a KV-writable type (string/ArrayBuffer/stream).
+   */
+  raw?: boolean;
+}
+/** Options for {@link Kv.list}. */
+interface KvListOptions {
+  /** Opaque cursor from a previous truncated page. */
+  cursor?: string;
+  /** Max keys per page (KV caps at 1000). */
+  limit?: number;
+  /** Restrict to keys starting with this prefix (combined with any `keyPrefix`). */
+  prefix?: string;
+}
+/** A single page of {@link Kv.list} results. */
+interface KvListResult<Metadata = unknown> {
+  /** Cursor for the next page; `undefined` when the listing is complete. */
+  cursor?: string;
+  /**
+   * The key names, with any instance `keyPrefix` stripped back off so callers
+   * see the same keys they wrote.
+   */
+  keys: KvListKey<Metadata>[];
+  /** True when this is the final page (no further `cursor`). */
+  listComplete: boolean;
+}
+/** A value together with its stored metadata (from {@link Kv.getWithMetadata}). */
+interface KvValueWithMetadata<Value, Metadata> {
+  /** The stored metadata, or `null` when none was set / the key is absent. */
+  metadata: Metadata | null;
+  /** The decoded value, or `null` when the key is absent. */
+  value: Value | null;
+}
+/**
+ * The typed Workers KV client bound to `ctx.kv`. JSON-decodes/encodes by
+ * default; a raw escape hatch ({@link Kv.getRaw} / `put(..., { raw: true })`)
+ * handles text/binary/stream values.
+ */
+interface Kv {
+  /** Delete a key. No-op if absent. */
+  delete: (key: string) => Promise<void>;
+  /**
+   * Read a key and `JSON.parse` it into `T`. Returns `null` when the key is
+   * absent. Throws if the stored value isn't valid JSON — use
+   * {@link Kv.getRaw} for non-JSON values.
+   */
+  get: <T = unknown>(key: string, options?: {
+    cacheTtl?: number;
+  }) => Promise<T | null>;
+  /** Read a raw value with an explicit decode `type` (default `"text"`). Returns `null` when absent. */
+  getRaw: <T = string>(key: string, options?: KvGetOptions) => Promise<T | null>;
+  /**
+   * Read a key's JSON value together with its metadata. Returns
+   * `{ value: null, metadata: null }` when the key is absent.
+   */
+  getWithMetadata: <T = unknown, M = unknown>(key: string, options?: {
+    cacheTtl?: number;
+  }) => Promise<KvValueWithMetadata<T, M>>;
+  /** List keys (optionally `prefix`-filtered, paginated via `cursor`). */
+  list: <M = unknown>(options?: KvListOptions) => Promise<KvListResult<M>>;
+  /**
+   * Write `value` to `key`. JSON-stringifies `value` unless `options.raw` is
+   * set (in which case `value` must be a KV-writable type). Forwards
+   * `expirationTtl`/`expiration`/`metadata` to the binding.
+   */
+  put: <T = unknown>(key: string, value: T, options?: KvPutOptions) => Promise<void>;
+}
+/**
+ * Compose a per-tenant key from a scope prefix and a caller-supplied key. Both
+ * halves are validated — the prefix may not contain `..` or NUL either, and the
+ * resulting key must stay under KV's length ceiling. Recommended for any
+ * multi-tenant deployment so client-supplied keys can't address peer data.
+ * Mirrors `scopeKey` from `@lunora/storage`.
+ */
+declare const scopeKey: (prefix: string, key: string) => string;
+declare const createKv: (options: LunoraKvOptions) => Kv;
+/** One KV namespace as the studio's KV browser surfaces it (mirrors the runtime's KvNamespaceSummary). */
+interface KvNamespaceSummaryLike {
+  binding: string;
+}
+/** One key entry as surfaced by the KV admin browser (mirrors the runtime's KvKeyEntry). */
+interface KvKeyEntryLike {
+  expiration?: number;
+  metadata?: unknown;
+  name: string;
+}
+/** A paginated page of KV keys (mirrors the runtime's KvKeyListResult). */
+interface KvKeyListResultLike {
+  cursor?: string;
+  keys: KvKeyEntryLike[];
+  listComplete: boolean;
+}
+/** A value together with its metadata (mirrors the runtime's KvValueResult). */
+interface KvValueResultLike {
+  metadata: unknown;
+  value: null | string;
+}
+/**
+ * The structural shape of a KV introspector — mirrors `KvIntrospector` from
+ * `@lunora/runtime` without importing it, keeping the dependency graph clean.
+ */
+interface KvIntrospectorLike {
+  deleteKey: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<void>;
+  getValue: (options: {
+    key: string;
+    namespace: string;
+  }) => Promise<KvValueResultLike>;
+  listKeys: (options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }) => Promise<KvKeyListResultLike>;
+  listNamespaces: () => Promise<KvNamespaceSummaryLike[]>;
+  putValue: (options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }) => Promise<void>;
+}
+/** Construction options for {@link createKvIntrospector}. */
+interface CreateKvIntrospectorOptions {
+  /**
+   * Map of binding name → bound KV namespace. Each entry becomes one
+   * namespace the studio can browse. Example:
+   * ```ts
+   * createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } })
+   * ```
+   */
+  namespaces: Record<string, KVNamespaceLike>;
+}
+/**
+ * Build a `KvIntrospector`-compatible object from a map of bound KV namespaces.
+ * Pass the result as `kvIntrospector` on `WorkerOptions` to enable the studio's
+ * KV browser (`/_lunora/admin/kv/*` endpoints).
+ * @example
+ * ```ts
+ * createWorker({
+ *   // …
+ *   kvIntrospector: createKvIntrospector({ namespaces: { MY_KV: env.MY_KV } }),
+ * });
+ * ```
+ */
+declare const createKvIntrospector: (options: CreateKvIntrospectorOptions) => KvIntrospectorLike;
+/**
+ * Zero-config KV introspector: scan a worker `env` for every bound Workers KV
+ * namespace and register each under its binding name. Every `kv_namespaces` entry
+ * in `wrangler.jsonc` then appears in the studio's KV browser automatically — no
+ * hand-written `createKvIntrospector({ namespaces: … })` call, and any binding
+ * name (not just `KV`) and any number of namespaces light up. Non-KV bindings
+ * (R2, Durable Objects, queues, secrets, …) are skipped via {@link isKvNamespace}.
+ *
+ * Returns an introspector even when `env` holds no KV namespaces — its
+ * `listNamespaces()` resolves to `[]`, so the studio renders an empty state
+ * rather than a "not configured" error.
+ * @example
+ * ```ts
+ * createWorker({
+ *   // …
+ *   kvIntrospector: createKvIntrospectorFromEnv(env),
+ * });
+ * ```
+ */
+declare const createKvIntrospectorFromEnv: (env: unknown) => KvIntrospectorLike;
+export { type CreateKvIntrospectorOptions, type KVNamespaceLike, type Kv, type KvGetOptions, type KvIntrospectorLike, type KvListKey, type KvListOptions, type KvListResult, type KvNamespaceListResult, type KvNamespacePutOptions, type KvPutOptions, type KvValue, type KvValueType, type KvValueWithMetadata, type LunoraKvOptions, createKv, createKvIntrospector, createKvIntrospectorFromEnv, scopeKey };

package/dist/kv/index.mjs

@@ -0,0 +1,2 @@
+export { createKv, scopeKey } from '../packem_shared/createKv-C8Iyu5hD.mjs';
+export { createKvIntrospector, createKvIntrospectorFromEnv } from '../packem_shared/createKvIntrospector-Byk4GfsY.mjs';

package/dist/packem_shared/AnalyticsSqlError-C2nz3jpH.mjs

@@ -0,0 +1,41 @@
+import { LunoraError } from '@lunora/errors';
+
+const SQL_API_BASE = "https://api.cloudflare.com/client/v4/accounts";
+class AnalyticsSqlError extends LunoraError {
+  constructor(status, body) {
+    super("ANALYTICS_SQL_ERROR", `Analytics Engine SQL API returned ${String(status)}: ${body}`, { name: "AnalyticsSqlError", status });
+  }
+}
+const createAnalyticsSqlClient = (config) => {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const endpoint = `${SQL_API_BASE}/${encodeURIComponent(config.accountId)}/analytics_engine/sql`;
+  const query = async (sql) => {
+    const response = await fetchImpl(endpoint, {
+      body: sql,
+      headers: {
+        Authorization: `Bearer ${config.apiToken}`,
+        "Content-Type": "text/plain"
+      },
+      method: "POST"
+    });
+    if (!response.ok) {
+      throw new AnalyticsSqlError(response.status, await response.text());
+    }
+    let raw;
+    try {
+      raw = await response.json();
+    } catch {
+      throw new AnalyticsSqlError(response.status, "Analytics Engine SQL API returned a non-JSON body.");
+    }
+    const body = raw;
+    const rows = body.data ?? [];
+    return {
+      columns: body.meta ?? [],
+      rowCount: body.rows ?? rows.length,
+      rows
+    };
+  };
+  return { query };
+};
+
+export { AnalyticsSqlError, createAnalyticsSqlClient };

package/dist/packem_shared/R2SqlError-drPKSCZ3.mjs

@@ -0,0 +1,65 @@
+import { LunoraError } from '@lunora/errors';
+import SelectBuilder from './SelectBuilder-BOqJQHEv.mjs';
+import { ident, toText } from './Sql-B3zq2YGx.mjs';
+
+const API_BASE = "https://api.sql.cloudflarestorage.com/api/v1/accounts";
+const inferColumns = (rows) => {
+  if (rows[0] === void 0) {
+    return [];
+  }
+  return Object.keys(rows[0]).map((name) => {
+    return { name };
+  });
+};
+class R2SqlError extends LunoraError {
+  constructor(status, body) {
+    super("R2_SQL_ERROR", `R2 SQL query failed (${String(status)}): ${body}`, { name: "R2SqlError", status });
+  }
+}
+const createR2Sql = (config) => {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const base = config.endpoint ?? API_BASE;
+  const endpoint = `${base}/${encodeURIComponent(config.accountId)}/r2-sql/query/${encodeURIComponent(config.bucket)}`;
+  const warehouse = `${config.accountId}_${config.bucket}`;
+  const exec = async (statement) => {
+    const response = await fetchImpl(endpoint, {
+      body: JSON.stringify({ query: statement, warehouse }),
+      headers: {
+        Authorization: `Bearer ${config.apiToken}`,
+        "Content-Type": "application/json"
+      },
+      method: "POST"
+    });
+    if (!response.ok) {
+      throw new R2SqlError(response.status, await response.text());
+    }
+    let raw;
+    try {
+      raw = await response.json();
+    } catch {
+      throw new R2SqlError(response.status, "R2 SQL returned a non-JSON body.");
+    }
+    const body = raw;
+    if (body.success === false || body.errors !== void 0 && body.errors.length > 0) {
+      throw new R2SqlError(response.status, JSON.stringify(body.errors ?? body));
+    }
+    const rows = body.result?.rows ?? [];
+    return {
+      columns: body.result?.schema ?? inferColumns(rows),
+      rowCount: rows.length,
+      rows
+    };
+  };
+  return {
+    describe: async (table) => exec(`DESCRIBE ${ident(table)}`),
+    explain: async (statement, options) => exec(`EXPLAIN ${options?.format === "json" ? "FORMAT JSON " : ""}${toText(statement)}`),
+    // `SelectBuilder`'s constructor validates the table reference (allowing an
+    // optional `[AS] alias`), so no pre-validation here.
+    from: (table) => new SelectBuilder(exec, table),
+    query: async (statement) => exec(toText(statement)),
+    showDatabases: async () => exec("SHOW DATABASES"),
+    showTables: async (namespace) => exec(`SHOW TABLES IN ${ident(namespace)}`)
+  };
+};
+
+export { R2SqlError, createR2Sql };

package/dist/packem_shared/SelectBuilder-BOqJQHEv.mjs

@@ -0,0 +1,168 @@
+import { renderOrderTerm } from './asc-DZbQCxh1.mjs';
+import SetOperation from './SetOperation-DmPgUL8W.mjs';
+import { tableRef, toText, assertLimit, lit } from './Sql-B3zq2YGx.mjs';
+
+const JOIN_KEYWORDS = {
+  cross: "CROSS JOIN",
+  full: "FULL OUTER JOIN",
+  inner: "INNER JOIN",
+  left: "LEFT JOIN",
+  right: "RIGHT JOIN"
+};
+class SelectBuilder {
+  exec;
+  table;
+  selectItems = [];
+  distinctFlag = false;
+  distinctOnItems = [];
+  joins = [];
+  whereConditions = [];
+  groupByItems = [];
+  havingConditions = [];
+  qualifyCondition;
+  orderByItems = [];
+  limitValue;
+  constructor(exec, table) {
+    this.exec = exec;
+    this.table = tableRef(table);
+  }
+  /** The `SELECT` list. Omit/empty for `SELECT *`. Items are columns, expressions, or aliased window fragments (`fn.rowNumber().over(...).as("rk")`). */
+  select(...items) {
+    this.selectItems.push(...items.map((item) => toText(item)));
+    return this;
+  }
+  /** `SELECT DISTINCT` — unique rows. */
+  distinct() {
+    this.distinctFlag = true;
+    return this;
+  }
+  /** `DISTINCT ON (cols)` — the first row per distinct combination, ordered by {@link orderBy}. */
+  distinctOn(...columns) {
+    this.distinctOnItems.push(...columns.map((column) => toText(column)));
+    return this;
+  }
+  /** `INNER JOIN table ON condition`. */
+  innerJoin(table, on) {
+    return this.addJoin("inner", table, on);
+  }
+  /** `LEFT JOIN table ON condition`. */
+  leftJoin(table, on) {
+    return this.addJoin("left", table, on);
+  }
+  /** `RIGHT JOIN table ON condition`. */
+  rightJoin(table, on) {
+    return this.addJoin("right", table, on);
+  }
+  /** `FULL OUTER JOIN table ON condition`. */
+  fullJoin(table, on) {
+    return this.addJoin("full", table, on);
+  }
+  /** `CROSS JOIN table` (no `ON`). */
+  crossJoin(table) {
+    return this.addJoin("cross", table);
+  }
+  /** Add `WHERE` condition(s). Multiple calls (and multiple args) are `AND`-ed. Bind values with the `sql` tag. */
+  where(...conditions) {
+    this.whereConditions.push(...conditions.map((condition) => toText(condition)));
+    return this;
+  }
+  /** `GROUP BY` column(s)/expression(s). */
+  groupBy(...columns) {
+    this.groupByItems.push(...columns.map((column) => toText(column)));
+    return this;
+  }
+  /** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed. */
+  having(...conditions) {
+    this.havingConditions.push(...conditions.map((condition) => toText(condition)));
+    return this;
+  }
+  /**
+   * `QUALIFY` — filter on a window function without a subquery, e.g.
+   * `.qualify(fn.rowNumber().over({ partitionBy: "region", orderBy: desc("total") }).lte(3))`.
+   */
+  qualify(condition) {
+    this.qualifyCondition = toText(condition);
+    return this;
+  }
+  /** `ORDER BY` term(s) — bare strings (ASC) or {@link import("./order").asc | asc}/{@link import("./order").desc | desc} tags. */
+  orderBy(...terms) {
+    this.orderByItems.push(...terms.map((term) => renderOrderTerm(term)));
+    return this;
+  }
+  /** `LIMIT n` (R2 SQL: 1–10,000, default 500). */
+  limit(n) {
+    assertLimit(n);
+    this.limitValue = n;
+    return this;
+  }
+  /** Re-type the result rows without changing the query (the builder carries no schema of its own). */
+  returns() {
+    return this;
+  }
+  /** `this UNION other` — all rows from both, duplicates removed. */
+  union(other) {
+    return this.setOperation("UNION", other);
+  }
+  /** `this UNION ALL other` — all rows from both, duplicates kept. */
+  unionAll(other) {
+    return this.setOperation("UNION ALL", other);
+  }
+  /** `this INTERSECT other` — rows present in both. */
+  intersect(other) {
+    return this.setOperation("INTERSECT", other);
+  }
+  /** `this EXCEPT other` — rows in `this` but not `other`. */
+  except(other) {
+    return this.setOperation("EXCEPT", other);
+  }
+  /** True when this query carries its own `ORDER BY`/`LIMIT` — so a set operation must parenthesise it. */
+  get needsWrapForSetOperation() {
+    return this.orderByItems.length > 0 || this.limitValue !== void 0;
+  }
+  /** Render the `SELECT` statement (no trailing semicolon). */
+  toSQL() {
+    const parts = [`${this.renderHead()} ${this.selectItems.length > 0 ? this.selectItems.join(", ") : "*"}`, `FROM ${this.table}`];
+    for (const join of this.joins) {
+      parts.push(join.on === void 0 ? `${JOIN_KEYWORDS[join.kind]} ${join.table}` : `${JOIN_KEYWORDS[join.kind]} ${join.table} ON ${toText(join.on)}`);
+    }
+    if (this.whereConditions.length > 0) {
+      parts.push(`WHERE ${this.whereConditions.join(" AND ")}`);
+    }
+    if (this.groupByItems.length > 0) {
+      parts.push(`GROUP BY ${this.groupByItems.join(", ")}`);
+    }
+    if (this.havingConditions.length > 0) {
+      parts.push(`HAVING ${this.havingConditions.join(" AND ")}`);
+    }
+    if (this.qualifyCondition !== void 0) {
+      parts.push(`QUALIFY ${this.qualifyCondition}`);
+    }
+    if (this.orderByItems.length > 0) {
+      parts.push(`ORDER BY ${this.orderByItems.join(", ")}`);
+    }
+    if (this.limitValue !== void 0) {
+      parts.push(`LIMIT ${lit(this.limitValue)}`);
+    }
+    return parts.join(" ");
+  }
+  /** Execute the query and return the typed result. */
+  async run() {
+    return this.exec(this.toSQL());
+  }
+  /** The `SELECT [DISTINCT [ON (...)]]` head. */
+  renderHead() {
+    if (this.distinctOnItems.length > 0) {
+      return `SELECT DISTINCT ON (${this.distinctOnItems.join(", ")})`;
+    }
+    return this.distinctFlag ? "SELECT DISTINCT" : "SELECT";
+  }
+  addJoin(kind, table, on) {
+    this.joins.push({ kind, on, table: tableRef(table) });
+    return this;
+  }
+  setOperation(operator, other) {
+    return new SetOperation(this.exec, [{ query: this }, { operator, query: other }]);
+  }
+}
+
+export { SelectBuilder as default };

package/dist/packem_shared/SetOperation-DmPgUL8W.mjs

@@ -0,0 +1,81 @@
+import { renderOrderTerm } from './asc-DZbQCxh1.mjs';
+import { assertLimit, lit } from './Sql-B3zq2YGx.mjs';
+
+const renderMember = (query) => {
+  const text = query.toSQL();
+  return query.needsWrapForSetOperation === true ? `(${text})` : text;
+};
+class SetOperation {
+  /**
+   * Always `true`: a nested set operation must be parenthesised when it is a
+   * member of another set operation, or mixed operators mis-associate — e.g.
+   * `a.union(b.except(c))` must render `a UNION (b EXCEPT c)`, not the flat
+   * `a UNION b EXCEPT c`.
+   */
+  needsWrapForSetOperation = true;
+  exec;
+  members;
+  orderByItems = [];
+  limitValue;
+  constructor(exec, members) {
+    this.exec = exec;
+    this.members = members;
+  }
+  /** Append `UNION other`. */
+  union(other) {
+    return this.add("UNION", other);
+  }
+  /** Append `UNION ALL other`. */
+  unionAll(other) {
+    return this.add("UNION ALL", other);
+  }
+  /** Append `INTERSECT other`. */
+  intersect(other) {
+    return this.add("INTERSECT", other);
+  }
+  /** Append `EXCEPT other`. */
+  except(other) {
+    return this.add("EXCEPT", other);
+  }
+  /** `ORDER BY` applied to the combined result. */
+  orderBy(...terms) {
+    this.orderByItems.push(...terms.map((term) => renderOrderTerm(term)));
+    return this;
+  }
+  /** `LIMIT` applied to the combined result. */
+  limit(n) {
+    assertLimit(n);
+    this.limitValue = n;
+    return this;
+  }
+  /** Re-type the combined result rows. */
+  returns() {
+    return this;
+  }
+  /** Render the combined statement. */
+  toSQL() {
+    const parts = this.members.map((member) => {
+      const text = renderMember(member.query);
+      return member.operator === void 0 ? text : `${member.operator} ${text}`;
+    });
+    const combined = parts.join(" ");
+    const tail = [];
+    if (this.orderByItems.length > 0) {
+      tail.push(`ORDER BY ${this.orderByItems.join(", ")}`);
+    }
+    if (this.limitValue !== void 0) {
+      tail.push(`LIMIT ${lit(this.limitValue)}`);
+    }
+    return tail.length > 0 ? `${combined} ${tail.join(" ")}` : combined;
+  }
+  /** Execute the combined query and return the typed result. */
+  async run() {
+    return this.exec(this.toSQL());
+  }
+  add(operator, other) {
+    this.members.push({ operator, query: other });
+    return this;
+  }
+}
+
+export { SetOperation as default };