@arkiv-network/sdk 0.7.0 → 0.8.0-advanced.3

package/dist/expiry-xr6mx4f7.cjs

@@ -0,0 +1,135 @@
+const require_errors = require('./errors-51znTSB1.cjs');
+
+//#region src/consts.ts
+const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044";
+const BLOCK_TIME = 2;
+
+//#endregion
+//#region src/entity/params.ts
+/**
+* Max uint64 value
+*/
+const MAX_EXPIRES_AT = 2n ** 64n - 1n;
+/** The operation tags of the `execute` ABI's tagged union. */
+const OperationType = {
+	Create: 1,
+	Patch: 2,
+	ExtendExpiry: 3,
+	TransferOwnership: 4,
+	Delete: 5
+};
+
+//#endregion
+//#region src/entity/expiry.ts
+/**
+* Builds a branded {@link Expiry}.
+*
+* Internal seam for {@link ExpirationTime}, which is the only thing that should call it — it is not
+* part of the package's public surface.
+*/
+function makeExpiry(minLifetime, expiresAt) {
+	return {
+		minLifetime,
+		expiresAt
+	};
+}
+/**
+* Resolves an expiry into the wire pair and the block the entity will expire at.
+*
+* Durations are converted to blocks at the nominal `BLOCK_TIME` (2 seconds), which makes them
+* **approximate**: block production is not a clock, so a lifetime asked for in days drifts if the
+* chain runs fast or slow. The block it was converted to comes back as
+* {@link ResolvedExpiry.target}, so the approximation is always observable rather than assumed.
+*
+* @throws {InvalidExpiryError} If the expiry is malformed, does not fit the `uint64` the wire
+* carries, or would leave the entity dead on arrival.
+*/
+function resolveExpiry(expiry, context) {
+	const { currentBlock } = context;
+	if (typeof expiry?.minLifetime !== "bigint" || expiry.expiresAt === void 0) throw new require_errors.InvalidExpiryError("expires must be built with ExpirationTime, e.g. ExpirationTime.fromDays(30) or ExpirationTime.atBlock(1_200_000n)");
+	const { minLifetime } = expiry;
+	const absolute = typeof expiry.expiresAt === "bigint" ? expiry.expiresAt : blockAtDate(expiry.expiresAt, currentBlock);
+	if (minLifetime === 0n && absolute === 0n) throw new require_errors.InvalidExpiryError("no expiry given. Pass ExpirationTime.fromDays(30) for a lifetime, ExpirationTime.atBlock(n) for an absolute deadline, or a deadline with { atLeast } to take whichever is later.");
+	if (absolute > MAX_EXPIRES_AT) throw new require_errors.InvalidExpiryError(`expiresAt resolves to block ${absolute}, which does not fit the uint64 the wire carries (max ${MAX_EXPIRES_AT}). Use ExpirationTime.permanent() for an entity that should not expire.`);
+	if (minLifetime > MAX_EXPIRES_AT) throw new require_errors.InvalidExpiryError(`the lifetime is ${minLifetime} blocks, which does not fit the uint64 the wire carries (max ${MAX_EXPIRES_AT})`);
+	const relative = minLifetime === 0n ? 0n : currentBlock + minLifetime;
+	const target = absolute > relative ? absolute : relative;
+	if (target <= currentBlock) throw new require_errors.InvalidExpiryError(`the entity would expire at block ${target}, which is not after the current block ${currentBlock}, so it would be dead on arrival`);
+	if (target > MAX_EXPIRES_AT) throw new require_errors.InvalidExpiryError(`a lifetime of ${minLifetime} blocks from block ${currentBlock} lands at ${target}, past the largest expiry the wire carries (${MAX_EXPIRES_AT})`);
+	return {
+		expiresAt: absolute,
+		minLifetime,
+		target
+	};
+}
+/**
+* A duration in seconds as a whole number of blocks.
+*
+* Arkiv counts lifetimes in blocks, so a duration that is not a whole number of them does not
+* describe anything the chain can store. Rather than silently round a caller's `3` up to two blocks
+* — four seconds, not what they asked for — this rejects it: a duration must be a positive multiple
+* of `BLOCK_TIME` (2 seconds). The {@link ExpirationTime} helpers all produce such multiples.
+*
+* @throws {InvalidExpiryError} If the duration is not a positive whole number of blocks' seconds.
+*/
+function toBlocks(seconds) {
+	if (!Number.isInteger(seconds) || seconds <= 0) throw new require_errors.InvalidExpiryError(`a lifetime must be a positive whole number of seconds, got ${seconds}. Use the ExpirationTime helpers, e.g. ExpirationTime.fromDays(30).`);
+	if (seconds % BLOCK_TIME !== 0) throw new require_errors.InvalidExpiryError(`a lifetime must be a multiple of the ${BLOCK_TIME}s block time, got ${seconds}, which is ${seconds / BLOCK_TIME} blocks. Try ${seconds - seconds % BLOCK_TIME} or ${seconds + BLOCK_TIME - seconds % BLOCK_TIME}, or ExpirationTime.fromBlocks(n).`);
+	return BigInt(seconds / BLOCK_TIME);
+}
+/**
+* The block a wall-clock instant lands on.
+*
+* Rounds **up**: a date almost never falls on a block boundary, and unlike a duration — which the
+* caller states and can state exactly — there is nothing here to reject, so the entity lives until
+* at least the instant asked for.
+*/
+function blockAtDate(date, currentBlock) {
+	const secondsAway = (date.getTime() - Date.now()) / 1e3;
+	if (secondsAway <= 0) throw new require_errors.InvalidExpiryError(`the deadline ${date.toISOString()} is in the past, so the entity would be dead on arrival`);
+	return currentBlock + BigInt(Math.ceil(secondsAway / BLOCK_TIME));
+}
+
+//#endregion
+Object.defineProperty(exports, 'ARKIV_ADDRESS', {
+  enumerable: true,
+  get: function () {
+    return ARKIV_ADDRESS;
+  }
+});
+Object.defineProperty(exports, 'BLOCK_TIME', {
+  enumerable: true,
+  get: function () {
+    return BLOCK_TIME;
+  }
+});
+Object.defineProperty(exports, 'MAX_EXPIRES_AT', {
+  enumerable: true,
+  get: function () {
+    return MAX_EXPIRES_AT;
+  }
+});
+Object.defineProperty(exports, 'OperationType', {
+  enumerable: true,
+  get: function () {
+    return OperationType;
+  }
+});
+Object.defineProperty(exports, 'makeExpiry', {
+  enumerable: true,
+  get: function () {
+    return makeExpiry;
+  }
+});
+Object.defineProperty(exports, 'resolveExpiry', {
+  enumerable: true,
+  get: function () {
+    return resolveExpiry;
+  }
+});
+Object.defineProperty(exports, 'toBlocks', {
+  enumerable: true,
+  get: function () {
+    return toBlocks;
+  }
+});

