@arkiv-network/sdk 0.7.0-dev.1 → 0.8.0-dev.1

package/dist/queryBuilder-CbLL4pG5.js

@@ -0,0 +1,963 @@
+import { C as str, D as TYPE_IDS, c as asTypeTag, h as addr, l as decodeRpcValue, s as validateAttributeName, w as toValue } from "./attr-BDZ-APg5.js";
+import { n as encodeCreationFlags, t as decodeCreationFlags } from "./flags-ZtlvOIIk.js";
+import { t as Entity } from "./entity-BIp_df9u.js";
+import { checksumAddress, hexToBytes, numberToHex } from "viem";
+
+//#region src/utils/logger.ts
+const ROOT_NAMESPACE = "arkiv";
+function getDebugEnv() {
+	if (typeof process !== "undefined") {
+		const debugEnv = process?.env?.DEBUG;
+		if (debugEnv) return debugEnv;
+	}
+	if (typeof globalThis !== "undefined" && "localStorage" in globalThis) try {
+		return globalThis.localStorage?.getItem("DEBUG") || "";
+	} catch {}
+	return "";
+}
+function matchesPattern(namespace, pattern) {
+	if (pattern === namespace) return true;
+	if (pattern.endsWith("*")) {
+		const prefix = pattern.slice(0, -1);
+		return namespace.startsWith(prefix);
+	}
+	if (pattern.startsWith("-")) return !matchesPattern(namespace, pattern.slice(1));
+	return false;
+}
+function isEnabled(namespace) {
+	const debugEnv = getDebugEnv();
+	if (!debugEnv) return false;
+	const patterns = debugEnv.split(/[\s,]+/).filter((p) => p.length > 0);
+	if (patterns.length === 0) return false;
+	let enabled = false;
+	for (const pattern of patterns) if (pattern.startsWith("-")) {
+		if (matchesPattern(namespace, pattern)) return false;
+	} else if (matchesPattern(namespace, pattern)) enabled = true;
+	return enabled;
+}
+const enabledNamespaces = /* @__PURE__ */ new Set();
+const disabledNamespaces = /* @__PURE__ */ new Set();
+const COLOR_PALETTE = [
+	"#0000FF",
+	"#008000",
+	"#FF0000",
+	"#FF00FF",
+	"#FFA500",
+	"#800080",
+	"#00CED1",
+	"#FF1493",
+	"#32CD32",
+	"#1E90FF",
+	"#FF4500",
+	"#9370DB",
+	"#00FA9A",
+	"#FFD700",
+	"#DC143C",
+	"#00BFFF",
+	"#FF69B4",
+	"#20B2AA",
+	"#DA70D6",
+	"#4682B4"
+];
+const isNode = typeof process !== "undefined" && process.versions?.node != null;
+const ANSI_COLORS = [
+	"\x1B[94m",
+	"\x1B[92m",
+	"\x1B[91m",
+	"\x1B[95m",
+	"\x1B[93m",
+	"\x1B[96m",
+	"\x1B[35m",
+	"\x1B[36m",
+	"\x1B[32m",
+	"\x1B[34m",
+	"\x1B[33m",
+	"\x1B[31m",
+	"\x1B[90m",
+	"\x1B[37m",
+	"\x1B[1m"
+];
+const ANSI_RESET = "\x1B[0m";
+const ANSI_BOLD = "\x1B[1m";
+const namespaceColors = /* @__PURE__ */ new Map();
+function getColorForNamespace(namespace) {
+	const cachedColor = namespaceColors.get(namespace);
+	if (cachedColor) return cachedColor;
+	let hash = 0;
+	for (let i = 0; i < namespace.length; i++) {
+		const char = namespace.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	const colorIndex = Math.abs(hash) % COLOR_PALETTE.length;
+	const color = {
+		css: COLOR_PALETTE[colorIndex] ?? "inherit",
+		ansi: ANSI_COLORS[colorIndex % ANSI_COLORS.length] ?? ""
+	};
+	namespaceColors.set(namespace, color);
+	return color;
+}
+function createDebugLogger(namespace) {
+	const colors = getColorForNamespace(namespace);
+	return (...args) => {
+		const envEnabled = isEnabled(namespace);
+		const progEnabled = enabledNamespaces.has(namespace) && !disabledNamespaces.has(namespace);
+		if (envEnabled || progEnabled) if (isNode) {
+			const coloredNamespace = `${ANSI_BOLD}${colors.ansi}${namespace}${ANSI_RESET}`;
+			console.log(coloredNamespace, ...args);
+		} else {
+			const style1 = `color: ${colors.css}; font-weight: bold`;
+			console.log(`%c${namespace}%c`, style1, "color: inherit; font-weight: normal", ...args);
+		}
+	};
+}
+const getLogger = (scope) => {
+	return createDebugLogger(`${ROOT_NAMESPACE}:${scope}`);
+};
+
+//#endregion
+//#region src/errors.ts
+var EntityMutationError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "EntityMutationError";
+	}
+};
+var NoMoreResultsError = class extends Error {
+	constructor() {
+		super("No more results — the last page carried no cursor. Check hasNextPage() before next().");
+		this.name = "NoMoreResultsError";
+	}
+};
+var NoEntityFoundError = class extends Error {
+	/** The key that matched nothing, when the lookup was by key. */
+	entityKey;
+	constructor(entityKey) {
+		super(entityKey === void 0 ? "No entity found" : `No live entity with key ${entityKey}. It was never created, or it has been deleted or has expired.`);
+		this.name = "NoEntityFoundError";
+		this.entityKey = entityKey;
+	}
+};
+var EmptyPatchError = class extends Error {
+	entityKey;
+	constructor(entityKey) {
+		super(`The patch for entity ${entityKey} has nothing to apply. Pass "set" to write attributes, "unset" to remove them, or "payload"/"contentType" to replace the contents.`);
+		this.name = "EmptyPatchError";
+		this.entityKey = entityKey;
+	}
+};
+var InvalidContentTypeError = class extends Error {
+	constructor(contentType) {
+		super(`Invalid content type "${contentType}". Must follow RFC 2045 MIME grammar and be lowercase only (e.g. "text/plain").`);
+		this.name = "InvalidContentTypeError";
+	}
+};
+
+//#endregion
+//#region src/utils/entities.ts
+const logger$1 = getLogger("utils:entities");
+/**
+* Turns the attribute array a query returns into a name-keyed map of typed values.
+*
+* Attribute names are unique per entity, so the map loses nothing and gives callers
+* `entity.attributes.level.value` instead of a linear search.
+*/
+function decodeAttributes(rpcAttributes) {
+	const attributes = {};
+	for (const { name, type, value } of rpcAttributes) attributes[name] = decodeRpcValue(type, value);
+	return attributes;
+}
+/** The same, for the values-free `attributeSchema` projection. */
+function decodeSchema(entries) {
+	const schema = {};
+	for (const { name, type } of entries) schema[name] = asTypeTag(type);
+	return schema;
+}
+/**
+* Builds an {@link Entity} from a query result row.
+*
+* A field the query did not select is absent from the response and stays `undefined` here — the
+* decoder never substitutes an empty value for one that was not asked for.
+*/
+function entityFromRpcResult(rpcEntity) {
+	logger$1("entityFromRpcResult %o", rpcEntity);
+	return new Entity({
+		key: rpcEntity.key,
+		owner: toAddress(rpcEntity.owner),
+		creator: toAddress(rpcEntity.creator),
+		createdAt: toBlock(rpcEntity.createdAt),
+		updatedAt: toBlock(rpcEntity.updatedAt),
+		expiresAt: toBlock(rpcEntity.expiresAt),
+		creationFlags: decodeFlags(rpcEntity.creationFlags),
+		contentType: rpcEntity.contentType,
+		payload: rpcEntity.payload !== void 0 ? hexToBytes(rpcEntity.payload) : void 0,
+		attributeSchema: rpcEntity.attributeSchema !== void 0 ? decodeSchema(rpcEntity.attributeSchema) : void 0,
+		attributes: rpcEntity.attributes !== void 0 ? decodeAttributes(rpcEntity.attributes) : void 0
+	});
+}
+function toBlock(value) {
+	return value === void 0 ? void 0 : BigInt(value);
+}
+function toAddress(value) {
+	if (value === void 0) return void 0;
+	if (!/^0x[0-9a-fA-F]{40}$/.test(value)) {
+		logger$1("unreadable address %o", value);
+		return value;
+	}
+	return checksumAddress(value);
+}
+/**
+* Resolves the `creationFlags` projection, preferring the byte.
+*/
+function decodeFlags(value) {
+	if (value === void 0) return void 0;
+	const raw = toFlagsByte(typeof value === "number" ? value : value.raw);
+	if (raw !== void 0) return decodeCreationFlags(raw);
+	if (typeof value === "object" && (value.readonly ?? value.permissionlessExtension) !== void 0) return decodeCreationFlags(encodeCreationFlags({
+		readonly: value.readonly ?? false,
+		permissionlessExtension: value.permissionlessExtension ?? false
+	}));
+	logger$1("unreadable creationFlags %o", value);
+}
+/**
+* A flags byte in whichever spelling arrived: a JSON number, or the `0x` QUANTITY that every other
+* numeric field on {@link RpcEntity} already uses. `undefined` for anything that is not a byte.
+*/
+function toFlagsByte(value) {
+	const parsed = typeof value === "number" ? value : typeof value === "string" && /^(0x[0-9a-fA-F]+|\d+)$/.test(value) ? Number(value) : NaN;
+	return Number.isInteger(parsed) && parsed >= 0 && parsed <= 255 ? parsed : void 0;
+}
+
+//#endregion
+//#region src/query/errors.ts
+/**
+* A predicate asked for an operator the query language does not define for that type.
+*
+* The operator × type matrix is part of the language, not a policy: a range comparison on an
+* equality-only type is a **parse error** at the node, not an empty result. Catching it here turns
+* a round trip and an RPC error code into a stack trace pointing at the call site.
+*
+* | | `=` `!=` | `<` `<=` `>` `>=` | `STARTSWITH` |
+* | --- | --- | --- | --- |
+* | `bool` | yes | no | no |
+* | `i32` `u256` `dec` | yes | yes | no |
+* | `str` | yes | no | yes |
+* | `addr` `key` `bytes32` | yes | no | no |
+*/
+var UnsupportedOperatorError = class extends Error {
+	/** The attribute the predicate names. */
+	attributeName;
+	/** The operator, as it would have been written in the query. */
+	operator;
+	/** The type of the value it was applied to. */
+	tag;
+	constructor(attributeName, operator, tag, hint) {
+		super(`The query language does not define ${operator} for a ${tag}, so "${attributeName} ${operator} ..." cannot be expressed.${hint ? ` ${hint}` : ""}`);
+		this.name = "UnsupportedOperatorError";
+		this.attributeName = attributeName;
+		this.operator = operator;
+		this.tag = tag;
+	}
+};
+/**
+* A predicate could not be expressed in the query language for a reason other than its operator —
+* a system attribute that is returned in results but cannot be filtered on, a system attribute
+* compared against the wrong type, or a combinator with nothing to combine.
+*/
+var InvalidPredicateError = class extends Error {
+	/** The attribute the predicate names, where there is one. */
+	attributeName;
+	constructor(message, attributeName) {
+		super(message);
+		this.name = "InvalidPredicateError";
+		this.attributeName = attributeName;
+	}
+};
+/** The JSON-RPC error codes `arkiv_query` answers with, and what each one means. */
+const QUERY_ERROR_KINDS = {
+	[-32001]: "parse",
+	[-32002]: "type",
+	[-32003]: "literal",
+	[-32004]: "limits",
+	[-32005]: "cursor",
+	[-32006]: "block"
+};
+/**
+* The node rejected a query.
+*
+* These codes are part of the frozen `arkiv_query` surface, so {@link kind} and {@link data} are
+* stable enough to branch on — which the underlying JSON-RPC error is not, because the codes
+* overlap Ethereum's own EIP-1474 numbering and get wrapped accordingly on the way up.
+*
+* @example
+* try {
+*   await result.next()
+* } catch (error) {
+*   if (error instanceof QueryError && error.kind === "cursor") {
+*     // The page is gone — start the query over.
+*   }
+* }
+*/
+var QueryError = class extends Error {
+	/** Which failure this is. */
+	kind;
+	/** The JSON-RPC error code. */
+	code;
+	/** The machine-readable detail the node sent, if any — e.g. `{ position, expected, got }`. */
+	data;
+	/** The query string that was rejected. */
+	query;
+	constructor(kind, code, query, data, detail) {
+		super(`Query rejected (${kind}, ${code})${detail ? `: ${detail}` : ""}. Query: ${query}`, { cause: data });
+		this.name = "QueryError";
+		this.kind = kind;
+		this.code = code;
+		this.data = data;
+		this.query = query;
+	}
+};
+/**
+* Recognises an `arkiv_query` failure in whatever the transport threw.
+*
+* The codes are dug out of the error chain rather than read off the top: viem maps this range onto
+* its own EIP-1474 error classes (`-32001` is its "resource not found"), so by the time an error
+* surfaces the Arkiv meaning is one or more `cause` links down.
+*
+* @returns The typed error, or `undefined` if this was not a query rejection.
+*/
+function asQueryError(error, query) {
+	let code;
+	let data;
+	let detail;
+	let current = error;
+	for (let depth = 0; current != null && depth < 8; depth++) {
+		const link = current;
+		if (code === void 0 && typeof link.code === "number") code = link.code;
+		if (data === void 0 && link.data !== void 0) data = link.data;
+		if (detail === void 0 && typeof link.shortMessage === "string") detail = link.shortMessage;
+		current = link.cause;
+	}
+	const kind = code === void 0 ? void 0 : QUERY_ERROR_KINDS[code];
+	if (kind === void 0 || code === void 0) return void 0;
+	return new QueryError(kind, code, query, data, detail);
+}
+
+//#endregion
+//#region src/query/engine.ts
+const logger = getLogger("query:engine");
+const MAX_LIMIT = 200;
+/**
+* Runs one query and decodes the page it returns.
+*
+* @throws {QueryError} If the node rejects the query.
+*/
+async function runQuery(client, request) {
+	const { query, select, limit, cursor, atBlock } = request;
+	if (limit !== void 0) {
+		if (!Number.isInteger(limit) || limit < 1) throw new Error(`limit must be a positive integer, got ${limit}.`);
+		if (limit > MAX_LIMIT) throw new Error(`limit ${limit} exceeds the node maximum of ${MAX_LIMIT}. Page through the results with the cursor instead.`);
+	}
+	const queryOptions = {
+		select,
+		...atBlock !== void 0 && { atBlock: numberToHex(atBlock) },
+		...limit !== void 0 && { limit: numberToHex(limit) },
+		...cursor !== void 0 && { cursor }
+	};
+	logger("arkiv_query %s %o", query, queryOptions);
+	const result = await client.request({
+		method: "arkiv_query",
+		params: [query, queryOptions]
+	}).catch((error) => {
+		throw asQueryError(error, query) ?? error;
+	});
+	logger("Raw result from query %o", result);
+	return {
+		entities: result.data.map((rpcEntity) => entityFromRpcResult(rpcEntity)),
+		blockNumber: BigInt(result.blockNumber),
+		cursor: result.cursor
+	};
+}
+
+//#endregion
+//#region src/query/expression.ts
+/**
+* The system attributes a query may filter on, and the type each one carries.
+*
+* Every other system attribute (`$createdAt`, `$updatedAt`, `$creationFlags`, `$contentType`,
+* `$payload`) is returned in query results but is not indexed, so it cannot appear in a predicate.
+*/
+const QUERYABLE_SYSTEM_ATTRIBUTES = {
+	$key: "key",
+	$owner: "addr",
+	$creator: "addr",
+	$expiresAt: "u64"
+};
+/** System attributes a query can ask for but not filter on — they carry no index. */
+const RESULT_ONLY_SYSTEM_ATTRIBUTES = [
+	"$createdAt",
+	"$updatedAt",
+	"$creationFlags",
+	"$contentType",
+	"$payload"
+];
+/** The types that carry an ordered index, and so accept `<` `<=` `>` `>=`. */
+const ORDERED_TAGS = new Set([
+	"i32",
+	"u64",
+	"u256",
+	"dec"
+]);
+const RANGE_OPERATORS = new Set([
+	"<",
+	"<=",
+	">",
+	">="
+]);
+/**
+* Checks an attribute reference, returning its fixed type when it names a system attribute.
+*
+* User attribute names go through the same grammar the write path enforces, so a name that could
+* never have been written is rejected here rather than matching nothing.
+*/
+function resolveReference(name) {
+	if (typeof name !== "string" || !name.startsWith("$")) {
+		validateAttributeName(name);
+		return;
+	}
+	const system = QUERYABLE_SYSTEM_ATTRIBUTES[name];
+	if (system !== void 0) return system;
+	if (RESULT_ONLY_SYSTEM_ATTRIBUTES.includes(name)) throw new InvalidPredicateError(`"${name}" is returned in query results but carries no index, so it cannot be filtered on. Select it and filter the results in JavaScript instead.`, name);
+	throw new InvalidPredicateError(`"${name}" is not a system attribute. The queryable ones are ${Object.keys(QUERYABLE_SYSTEM_ATTRIBUTES).join(", ")}. "\$" is reserved for these, so a user attribute cannot be named this.`, name);
+}
+/**
+* Whether a string names a type a client may set. `bytes` is excluded: it backs `$payload`, which
+* is neither settable nor queryable.
+*
+* Takes a `string` rather than a `UserTypeTag` on purpose — the callers' static types already say
+* as much, and this is the runtime check for the code that has no types.
+*/
+function isUserTypeTag(tag) {
+	return Object.hasOwn(TYPE_IDS, tag) && tag !== "bytes";
+}
+/** Freezes a node and gives it a (non-enumerable, so still `toEqual`-able) rendering. */
+function node(value) {
+	Object.defineProperty(value, "toString", {
+		value: () => render(value),
+		enumerable: false
+	});
+	return Object.freeze(value);
+}
+function comparison(name, operator, input) {
+	const system = resolveReference(name);
+	const value = toValue(input, name);
+	if (system !== void 0 && value.type !== system) throw new InvalidPredicateError(`"${name}" is a ${system}, but the value is a ${value.type}. System attributes have a fixed type — write ${system}(...) around the value.`, name);
+	if (RANGE_OPERATORS.has(operator) && !ORDERED_TAGS.has(value.type)) throw new UnsupportedOperatorError(name, operator, value.type, `Only i32, u64, u256 and dec carry an ordered index; ${value.type} is equality-only.`);
+	return node({
+		kind: "comparison",
+		name,
+		operator,
+		value
+	});
+}
+/**
+* Attribute equals value — set with this exact type, and holding this value.
+*
+* Bare booleans, numbers, bigints and strings take the same default types they take when written
+* (`number` is an `i32`, `bigint` a `u256`, `string` a `str`); anything else names its type.
+*
+* @throws {InvalidPredicateError} If the name is not a queryable attribute, or a system attribute
+* is compared against the wrong type.
+*
+* @example
+* eq("status", str("open"))     // status = str('open')
+* eq("flagged", true)           // flagged = true
+* eq("$owner", addr(account))   // $owner = addr(0xd8dA…)
+*/
+function eq(name, value) {
+	return comparison(name, "=", value);
+}
+/**
+* Attribute is set with this type and holds a **different** value.
+*
+* This is typed value-negation, not the complement: an entity that never set the attribute, or set
+* it with another type, does not match. Use `not(eq(...))` for the full complement.
+*
+* @example
+* ne("status", str("closed"))          // status != str('closed')
+* not(eq("status", str("closed")))     // NOT status = str('closed') — also matches entities with no status
+*/
+function ne(name, value) {
+	return comparison(name, "!=", value);
+}
+/**
+* Attribute is greater than value. Ordered types only (`i32`, `u256`, `dec`).
+*
+* @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
+*
+* @example
+* gt("level", i32(10))              // level > i32(10)
+* gt("$expiresAt", u64(1_200_000n)) // $expiresAt > u64(1200000)
+*/
+function gt(name, value) {
+	return comparison(name, ">", value);
+}
+/**
+* Attribute is greater than or equal to value. Ordered types only (`i32`, `u256`, `dec`).
+*
+* @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
+*
+* @example
+* gte("score", dec("3.5")) // score >= dec(3.5)
+*/
+function gte(name, value) {
+	return comparison(name, ">=", value);
+}
+/**
+* Attribute is less than value. Ordered types only (`i32`, `u256`, `dec`).
+*
+* @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
+*
+* @example
+* lt("level", i32(10)) // level < i32(10)
+*/
+function lt(name, value) {
+	return comparison(name, "<", value);
+}
+/**
+* Attribute is less than or equal to value. Ordered types only (`i32`, `u256`, `dec`).
+*
+* @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
+*
+* @example
+* lte("score", dec("5")) // score <= dec(5)
+*/
+function lte(name, value) {
+	return comparison(name, "<=", value);
+}
+/**
+* Attribute is a `str` beginning with this prefix.
+*
+* The match is on **raw UTF-8 bytes** with no normalization — it is the index encoding, so
+* `startsWith("name", "é")` matches only the same byte sequence, not another normal form of it.
+*
+* @param prefix - The prefix, as a bare string or a `str` value.
+* @throws {UnsupportedOperatorError} If given a value that is not a `str`.
+*
+* @example
+* startsWith("desc", "ab") // desc STARTSWITH str('ab')
+*/
+function startsWith(name, prefix) {
+	const system = resolveReference(name);
+	const value = typeof prefix === "string" ? str(prefix) : toValue(prefix, name);
+	if (value.type !== "str") throw new UnsupportedOperatorError(name, "STARTSWITH", value.type, "Only str carries a prefix index.");
+	if (system !== void 0) throw new UnsupportedOperatorError(name, "STARTSWITH", system, "No queryable system attribute is a str.");
+	return node({
+		kind: "startsWith",
+		name,
+		value
+	});
+}
+/**
+* The attribute is set, with any type.
+*
+* @throws {InvalidPredicateError} If given a system attribute — every entity has all of them, so
+* the test would be a constant.
+*
+* @example
+* exists("reviewedBy")        // EXISTS(reviewedBy)
+* not(exists("closedAt"))     // NOT EXISTS(closedAt)
+*/
+function exists(name) {
+	if (resolveReference(name) !== void 0) throw new InvalidPredicateError(`"${name}" is a system attribute, so it is set on every entity and EXISTS(${name}) is always true.`, name);
+	return node({
+		kind: "exists",
+		name
+	});
+}
+/**
+* The attribute is set with exactly this type, whatever its value.
+*
+* Useful when the same name is written with different types across entities — a comparison already
+* asserts the type, so this is for asking about the type alone.
+*
+* @param tag - The type tag: `bool`, `i32`, `u256`, `dec`, `bytes32`, `str`, `addr` or `key`.
+* @throws {InvalidPredicateError} If the tag is not a settable type, or the name is a system
+* attribute (whose type is fixed).
+*
+* @example
+* hasType("age", "i32") // TYPEOF(age) = i32
+*/
+function hasType(name, tag) {
+	const system = resolveReference(name);
+	if (system !== void 0) throw new InvalidPredicateError(`"${name}" is always a ${system} — a system attribute has a fixed type, so TYPEOF(${name}) is a constant.`, name);
+	if (!isUserTypeTag(tag)) throw new InvalidPredicateError(`"${tag}" is not a settable attribute type. Use one of bool, i32, u256, dec, bytes32, str, addr, key.`, name);
+	return node({
+		kind: "typeOf",
+		name,
+		tag
+	});
+}
+/**
+* The complement of an expression, evaluated against the set of live entities — unlike `!=`, it
+* matches entities that never set the attribute at all.
+*
+* @example
+* not(exists("closedAt"))            // NOT EXISTS(closedAt)
+* not(and(eq("a", 1), eq("b", 2)))   // NOT (a = i32(1) AND b = i32(2))
+*/
+function not(expression) {
+	return node({
+		kind: "not",
+		expression
+	});
+}
+function and(...expressions) {
+	return combine("and", expressions.flat());
+}
+function or(...expressions) {
+	return combine("or", expressions.flat());
+}
+function combine(kind, expressions) {
+	if (expressions.length === 0) throw new InvalidPredicateError(`${kind}() needs at least one expression. An empty ${kind === "and" ? "conjunction" : "disjunction"} has no query-language spelling — leave the ${kind}() out, or omit the filter entirely to match everything.`);
+	const only = expressions[0];
+	if (expressions.length === 1 && only !== void 0) return only;
+	return node(kind === "and" ? {
+		kind: "and",
+		expressions: Object.freeze(expressions)
+	} : {
+		kind: "or",
+		expressions: Object.freeze(expressions)
+	});
+}
+/**
+* Binding strength, tightest last — `NOT` binds tighter than `AND`, which binds tighter than `OR`.
+* A leaf never needs parentheses, so it sits above them all.
+*/
+const PRECEDENCE = {
+	or: 1,
+	and: 2,
+	not: 3,
+	leaf: 4
+};
+function precedenceOf(expression) {
+	switch (expression.kind) {
+		case "or": return PRECEDENCE.or;
+		case "and": return PRECEDENCE.and;
+		case "not": return PRECEDENCE.not;
+		default: return PRECEDENCE.leaf;
+	}
+}
+/** Renders a subexpression, parenthesising it only where the precedence would otherwise change it. */
+function nested(expression, minimum) {
+	const rendered = render(expression);
+	return precedenceOf(expression) < minimum ? `(${rendered})` : rendered;
+}
+/**
+* Renders an expression as the query string the node parses. Equivalent to `String(expression)`.
+*
+* Literals are always written tagged, even where the language would infer them: an untagged number
+* defaults to `i32`, but spelling it `i32(10)` keeps the exact-type assertion visible in the query
+* that actually went over the wire.
+*/
+function render(expression) {
+	switch (expression.kind) {
+		case "comparison": return `${expression.name} ${expression.operator} ${renderLiteral(expression.value)}`;
+		case "startsWith": return `${expression.name} STARTSWITH ${renderLiteral(expression.value)}`;
+		case "exists": return `EXISTS(${expression.name})`;
+		case "typeOf": return `TYPEOF(${expression.name}) = ${expression.tag}`;
+		case "not": return `NOT ${nested(expression.expression, PRECEDENCE.not)}`;
+		case "and": return expression.expressions.map((sub) => nested(sub, PRECEDENCE.and)).join(" AND ");
+		case "or": return expression.expressions.map((sub) => nested(sub, PRECEDENCE.or)).join(" OR ");
+	}
+}
+/** Renders a typed value as its query literal. `bool` is the one type written bare. */
+function renderLiteral(value) {
+	switch (value.type) {
+		case "bool": return value.value ? "true" : "false";
+		case "i32": return `i32(${value.value})`;
+		case "u64": return `u64(${value.value})`;
+		case "u256": return `u256(${value.value})`;
+		case "dec": return `dec(${value.value})`;
+		case "bytes32": return `bytes32(${value.value})`;
+		case "key": return `key(${value.value})`;
+		case "addr": return `addr(${value.value})`;
+		case "str": return `str('${value.value.replaceAll("'", "''")}')`;
+	}
+}
+
+//#endregion
+//#region src/query/selection.ts
+/** The selection keys, in the order they are written into the RPC `select` object. */
+const SELECTION_KEYS = [
+	"key",
+	"owner",
+	"creator",
+	"createdAt",
+	"updatedAt",
+	"expiresAt",
+	"creationFlags",
+	"contentType",
+	"payload",
+	"attributeSchema",
+	"attributes"
+];
+/**
+* Converts a {@link SelectArg} into the RPC `select` object.
+*
+* Every field is opt-in — anything not explicitly selected is sent as `false`, including the key.
+* Sending the full object rather than omitting the `false`s keeps what the SDK asked for legible in
+* a request log, and pins the answer even if a node's defaults change.
+*
+* `undefined` or `"*"` selects everything.
+*
+* @throws If the selection asks for nothing.
+*
+* @example
+* toRpcSelect()                    // everything
+* toRpcSelect({ key: true })       // only the key
+* toRpcSelect({ attributes: { projectId: true } })  // one named attribute
+*/
+function toRpcSelect(selection) {
+	if (selection === void 0 || selection === "*") return Object.fromEntries(SELECTION_KEYS.map((field) => [field, true]));
+	const select = {};
+	let any = false;
+	for (const field of SELECTION_KEYS) {
+		const value = selection[field];
+		if (field === "attributes" && typeof value === "object" && value !== null) {
+			const names = Object.entries(value).filter(([, wanted]) => wanted);
+			for (const [name] of names) validateAttributeName(name);
+			select.attributes = names.length > 0 ? Object.fromEntries(names) : false;
+			any ||= names.length > 0;
+			continue;
+		}
+		select[field] = value === true;
+		any ||= value === true;
+	}
+	if (!any) throw new Error("select() requires at least one field to be selected. Pass select() or select(\"*\") to select everything.");
+	return select;
+}
+
+//#endregion
+//#region src/query/queryResult.ts
+/**
+* One page of query results.
+*
+* A page is immutable: {@link next} returns the following page rather than mutating this one, so a
+* page that has been read stays readable.
+*
+* @typeParam TEntity - The shape of each entity, inferred from the selection by `client.select()`.
+*
+* @example
+* let page = await client.select({ key: true }).where(eq("category", "docs")).limit(100).fetch()
+* while (page.hasNextPage()) {
+*   page = await page.next()
+* }
+*/
+var QueryResult = class {
+	/** The entities on this page. */
+	entities;
+	/**
+	* The block this page was read at.
+	*
+	* Every page of one walk reads the same block — the cursor is bound to it — so results cannot
+	* shift under a paginating reader.
+	*/
+	blockNumber;
+	/** The cursor for the next page, or `undefined` when this was the last one. */
+	cursor;
+	fetchPage;
+	constructor(entities, blockNumber, cursor, fetchPage$1) {
+		this.entities = entities;
+		this.blockNumber = blockNumber;
+		this.cursor = cursor;
+		this.fetchPage = fetchPage$1;
+	}
+	/**
+	* Whether another page follows.
+	*
+	* The node omits the cursor once nothing remains, so this is an answer rather than the guess a
+	* short final page would be — a full last page is reported correctly.
+	*/
+	hasNextPage() {
+		return this.cursor !== void 0;
+	}
+	/**
+	* Fetches the next page.
+	*
+	* @throws {NoMoreResultsError} If this was the last page — check {@link hasNextPage} first.
+	* @throws {QueryError} If the node rejects the request; `kind === "cursor"` means the cursor
+	* expired and the walk has to start again.
+	*/
+	async next() {
+		if (this.cursor === void 0) throw new NoMoreResultsError();
+		return this.fetchPage(this.cursor);
+	}
+};
+
+//#endregion
+//#region src/query/queryBuilder.ts
+/**
+* Builds and runs a query.
+*
+* The selection is fixed when the builder is created and the filter is added by chaining, so the
+* result type is known before a single predicate is written. Create one with `client.select(...)`
+* rather than constructing it directly — that is what infers the entity shape from the selection.
+*
+* Every filter added with {@link where}, {@link ownedBy} and {@link createdBy} must hold; use
+* {@link or} for alternatives inside one call.
+*
+* @typeParam TEntity - The projected entity shape, inferred from the selection by `client.select()`.
+*
+* @example
+* import { createPublicClient } from "@arkiv-network/sdk"
+* import { i32 } from "@arkiv-network/sdk/attr"
+* import { cheesecake } from "@arkiv-network/sdk/chains"
+* import { eq, gte, or } from "@arkiv-network/sdk/query"
+* import { http } from "viem"
+*
+* const client = createPublicClient({ chain: cheesecake, transport: http() })
+*
+* const page = await client
+*   .select({ key: true, attributes: true })
+*   .where(gte("level", i32(10)), or(eq("status", "open"), eq("status", "review")))
+*   .ownedBy(owner)
+*   .limit(100)
+*   .fetch()
+*
+* for (const entity of page.entities) console.log(entity.key, entity.attributes)
+*/
+var SelectQueryBuilder = class {
+	_client;
+	_select;
+	_filters = [];
+	_ownedBy;
+	_createdBy;
+	_limit;
+	_cursor;
+	_atBlock;
+	constructor(client, selection) {
+		this._client = client;
+		this._select = toRpcSelect(selection);
+	}
+	where(...expressions) {
+		this._filters.push(...expressions.flat());
+		return this;
+	}
+	/**
+	* Restricts the results to entities this account owns — shorthand for
+	* `where(eq("$owner", addr(owner)))`. Calling it again replaces the filter.
+	*
+	* @example
+	* builder.ownedBy("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+	*/
+	ownedBy(owner) {
+		this._ownedBy = eq("$owner", addr(owner));
+		return this;
+	}
+	/**
+	* Restricts the results to entities this account created — shorthand for
+	* `where(eq("$creator", addr(creator)))`. Calling it again replaces the filter.
+	*
+	* The creator never changes; the owner does, so these differ after a transfer.
+	*/
+	createdBy(creator) {
+		this._createdBy = eq("$creator", addr(creator));
+		return this;
+	}
+	/**
+	* Sets the page size, up to the node maximum of 200. Without it the node picks the page size.
+	*
+	* @example
+	* builder.limit(100)
+	*/
+	limit(limit) {
+		this._limit = limit;
+		return this;
+	}
+	/**
+	* Starts from a cursor returned by an earlier page.
+	*
+	* Pagination normally goes through {@link QueryResult.next}, which carries the cursor for you;
+	* this is for resuming a walk in a later process. A cursor is bound to the query, block and
+	* selection it came from, so it must be used with an identically-built query.
+	*/
+	cursor(cursor) {
+		this._cursor = cursor;
+		return this;
+	}
+	/**
+	* Reads the state as of a given block rather than the head. The block must be within the range
+	* the node retains.
+	*
+	* @example
+	* builder.atBlock(1_297_000n)
+	*/
+	atBlock(block) {
+		this._atBlock = block;
+		return this;
+	}
+	/**
+	* The query string this builder will send — the same text the node parses.
+	*
+	* @throws {InvalidPredicateError} If no filter has been added.
+	*/
+	toString() {
+		const filters = [...this._filters];
+		if (this._ownedBy) filters.push(this._ownedBy);
+		if (this._createdBy) filters.push(this._createdBy);
+		if (filters.length === 0) throw new InvalidPredicateError("A query needs at least one filter — the language has no spelling for 'match every entity\". Add a where(...) predicate, or narrow by ownedBy(...) / createdBy(...).");
+		return and(filters).toString();
+	}
+	/**
+	* Runs the query and returns the first page.
+	*
+	* @throws {InvalidPredicateError} If no filter has been added.
+	* @throws {QueryError} If the node rejects the query.
+	*
+	* @example
+	* const page = await client.select({ key: true }).where(eq("category", "docs")).fetch()
+	* page.entities        // this page
+	* await page.next()    // the next one
+	*/
+	async fetch() {
+		const request = Object.freeze({
+			query: this.toString(),
+			select: this._select,
+			limit: this._limit,
+			atBlock: this._atBlock
+		});
+		return fetchPage(this._client, request, this._cursor);
+	}
+	/**
+	* Walks every page, yielding one entity at a time.
+	*
+	* @example
+	* for await (const entity of client.select({ key: true }).where(eq("category", "docs"))) {
+	*   console.log(entity.key)
+	* }
+	*/
+	async *[Symbol.asyncIterator]() {
+		let page = await this.fetch();
+		while (page) {
+			yield* page.entities;
+			page = page.hasNextPage() ? await page.next() : void 0;
+		}
+	}
+};
+/**
+* Fetches one page and wires up the next.
+*
+* Free-standing rather than a method: a page holds this closure for its lifetime, and closing over
+* a frozen request keeps the builder — and everything it references — out of that reference.
+*/
+async function fetchPage(client, request, cursor) {
+	const response = await runQuery(client, {
+		...request,
+		cursor
+	});
+	return new QueryResult(response.entities, response.blockNumber, response.cursor, (next) => fetchPage(client, request, next));
+}
+
+//#endregion
+export { EntityMutationError as C, getLogger as D, NoMoreResultsError as E, EmptyPatchError as S, NoEntityFoundError as T, MAX_LIMIT as _, eq as a, QueryError as b, gte as c, lte as d, ne as f, startsWith as g, render as h, and as i, hasType as l, or as m, QueryResult as n, exists as o, not as p, toRpcSelect as r, gt as s, SelectQueryBuilder as t, lt as u, runQuery as v, InvalidContentTypeError as w, UnsupportedOperatorError as x, InvalidPredicateError as y };
+//# sourceMappingURL=queryBuilder-CbLL4pG5.js.map