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

package/dist/queryBuilder-BXDvX1K_.cjs

@@ -0,0 +1,1123 @@
+const require_attr = require('./attr-BvxHN99W.cjs');
+const require_flags = require('./flags-Ct8k0gpB.cjs');
+const require_entity = require('./entity-B0t6sN7F.cjs');
+let viem = require("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] = require_attr.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] = require_attr.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 require_entity.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 ? (0, viem.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 (0, viem.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 require_flags.decodeCreationFlags(raw);
+	if (typeof value === "object" && (value.readonly ?? value.permissionlessExtension) !== void 0) return require_flags.decodeCreationFlags(require_flags.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: (0, viem.numberToHex)(atBlock) },
+		...limit !== void 0 && { limit: (0, viem.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("$")) {
+		require_attr.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(require_attr.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 = require_attr.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" ? require_attr.str(prefix) : require_attr.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) require_attr.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", require_attr.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", require_attr.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
+Object.defineProperty(exports, 'EmptyPatchError', {
+  enumerable: true,
+  get: function () {
+    return EmptyPatchError;
+  }
+});
+Object.defineProperty(exports, 'EntityMutationError', {
+  enumerable: true,
+  get: function () {
+    return EntityMutationError;
+  }
+});
+Object.defineProperty(exports, 'InvalidContentTypeError', {
+  enumerable: true,
+  get: function () {
+    return InvalidContentTypeError;
+  }
+});
+Object.defineProperty(exports, 'InvalidPredicateError', {
+  enumerable: true,
+  get: function () {
+    return InvalidPredicateError;
+  }
+});
+Object.defineProperty(exports, 'MAX_LIMIT', {
+  enumerable: true,
+  get: function () {
+    return MAX_LIMIT;
+  }
+});
+Object.defineProperty(exports, 'NoEntityFoundError', {
+  enumerable: true,
+  get: function () {
+    return NoEntityFoundError;
+  }
+});
+Object.defineProperty(exports, 'NoMoreResultsError', {
+  enumerable: true,
+  get: function () {
+    return NoMoreResultsError;
+  }
+});
+Object.defineProperty(exports, 'QueryError', {
+  enumerable: true,
+  get: function () {
+    return QueryError;
+  }
+});
+Object.defineProperty(exports, 'QueryResult', {
+  enumerable: true,
+  get: function () {
+    return QueryResult;
+  }
+});
+Object.defineProperty(exports, 'SelectQueryBuilder', {
+  enumerable: true,
+  get: function () {
+    return SelectQueryBuilder;
+  }
+});
+Object.defineProperty(exports, 'UnsupportedOperatorError', {
+  enumerable: true,
+  get: function () {
+    return UnsupportedOperatorError;
+  }
+});
+Object.defineProperty(exports, 'and', {
+  enumerable: true,
+  get: function () {
+    return and;
+  }
+});
+Object.defineProperty(exports, 'eq', {
+  enumerable: true,
+  get: function () {
+    return eq;
+  }
+});
+Object.defineProperty(exports, 'exists', {
+  enumerable: true,
+  get: function () {
+    return exists;
+  }
+});
+Object.defineProperty(exports, 'getLogger', {
+  enumerable: true,
+  get: function () {
+    return getLogger;
+  }
+});
+Object.defineProperty(exports, 'gt', {
+  enumerable: true,
+  get: function () {
+    return gt;
+  }
+});
+Object.defineProperty(exports, 'gte', {
+  enumerable: true,
+  get: function () {
+    return gte;
+  }
+});
+Object.defineProperty(exports, 'hasType', {
+  enumerable: true,
+  get: function () {
+    return hasType;
+  }
+});
+Object.defineProperty(exports, 'lt', {
+  enumerable: true,
+  get: function () {
+    return lt;
+  }
+});
+Object.defineProperty(exports, 'lte', {
+  enumerable: true,
+  get: function () {
+    return lte;
+  }
+});
+Object.defineProperty(exports, 'ne', {
+  enumerable: true,
+  get: function () {
+    return ne;
+  }
+});
+Object.defineProperty(exports, 'not', {
+  enumerable: true,
+  get: function () {
+    return not;
+  }
+});
+Object.defineProperty(exports, 'or', {
+  enumerable: true,
+  get: function () {
+    return or;
+  }
+});
+Object.defineProperty(exports, 'render', {
+  enumerable: true,
+  get: function () {
+    return render;
+  }
+});
+Object.defineProperty(exports, 'runQuery', {
+  enumerable: true,
+  get: function () {
+    return runQuery;
+  }
+});
+Object.defineProperty(exports, 'startsWith', {
+  enumerable: true,
+  get: function () {
+    return startsWith;
+  }
+});
+Object.defineProperty(exports, 'toRpcSelect', {
+  enumerable: true,
+  get: function () {
+    return toRpcSelect;
+  }
+});