package/dist/flags-5dTNRnow.d.ts

@@ -0,0 +1,41 @@
+//#region src/entity/flags.d.ts
+/**
+ * The immutable properties an entity is created with. Both default to `false`.
+ *
+ * Creation flags are fixed at creation: there is no operation that changes them, so an entity is
+ * whatever it was created as for its whole life.
+ */
+type CreationFlags = {
+  /**
+   * The entity's attributes and payload can never be changed — only its expiry extended, its
+   * ownership transferred, and the entity deleted.
+   */
+  readonly?: boolean;
+  /**
+   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something
+   * alive without being able to change it.
+   */
+  permissionlessExtension?: boolean;
+};
+/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */
+type ResolvedCreationFlags = {
+  readonly: boolean;
+  permissionlessExtension: boolean;
+  raw: number;
+};
+/**
+ * Packs creation flags into the `creationFlags` byte.
+ *
+ * @throws {InvalidCreationFlagsError} If a value is not a boolean.
+ */
+declare function encodeCreationFlags(flags?: CreationFlags): number;
+/**
+ * Reads the `creationFlags` byte back.
+ *
+ * @param raw - The `creationFlags` byte.
+ * @throws {InvalidCreationFlagsError} Malformed input
+ */
+declare function decodeCreationFlags(raw: number): ResolvedCreationFlags;
+//#endregion
+export { encodeCreationFlags as i, ResolvedCreationFlags as n, decodeCreationFlags as r, CreationFlags as t };
+//# sourceMappingURL=flags-5dTNRnow.d.ts.map

