@gscdump/cloudflare 0.25.13 → 0.26.0

package/dist/server-tail/index.d.mts

@@ -1,4 +1,5 @@
 import { ArchetypeQuery, ArchetypeResult, ArchetypeResultRow } from "@gscdump/sdk";
+import { Result } from "gscdump/result";
 import { IcebergTableName } from "@gscdump/engine/iceberg";
 import { ServerTailDirective } from "@gscdump/contracts";
 /** Placeholder substituted for the engine-specific table reference. */
@@ -69,6 +70,16 @@ declare class DuckDbIcebergTimeoutError extends Error {
   name: string;
   constructor(timeoutMs: number);
 }
+/**
+ * The modelled, caller-actionable failure channel for a DuckDB-over-Iceberg
+ * query. As with the R2 SQL client, callers branch on which class came back: a
+ * `DuckDbIcebergTimeoutError` is the retry-able deadline overrun, a
+ * `DuckDbIcebergError` is a hard sibling-RPC failure (or the `aux-cloud-only`
+ * routing reject). The error variant IS the existing throwable class, so the
+ * throwing wrappers preserve the identity/message tests assert
+ * (`rejects.toThrow(/OOM in sibling/)`, `rejects.toThrow(DuckDbIcebergError)`).
+ */
+type DuckDbIcebergQueryError = DuckDbIcebergError | DuckDbIcebergTimeoutError;
 /** A configured DuckDB-over-Iceberg executor. */
 interface DuckDbIcebergExecutor {
   /** Run a raw SQL string with `{{TABLE_<name>}}` placeholders resolved. */
@@ -77,6 +88,16 @@ interface DuckDbIcebergExecutor {
   runPlan: (plan: ArchetypeSqlPlan) => Promise<DuckDbIcebergResult>;
   /** Translate + run an archetype query. Handles `arbitrary-sql` verbatim. */
   runArchetype: (query: ArchetypeQuery) => Promise<DuckDbIcebergResult>;
+  /**
+   * Errors-as-values core for {@link DuckDbIcebergExecutor.runArchetype}:
+   * returns the modelled timeout-vs-hard-fail `DuckDbIcebergQueryError` instead
+   * of throwing, so the dispatcher can branch on retry-ability (a timeout may be
+   * worth a fallback) without `instanceof` over a `catch`. Optional so a
+   * hand-rolled executor (e.g. a host app's own service-binding executor) can
+   * implement only the throwing surface; {@link createDuckDbIcebergExecutor}
+   * always provides it.
+   */
+  runArchetypeResult?: (query: ArchetypeQuery) => Promise<Result<DuckDbIcebergResult, DuckDbIcebergQueryError>>;
 }
 /**
  * Create a DuckDB-over-Iceberg-files executor.
@@ -124,10 +145,31 @@ declare class R2SqlTimeoutError extends Error {
   name: string;
   constructor(timeoutMs: number);
 }
+/**
+ * The modelled, caller-actionable failure channel for an R2 SQL query. Callers
+ * branch on which class came back — a `R2SqlTimeoutError` is a transient retry
+ * candidate (the query outran the per-query deadline), while a `R2SqlError`
+ * (HTTP 4xx/5xx, a rejected envelope, a transport blow-up) is a hard failure.
+ * The error variant IS the existing throwable class, so the throwing wrapper
+ * preserves the exact identity/message tests assert (`rejects.toThrow(/HTTP 403/)`,
+ * `rejects.toBeInstanceOf(R2SqlTimeoutError)`). Defects — a programmer handing
+ * the client malformed params (`escapeSqlValue` / `inlineParams`) — are NOT
+ * modelled here; they keep throwing `R2SqlError` synchronously.
+ */
+type R2SqlQueryError = R2SqlError | R2SqlTimeoutError;
 /** A configured R2 SQL client. */
 interface R2SqlClient {
   /** Run a raw SQL string (table reference already resolved). */
   query: (sql: string) => Promise<R2SqlResult>;
+  /**
+   * Errors-as-values core for {@link R2SqlClient.query}: returns the modelled
+   * timeout-vs-hard-fail `R2SqlQueryError` instead of throwing, so callers can
+   * branch on retry-ability without `instanceof` over a `catch`. Optional so a
+   * hand-rolled `R2SqlClient` (e.g. a host app's own endpoint-backed client) can
+   * implement only the throwing surface; {@link createR2SqlClient} always
+   * provides it.
+   */
+  queryResult?: (sql: string) => Promise<Result<R2SqlResult, R2SqlQueryError>>;
   /** Run a dialect-neutral plan: resolve `{{TABLE}}`, inline params, send. */
   runPlan: (plan: ArchetypeSqlPlan) => Promise<R2SqlResult>;
   /** Translate + run an archetype query end to end. */
@@ -148,10 +190,19 @@ interface ServerTailDispatcherConfig {
 declare class ServerTailRoutingError extends Error {
   name: string;
 }
+/**
+ * Errors-as-values core for {@link resolveServerTailEngine}: returns a
+ * `ServerTailRoutingError` instead of throwing when an archetype is `cloud-only`
+ * (the one caller-actionable routing failure — the consumer must route that
+ * query through the cloud endpoints, not the server tail). Pure — no I/O.
+ */
+declare function resolveServerTailEngineResult(query: ArchetypeQuery): Result<ServerTailEngine, ServerTailRoutingError>;
 /**
  * Decide which engine answers an archetype query. Pure — no I/O. Exposed so
  * the file-resolution endpoint can compute the `ServerTailDirective.engine`
- * with the SAME logic the dispatcher uses at execution time.
+ * with the SAME logic the dispatcher uses at execution time. Throws
+ * `ServerTailRoutingError` for a `cloud-only` archetype; see
+ * {@link resolveServerTailEngineResult} for the errors-as-values core.
  */
 declare function resolveServerTailEngine(query: ArchetypeQuery): ServerTailEngine;
 /** A configured server-tail dispatcher. */
@@ -170,4 +221,4 @@ interface ServerTailDispatcher {
  * executor and routes every `ArchetypeQuery` to one of them.
  */
 declare function createServerTailDispatcher(config: ServerTailDispatcherConfig): ServerTailDispatcher;
-export { type ArchetypeSqlPlan, DuckDbIcebergError, type DuckDbIcebergExecutor, type DuckDbIcebergExecutorConfig, type DuckDbIcebergResult, type DuckDbIcebergRow, DuckDbIcebergTimeoutError, type DuckDbSvc, type R2SqlClient, type R2SqlClientConfig, R2SqlError, type R2SqlResult, type R2SqlRow, R2SqlTimeoutError, type ServerTailDispatcher, type ServerTailDispatcherConfig, type ServerTailEngine, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createServerTailDispatcher, resolveServerTailEngine };
+export { type ArchetypeSqlPlan, DuckDbIcebergError, type DuckDbIcebergExecutor, type DuckDbIcebergExecutorConfig, type DuckDbIcebergQueryError, type DuckDbIcebergResult, type DuckDbIcebergRow, DuckDbIcebergTimeoutError, type DuckDbSvc, type R2SqlClient, type R2SqlClientConfig, R2SqlError, type R2SqlQueryError, type R2SqlResult, type R2SqlRow, R2SqlTimeoutError, type ServerTailDispatcher, type ServerTailDispatcherConfig, type ServerTailEngine, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult };

package/dist/server-tail/index.mjs

@@ -1,5 +1,6 @@
 import { bindLiterals, inferTable } from "@gscdump/engine";
 import { ARCHETYPE_EXECUTION_CLASS } from "@gscdump/sdk";
+import { err, ok, unwrapResult } from "gscdump/result";
 const TABLE_PLACEHOLDER = "{{TABLE}}";
 function dimColumn(dim) {
 	if (dim === "page") return "url";
@@ -133,7 +134,7 @@ function buildTopNBreakdown(q) {
 	const metrics = (q.metrics.includes(q.orderBy.metric) ? q.metrics : [...q.metrics, q.orderBy.metric]).map(metricExpr).join(", ");
 	const order = `${q.orderBy.metric} ${q.orderBy.dir.toUpperCase()}`;
 	const facet = facetPredicate(q);
-	let sql = `SELECT ${col}, ${metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause}${facet.sql} GROUP BY ${col} ORDER BY ${order} LIMIT ${Math.max(0, Math.floor(q.limit))}`;
+	let sql = `SELECT ${col}, ${metrics}${q.includeTotal ? ", COUNT(*) OVER() AS __total" : ""} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause}${facet.sql} GROUP BY ${col} ORDER BY ${order} LIMIT ${Math.max(0, Math.floor(q.limit))}`;
 	if (q.offset && q.offset > 0) sql += ` OFFSET ${Math.floor(q.offset)}`;
 	return {
 		table,
@@ -220,18 +221,36 @@ function buildArchetypeSql(query) {
 var ServerTailRoutingError = class extends Error {
 	name = "ServerTailRoutingError";
 };
-function resolveServerTailEngine(query) {
+function routingErrorToException(error) {
+	return error;
+}
+function resolveServerTailEngineResult(query) {
 	const cls = ARCHETYPE_EXECUTION_CLASS[query.archetype];
-	if (cls === "cloud-only") throw new ServerTailRoutingError(`archetype '${query.archetype}' is cloud-only — not a server-tail query`);
-	if (cls === "duckdb") return "duckdb";
-	if (query.archetype === "top-n-breakdown" && query.offset && query.offset > 0) return "duckdb";
+	if (cls === "cloud-only") return err(new ServerTailRoutingError(`archetype '${query.archetype}' is cloud-only — not a server-tail query`));
+	if (cls === "duckdb") return ok("duckdb");
+	if (query.archetype === "top-n-breakdown" && query.offset && query.offset > 0) return ok("duckdb");
+	if (query.archetype === "top-n-breakdown" && query.includeTotal) return ok("duckdb");
 	const facets = query.facets;
-	if (facets && facets.length > 0) return "duckdb";
-	return "r2-sql";
+	if (facets && facets.length > 0) return ok("duckdb");
+	return ok("r2-sql");
+}
+function resolveServerTailEngine(query) {
+	return unwrapResult(resolveServerTailEngineResult(query), routingErrorToException);
 }
 function sourceFor(engine) {
 	return engine === "r2-sql" ? "server-r2-sql" : "server-duckdb";
 }
+function extractTotal(rows) {
+	if (!rows.length || !("__total" in rows[0])) return { rows };
+	const totalRows = Number(rows[0].__total) || 0;
+	return {
+		rows: rows.map((r) => {
+			const { __total, ...rest } = r;
+			return rest;
+		}),
+		totalRows
+	};
+}
 function createServerTailDispatcher(config) {
 	function route(query) {
 		return resolveServerTailEngine(query);
@@ -255,13 +274,15 @@ function createServerTailDispatcher(config) {
 			};
 		}
 		const res = await config.duckdb.runArchetype(query);
+		const { rows, totalRows } = extractTotal(res.rows);
 		return {
 			archetype: query.archetype,
-			rows: res.rows,
+			rows,
 			source: sourceFor("duckdb"),
 			meta: {
-				rowCount: res.rows.length,
-				queryMs: res.queryMs
+				rowCount: rows.length,
+				queryMs: res.queryMs,
+				...totalRows !== void 0 ? { totalRows } : {}
 			}
 		};
 	}
@@ -279,6 +300,9 @@ var DuckDbIcebergTimeoutError = class extends Error {
 		super(`DuckDB-over-Iceberg query exceeded ${timeoutMs}ms deadline`);
 	}
 };
+function duckDbIcebergErrorToException(error) {
+	return error;
+}
 const DEFAULT_TIMEOUT_MS$1 = 25e3;
 function icebergTableRef(config, table) {
 	if (config.tableRefStyle === "catalog") return `${config.namespace}.${table}`;
@@ -295,17 +319,22 @@ function resolveTablePlaceholders(sql, config) {
 }
 function createDuckDbIcebergExecutor(config) {
 	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS$1;
-	async function send(sql) {
+	async function sendResult(sql) {
 		const started = Date.now();
-		const result = await withDeadline(config.svc.runSQL({ sql }), timeoutMs).catch((err) => {
-			if (err instanceof DuckDbIcebergTimeoutError) throw err;
-			throw new DuckDbIcebergError(`DUCKDB_SVC.runSQL failed: ${err.message}`);
-		});
-		return {
+		const raced = await withDeadline(config.svc.runSQL({ sql }), timeoutMs).then((value) => ok(value)).catch((error) => error instanceof DuckDbIcebergTimeoutError ? err(error) : err(new DuckDbIcebergError(`DUCKDB_SVC.runSQL failed: ${error.message}`)));
+		if (!raced.ok) return raced;
+		const result = raced.value;
+		return ok({
 			rows: result.rows ?? [],
 			sql: result.sql ?? sql,
 			queryMs: Date.now() - started
-		};
+		});
+	}
+	async function send(sql) {
+		return unwrapResult(await sendResult(sql), duckDbIcebergErrorToException);
+	}
+	function runSqlResult(sql, params = []) {
+		return sendResult(bindLiterals(resolveTablePlaceholders(sql, config), params));
 	}
 	function runSql(sql, params = []) {
 		return send(bindLiterals(resolveTablePlaceholders(sql, config), params));
@@ -313,15 +342,22 @@ function createDuckDbIcebergExecutor(config) {
 	function runPlan(plan) {
 		return send(bindLiterals(plan.sql.split(TABLE_PLACEHOLDER).join(icebergTableRef(config, plan.table)), plan.params));
 	}
+	function runPlanResult(plan) {
+		return sendResult(bindLiterals(plan.sql.split(TABLE_PLACEHOLDER).join(icebergTableRef(config, plan.table)), plan.params));
+	}
+	function runArchetypeResult(query) {
+		if (query.archetype === "arbitrary-sql") return runSqlResult(query.sql, query.params ?? []);
+		if (query.archetype === "aux-cloud-only") return Promise.resolve(err(new DuckDbIcebergError("aux-cloud-only is not an Iceberg query")));
+		return runPlanResult(buildArchetypeSql(query));
+	}
 	async function runArchetype(query) {
-		if (query.archetype === "arbitrary-sql") return runSql(query.sql, query.params ?? []);
-		if (query.archetype === "aux-cloud-only") throw new DuckDbIcebergError("aux-cloud-only is not an Iceberg query");
-		return runPlan(buildArchetypeSql(query));
+		return unwrapResult(await runArchetypeResult(query), duckDbIcebergErrorToException);
 	}
 	return {
 		runSql,
 		runPlan,
-		runArchetype
+		runArchetype,
+		runArchetypeResult
 	};
 }
 function r2TableRef(namespace, table) {
@@ -341,6 +377,9 @@ var R2SqlTimeoutError = class extends Error {
 		super(`R2 SQL query exceeded ${timeoutMs}ms deadline`);
 	}
 };
+function r2SqlErrorToException(error) {
+	return error;
+}
 const DEFAULT_API_BASE = "https://api.sql.cloudflarestorage.com/api/v1";
 const DEFAULT_TIMEOUT_MS = 25e3;
 const PARTITION_PREDICATE_RE = /\b(site_id|search_type)(\s*=)/g;
@@ -403,7 +442,7 @@ function createR2SqlClient(config) {
 	const apiBase = config.apiBase ?? DEFAULT_API_BASE;
 	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const endpoint = `${apiBase}/accounts/${config.accountId}/r2-sql/query/${config.bucket}`;
-	async function query(sql) {
+	async function queryResult(sql) {
 		const started = Date.now();
 		const controller = new AbortController();
 		const timer = setTimeout(() => controller.abort(new R2SqlTimeoutError(timeoutMs)), timeoutMs);
@@ -419,23 +458,26 @@ function createR2SqlClient(config) {
 				body: JSON.stringify({ query: sql }),
 				signal: controller.signal
 			});
-		} catch (err) {
-			if (err instanceof R2SqlTimeoutError || err?.name === "AbortError") throw new R2SqlTimeoutError(timeoutMs);
-			throw new R2SqlError(`R2 SQL request failed: ${err.message}`);
+		} catch (error) {
+			if (error instanceof R2SqlTimeoutError || error?.name === "AbortError") return err(new R2SqlTimeoutError(timeoutMs));
+			return err(new R2SqlError(`R2 SQL request failed: ${error.message}`));
 		} finally {
 			clearTimeout(timer);
 		}
 		if (!response.ok) {
 			const text = await response.text().catch(() => "");
-			throw new R2SqlError(`R2 SQL HTTP ${response.status}: ${text}`, response.status);
+			return err(new R2SqlError(`R2 SQL HTTP ${response.status}: ${text}`, response.status));
 		}
 		const envelope = await response.json();
-		if (!envelope.success) throw new R2SqlError(`R2 SQL query rejected: ${envelope.errors?.map((e) => e.message).join("; ") ?? "unknown R2 SQL error"}`);
-		return {
+		if (!envelope.success) return err(new R2SqlError(`R2 SQL query rejected: ${envelope.errors?.map((e) => e.message).join("; ") ?? "unknown R2 SQL error"}`));
+		return ok({
 			rows: normalizeRows(envelope.result),
 			sql,
 			queryMs: Date.now() - started
-		};
+		});
+	}
+	async function query(sql) {
+		return unwrapResult(await queryResult(sql), r2SqlErrorToException);
 	}
 	function runPlan(plan) {
 		const tableRef = r2TableRef(config.namespace, plan.table);
@@ -446,8 +488,9 @@ function createR2SqlClient(config) {
 	}
 	return {
 		query,
+		queryResult,
 		runPlan,
 		runArchetype
 	};
 }
-export { DuckDbIcebergError, DuckDbIcebergTimeoutError, R2SqlError, R2SqlTimeoutError, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createServerTailDispatcher, resolveServerTailEngine };
+export { DuckDbIcebergError, DuckDbIcebergTimeoutError, R2SqlError, R2SqlTimeoutError, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createR2SqlClient, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cloudflare",
   "type": "module",
-  "version": "0.25.13",
+  "version": "0.26.0",
   "description": "Cloudflare-Workers-flavored helpers for the gscdump analytics stack: AnalyticsEnv binding contract, R2 SigV4 presigner, size-hint HMAC, DuckDB Workers shims, engine factory.",
   "author": {
     "name": "Harlan Wilton",
@@ -46,18 +46,18 @@
   "dependencies": {
     "@uwdata/flechette": "^2.5.0",
     "aws4fetch": "^1.0.20",
-    "@gscdump/engine": "0.25.13",
-    "@gscdump/contracts": "0.25.13",
-    "@gscdump/sdk": "0.25.13",
-    "gscdump": "0.25.13",
-    "@gscdump/engine-sqlite": "0.25.13"
+    "@gscdump/contracts": "0.26.0",
+    "@gscdump/engine-sqlite": "0.26.0",
+    "@gscdump/sdk": "0.26.0",
+    "@gscdump/engine": "0.26.0",
+    "gscdump": "0.26.0"
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "^0.16.10",
-    "@cloudflare/workers-types": "^4.20260531.1",
+    "@cloudflare/vitest-pool-workers": "^0.16.12",
+    "@cloudflare/workers-types": "^4.20260603.1",
     "h3": "^1.15.11",
     "typescript": "^6.0.3",
-    "wrangler": "^4.95.0"
+    "wrangler": "^4.97.0"
   },
   "scripts": {
     "build": "obuild",