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

package/dist/index-VCqgn29D.d.ts

@@ -0,0 +1,278 @@
+import { K as TypeTag } from "./index-DVYFaXNV.js";
+import { R as RpcSelect, d as Expression, i as SelectArg, j as ArkivClient, k as Entity } from "./selection-fpmI3ADQ.js";
+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` `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.
+   */
+  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-VCqgn29D.d.ts.map

package/dist/index-VCqgn29D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-VCqgn29D.d.ts","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;EAuEgB;;;;;;;iBAlFpB;;;;;;;qBAWI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAuEJ,QAAQ,YAAY;;;;;;;;;GAqB3B,MAAA,CAAO,aAAA,KAAkB,eAAe"}