package/dist/flags-5dTNRnow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-5dTNRnow.d.ts","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":[],"mappings":";;AAYA;AAcA;AAWA;AAkBA;;KA3CY,aAAA;;;;;;;;;;;;;KAcA,qBAAA;;;;;;;;;;iBAWI,mBAAA,SAA2B;;;;;;;iBAkB3B,mBAAA,eAAkC"}

package/dist/flags-Bh0HJldY.cjs

@@ -0,0 +1,43 @@
+const require_errors = require('./errors-51znTSB1.cjs');
+
+//#region src/entity/flags.ts
+/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */
+const READONLY_BIT = 1;
+const PERMISSIONLESS_EXTENSION_BIT = 2;
+/**
+* Packs creation flags into the `creationFlags` byte.
+*
+* @throws {InvalidCreationFlagsError} If a value is not a boolean.
+*/
+function encodeCreationFlags(flags = {}) {
+	for (const [name, value] of Object.entries(flags)) if (value !== void 0 && typeof value !== "boolean") throw new require_errors.InvalidCreationFlagsError(`"${name}" must be a boolean, got ${typeof value}`);
+	return (flags.readonly ? READONLY_BIT : 0) | (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0);
+}
+/**
+* Reads the `creationFlags` byte back.
+*
+* @param raw - The `creationFlags` byte.
+* @throws {InvalidCreationFlagsError} Malformed input
+*/
+function decodeCreationFlags(raw) {
+	if (!Number.isInteger(raw) || raw < 0 || raw > 255) throw new require_errors.InvalidCreationFlagsError(`${raw} is not a byte`);
+	return {
+		readonly: (raw & READONLY_BIT) !== 0,
+		permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,
+		raw
+	};
+}
+
+//#endregion
+Object.defineProperty(exports, 'decodeCreationFlags', {
+  enumerable: true,
+  get: function () {
+    return decodeCreationFlags;
+  }
+});
+Object.defineProperty(exports, 'encodeCreationFlags', {
+  enumerable: true,
+  get: function () {
+    return encodeCreationFlags;
+  }
+});

package/dist/flags-CRjPpoh3.d.cts

@@ -0,0 +1,41 @@
+//#region src/entity/flags.d.ts
+/**
+ * The immutable properties an entity is created with. Both default to `false`.
+ *
+ * Creation flags are fixed at creation: there is no operation that changes them, so an entity is
+ * whatever it was created as for its whole life.
+ */
+type CreationFlags = {
+  /**
+   * The entity's attributes and payload can never be changed — only its expiry extended, its
+   * ownership transferred, and the entity deleted.
+   */
+  readonly?: boolean;
+  /**
+   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something
+   * alive without being able to change it.
+   */
+  permissionlessExtension?: boolean;
+};
+/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */
+type ResolvedCreationFlags = {
+  readonly: boolean;
+  permissionlessExtension: boolean;
+  raw: number;
+};
+/**
+ * Packs creation flags into the `creationFlags` byte.
+ *
+ * @throws {InvalidCreationFlagsError} If a value is not a boolean.
+ */
+declare function encodeCreationFlags(flags?: CreationFlags): number;
+/**
+ * Reads the `creationFlags` byte back.
+ *
+ * @param raw - The `creationFlags` byte.
+ * @throws {InvalidCreationFlagsError} Malformed input
+ */
+declare function decodeCreationFlags(raw: number): ResolvedCreationFlags;
+//#endregion
+export { encodeCreationFlags as i, ResolvedCreationFlags as n, decodeCreationFlags as r, CreationFlags as t };
+//# sourceMappingURL=flags-CRjPpoh3.d.cts.map

