@burojs/hasura 0.2.0 → 0.5.0

package/dist/index.js

@@ -1,839 +1,968 @@
-import { defineDataProvider, normalizeDataError, isDataError } from '@burojs/core';
-import { createClient } from 'graphql-ws';
-
-// src/data-provider.ts
-
-// src/endpoint.ts
-var DEFAULT_HASURA_ENDPOINT = "/gql/v1/graphql";
+import { defineDataProvider, isDataError, normalizeDataError } from "@burojs/core";
+import { createClient } from "graphql-ws";
+//#region src/cursor.ts
+const HASURA_CURSOR_CODES = Object.freeze({
+	unorderable: "cursor-unorderable",
+	backward: "cursor-backward-unsupported",
+	limit: "cursor-limit-invalid",
+	malformed: "cursor-malformed",
+	mismatch: "cursor-ordering-mismatch",
+	boundaryNull: "cursor-boundary-null"
+});
+const CURSOR_VERSION = 1;
+function cursorError(code, kind, message) {
+	return {
+		kind,
+		code,
+		message
+	};
+}
+function orderingSignature(ordering) {
+	return ordering.map((column) => `${column.field}:${column.direction}`).join(",");
+}
+function effectiveCursorOrdering(sort, mapping) {
+	const pkField = mapping.pkField ?? "id";
+	const requested = (sort ?? []).filter((entry) => Boolean(entry.field));
+	const columns = requested.length > 0 ? requested.map((entry) => ({
+		field: entry.field,
+		direction: entry.direction
+	})) : [{
+		field: mapping.orderByField ?? pkField,
+		direction: "desc"
+	}];
+	if (columns.some((column) => column.field === pkField)) return columns;
+	const last = columns[columns.length - 1];
+	return [...columns, {
+		field: pkField,
+		direction: last?.direction ?? "asc"
+	}];
+}
+function assertCursorOrderable(ordering, sort, mapping) {
+	const nulled = (sort ?? []).find((entry) => entry.nulls !== void 0);
+	if (nulled !== void 0) throw cursorError(HASURA_CURSOR_CODES.unorderable, "capability", `@burojs/hasura cannot cursor-paginate '${mapping.table}' ordered by '${nulled.field}' with an explicit nulls placement: a keyset predicate over NULLs is not expressible here. Sort without \`nulls\`, or use offset pagination.`);
+	const selected = new Set(mapping.selectFields);
+	const missing = ordering.filter((column) => !selected.has(column.field));
+	if (missing.length > 0) throw cursorError(HASURA_CURSOR_CODES.unorderable, "capability", `@burojs/hasura cannot cursor-paginate '${mapping.table}': the ordering needs ${missing.map((column) => `'${column.field}'`).join(", ")}, which the mapping does not select, so no page can carry the value the next cursor is made of. Cursor pagination orders by the sort columns plus the primary key ('${ordering[ordering.length - 1]?.field ?? "id"}'), and every one of them must be in \`selectFields\`.`);
+}
+function assertCursorLimit(limit, table) {
+	if (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0) throw cursorError(HASURA_CURSOR_CODES.limit, "validation", `@burojs/hasura cursor pagination on '${table}' needs a positive integer \`limit\`, got ${JSON.stringify(limit)}.`);
+}
+function base64UrlEncode(text) {
+	const bytes = new TextEncoder().encode(text);
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return (typeof btoa === "function" ? btoa(binary) : Buffer.from(bytes).toString("base64")).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(text) {
+	const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+	if (typeof atob === "function") {
+		const binary = atob(base64);
+		const bytes = new Uint8Array(binary.length);
+		for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+		return new TextDecoder().decode(bytes);
+	}
+	return Buffer.from(base64, "base64").toString("utf8");
+}
+function encodeCursor(ordering, row, table) {
+	const values = [];
+	for (const column of ordering) {
+		const value = row[column.field];
+		if (value === null || value === void 0) throw cursorError(HASURA_CURSOR_CODES.boundaryNull, "capability", `@burojs/hasura cannot mint a cursor for '${table}': the last row of the page has no value for the ordering column '${column.field}', and a keyset predicate over NULL matches nothing. Order by a non-null column, or use offset pagination.`);
+		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") throw cursorError(HASURA_CURSOR_CODES.boundaryNull, "capability", `@burojs/hasura cannot mint a cursor for '${table}': ordering column '${column.field}' holds ${typeof value}, which has no total order to seek on.`);
+		values.push(value);
+	}
+	const envelope = {
+		v: CURSOR_VERSION,
+		o: orderingSignature(ordering),
+		k: values
+	};
+	return base64UrlEncode(JSON.stringify(envelope));
+}
+function decodeCursor(raw, ordering, table) {
+	if (typeof raw !== "string" || raw.length === 0) throw cursorError(HASURA_CURSOR_CODES.malformed, "validation", `@burojs/hasura got a non-string cursor for '${table}': ${JSON.stringify(raw)}. A cursor is opaque — pass back exactly what \`pageInfo.nextCursor\` returned.`);
+	let envelope;
+	try {
+		envelope = JSON.parse(base64UrlDecode(raw));
+	} catch (cause) {
+		throw {
+			...cursorError(HASURA_CURSOR_CODES.malformed, "validation", `@burojs/hasura could not decode the cursor for '${table}'. A cursor is opaque — pass back exactly what \`pageInfo.nextCursor\` returned.`),
+			cause
+		};
+	}
+	if (envelope === null || typeof envelope !== "object" || envelope.v !== CURSOR_VERSION || typeof envelope.o !== "string" || !Array.isArray(envelope.k)) throw cursorError(HASURA_CURSOR_CODES.malformed, "validation", `@burojs/hasura got a cursor for '${table}' it did not mint (envelope version ${String(envelope?.v)}).`);
+	const signature = orderingSignature(ordering);
+	if (envelope.o !== signature) throw cursorError(HASURA_CURSOR_CODES.mismatch, "validation", `@burojs/hasura refuses a cursor for '${table}' minted under ordering '${envelope.o}' against a request ordered '${signature}': the page it addressed no longer exists. Restart from the first page when the sort changes.`);
+	if (envelope.k.length !== ordering.length) throw cursorError(HASURA_CURSOR_CODES.malformed, "validation", `@burojs/hasura got a cursor for '${table}' carrying ${envelope.k.length} boundary values for ${ordering.length} ordering columns.`);
+	return envelope.k;
+}
+function keysetWhere(ordering, boundary, int64Fields) {
+	const int64 = new Set(int64Fields ?? []);
+	const value = (index, field) => {
+		const raw = boundary[index];
+		return int64.has(field) ? String(raw) : raw;
+	};
+	const branches = [];
+	for (let index = 0; index < ordering.length; index += 1) {
+		const column = ordering[index];
+		if (column === void 0) continue;
+		const strict = column.direction === "desc" ? "_lt" : "_gt";
+		const tail = { [column.field]: { [strict]: value(index, column.field) } };
+		if (index === 0) {
+			branches.push(tail);
+			continue;
+		}
+		const clauses = [];
+		for (let prior = 0; prior < index; prior += 1) {
+			const priorColumn = ordering[prior];
+			if (priorColumn === void 0) continue;
+			clauses.push({ [priorColumn.field]: { _eq: value(prior, priorColumn.field) } });
+		}
+		clauses.push(tail);
+		branches.push({ _and: clauses });
+	}
+	return { _or: branches };
+}
+//#endregion
+//#region src/endpoint.ts
+const DEFAULT_HASURA_ENDPOINT = "/gql/v1/graphql";
+//#endregion
+//#region src/live-provider.ts
 function hasuraWsUrl(endpoint) {
-  if (typeof window === "undefined") return endpoint;
-  const url = new URL(endpoint, window.location.origin);
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-  return url.toString();
+	if (typeof window === "undefined") return endpoint;
+	const url = new URL(endpoint, window.location.origin);
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	return url.toString();
 }
 function listSubscription(mapping) {
-  const where = mapping.fixedFilter;
-  return {
-    query: where ? `subscription Live_${mapping.table}_list($where: ${mapping.table}_bool_exp) {
+	const where = mapping.fixedFilter;
+	return {
+		query: where ? `subscription Live_${mapping.table}_list($where: ${mapping.table}_bool_exp) {
           ${mapping.table}_aggregate(where: $where) { aggregate { count max { updated_at } } }
         }` : `subscription Live_${mapping.table}_list {
           ${mapping.table}_aggregate { aggregate { count max { updated_at } } }
         }`,
-    ...where === void 0 ? {} : { variables: { where } }
-  };
+		...where === void 0 ? {} : { variables: { where } }
+	};
 }
 function oneSubscription(mapping, id) {
-  const pkField = mapping.pkField ?? "id";
-  const pkType = mapping.pkType ?? "bigint";
-  const root = mapping.byPkRoot === false ? null : mapping.byPkRoot ?? `${mapping.table}_by_pk`;
-  if (root === null) return null;
-  return {
-    query: `subscription Live_${mapping.table}_one($id: ${pkType}!) {
+	const pkField = mapping.pkField ?? "id";
+	const pkType = mapping.pkType ?? "bigint";
+	const root = mapping.byPkRoot === false ? null : mapping.byPkRoot ?? `${mapping.table}_by_pk`;
+	if (root === null) return null;
+	return {
+		query: `subscription Live_${mapping.table}_one($id: ${pkType}!) {
       ${root}(${pkField}: $id) { ${pkField} updated_at }
     }`,
-    variables: { id }
-  };
+		variables: { id }
+	};
 }
 function createHasuraLiveProvider(config) {
-  const listeners = /* @__PURE__ */ new Set();
-  const endpoint = config.endpoint ?? DEFAULT_HASURA_ENDPOINT;
-  const role = config.role ?? null;
-  let client;
-  const status = (value) => {
-    for (const listener of listeners) listener(value);
-  };
-  function getClient() {
-    if (client !== void 0) return client;
-    const options = {
-      url: hasuraWsUrl(endpoint),
-      lazy: true,
-      keepAlive: 1e4,
-      retryAttempts: Number.POSITIVE_INFINITY,
-      shouldRetry: () => true,
-      connectionParams: async () => {
-        const token = await config.getToken();
-        return {
-          headers: {
-            ...token ? { Authorization: `Bearer ${token}` } : {},
-            ...role ? { "X-Hasura-Role": role } : {}
-          }
-        };
-      },
-      on: {
-        connecting: () => status("connecting"),
-        connected: () => status("connected"),
-        closed: () => status("degraded")
-      }
-    };
-    client = config.clientFactory?.(options) ?? createClient(options);
-    return client;
-  }
-  return {
-    async open(descriptor, openContext) {
-      if (openContext.signal.aborted) return null;
-      const mapping = config.resources[descriptor.resource];
-      if (mapping?.live !== true) return null;
-      const payload = descriptor.kind === "list" ? listSubscription(mapping) : descriptor.kind === "one" ? oneSubscription(mapping, descriptor.id) : null;
-      if (payload === null) return null;
-      return {
-        kind: "invalidate",
-        initial: "query",
-        subscribe(observer, subscribeContext) {
-          if (openContext.signal.aborted || subscribeContext.signal.aborted) return () => void 0;
-          let primed = false;
-          let closed = false;
-          let upstream = void 0;
-          const close = () => {
-            if (closed) return;
-            closed = true;
-            listeners.delete(onStatus);
-            openContext.signal.removeEventListener("abort", close);
-            subscribeContext.signal.removeEventListener("abort", close);
-            upstream?.();
-          };
-          const onStatus = (value) => {
-            if (!closed) observer.status(value);
-          };
-          const sink = {
-            next: () => {
-              if (closed) return;
-              if (!primed) {
-                primed = true;
-                return;
-              }
-              observer.next(void 0);
-            },
-            error: (error) => {
-              if (closed) return;
-              observer.error(normalizeDataError(error));
-              close();
-            },
-            complete: () => {
-              if (!closed) observer.status("degraded");
-            }
-          };
-          listeners.add(onStatus);
-          openContext.signal.addEventListener("abort", close, { once: true });
-          subscribeContext.signal.addEventListener("abort", close, { once: true });
-          upstream = getClient().subscribe(payload, sink);
-          if (closed) upstream();
-          if (openContext.signal.aborted || subscribeContext.signal.aborted) close();
-          return Promise.resolve(close);
-        }
-      };
-    }
-  };
+	const listeners = new Set();
+	const endpoint = config.endpoint ?? "/gql/v1/graphql";
+	const role = config.role ?? null;
+	let client;
+	const status = (value) => {
+		for (const listener of listeners) listener(value);
+	};
+	function getClient() {
+		if (client !== void 0) return client;
+		const options = {
+			url: hasuraWsUrl(endpoint),
+			lazy: true,
+			keepAlive: 1e4,
+			retryAttempts: Number.POSITIVE_INFINITY,
+			shouldRetry: () => true,
+			connectionParams: async () => {
+				const token = await config.getToken();
+				return { headers: {
+					...token ? { Authorization: `Bearer ${token}` } : {},
+					...role ? { "X-Hasura-Role": role } : {}
+				} };
+			},
+			on: {
+				connecting: () => status("connecting"),
+				connected: () => status("connected"),
+				closed: () => status("degraded")
+			}
+		};
+		client = config.clientFactory?.(options) ?? createClient(options);
+		return client;
+	}
+	return {
+		declaredPushInvalidation() {
+			return Object.entries(config.resources).filter(([, mapping]) => mapping?.live === true).map(([resource]) => resource);
+		},
+		async open(descriptor, openContext) {
+			if (openContext.signal.aborted) return null;
+			const mapping = config.resources[descriptor.resource];
+			if (mapping?.live !== true) return null;
+			const payload = descriptor.kind === "list" ? listSubscription(mapping) : descriptor.kind === "one" ? oneSubscription(mapping, descriptor.id) : null;
+			if (payload === null) return null;
+			return {
+				kind: "invalidate",
+				initial: "query",
+				subscribe(observer, subscribeContext) {
+					if (openContext.signal.aborted || subscribeContext.signal.aborted) return () => void 0;
+					let primed = false;
+					let closed = false;
+					let upstream = void 0;
+					const close = () => {
+						if (closed) return;
+						closed = true;
+						listeners.delete(onStatus);
+						openContext.signal.removeEventListener("abort", close);
+						subscribeContext.signal.removeEventListener("abort", close);
+						upstream?.();
+					};
+					const onStatus = (value) => {
+						if (!closed) observer.status(value);
+					};
+					const sink = {
+						next: () => {
+							if (closed) return;
+							if (!primed) {
+								primed = true;
+								return;
+							}
+							observer.next(void 0);
+						},
+						error: (error) => {
+							if (closed) return;
+							observer.error(normalizeDataError(error));
+							close();
+						},
+						complete: () => {
+							if (!closed) observer.status("degraded");
+						}
+					};
+					listeners.add(onStatus);
+					openContext.signal.addEventListener("abort", close, { once: true });
+					subscribeContext.signal.addEventListener("abort", close, { once: true });
+					upstream = getClient().subscribe(payload, sink);
+					if (closed) upstream();
+					if (openContext.signal.aborted || subscribeContext.signal.aborted) close();
+					return Promise.resolve(close);
+				}
+			};
+		}
+	};
 }
-
-// src/data-provider.ts
+//#endregion
+//#region src/data-provider.ts
 function setNestedPath(obj, path, value) {
-  const parts = path.split(".");
-  const leaf = parts.pop();
-  if (leaf === void 0) return;
-  let cur = obj;
-  for (const p of parts) {
-    const next = cur[p];
-    if (typeof next !== "object" || next === null) cur[p] = {};
-    cur = cur[p];
-  }
-  cur[leaf] = value;
+	const parts = path.split(".");
+	const leaf = parts.pop();
+	if (leaf === void 0) return;
+	let cur = obj;
+	for (const p of parts) {
+		const next = cur[p];
+		if (typeof next !== "object" || next === null) cur[p] = {};
+		cur = cur[p];
+	}
+	cur[leaf] = value;
 }
 function getNestedPath(obj, path) {
-  let cur = obj;
-  for (const p of path.split(".")) {
-    if (cur == null || typeof cur !== "object") return void 0;
-    cur = cur[p];
-  }
-  return cur;
+	let cur = obj;
+	for (const p of path.split(".")) {
+		if (cur == null || typeof cur !== "object") return void 0;
+		cur = cur[p];
+	}
+	return cur;
 }
 function partitionDataBody(values, cfg) {
-  const keySet = new Set(cfg.keys);
-  const dataBody = {};
-  const rest = {};
-  let hasDataBody = false;
-  for (const [key, value] of Object.entries(values)) {
-    if (key === cfg.relationship) continue;
-    if (keySet.has(key)) {
-      if (value !== void 0) {
-        dataBody[key] = value;
-        hasDataBody = true;
-      }
-    } else {
-      rest[key] = value;
-    }
-  }
-  return { dataBody, rest, hasDataBody };
+	const keySet = new Set(cfg.keys);
+	const dataBody = {};
+	const rest = {};
+	let hasDataBody = false;
+	for (const [key, value] of Object.entries(values)) {
+		if (key === cfg.relationship) continue;
+		if (keySet.has(key)) {
+			if (value !== void 0) {
+				dataBody[key] = value;
+				hasDataBody = true;
+			}
+		} else rest[key] = value;
+	}
+	return {
+		dataBody,
+		rest,
+		hasDataBody
+	};
 }
 function partitionJsonbSpill(values, spill, baseColumns) {
-  const baseSet = new Set(baseColumns);
-  const metaSet = new Set(spill.metaKeys);
-  const nestedKeys = spill.nestedKeys ?? {};
-  const base = {};
-  const headExplicit = {};
-  const metaExplicit = {};
-  const headSpill = {};
-  const metaSpill = {};
-  const nestedSpill = [];
-  for (const [key, value] of Object.entries(values)) {
-    if (value === void 0) continue;
-    const nestedPath = nestedKeys[key];
-    if (key === spill.column) {
-      if (value && typeof value === "object")
-        Object.assign(headExplicit, value);
-    } else if (key === spill.metaColumn) {
-      if (value && typeof value === "object")
-        Object.assign(metaExplicit, value);
-    } else if (metaSet.has(key)) {
-      metaSpill[key] = value;
-    } else if (nestedPath) {
-      nestedSpill.push([nestedPath, value]);
-    } else if (baseSet.has(key)) {
-      base[key] = value;
-    } else {
-      headSpill[key] = value;
-    }
-  }
-  const head = { ...headExplicit, ...headSpill };
-  for (const [path, value] of nestedSpill) setNestedPath(head, path, value);
-  const meta = { ...metaExplicit, ...metaSpill };
-  const out = { ...base };
-  if (Object.keys(head).length > 0) out[spill.column] = head;
-  if (Object.keys(meta).length > 0) out[spill.metaColumn] = meta;
-  return out;
+	const baseSet = new Set(baseColumns);
+	const metaSet = new Set(spill.metaKeys);
+	const nestedKeys = spill.nestedKeys ?? {};
+	const base = {};
+	const headExplicit = {};
+	const metaExplicit = {};
+	const headSpill = {};
+	const metaSpill = {};
+	const nestedSpill = [];
+	for (const [key, value] of Object.entries(values)) {
+		if (value === void 0) continue;
+		const nestedPath = nestedKeys[key];
+		if (key === spill.column) {
+			if (value && typeof value === "object") Object.assign(headExplicit, value);
+		} else if (key === spill.metaColumn) {
+			if (value && typeof value === "object") Object.assign(metaExplicit, value);
+		} else if (metaSet.has(key)) metaSpill[key] = value;
+		else if (nestedPath) nestedSpill.push([nestedPath, value]);
+		else if (baseSet.has(key)) base[key] = value;
+		else headSpill[key] = value;
+	}
+	const head = {
+		...headExplicit,
+		...headSpill
+	};
+	for (const [path, value] of nestedSpill) setNestedPath(head, path, value);
+	const meta = {
+		...metaExplicit,
+		...metaSpill
+	};
+	const out = { ...base };
+	if (Object.keys(head).length > 0) out[spill.column] = head;
+	if (Object.keys(meta).length > 0) out[spill.metaColumn] = meta;
+	return out;
 }
 function flattenJsonbSpill(item, spill) {
-  if (!item || typeof item !== "object") return item;
-  const rec = item;
-  const headObj = rec[spill.column];
-  const metaObj = rec[spill.metaColumn];
-  const out = {
-    ...headObj && typeof headObj === "object" ? headObj : {},
-    ...metaObj && typeof metaObj === "object" ? metaObj : {},
-    ...rec
-  };
-  if (spill.nestedKeys && headObj && typeof headObj === "object") {
-    for (const [flatKey, path] of Object.entries(spill.nestedKeys)) {
-      const v = getNestedPath(headObj, path);
-      if (v !== void 0) out[flatKey] = v;
-    }
-  }
-  return out;
-}
-var NOT_AUTHENTICATED_CODE = "not-authenticated";
-var OP_MAP = {
-  eq: "_eq",
-  neq: "_neq",
-  ne: "_neq",
-  lt: "_lt",
-  lte: "_lte",
-  gt: "_gt",
-  gte: "_gte",
-  in: "_in",
-  notIn: "_nin",
-  nin: "_nin",
-  contains: "_ilike",
-  containss: "_like",
-  startsWith: "_ilike",
-  endsWith: "_ilike",
-  startswith: "_ilike",
-  endswith: "_ilike",
-  null: "_is_null"
+	if (!item || typeof item !== "object") return item;
+	const rec = item;
+	const headObj = rec[spill.column];
+	const metaObj = rec[spill.metaColumn];
+	const out = {
+		...headObj && typeof headObj === "object" ? headObj : {},
+		...metaObj && typeof metaObj === "object" ? metaObj : {},
+		...rec
+	};
+	if (spill.nestedKeys && headObj && typeof headObj === "object") for (const [flatKey, path] of Object.entries(spill.nestedKeys)) {
+		const v = getNestedPath(headObj, path);
+		if (v !== void 0) out[flatKey] = v;
+	}
+	return out;
+}
+const NOT_AUTHENTICATED_CODE = "not-authenticated";
+const FORBIDDEN_CODES = new Set(["access-denied", "permission-error"]);
+const HASURA_EXTERNAL_FAILURE_CODES = new Set([
+	"unexpected",
+	"remote-schema-error",
+	"parse-failed"
+]);
+const MUTATION_REFUSAL_CODES = new Map([["constraint-violation", "conflict"], ["validation-failed", "validation"]]);
+function graphqlError(errors, operation, external) {
+	const message = errors.map((e) => e.message).join("; ");
+	const codes = errors.flatMap((e) => typeof e.extensions?.code === "string" ? [e.extensions.code] : []);
+	if (codes.includes("invalid-jwt")) return {
+		kind: "auth",
+		code: "invalid-jwt",
+		message,
+		details: errors
+	};
+	const outside = operation === "mutation" && external ? codes.find((code) => HASURA_EXTERNAL_FAILURE_CODES.has(code) || MUTATION_REFUSAL_CODES.has(code) || FORBIDDEN_CODES.has(code)) : void 0;
+	if (outside !== void 0) return {
+		kind: "sent",
+		code: outside,
+		message,
+		retryable: false,
+		details: errors
+	};
+	const forbidden = codes.find((code) => FORBIDDEN_CODES.has(code));
+	if (forbidden !== void 0) return {
+		kind: "forbidden",
+		code: forbidden,
+		message,
+		details: errors
+	};
+	if (operation === "mutation") for (const code of codes) {
+		const kind = MUTATION_REFUSAL_CODES.get(code);
+		if (kind !== void 0) return {
+			kind,
+			code,
+			message,
+			details: errors
+		};
+	}
+	return {
+		kind: "protocol",
+		code: "graphql-error",
+		message,
+		details: errors
+	};
+}
+function answerLost(code, message, status, cause) {
+	return {
+		kind: "sent",
+		code,
+		message,
+		status,
+		retryable: false,
+		...cause === void 0 ? {} : { cause }
+	};
+}
+const LOCALE_REQUIRED_CODE = "locale-required";
+function localeWhere(m, locale) {
+	if (m.localeField === void 0) return void 0;
+	if (typeof locale !== "string" || locale.length === 0) throw {
+		kind: "capability",
+		code: LOCALE_REQUIRED_CODE,
+		message: `@burojs/hasura: '${m.table}' maps a localeField ('${m.localeField}') but this read carries no locale. Declare \`data: { localeVarying: true }\` on the resource so @burojs/core puts the active locale on the descriptor, or drop the localeField. Serving the request anyway would return every language's rows at once.`
+	};
+	return { [m.localeField]: { _eq: locale } };
+}
+const OP_MAP = {
+	eq: "_eq",
+	neq: "_neq",
+	ne: "_neq",
+	lt: "_lt",
+	lte: "_lte",
+	gt: "_gt",
+	gte: "_gte",
+	in: "_in",
+	notIn: "_nin",
+	nin: "_nin",
+	contains: "_ilike",
+	containss: "_like",
+	startsWith: "_ilike",
+	endsWith: "_ilike",
+	startswith: "_ilike",
+	endswith: "_ilike",
+	null: "_is_null"
 };
-var FILTER_OPERATOR_UNSUPPORTED_CODE = "filter-operator-unsupported";
-var UNEXPRESSIBLE_OPS = {
-  has: "a collection-membership test",
-  hasAny: "a collection-membership test",
-  hasAll: "a collection-membership test"
+const FILTER_OPERATOR_UNSUPPORTED_CODE = "filter-operator-unsupported";
+const UNEXPRESSIBLE_OPS = {
+	has: "a collection-membership test",
+	hasAny: "a collection-membership test",
+	hasAll: "a collection-membership test"
 };
 function unsupportedOperator(field, op) {
-  const why = UNEXPRESSIBLE_OPS[op];
-  return {
-    kind: "capability",
-    code: FILTER_OPERATOR_UNSUPPORTED_CODE,
-    message: why ? `@burojs/hasura cannot express the '${op}' filter operator on '${field}': ${why}, whose Hasura encoding depends on whether the column is jsonb or a Postgres array \u2014 something no ResourceMapping field declares. Declare it and translate explicitly, or filter on a scalar column.` : `@burojs/hasura does not support the filter operator '${op}' (on '${field}').`
-  };
+	const why = UNEXPRESSIBLE_OPS[op];
+	return {
+		kind: "capability",
+		code: FILTER_OPERATOR_UNSUPPORTED_CODE,
+		message: why ? `@burojs/hasura cannot express the '${op}' filter operator on '${field}': ${why}, whose Hasura encoding depends on whether the column is jsonb or a Postgres array — something no ResourceMapping field declares. Declare it and translate explicitly, or filter on a scalar column.` : `@burojs/hasura does not support the filter operator '${op}' (on '${field}').`
+	};
 }
 function scopeToWhere(scope, scopeFields) {
-  const clauses = [];
-  for (const key of scopeFields) {
-    const v = scope[key];
-    if (v == null || v === "") continue;
-    clauses.push({ [key]: { _eq: v } });
-  }
-  if (clauses.length === 0) return void 0;
-  if (clauses.length === 1) return clauses[0];
-  return { _and: clauses };
+	const clauses = [];
+	for (const key of scopeFields) {
+		const v = scope[key];
+		if (v == null || v === "") continue;
+		clauses.push({ [key]: { _eq: v } });
+	}
+	if (clauses.length === 0) return void 0;
+	if (clauses.length === 1) return clauses[0];
+	return { _and: clauses };
 }
 function mergeWhere(a, b) {
-  if (!a) return b;
-  if (!b) return a;
-  return { _and: [a, b] };
+	if (!a) return b;
+	if (!b) return a;
+	return { _and: [a, b] };
+}
+function atFieldPath(field, predicate) {
+	const parts = field.split(".");
+	let out = predicate;
+	for (let i = parts.length - 1; i >= 0; i -= 1) out = { [parts[i]]: out };
+	return out;
 }
 function filtersToWhere(filter) {
-  if (!filter || typeof filter !== "object") return void 0;
-  if ("and" in filter) {
-    if (filter.and.length === 0) return { _and: [] };
-    const clauses = filter.and.map(filtersToWhere).filter((item) => item !== void 0);
-    if (clauses.length === 0) return void 0;
-    return clauses.length === 1 ? clauses[0] : { _and: clauses };
-  }
-  if ("or" in filter) {
-    if (filter.or.length === 0) return { _or: [] };
-    const clauses = filter.or.map(filtersToWhere).filter((item) => item !== void 0);
-    if (clauses.length === 0) return void 0;
-    return clauses.length === 1 ? clauses[0] : { _or: clauses };
-  }
-  if ("not" in filter) {
-    const clause = filtersToWhere(filter.not);
-    return clause === void 0 ? void 0 : { _not: clause };
-  }
-  if (!("field" in filter) || typeof filter.field !== "string" || !("op" in filter))
-    return void 0;
-  const { field, op } = filter;
-  if (op === "isNull") return { [field]: { _is_null: true } };
-  if (op === "isNotNull") return { [field]: { _is_null: false } };
-  if (!("value" in filter) || filter.value === void 0) return void 0;
-  const operator = OP_MAP[op];
-  if (operator === void 0) throw unsupportedOperator(field, op);
-  let value = filter.value;
-  if (operator === "_ilike" || operator === "_like") {
-    const text = String(value);
-    value = op === "startsWith" ? `${text}%` : op === "endsWith" ? `%${text}` : `%${text}%`;
-  }
-  return { [field]: { [operator]: value } };
+	if (!filter || typeof filter !== "object") return void 0;
+	if ("and" in filter) {
+		if (filter.and.length === 0) return { _and: [] };
+		const clauses = filter.and.map(filtersToWhere).filter((item) => item !== void 0);
+		if (clauses.length === 0) return void 0;
+		return clauses.length === 1 ? clauses[0] : { _and: clauses };
+	}
+	if ("or" in filter) {
+		if (filter.or.length === 0) return { _or: [] };
+		const clauses = filter.or.map(filtersToWhere).filter((item) => item !== void 0);
+		if (clauses.length === 0) return void 0;
+		return clauses.length === 1 ? clauses[0] : { _or: clauses };
+	}
+	if ("not" in filter) {
+		const clause = filtersToWhere(filter.not);
+		return clause === void 0 ? void 0 : { _not: clause };
+	}
+	if (!("field" in filter) || typeof filter.field !== "string" || !("op" in filter)) return void 0;
+	const { field, op } = filter;
+	if (op === "isNull") return atFieldPath(field, { _is_null: true });
+	if (op === "isNotNull") return atFieldPath(field, { _is_null: false });
+	if (!("value" in filter) || filter.value === void 0) return void 0;
+	const operator = OP_MAP[op];
+	if (operator === void 0) throw unsupportedOperator(field, op);
+	let value = filter.value;
+	if (operator === "_ilike" || operator === "_like") {
+		const text = String(value);
+		value = op === "startsWith" ? `${text}%` : op === "endsWith" ? `%${text}` : `%${text}%`;
+	}
+	return atFieldPath(field, { [operator]: value });
 }
 function coerceInt64Filter(filter, fields) {
-  if (!filter || !fields?.length) return filter;
-  if ("and" in filter)
-    return {
-      and: filter.and.map(
-        (entry) => coerceInt64Filter(entry, fields)
-      )
-    };
-  if ("or" in filter)
-    return {
-      or: filter.or.map(
-        (entry) => coerceInt64Filter(entry, fields)
-      )
-    };
-  if ("not" in filter)
-    return { not: coerceInt64Filter(filter.not, fields) };
-  if ("field" in filter && fields.includes(filter.field) && "value" in filter && filter.value != null) {
-    const value = Array.isArray(filter.value) ? filter.value.map(String) : String(filter.value);
-    return { ...filter, value };
-  }
-  return filter;
+	if (!filter || !fields?.length) return filter;
+	if ("and" in filter) return { and: filter.and.map((entry) => coerceInt64Filter(entry, fields)) };
+	if ("or" in filter) return { or: filter.or.map((entry) => coerceInt64Filter(entry, fields)) };
+	if ("not" in filter) return { not: coerceInt64Filter(filter.not, fields) };
+	if ("field" in filter && fields.includes(filter.field) && "value" in filter && filter.value != null) {
+		const value = Array.isArray(filter.value) ? filter.value.map(String) : String(filter.value);
+		return {
+			...filter,
+			value
+		};
+	}
+	return filter;
 }
 function hasuraError(error, signal, fallback) {
-  if (isDataError(error)) return error;
-  if (signal.aborted)
-    return {
-      kind: "cancelled",
-      code: "request-aborted",
-      message: "Hasura request was aborted.",
-      cause: error
-    };
-  return {
-    kind: "transport",
-    code: "hasura-request-failed",
-    message: error instanceof Error && error.message ? error.message : fallback,
-    cause: error
-  };
+	if (isDataError(error)) return error;
+	if (signal.aborted) return {
+		kind: "cancelled",
+		code: "request-aborted",
+		message: "Hasura request was aborted.",
+		cause: error
+	};
+	return {
+		kind: "transport",
+		code: "hasura-request-failed",
+		message: error instanceof Error && error.message ? error.message : fallback,
+		cause: error
+	};
 }
 function aggregateRoot(m) {
-  if (m.aggregate === false) return null;
-  return typeof m.aggregate === "string" ? m.aggregate : `${m.table}_aggregate`;
+	if (m.aggregate === false) return null;
+	return typeof m.aggregate === "string" ? m.aggregate : `${m.table}_aggregate`;
 }
 function byPkRoot(m) {
-  if (m.byPkRoot === false) return null;
-  return m.byPkRoot ?? `${m.table}_by_pk`;
+	if (m.byPkRoot === false) return null;
+	return m.byPkRoot ?? `${m.table}_by_pk`;
 }
 function snapshotOperationRegistry(source) {
-  if (source === void 0) return Object.freeze({});
-  const resources = {};
-  for (const [resource, operations] of Object.entries(source)) {
-    const entries = {};
-    for (const [name, operation] of Object.entries(operations)) {
-      entries[name] = Object.freeze({ ...operation });
-    }
-    resources[resource] = Object.freeze(entries);
-  }
-  return Object.freeze(resources);
+	if (source === void 0) return Object.freeze({});
+	const resources = {};
+	for (const [resource, operations] of Object.entries(source)) {
+		const entries = {};
+		for (const [name, operation] of Object.entries(operations)) entries[name] = Object.freeze({ ...operation });
+		resources[resource] = Object.freeze(entries);
+	}
+	return Object.freeze(resources);
 }
 function hasRegisteredOperationKind(operations, kind) {
-  return Object.values(operations).some(
-    (byName) => Object.values(byName).some((operation) => operation.kind === kind)
-  );
+	return Object.values(operations).some((byName) => Object.values(byName).some((operation) => operation.kind === kind));
 }
 function normalizeRole(role) {
-  return role === void 0 || role === null || role === "" ? null : role;
+	return role === void 0 || role === null || role === "" ? null : role;
 }
 function createHasuraDataProvider(config) {
-  const endpoint = config.endpoint ?? DEFAULT_HASURA_ENDPOINT;
-  const defaultRole = normalizeRole(config.defaultRole);
-  const operations = snapshotOperationRegistry(config.operations);
-  const hasCustomQueries = hasRegisteredOperationKind(operations, "query");
-  const hasCustomMutations = hasRegisteredOperationKind(operations, "mutation");
-  async function gql(query, variables, role, signal) {
-    try {
-      const request = async (token2) => {
-        const headers = {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${token2}`
-        };
-        const effectiveRole = role === void 0 ? defaultRole : normalizeRole(role);
-        if (effectiveRole !== null) headers["X-Hasura-Role"] = effectiveRole;
-        const fetchImpl = config.fetchImpl ?? fetch;
-        return fetchImpl(endpoint, {
-          method: "POST",
-          headers,
-          body: JSON.stringify({ query, variables }),
-          signal
-        });
-      };
-      let token = await config.getToken();
-      if (!token)
-        throw {
-          kind: "auth",
-          code: NOT_AUTHENTICATED_CODE,
-          message: "Not authenticated."
-        };
-      let res = await request(token);
-      if (res.status === 401 && config.recoverAuth && await config.recoverAuth()) {
-        token = await config.getToken();
-        if (!token)
-          throw {
-            kind: "auth",
-            code: NOT_AUTHENTICATED_CODE,
-            message: "Not authenticated."
-          };
-        res = await request(token);
-      }
-      if (!res.ok)
-        throw {
-          kind: "transport",
-          code: "graphql-http-error",
-          message: `GraphQL HTTP ${res.status}`,
-          status: res.status
-        };
-      const body = await res.json();
-      if (body.errors?.length)
-        throw {
-          kind: "protocol",
-          code: "graphql-error",
-          message: body.errors.map((e) => e.message).join("; "),
-          details: body.errors
-        };
-      if (body.data === void 0)
-        throw {
-          kind: "protocol",
-          code: "empty-graphql-response",
-          message: "Empty GraphQL response."
-        };
-      return body.data;
-    } catch (error) {
-      throw hasuraError(error, signal, "Hasura request failed.");
-    }
-  }
-  function mapping(resource) {
-    const m = config.resources[resource];
-    if (!m)
-      throw {
-        kind: "configuration",
-        code: "unknown-resource",
-        message: `Unknown resource: ${resource}`
-      };
-    return m;
-  }
-  function registeredOperation(resource, operation, kind) {
-    const registered = operations[resource]?.[operation];
-    if (registered === void 0 || registered.kind !== kind) {
-      throw {
-        kind: "capability",
-        code: "hasura-custom-operation-unsupported",
-        message: `Hasura ${kind} operation '${operation}' is not declared for '${resource}'.`
-      };
-    }
-    return registered;
-  }
-  async function executeCustomOperation(resource, operationName, input, kind, signal) {
-    const operation = registeredOperation(resource, operationName, kind);
-    const result = await gql(
-      operation.document,
-      operation.variables(input),
-      operation.role ?? config.resources[resource]?.role,
-      signal
-    );
-    return operation.mapResult?.(result) ?? result;
-  }
-  function composeListWhere(m, descriptor, context) {
-    const userWhere = filtersToWhere(coerceInt64Filter(descriptor.filter, m.int64Fields));
-    const ignoreScope = descriptor.providerOptions?.ignoreScope === true;
-    const sessionScope = context.session.scopeKey !== null && typeof context.session.scopeKey === "object" && !Array.isArray(context.session.scopeKey) ? context.session.scopeKey : {};
-    const scope = ignoreScope ? {} : { ...sessionScope, ...config.getScope?.(context) ?? {} };
-    const scopeWhere = scopeToWhere(scope, m.scopeFields ?? []);
-    return mergeWhere(mergeWhere(userWhere, scopeWhere), m.fixedFilter);
-  }
-  async function runAggregateCount(m, root, where, signal) {
-    const aggWhereArg = where ? "($where: " + m.table + "_bool_exp)" : "";
-    const aggWhereParam = where ? "(where: $where)" : "";
-    const metaQuery = `query Count_${m.table} ${aggWhereArg} {
+	const endpoint = config.endpoint ?? "/gql/v1/graphql";
+	const defaultRole = normalizeRole(config.defaultRole);
+	const operations = snapshotOperationRegistry(config.operations);
+	const hasCustomQueries = hasRegisteredOperationKind(operations, "query");
+	const hasCustomMutations = hasRegisteredOperationKind(operations, "mutation");
+	async function gql(query, variables, role, signal, operation, external = false) {
+		try {
+			const requestBody = JSON.stringify({
+				query,
+				variables
+			});
+			const request = async (token) => {
+				const headers = {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${token}`
+				};
+				const effectiveRole = role === void 0 ? defaultRole : normalizeRole(role);
+				if (effectiveRole !== null) headers["X-Hasura-Role"] = effectiveRole;
+				const fetchImpl = config.fetchImpl ?? fetch;
+				try {
+					return await fetchImpl(endpoint, {
+						method: "POST",
+						headers,
+						body: requestBody,
+						signal
+					});
+				} catch (cause) {
+					if (operation === "mutation" && !signal.aborted) throw {
+						kind: "sent",
+						code: "hasura-request-sent",
+						message: "Hasura did not answer a mutation; it may have been applied.",
+						retryable: false,
+						cause
+					};
+					throw cause;
+				}
+			};
+			let token = await config.getToken();
+			if (!token) throw {
+				kind: "auth",
+				code: NOT_AUTHENTICATED_CODE,
+				message: "Not authenticated."
+			};
+			let res = await request(token);
+			if (res.status === 401 && config.recoverAuth && await config.recoverAuth()) {
+				token = await config.getToken();
+				if (!token) throw {
+					kind: "auth",
+					code: NOT_AUTHENTICATED_CODE,
+					message: "Not authenticated."
+				};
+				res = await request(token);
+			}
+			if (!res.ok) {
+				if (operation === "mutation" && res.status >= 500) throw answerLost("hasura-answer-lost", `GraphQL HTTP ${res.status} after a mutation was sent; it may have been applied.`, res.status);
+				throw {
+					kind: "transport",
+					code: "graphql-http-error",
+					message: `GraphQL HTTP ${res.status}`,
+					status: res.status
+				};
+			}
+			let body;
+			try {
+				body = await res.json();
+				if (body === null || typeof body !== "object") throw new TypeError("The GraphQL answer is not an object.");
+			} catch (cause) {
+				if (operation === "mutation" && !signal.aborted) throw answerLost("hasura-answer-unreadable", "Hasura answered a mutation with a body that could not be read; it may have been applied.", res.status, cause);
+				throw cause;
+			}
+			if (body.errors?.length) throw graphqlError(body.errors, operation, external);
+			if (body.data === void 0) {
+				if (operation === "mutation") throw answerLost("hasura-answer-unreadable", "Hasura answered a mutation without data or errors; it may have been applied.", res.status);
+				throw {
+					kind: "protocol",
+					code: "empty-graphql-response",
+					message: "Empty GraphQL response."
+				};
+			}
+			return body.data;
+		} catch (error) {
+			throw hasuraError(error, signal, "Hasura request failed.");
+		}
+	}
+	function mapping(resource) {
+		const m = config.resources[resource];
+		if (!m) throw {
+			kind: "configuration",
+			code: "unknown-resource",
+			message: `Unknown resource: ${resource}`
+		};
+		return m;
+	}
+	function registeredOperation(resource, operation, kind) {
+		const registered = operations[resource]?.[operation];
+		if (registered === void 0 || registered.kind !== kind) throw {
+			kind: "capability",
+			code: "hasura-custom-operation-unsupported",
+			message: `Hasura ${kind} operation '${operation}' is not declared for '${resource}'.`
+		};
+		return registered;
+	}
+	async function executeCustomOperation(resource, operationName, input, kind, signal) {
+		const operation = registeredOperation(resource, operationName, kind);
+		const result = await gql(operation.document, operation.variables(input), operation.role ?? config.resources[resource]?.role, signal, kind, kind === "mutation");
+		return operation.mapResult === void 0 ? result : operation.mapResult(result);
+	}
+	function composeListWhere(m, descriptor, context) {
+		const userWhere = filtersToWhere(coerceInt64Filter(descriptor.filter, m.int64Fields));
+		const ignoreScope = descriptor.providerOptions?.ignoreScope === true;
+		const sessionScope = context.session.scopeKey !== null && typeof context.session.scopeKey === "object" && !Array.isArray(context.session.scopeKey) ? context.session.scopeKey : {};
+		return mergeWhere(mergeWhere(mergeWhere(userWhere, scopeToWhere(ignoreScope ? {} : {
+			...sessionScope,
+			...config.getScope?.(context) ?? {}
+		}, m.scopeFields ?? [])), m.fixedFilter), localeWhere(m, descriptor.locale));
+	}
+	async function runAggregateCount(m, root, where, signal) {
+		const aggWhereArg = where ? `($where: ${m.table}_bool_exp)` : "";
+		const aggWhereParam = where ? "(where: $where)" : "";
+		const metaQuery = `query Count_${m.table} ${aggWhereArg} {
       meta: ${root} ${aggWhereParam} { aggregate { count } }
     }`;
-    const aggVars = {};
-    if (where) aggVars["where"] = where;
-    const metaData = await gql(
-      metaQuery,
-      where ? aggVars : void 0,
-      m.role,
-      signal
-    );
-    return metaData.meta.aggregate.count;
-  }
-  async function upsertDataBody(db, parentId, body, role, signal) {
-    const mutation = `mutation UpsertDataBody($object: ${db.table}_insert_input!) {
+		const aggVars = {};
+		if (where) aggVars.where = where;
+		return (await gql(metaQuery, where ? aggVars : void 0, m.role, signal, "query")).meta.aggregate.count;
+	}
+	async function upsertDataBody(db, parentId, body, role, signal) {
+		await gql(`mutation UpsertDataBody($object: ${db.table}_insert_input!) {
       result: insert_${db.table}_one(
         object: $object,
         on_conflict: { constraint: ${db.constraint}, update_columns: [${db.column}] }
       ) { ${db.fk} }
-    }`;
-    await gql(mutation, { object: { [db.fk]: parentId, [db.column]: body } }, role, signal);
-  }
-  function mutationRecord(m, idField, item, resource, expectedId) {
-    if (item === null || typeof item !== "object" || Array.isArray(item)) {
-      throw {
-        kind: "protocol",
-        code: "record-not-found",
-        message: `Not found: ${resource}`
-      };
-    }
-    const record = item;
-    const id = record[m.pkField ?? idField];
-    if (typeof id !== "string" && (typeof id !== "number" || !Number.isFinite(id))) {
-      throw {
-        kind: "protocol",
-        code: "mutation-record-id-missing",
-        message: `Mutation for '${resource}' returned no valid '${m.pkField ?? idField}'.`
-      };
-    }
-    if (expectedId !== void 0 && id !== expectedId) {
-      throw {
-        kind: "protocol",
-        code: "unexpected-record-id",
-        message: `Mutation for '${resource}' returned '${String(id)}' instead of '${String(expectedId)}'.`
-      };
-    }
-    return { kind: "record", id, record: item, completeness: "partial" };
-  }
-  async function readMutationRecord(m, id, signal) {
-    const fields = m.selectFields.join(" ");
-    const pkType = m.pkType ?? "bigint";
-    const pkField = m.pkField ?? "id";
-    const root = byPkRoot(m);
-    if (m.fixedFilter || root === null) {
-      const where = mergeWhere({ [pkField]: { _eq: id } }, m.fixedFilter);
-      const query2 = `query One_${m.table}($where: ${m.table}_bool_exp) {
+    }`, { object: {
+			[db.fk]: parentId,
+			[db.column]: body
+		} }, role, signal, "mutation");
+	}
+	function mutationRecord(m, idField, item, resource, expectedId) {
+		if (item === null || typeof item !== "object" || Array.isArray(item)) throw {
+			kind: "not-found",
+			code: "record-not-found",
+			message: `Not found: ${resource}`
+		};
+		const id = item[m.pkField ?? idField];
+		if (typeof id !== "string" && (typeof id !== "number" || !Number.isFinite(id))) throw {
+			kind: "protocol",
+			code: "mutation-record-id-missing",
+			message: `Mutation for '${resource}' returned no valid '${m.pkField ?? idField}'.`
+		};
+		if (expectedId !== void 0 && id !== expectedId) throw {
+			kind: "protocol",
+			code: "unexpected-record-id",
+			message: `Mutation for '${resource}' returned '${String(id)}' instead of '${String(expectedId)}'.`
+		};
+		return {
+			kind: "record",
+			id,
+			record: item,
+			completeness: "partial"
+		};
+	}
+	async function readMutationRecord(m, id, signal) {
+		const fields = m.selectFields.join(" ");
+		const pkType = m.pkType ?? "bigint";
+		const pkField = m.pkField ?? "id";
+		const root = byPkRoot(m);
+		if (m.fixedFilter || root === null) {
+			const where = mergeWhere({ [pkField]: { _eq: id } }, m.fixedFilter);
+			return (await gql(`query One_${m.table}($where: ${m.table}_bool_exp) {
         items: ${m.table}(where: $where, limit: 1) { ${fields} }
-      }`;
-      const data2 = await gql(query2, { where }, m.role, signal);
-      return data2.items?.[0] ?? null;
-    }
-    const query = `query One_${m.table}($id: ${pkType}!) {
+      }`, { where }, m.role, signal, "query")).items?.[0] ?? null;
+		}
+		return (await gql(`query One_${m.table}($id: ${pkType}!) {
       item: ${root}(${pkField}: $id) { ${fields} }
-    }`;
-    const data = await gql(query, { id }, m.role, signal);
-    return data.item;
-  }
-  return defineDataProvider({
-    queries: {
-      async list(descriptor, context) {
-        const m = mapping(descriptor.resource);
-        if (descriptor.pagination?.kind === "cursor") {
-          throw {
-            kind: "capability",
-            code: "cursor-pagination-unsupported",
-            message: "Hasura provider supports offset pagination only."
-          };
-        }
-        const limit = descriptor.pagination?.kind === "offset" ? descriptor.pagination.pageSize : 25;
-        const page = descriptor.pagination?.kind === "offset" ? descriptor.pagination.page : 1;
-        const offset = (page - 1) * limit;
-        const where = composeListWhere(m, descriptor, context);
-        const sorters = descriptor.sort?.filter((s) => s.field);
-        let orderByExpr;
-        if (sorters && sorters.length > 0) {
-          orderByExpr = `[${sorters.map((s) => `{${s.field}: ${s.direction}}`).join(", ")}]`;
-        } else {
-          const defaultField = m.orderByField ?? "id";
-          orderByExpr = `{${defaultField}: desc}`;
-        }
-        const fields = m.selectFields.join(" ");
-        const whereArg = where ? ", $where: " + m.table + "_bool_exp" : "";
-        const whereParam = where ? ", where: $where" : "";
-        const itemsQuery = `query List_${m.table}($limit: Int, $offset: Int${whereArg}) {
+    }`, { id }, m.role, signal, "query")).item;
+	}
+	async function listByCursor(m, descriptor, pagination, context) {
+		if (pagination.before !== void 0) throw {
+			kind: "capability",
+			code: HASURA_CURSOR_CODES.backward,
+			message: `@burojs/hasura implements forward cursor pagination only; '${m.table}' was asked to page backwards with \`before\`. Nothing in this framework drives backward keyset paging today, and an unexercised implementation of it would be a worse answer than a refusal.`
+		};
+		assertCursorLimit(pagination.limit, m.table);
+		const sorters = descriptor.sort?.filter((s) => s.field);
+		const ordering = effectiveCursorOrdering(sorters, m);
+		assertCursorOrderable(ordering, sorters, m);
+		const baseWhere = composeListWhere(m, descriptor, context);
+		const where = pagination.after === void 0 ? baseWhere : mergeWhere(baseWhere, keysetWhere(ordering, decodeCursor(pagination.after, ordering, m.table), m.int64Fields));
+		const fields = m.selectFields.join(" ");
+		const orderByExpr = `[${ordering.map((c) => `{${c.field}: ${c.direction}}`).join(", ")}]`;
+		const whereArg = where ? `, $where: ${m.table}_bool_exp` : "";
+		const whereParam = where ? ", where: $where" : "";
+		const itemsQuery = `query ListCursor_${m.table}($limit: Int${whereArg}) {
+        items: ${m.table}(limit: $limit, order_by: ${orderByExpr}${whereParam}) { ${fields} }
+      }`;
+		const itemsVars = { limit: pagination.limit + 1 };
+		if (where) itemsVars.where = where;
+		const fetched = (await gql(itemsQuery, itemsVars, m.role, context.signal, "query")).items ?? [];
+		const hasNextPage = fetched.length > pagination.limit;
+		const rows = hasNextPage ? fetched.slice(0, pagination.limit) : fetched;
+		let total;
+		const listAggRoot = aggregateRoot(m);
+		if (!m.noAggregate && listAggRoot) try {
+			total = await runAggregateCount(m, listAggRoot, baseWhere, context.signal);
+		} catch (err) {
+			console.warn(`[hasura] count failed for ${m.table}; rendering unknown-total`, err);
+		}
+		const boundary = rows[rows.length - 1];
+		const nextCursor = hasNextPage && boundary !== null && typeof boundary === "object" ? encodeCursor(ordering, boundary, m.table) : void 0;
+		const spill = m.jsonbSpill;
+		return {
+			data: spill ? rows.map((it) => flattenJsonbSpill(it, spill)) : rows,
+			total,
+			pageInfo: {
+				nextCursor,
+				hasNextPage
+			}
+		};
+	}
+	return defineDataProvider({
+		queries: {
+			async list(descriptor, context) {
+				const m = mapping(descriptor.resource);
+				if (descriptor.pagination?.kind === "cursor") return await listByCursor(m, descriptor, descriptor.pagination, context);
+				const limit = descriptor.pagination?.kind === "offset" ? descriptor.pagination.pageSize : 25;
+				const offset = ((descriptor.pagination?.kind === "offset" ? descriptor.pagination.page : 1) - 1) * limit;
+				const where = composeListWhere(m, descriptor, context);
+				const sorters = descriptor.sort?.filter((s) => s.field);
+				let orderByExpr;
+				if (sorters && sorters.length > 0) orderByExpr = `[${sorters.map((s) => `{${s.field}: ${s.direction}}`).join(", ")}]`;
+				else orderByExpr = `{${m.orderByField ?? "id"}: desc}`;
+				const fields = m.selectFields.join(" ");
+				const whereArg = where ? `, $where: ${m.table}_bool_exp` : "";
+				const whereParam = where ? ", where: $where" : "";
+				const itemsQuery = `query List_${m.table}($limit: Int, $offset: Int${whereArg}) {
         items: ${m.table}(limit: $limit, offset: $offset, order_by: ${orderByExpr}${whereParam}) { ${fields} }
       }`;
-        const itemsVars = { limit, offset };
-        if (where) itemsVars["where"] = where;
-        const itemsData = await gql(
-          itemsQuery,
-          itemsVars,
-          m.role,
-          context.signal
-        );
-        let total;
-        const listAggRoot = aggregateRoot(m);
-        if (!m.noAggregate && listAggRoot) {
-          try {
-            total = await runAggregateCount(m, listAggRoot, where, context.signal);
-          } catch (err) {
-            console.warn(`[hasura] count failed for ${m.table}; rendering unknown-total`, err);
-          }
-        }
-        const spill = m.jsonbSpill;
-        const items = spill ? itemsData.items.map((it) => flattenJsonbSpill(it, spill)) : itemsData.items;
-        return { data: items, total };
-      },
-      /**
-       * On-demand row count — the answer to "how many are there?" on the lists
-       * that page without a grand total (`noAggregate`). Never fired implicitly:
-       * one source app measured ~55 s for a single COUNT, which is exactly why
-       * the list stopped issuing one on every page.
-       *
-       * `{ total: null }` means "not countable here at all" — the registry says
-       * this table has no aggregate root, or the resource isn't mapped by this
-       * provider. It is a DECISION, and the UI latches the affordance off for the
-       * session. A transient backend failure REJECTS instead (it propagates out of
-       * `gql`), so a retry stays possible; never conflate the two.
-       *
-       * The `where` comes from the same {@link composeListWhere} `getList` uses —
-       * same filters, same scope, same `fixedFilter` — so the number always
-       * describes the rows the list is paging through.
-       */
-      async count(descriptor, context) {
-        const m = config.resources[descriptor.resource];
-        if (!m) return { total: null };
-        const root = aggregateRoot(m);
-        if (!root) return { total: null };
-        return {
-          total: await runAggregateCount(
-            m,
-            root,
-            composeListWhere(m, descriptor, context),
-            context.signal
-          )
-        };
-      },
-      async many(descriptor, context) {
-        const m = mapping(descriptor.resource);
-        if (descriptor.ids.length === 0) return { data: [] };
-        const pkField = m.pkField ?? "id";
-        const idsWhere = { [pkField]: { _in: descriptor.ids } };
-        const where = mergeWhere(
-          idsWhere,
-          composeListWhere(m, descriptor, context)
-        );
-        const fields = m.selectFields.join(" ");
-        const query = `query Many_${m.table}($where: ${m.table}_bool_exp) {
+				const itemsVars = {
+					limit,
+					offset
+				};
+				if (where) itemsVars.where = where;
+				const itemsData = await gql(itemsQuery, itemsVars, m.role, context.signal, "query");
+				let total;
+				const listAggRoot = aggregateRoot(m);
+				if (!m.noAggregate && listAggRoot) try {
+					total = await runAggregateCount(m, listAggRoot, where, context.signal);
+				} catch (err) {
+					console.warn(`[hasura] count failed for ${m.table}; rendering unknown-total`, err);
+				}
+				const spill = m.jsonbSpill;
+				return {
+					data: spill ? itemsData.items.map((it) => flattenJsonbSpill(it, spill)) : itemsData.items,
+					total
+				};
+			},
+			async count(descriptor, context) {
+				const m = config.resources[descriptor.resource];
+				if (!m) return { total: null };
+				const root = aggregateRoot(m);
+				if (!root) return { total: null };
+				return { total: await runAggregateCount(m, root, composeListWhere(m, descriptor, context), context.signal) };
+			},
+			async many(descriptor, context) {
+				const m = mapping(descriptor.resource);
+				localeWhere(m, descriptor.locale);
+				if (descriptor.ids.length === 0) return { data: [] };
+				const where = mergeWhere({ [m.pkField ?? "id"]: { _in: descriptor.ids } }, composeListWhere(m, descriptor, context));
+				const fields = m.selectFields.join(" ");
+				const data = await gql(`query Many_${m.table}($where: ${m.table}_bool_exp) {
         items: ${m.table}(where: $where) { ${fields} }
-      }`;
-        const data = await gql(query, { where }, m.role, context.signal);
-        const spill = m.jsonbSpill;
-        const items = spill ? data.items.map((item) => flattenJsonbSpill(item, spill)) : data.items;
-        return { data: items };
-      },
-      async one(descriptor, context) {
-        const m = mapping(descriptor.resource);
-        const dbSelect = m.dataBody ? ` ${m.dataBody.relationship} { ${m.dataBody.column} }` : "";
-        const fields = m.selectFields.join(" ") + dbSelect;
-        const pkType = m.pkType ?? "bigint";
-        const pkField = m.pkField ?? "id";
-        let item;
-        const root = byPkRoot(m);
-        if (m.fixedFilter || root === null) {
-          const where = mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter);
-          const query = `query One_${m.table}($where: ${m.table}_bool_exp) {
+      }`, { where }, m.role, context.signal, "query");
+				const spill = m.jsonbSpill;
+				return { data: spill ? data.items.map((item) => flattenJsonbSpill(item, spill)) : data.items };
+			},
+			async one(descriptor, context) {
+				const m = mapping(descriptor.resource);
+				const dbSelect = m.dataBody ? ` ${m.dataBody.relationship} { ${m.dataBody.column} }` : "";
+				const fields = m.selectFields.join(" ") + dbSelect;
+				const pkType = m.pkType ?? "bigint";
+				const pkField = m.pkField ?? "id";
+				let item;
+				const root = byPkRoot(m);
+				const localeSlice = localeWhere(m, descriptor.locale);
+				if (m.fixedFilter || localeSlice || root === null) {
+					const where = mergeWhere(mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter), localeSlice);
+					item = (await gql(`query One_${m.table}($where: ${m.table}_bool_exp) {
           items: ${m.table}(where: $where, limit: 1) { ${fields} }
-        }`;
-          const data = await gql(query, { where }, m.role, context.signal);
-          item = data.items?.[0] ?? null;
-        } else {
-          const query = `query One_${m.table}($id: ${pkType}!) {
+        }`, { where }, m.role, context.signal, "query")).items?.[0] ?? null;
+				} else item = (await gql(`query One_${m.table}($id: ${pkType}!) {
           item: ${root}(${pkField}: $id) { ${fields} }
-        }`;
-          const data = await gql(
-            query,
-            { id: descriptor.id },
-            m.role,
-            context.signal
-          );
-          item = data.item;
-        }
-        if (item == null)
-          throw {
-            kind: "protocol",
-            code: "record-not-found",
-            message: `Not found: ${descriptor.resource}/${descriptor.id}`
-          };
-        let result = m.jsonbSpill ? flattenJsonbSpill(item, m.jsonbSpill) : item;
-        if (m.dataBody && result && typeof result === "object") {
-          const rec = { ...result };
-          const sibling = rec[m.dataBody.relationship];
-          const body = sibling && typeof sibling === "object" ? sibling[m.dataBody.column] : null;
-          delete rec[m.dataBody.relationship];
-          result = body && typeof body === "object" ? { ...rec, ...body } : rec;
-        }
-        return { data: result };
-      },
-      ...hasCustomQueries ? {
-        async custom(descriptor, context) {
-          return executeCustomOperation(
-            descriptor.resource,
-            descriptor.operation,
-            descriptor.input,
-            "query",
-            context.signal
-          );
-        }
-      } : {}
-    },
-    mutations: {
-      async createOne(descriptor, context) {
-        const m = mapping(descriptor.resource);
-        const fields = m.selectFields.join(" ");
-        const rawInput = descriptor.input;
-        let mainInput = rawInput;
-        let dataBody;
-        if (m.dataBody) {
-          const split = partitionDataBody(rawInput, m.dataBody);
-          mainInput = split.rest;
-          dataBody = split.hasDataBody ? split.dataBody : void 0;
-        }
-        const object = m.jsonbSpill ? partitionJsonbSpill(mainInput, m.jsonbSpill, m.selectFields) : mainInput;
-        const query = `mutation Create_${m.table}($object: ${m.table}_insert_input!) {
+        }`, { id: descriptor.id }, m.role, context.signal, "query")).item;
+				if (item == null) throw {
+					kind: "not-found",
+					code: "record-not-found",
+					message: `Not found: ${descriptor.resource}/${descriptor.id}`
+				};
+				let result = m.jsonbSpill ? flattenJsonbSpill(item, m.jsonbSpill) : item;
+				if (m.dataBody && result && typeof result === "object") {
+					const rec = { ...result };
+					const sibling = rec[m.dataBody.relationship];
+					const body = sibling && typeof sibling === "object" ? sibling[m.dataBody.column] : null;
+					delete rec[m.dataBody.relationship];
+					result = body && typeof body === "object" ? {
+						...rec,
+						...body
+					} : rec;
+				}
+				return { data: result };
+			},
+			...hasCustomQueries ? { async custom(descriptor, context) {
+				return executeCustomOperation(descriptor.resource, descriptor.operation, descriptor.input, "query", context.signal);
+			} } : {}
+		},
+		mutations: {
+			async createOne(descriptor, context) {
+				const m = mapping(descriptor.resource);
+				const fields = m.selectFields.join(" ");
+				const rawInput = descriptor.input;
+				let mainInput = rawInput;
+				let dataBody;
+				if (m.dataBody) {
+					const split = partitionDataBody(rawInput, m.dataBody);
+					mainInput = split.rest;
+					dataBody = split.hasDataBody ? split.dataBody : void 0;
+				}
+				const object = m.jsonbSpill ? partitionJsonbSpill(mainInput, m.jsonbSpill, m.selectFields) : mainInput;
+				const data = await gql(`mutation Create_${m.table}($object: ${m.table}_insert_input!) {
         item: insert_${m.table}_one(object: $object) { ${fields} }
-      }`;
-        const data = await gql(query, { object }, m.role, context.signal);
-        const result = mutationRecord(m, descriptor.idField, data.item, descriptor.resource);
-        if (m.dataBody && dataBody)
-          await upsertDataBody(m.dataBody, result.id, dataBody, m.role, context.signal);
-        return result;
-      },
-      async updateOne(descriptor, context) {
-        const m = mapping(descriptor.resource);
-        const fields = m.selectFields.join(" ");
-        const rawInput = descriptor.input;
-        let mainInput = rawInput;
-        let dataBody;
-        if (m.dataBody) {
-          const split = partitionDataBody(rawInput, m.dataBody);
-          mainInput = split.rest;
-          dataBody = split.hasDataBody ? split.dataBody : void 0;
-        }
-        const set = m.jsonbSpill ? partitionJsonbSpill(mainInput, m.jsonbSpill, m.selectFields) : mainInput;
-        const pkField = m.pkField ?? descriptor.idField;
-        const ifUpdatedAt = descriptor.providerOptions?.ifUpdatedAt;
-        let item;
-        if (Object.keys(set).length === 0) {
-          item = await readMutationRecord(m, descriptor.id, context.signal);
-        } else if (m.fixedFilter || ifUpdatedAt != null) {
-          let where = mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter);
-          if (ifUpdatedAt != null) where = mergeWhere(where, { updated_at: { _eq: ifUpdatedAt } });
-          const query = `mutation Update_${m.table}($where: ${m.table}_bool_exp!, $set: ${m.table}_set_input!) {
+      }`, { object }, m.role, context.signal, "mutation");
+				const result = mutationRecord(m, descriptor.idField, data.item, descriptor.resource);
+				if (m.dataBody && dataBody) await upsertDataBody(m.dataBody, result.id, dataBody, m.role, context.signal);
+				return result;
+			},
+			async updateOne(descriptor, context) {
+				const m = mapping(descriptor.resource);
+				const fields = m.selectFields.join(" ");
+				const rawInput = descriptor.input;
+				let mainInput = rawInput;
+				let dataBody;
+				if (m.dataBody) {
+					const split = partitionDataBody(rawInput, m.dataBody);
+					mainInput = split.rest;
+					dataBody = split.hasDataBody ? split.dataBody : void 0;
+				}
+				const set = m.jsonbSpill ? partitionJsonbSpill(mainInput, m.jsonbSpill, m.selectFields) : mainInput;
+				const pkField = m.pkField ?? descriptor.idField;
+				const ifUpdatedAt = descriptor.providerOptions?.ifUpdatedAt;
+				let item;
+				if (Object.keys(set).length === 0) item = await readMutationRecord(m, descriptor.id, context.signal);
+				else if (m.fixedFilter || ifUpdatedAt != null) {
+					let where = mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter);
+					if (ifUpdatedAt != null) where = mergeWhere(where, { updated_at: { _eq: ifUpdatedAt } });
+					const data = await gql(`mutation Update_${m.table}($where: ${m.table}_bool_exp!, $set: ${m.table}_set_input!) {
           result: update_${m.table}(where: $where, _set: $set) { affected_rows returning { ${fields} } }
-        }`;
-          const data = await gql(
-            query,
-            { where, set },
-            m.role,
-            context.signal
-          );
-          if (ifUpdatedAt != null && ((data.result.affected_rows ?? 0) === 0 || (data.result.returning?.length ?? 0) === 0)) {
-            throw {
-              kind: "conflict",
-              code: "stale-record",
-              message: `Update for '${descriptor.resource}/${descriptor.id}' matched no row: the record was changed since it was loaded.`
-            };
-          }
-          item = data.result.returning?.[0] ?? null;
-        } else {
-          const pkType = m.pkType ?? "bigint";
-          const query = `mutation Update_${m.table}($id: ${pkType}!, $set: ${m.table}_set_input!) {
+        }`, {
+						where,
+						set
+					}, m.role, context.signal, "mutation");
+					if (ifUpdatedAt != null && ((data.result.affected_rows ?? 0) === 0 || (data.result.returning?.length ?? 0) === 0)) throw {
+						kind: "conflict",
+						code: "stale-record",
+						message: `Update for '${descriptor.resource}/${descriptor.id}' matched no row: the record was changed since it was loaded.`
+					};
+					item = data.result.returning?.[0] ?? null;
+				} else {
+					const pkType = m.pkType ?? "bigint";
+					item = (await gql(`mutation Update_${m.table}($id: ${pkType}!, $set: ${m.table}_set_input!) {
           item: update_${m.table}_by_pk(pk_columns: {${pkField}: $id}, _set: $set) { ${fields} }
-        }`;
-          const data = await gql(
-            query,
-            { id: descriptor.id, set },
-            m.role,
-            context.signal
-          );
-          item = data.item;
-        }
-        const result = mutationRecord(
-          m,
-          descriptor.idField,
-          item,
-          descriptor.resource,
-          descriptor.id
-        );
-        if (m.dataBody && dataBody)
-          await upsertDataBody(m.dataBody, result.id, dataBody, m.role, context.signal);
-        return result;
-      },
-      async deleteOne(descriptor, context) {
-        const m = mapping(descriptor.resource);
-        const fields = m.selectFields.join(" ");
-        const pkField = m.pkField ?? descriptor.idField;
-        let item;
-        if (m.fixedFilter) {
-          const where = mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter);
-          const query = `mutation Delete_${m.table}($where: ${m.table}_bool_exp!) {
+        }`, {
+						id: descriptor.id,
+						set
+					}, m.role, context.signal, "mutation")).item;
+				}
+				const result = mutationRecord(m, descriptor.idField, item, descriptor.resource, descriptor.id);
+				if (m.dataBody && dataBody) await upsertDataBody(m.dataBody, result.id, dataBody, m.role, context.signal);
+				return result;
+			},
+			async deleteOne(descriptor, context) {
+				const m = mapping(descriptor.resource);
+				const fields = m.selectFields.join(" ");
+				const pkField = m.pkField ?? descriptor.idField;
+				let item;
+				if (m.fixedFilter) {
+					const where = mergeWhere({ [pkField]: { _eq: descriptor.id } }, m.fixedFilter);
+					item = (await gql(`mutation Delete_${m.table}($where: ${m.table}_bool_exp!) {
           result: delete_${m.table}(where: $where) { affected_rows returning { ${fields} } }
-        }`;
-          const data = await gql(
-            query,
-            { where },
-            m.role,
-            context.signal
-          );
-          item = data.result.returning?.[0] ?? null;
-        } else {
-          const pkType = m.pkType ?? "bigint";
-          const query = `mutation Delete_${m.table}($id: ${pkType}!) {
+        }`, { where }, m.role, context.signal, "mutation")).result.returning?.[0] ?? null;
+				} else {
+					const pkType = m.pkType ?? "bigint";
+					item = (await gql(`mutation Delete_${m.table}($id: ${pkType}!) {
           item: delete_${m.table}_by_pk(${pkField}: $id) { ${fields} }
-        }`;
-          const data = await gql(
-            query,
-            { id: descriptor.id },
-            m.role,
-            context.signal
-          );
-          item = data.item;
-        }
-        mutationRecord(m, descriptor.idField, item, descriptor.resource, descriptor.id);
-        return { kind: "identity", id: descriptor.id };
-      },
-      ...hasCustomMutations ? {
-        async custom(descriptor, context) {
-          return executeCustomOperation(
-            descriptor.resource,
-            descriptor.operation,
-            descriptor.input,
-            "mutation",
-            context.signal
-          );
-        }
-      } : {}
-    },
-    live: createHasuraLiveProvider({
-      resources: config.resources,
-      getToken: config.getToken,
-      endpoint,
-      role: defaultRole
-    })
-  });
+        }`, { id: descriptor.id }, m.role, context.signal, "mutation")).item;
+				}
+				mutationRecord(m, descriptor.idField, item, descriptor.resource, descriptor.id);
+				return {
+					kind: "identity",
+					id: descriptor.id
+				};
+			},
+			...hasCustomMutations ? { async custom(descriptor, context) {
+				return executeCustomOperation(descriptor.resource, descriptor.operation, descriptor.input, "mutation", context.signal);
+			} } : {}
+		},
+		live: createHasuraLiveProvider({
+			resources: config.resources,
+			getToken: config.getToken,
+			endpoint,
+			role: defaultRole
+		})
+	});
 }
+//#endregion
+export { DEFAULT_HASURA_ENDPOINT, FILTER_OPERATOR_UNSUPPORTED_CODE, HASURA_CURSOR_CODES, HASURA_EXTERNAL_FAILURE_CODES, LOCALE_REQUIRED_CODE, NOT_AUTHENTICATED_CODE, aggregateRoot, assertCursorLimit, assertCursorOrderable, byPkRoot, coerceInt64Filter, createHasuraDataProvider, createHasuraLiveProvider, decodeCursor, effectiveCursorOrdering, encodeCursor, filtersToWhere, flattenJsonbSpill, hasuraWsUrl, keysetWhere, localeWhere, mergeWhere, orderingSignature, partitionDataBody, partitionJsonbSpill, scopeToWhere };
 
-export { DEFAULT_HASURA_ENDPOINT, FILTER_OPERATOR_UNSUPPORTED_CODE, NOT_AUTHENTICATED_CODE, aggregateRoot, byPkRoot, createHasuraDataProvider, createHasuraLiveProvider, filtersToWhere, flattenJsonbSpill, hasuraWsUrl, mergeWhere, partitionDataBody, partitionJsonbSpill, scopeToWhere };
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map