package/dist/flags-CRjPpoh3.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-CRjPpoh3.d.cts","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":[],"mappings":";;AAYA;AAcA;AAWA;AAkBA;;KA3CY,aAAA;;;;;;;;;;;;;KAcA,qBAAA;;;;;;;;;;iBAWI,mBAAA,SAA2B;;;;;;;iBAkB3B,mBAAA,eAAkC"}

package/dist/flags-Cr76ldwF.js

@@ -0,0 +1,33 @@
+import { t as InvalidCreationFlagsError } from "./errors-CwPJ16bn.js";
+
+//#region src/entity/flags.ts
+/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */
+const READONLY_BIT = 1;
+const PERMISSIONLESS_EXTENSION_BIT = 2;
+/**
+* Packs creation flags into the `creationFlags` byte.
+*
+* @throws {InvalidCreationFlagsError} If a value is not a boolean.
+*/
+function encodeCreationFlags(flags = {}) {
+	for (const [name, value] of Object.entries(flags)) if (value !== void 0 && typeof value !== "boolean") throw new InvalidCreationFlagsError(`"${name}" must be a boolean, got ${typeof value}`);
+	return (flags.readonly ? READONLY_BIT : 0) | (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0);
+}
+/**
+* Reads the `creationFlags` byte back.
+*
+* @param raw - The `creationFlags` byte.
+* @throws {InvalidCreationFlagsError} Malformed input
+*/
+function decodeCreationFlags(raw) {
+	if (!Number.isInteger(raw) || raw < 0 || raw > 255) throw new InvalidCreationFlagsError(`${raw} is not a byte`);
+	return {
+		readonly: (raw & READONLY_BIT) !== 0,
+		permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,
+		raw
+	};
+}
+
+//#endregion
+export { encodeCreationFlags as n, decodeCreationFlags as t };
+//# sourceMappingURL=flags-Cr76ldwF.js.map

package/dist/flags-Cr76ldwF.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-Cr76ldwF.js","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":["import { InvalidCreationFlagsError } from \"./errors\"\n\n/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */\nconst READONLY_BIT = 0b0000_0001\nconst PERMISSIONLESS_EXTENSION_BIT = 0b0000_0010\n\n/**\n * The immutable properties an entity is created with. Both default to `false`.\n *\n * Creation flags are fixed at creation: there is no operation that changes them, so an entity is\n * whatever it was created as for its whole life.\n */\nexport type CreationFlags = {\n  /**\n   * The entity's attributes and payload can never be changed — only its expiry extended, its\n   * ownership transferred, and the entity deleted.\n   */\n  readonly?: boolean\n  /**\n   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something\n   * alive without being able to change it.\n   */\n  permissionlessExtension?: boolean\n}\n\n/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */\nexport type ResolvedCreationFlags = {\n  readonly: boolean\n  permissionlessExtension: boolean\n  raw: number\n}\n\n/**\n * Packs creation flags into the `creationFlags` byte.\n *\n * @throws {InvalidCreationFlagsError} If a value is not a boolean.\n */\nexport function encodeCreationFlags(flags: CreationFlags = {}): number {\n  for (const [name, value] of Object.entries(flags)) {\n    if (value !== undefined && typeof value !== \"boolean\") {\n      throw new InvalidCreationFlagsError(`\"${name}\" must be a boolean, got ${typeof value}`)\n    }\n  }\n  return (\n    (flags.readonly ? READONLY_BIT : 0) |\n    (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0)\n  )\n}\n\n/**\n * Reads the `creationFlags` byte back.\n *\n * @param raw - The `creationFlags` byte.\n * @throws {InvalidCreationFlagsError} Malformed input\n */\nexport function decodeCreationFlags(raw: number): ResolvedCreationFlags {\n  if (!Number.isInteger(raw) || raw < 0 || raw > 0xff) {\n    throw new InvalidCreationFlagsError(`${raw} is not a byte`)\n  }\n  return {\n    readonly: (raw & READONLY_BIT) !== 0,\n    permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,\n    raw,\n  }\n}\n"],"mappings":";;;;AAGA,MAAM,eAAe;AACrB,MAAM,+BAA+B;;;;;;AAiCrC,SAAgB,oBAAoB,QAAuB,EAAE,EAAU;AACrE,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,MAAM,CAC/C,KAAI,UAAU,UAAa,OAAO,UAAU,UAC1C,OAAM,IAAI,0BAA0B,IAAI,KAAK,2BAA2B,OAAO,QAAQ;AAG3F,SACG,MAAM,WAAW,eAAe,MAChC,MAAM,0BAA0B,+BAA+B;;;;;;;;AAUpE,SAAgB,oBAAoB,KAAoC;AACtE,KAAI,CAAC,OAAO,UAAU,IAAI,IAAI,MAAM,KAAK,MAAM,IAC7C,OAAM,IAAI,0BAA0B,GAAG,IAAI,gBAAgB;AAE7D,QAAO;EACL,WAAW,MAAM,kBAAkB;EACnC,0BAA0B,MAAM,kCAAkC;EAClE;EACD"}

package/dist/index-CMeD8uEq.d.cts

@@ -0,0 +1,280 @@
+import { R as RpcSelect, i as SelectArg, j as ArkivClient, p as Expression, s as Entity } from "./selection-C6KeWJ7g.cjs";
+import { K as TypeTag } from "./index-NbfnXxgr.cjs";
+import { Hex } from "viem";
+
+//#region src/query/engine.d.ts
+declare const MAX_LIMIT = 200;
+/** One `arkiv_query` call. */
+type QueryRequest = {
+  /** The query expression, already rendered. */
+  query: string;
+  /** What to return. */
+  select: RpcSelect;
+  /** Page size, up to {@link MAX_LIMIT}. Defaults to the node's own page size. */
+  limit?: number | undefined;
+  /** Cursor from a previous page. */
+  cursor?: string | undefined;
+  /** Block height to read at. Defaults to the head. */
+  atBlock?: bigint | undefined;
+};
+/** One page of results. */
+type QueryResponse = {
+  entities: Entity[];
+  /** The block the page was read at — the same for every page of a paginated query. */
+  blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  cursor: string | undefined;
+};
+/**
+ * Runs one query and decodes the page it returns.
+ *
+ * @throws {QueryError} If the node rejects the query.
+ */
+declare function runQuery(client: ArkivClient, request: QueryRequest): Promise<QueryResponse>;
+//#endregion
+//#region src/query/errors.d.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` `u64` `u256` `dec` | yes | yes | no |
+ * | `str` | yes | no | yes |
+ * | `addr` `key` `bytes32` | yes | no | no |
+ */
+declare class UnsupportedOperatorError extends Error {
+  /** The attribute the predicate names. */
+  readonly attributeName: string;
+  /** The operator, as it would have been written in the query. */
+  readonly operator: string;
+  /** The type of the value it was applied to. */
+  readonly tag: TypeTag;
+  constructor(attributeName: string, operator: string, tag: TypeTag, hint?: string);
+}
+/**
+ * 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.
+ */
+declare class InvalidPredicateError extends Error {
+  /** The attribute the predicate names, where there is one. */
+  readonly attributeName: string | undefined;
+  constructor(message: string, attributeName?: string);
+}
+/**
+ * What a node rejected a query for. Part of the frozen RPC surface, so it is safe to branch on —
+ * a `"cursor"` failure means start the query again, a `"block"` failure means the node no longer
+ * retains that height, and the rest mean the query itself needs fixing.
+ */
+type QueryErrorKind = /** The query string does not parse. `data` locates it: `{ position, expected, got }`. */
+"parse"
+/** A predicate is well-formed but ill-typed — a range operator on an equality-only type, an unknown tag. */ | "type"
+/** A literal failed validation — an `i32` out of range, a bad EIP-55 checksum, more than 18 decimal places. */ | "literal"
+/** A node budget was exceeded — query length, predicate count, nesting depth, bitmap operations. */ | "limits"
+/** The cursor expired, is malformed, or belongs to a different query, block or selection. */ | "cursor"
+/** `atBlock` is outside the range the node retains. */ | "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.
+ *   }
+ * }
+ */
+declare class QueryError extends Error {
+  /** Which failure this is. */
+  readonly kind: QueryErrorKind;
+  /** The JSON-RPC error code. */
+  readonly code: number;
+  /** The machine-readable detail the node sent, if any — e.g. `{ position, expected, got }`. */
+  readonly data: unknown;
+  /** The query string that was rejected. */
+  readonly query: string;
+  constructor(kind: QueryErrorKind, code: number, query: string, data: unknown, detail?: string);
+}
+//#endregion
+//#region src/query/queryResult.d.ts
+/** Fetches the page a cursor points at. */
+type FetchPage<TEntity> = (cursor: string) => Promise<QueryResult<TEntity>>;
+/**
+ * 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()
+ * }
+ */
+declare class QueryResult<TEntity = Entity> {
+  /** The entities on this page. */
+  readonly entities: readonly TEntity[];
+  /**
+   * 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.
+   */
+  readonly blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  readonly cursor: string | undefined;
+  private readonly fetchPage;
+  constructor(entities: readonly TEntity[], blockNumber: bigint, cursor: string | undefined, fetchPage: FetchPage<TEntity>);
+  /**
+   * 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(): boolean;
+  /**
+   * 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.
+   */
+  next(): Promise<QueryResult<TEntity>>;
+}
+//#endregion
+//#region src/query/queryBuilder.d.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)
+ */
+declare class SelectQueryBuilder<TEntity = Entity> {
+  private readonly _client;
+  private readonly _select;
+  private readonly _filters;
+  private _ownedBy;
+  private _createdBy;
+  private _limit;
+  private _cursor;
+  private _atBlock;
+  constructor(client: ArkivClient, selection?: SelectArg);
+  /**
+   * Adds filters. Everything passed here, and across repeated calls, must hold.
+   *
+   * @param expressions - The expressions, as separate arguments or one array.
+   *
+   * @example
+   * builder.where(eq("category", "docs"))
+   * builder.where(gte("level", i32(10)), lt("level", i32(20)))
+   * builder.where(or(eq("status", "open"), not(exists("closedAt"))))
+   */
+  where(expressions: readonly Expression[]): this;
+  where(...expressions: Expression[]): 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: Hex): 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: Hex): 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: number): 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 — {@link atBlock}
+   * set to the `blockNumber` of the page the cursor came from is required (persist the two
+   * together), and a fetch with a cursor but no block rejects locally.
+   */
+  cursor(cursor: string): 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: bigint): this;
+  /**
+   * The query string this builder will send — the same text the node parses.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added.
+   */
+  toString(): string;
+  /**
+   * 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
+   */
+  fetch(): Promise<QueryResult<TEntity>>;
+  /**
+   * 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)
+   * }
+   */
+  [Symbol.asyncIterator](): AsyncGenerator<TEntity>;
+}
+//#endregion
+export { QueryErrorKind as a, QueryRequest as c, QueryError as i, QueryResponse as l, QueryResult as n, UnsupportedOperatorError as o, InvalidPredicateError as r, MAX_LIMIT as s, SelectQueryBuilder as t, runQuery as u };
+//# sourceMappingURL=index-CMeD8uEq.d.cts.map

package/dist/index-CMeD8uEq.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CMeD8uEq.d.cts","names":[],"sources":["../src/query/engine.ts","../src/query/errors.ts","../src/query/queryResult.ts","../src/query/queryBuilder.ts"],"sourcesContent":[],"mappings":";;;;;cAUa,SAAA;;AAAA,KAGD,YAAA,GAHU;EAGV;EAcA,KAAA,EAAA,MAAA;EAaU;EAAiB,MAAA,EAvB7B,SAuB6B;EAAsB;EAAuB,KAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAR;EAAO,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;;;ACxBnF;AAMgB,KDKJ,aAAA,GCLI;EAE4C,QAAA,EDIhD,MCJgD,EAAA;EARd;EAAK,WAAA,EAAA,MAAA;EAyBtC;EAgBD,MAAA,EAAA,MAAA,GAAc,SAAA;AAwC1B,CAAA;;;;;;iBDzDsB,QAAA,SAAiB,sBAAsB,eAAe,QAAQ;;;;;;;AA9BpF;AAGA;AAcA;AAaA;;;;;;;cCxBa,wBAAA,SAAiC,KAAA;;EAAjC,SAAA,aAAA,EAAA,MAAyB;EAMtB;EAE4C,SAAA,QAAA,EAAA,MAAA;EARd;EAAK,SAAA,GAAA,EAMnC,OANmC;EAyBtC,WAAA,CAAA,aAAsB,EAAA,MAAA,EAAA,QAAa,EAAA,MAAA,EAAA,GAAA,EAjBY,OAiBZ,EAAA,IAAA,CAAA,EAAA,MAAA;AAgBhD;AAwCA;;;;;cAxDa,qBAAA,SAA8B,KAAA;;;ECrCtC,WAAA,CAAS,OAAA,EAAA,MAAA,EAAA,aAAA,CAAA,EAAA,MAAA;;;;;AAgBd;;AAE8B,KDmClB,cAAA;;+GCSwB;kHAApB;;;ACzBhB,0DAA0C,OAAA;;;;;;;;;;;;;;;;;cFwD7B,UAAA,SAAmB,KAAA;;iBAEf;;;;;;;oBAQG;;;;;KCvGf,yCAAyC,QAAQ,YAAY;;;AFMlE;AAGA;AAcA;AAaA;;;;;;;;;ACxBa,cCIA,WDJyB,CAAA,UCIH,MDJG,CAAA,CAAA;EAMtB;EAE4C,SAAA,QAAA,EAAA,SCF9B,ODE8B,EAAA;EARd;;AAyB9C;AAgBA;AAwCA;;EAUoB,SAAA,WAAA,EAAA,MAAA;EAVY;EAAK,SAAA,MAAA,EAAA,MAAA,GAAA,SAAA;;iCC7Dd,uEAGR,UAAU;;AAtCoB;;;;;EAmBhC,WAAA,CAAA,CAAA,EAAW,OAAA;EAAW;;;;;;;EA8CnB,IAAA,CAAA,CAAA,EAAA,OAAA,CAAQ,WAAR,CAAoB,OAApB,CAAA,CAAA;;;;AFrDhB;AAcA;AAaA;;;;;;;;;ACxBA;;;;;AAyBA;AAgBA;AAwCA;;;;;;;;AChG6C;;;;AAGQ,cCqCxC,kBDrCwC,CAAA,UCqCX,MDrCW,CAAA,CAAA;EAgBxC,iBAAW,OAAA;EAAW,iBAAA,OAAA;EAEL,iBAAA,QAAA;EAcP,QAAA,QAAA;EAGE,QAAA,UAAA;EAAV,QAAA,MAAA;EA2BqB,QAAA,OAAA;EAAZ,QAAA,QAAA;EAAR,WAAA,CAAA,MAAA,ECfM,WDeN,EAAA,SAAA,CAAA,ECf+B,SDe/B;EAAO;;;;ACzBvB;;;;;;EAuCiB,KAAA,CAAA,WAAA,EAAA,SAda,UAcb,EAAA,CAAA,EAAA,IAAA;EAWI,KAAA,CAAA,GAAA,WAAA,EAxBG,UAwBH,EAAA,CAAA,EAAA,IAAA;EAyEgB;;;;;;;iBApFpB;;;;;;;qBAWI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAyEJ,QAAQ,YAAY;;;;;;;;;GAqB3B,MAAA,CAAO,aAAA,KAAkB,eAAe"}