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

package/src/query/queryResult.ts

@@ -1,70 +1,73 @@
-import { NoCursorOrLimitError, NoMoreResultsError } from "../errors"
+import { NoMoreResultsError } from "../errors"
 import type { Entity } from "../types/entity"
-import { getLogger } from "../utils/logger"
-import type { BaseQueryBuilder } from "./queryBuilder"
 
-const logger = getLogger("query:result")
+/** Fetches the page a cursor points at. */
+type FetchPage<TEntity> = (cursor: string) => Promise<QueryResult<TEntity>>
 
 /**
- * The result of a query. Holds the fetched entities and supports cursor-based pagination.
+ * One page of query results.
  *
- * @typeParam TEntity - The shape of each entity, inferred from the query builder
- *   (a full {@link Entity}, or a projected object inferred from a `select()` selection).
+ * 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()
+ * }
  */
 export class QueryResult<TEntity = Entity> {
-  entities: TEntity[]
-  private _endOfIteration: boolean
-  private _cursor: string | undefined
-  private _limit: number | undefined
-  private _validAtBlock: bigint | undefined
-  private _queryBuilder: BaseQueryBuilder<TEntity>
-
-  // Public getters for internal state
-  get queryBuilder(): BaseQueryBuilder<TEntity> {
-    return this._queryBuilder
-  }
+  /** 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
 
-  get cursor(): string | undefined {
-    return this._cursor
-  }
+  private readonly fetchPage: FetchPage<TEntity>
 
   constructor(
-    entities: TEntity[],
-    queryBuilder: BaseQueryBuilder<TEntity>,
+    entities: readonly TEntity[],
+    blockNumber: bigint,
     cursor: string | undefined,
-    limit: number | undefined,
-    validAtBlock: bigint | undefined,
+    fetchPage: FetchPage<TEntity>,
   ) {
     this.entities = entities
-    this._queryBuilder = queryBuilder
-    this._endOfIteration = !limit || entities.length < limit
-    this._cursor = cursor
-    this._limit = limit
-    this._validAtBlock = validAtBlock
+    this.blockNumber = blockNumber
+    this.cursor = cursor
+    this.fetchPage = fetchPage
   }
 
-  async next() {
-    if (this._cursor === undefined || this._limit === undefined) {
-      throw new NoCursorOrLimitError()
-    }
-    if (this._endOfIteration) {
-      throw new NoMoreResultsError()
-    }
-    this._queryBuilder.cursor(this._cursor)
-    const result = await this._queryBuilder.fetch()
-    this.entities = result.entities
-    // Update the query builder reference
-    this._queryBuilder = result.queryBuilder
-    // Check if we've reached the end (no more cursor or we got fewer entities than limit)
-    this._endOfIteration = !result.cursor || result.entities.length < this._limit
-    // Update the cursor
-    this._cursor = result.cursor
-
-    // TODO check current block height and if it is not too old
-    logger("Current block height for next page %s", this._validAtBlock?.toString() ?? "unknown")
+  /**
+   * 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 {
+    return this.cursor !== undefined
   }
 
-  hasNextPage() {
-    return !this._endOfIteration
+  /**
+   * 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 so that "no more pages" arrives as a rejection like every other failure here, rather
+  // than as a synchronous throw the caller's `.catch` would miss.
+  async next(): Promise<QueryResult<TEntity>> {
+    if (this.cursor === undefined) {
+      throw new NoMoreResultsError()
+    }
+    return this.fetchPage(this.cursor)
   }
 }

package/src/query/selection.test.ts

@@ -1,120 +1,70 @@
-import { describe, expect, test } from "bun:test"
-import { selectionToIncludeData } from "./selection"
+import { describe, expect, it } from "bun:test"
+import { toRpcSelect } from "./selection"
 
-const ALL = {
+const EVERY_FIELD = {
   key: true,
-  attributes: true,
-  payload: true,
-  contentType: true,
-  expiration: true,
   owner: true,
   creator: true,
-  createdAtBlock: true,
-  lastModifiedAtBlock: true,
-  transactionIndexInBlock: true,
-  operationIndexInTransaction: true,
-}
-
-const EMPTY = {
-  key: false,
-  attributes: false,
-  payload: false,
-  contentType: false,
-  expiration: false,
-  owner: false,
-  creator: false,
-  createdAtBlock: false,
-  lastModifiedAtBlock: false,
-  transactionIndexInBlock: false,
-  operationIndexInTransaction: false,
+  createdAt: true,
+  updatedAt: true,
+  expiresAt: true,
+  creationFlags: true,
+  contentType: true,
+  payload: true,
+  attributeSchema: true,
+  attributes: true,
 }
 
-describe("selectionToIncludeData", () => {
-  test("select() with no argument selects everything", () => {
-    expect(selectionToIncludeData()).toEqual(ALL)
-  })
-
-  test('select("*") selects everything', () => {
-    expect(selectionToIncludeData("*")).toEqual(ALL)
-  })
-
-  test("empty object throws", () => {
-    // @ts-expect-error – select requires at least one field
-    expect(() => selectionToIncludeData({})).toThrow()
-  })
-
-  test("an all-false selection throws (no field is actually selected)", () => {
-    expect(() => selectionToIncludeData({ key: false })).toThrow()
-    expect(() => selectionToIncludeData({ owner: false, payload: false })).toThrow()
-  })
-
-  test("key: true selects only the key", () => {
-    expect(selectionToIncludeData({ key: true })).toEqual({ ...EMPTY, key: true })
+describe("toRpcSelect", () => {
+  it("selects everything for no argument or a star", () => {
+    expect(toRpcSelect()).toEqual(EVERY_FIELD)
+    expect(toRpcSelect("*")).toEqual(EVERY_FIELD)
   })
 
-  test("key is opt-in like every other field", () => {
-    expect(selectionToIncludeData({ key: true }).key).toBe(true)
-    expect(selectionToIncludeData({ attributes: true }).key).toBe(false)
-    expect(selectionToIncludeData({ owner: true }).key).toBe(false)
-  })
-
-  test("attributes only (no key)", () => {
-    expect(selectionToIncludeData({ attributes: true })).toEqual({
-      ...EMPTY,
-      attributes: true,
-    })
-  })
-
-  test("payload only (no key)", () => {
-    expect(selectionToIncludeData({ payload: true })).toEqual({
-      ...EMPTY,
-      payload: true,
-    })
-  })
-
-  test("a single metadata field, selected flat (no key)", () => {
-    expect(selectionToIncludeData({ owner: true })).toEqual({
-      ...EMPTY,
+  it("sends every field, so what was asked for is legible in the request", () => {
+    // The node defaults everything but `key` to off. Spelling out the false ones costs nothing and
+    // pins the answer even if those defaults move.
+    expect(toRpcSelect({ owner: true })).toEqual({
+      key: false,
       owner: true,
+      creator: false,
+      createdAt: false,
+      updatedAt: false,
+      expiresAt: false,
+      creationFlags: false,
+      contentType: false,
+      payload: false,
+      attributeSchema: false,
+      attributes: false,
     })
   })
 
-  test("expiresAtBlock maps to the RPC `expiration` field", () => {
-    expect(selectionToIncludeData({ expiresAtBlock: true })).toEqual({
-      ...EMPTY,
-      expiration: true,
+  it("passes a named attribute subset through", () => {
+    expect(
+      toRpcSelect({ key: true, attributes: { projectId: true, version: true } }),
+    ).toMatchObject({
+      key: true,
+      attributes: { projectId: true, version: true },
     })
   })
 
-  test("several fields selected together", () => {
+  it("drops names the subset turned off, and falls back to false when none are left", () => {
     expect(
-      selectionToIncludeData({
-        owner: true,
-        creator: true,
-        createdAtBlock: true,
-        attributes: true,
-      }),
-    ).toEqual({
-      ...EMPTY,
-      owner: true,
-      creator: true,
-      createdAtBlock: true,
-      attributes: true,
-    })
+      toRpcSelect({ key: true, attributes: { projectId: true, version: false } }),
+    ).toMatchObject({ attributes: { projectId: true } })
+    // An empty subset asks for no attributes, which is what `false` already means.
+    expect(toRpcSelect({ key: true, attributes: {} })).toMatchObject({ attributes: false })
   })
 
-  test("key can be combined with other fields", () => {
-    expect(selectionToIncludeData({ key: true, attributes: true })).toEqual({
-      ...EMPTY,
-      key: true,
-      attributes: true,
-    })
+  it("rejects a selection that asks for nothing", () => {
+    // @ts-expect-error - AtLeastOne rejects this at compile time too
+    expect(() => toRpcSelect({})).toThrow(/at least one field/)
+    // The type system permits an explicit `false`; the node would answer it with empty rows.
+    expect(() => toRpcSelect({ key: false })).toThrow(/at least one field/)
+    expect(() => toRpcSelect({ key: false, attributes: {} })).toThrow(/at least one field/)
   })
 
-  test("a field set to false is not selected", () => {
-    expect(selectionToIncludeData({ owner: true, creator: false })).toEqual({
-      ...EMPTY,
-      owner: true,
-    })
+  it("counts a named attribute subset as a selection in its own right", () => {
+    expect(() => toRpcSelect({ attributes: { projectId: true } })).not.toThrow()
   })
 })

package/src/query/selection.ts

@@ -1,25 +1,42 @@
+import { validateAttributeName } from "../attr"
 import type { Entity } from "../types/entity"
-import type { RpcIncludeData } from "../types/rpcSchema"
-
-/** The entity fields that can be selected. These match the fields of {@link Entity} one-to-one. */
-type DataKey =
-  | "key"
-  | "contentType"
-  | "owner"
-  | "creator"
-  | "expiresAtBlock"
-  | "createdAtBlock"
-  | "lastModifiedAtBlock"
-  | "transactionIndexInBlock"
-  | "operationIndexInTransaction"
-  | "attributes"
-  | "payload"
+import type { RpcSelect } from "../types/rpcSchema"
 
 /**
- * The parts of an entity that can be selected. Every field is opt-in (including the `key`) and maps
- * directly to a field of the returned {@link Entity} — the selection is flat.
+ * The entity fields a query can select. Each maps one-to-one onto a field of {@link Entity}.
+ *
+ * `attributes` takes a third form beyond `true`/`false`: a map of names, to fetch only those.
  */
-export type SelectionFields = { [K in DataKey]?: boolean }
+export type SelectionFields = {
+  key?: boolean
+  owner?: boolean
+  creator?: boolean
+  createdAt?: boolean
+  updatedAt?: boolean
+  expiresAt?: boolean
+  creationFlags?: boolean
+  contentType?: boolean
+  payload?: boolean
+  /** Attribute names and types, without their values. */
+  attributeSchema?: boolean
+  /** `true` for every attribute, or a map of names for a subset. */
+  attributes?: boolean | Readonly<Record<string, boolean>>
+}
+
+/** 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",
+] as const satisfies readonly (keyof SelectionFields)[]
 
 /**
  * Requires at least one property of `T` to be present.
@@ -38,79 +55,74 @@ export type EntitySelection = AtLeastOne<SelectionFields>
 /** Argument accepted by `select()` — a non-empty {@link EntitySelection}, or `"*"` for everything. */
 export type SelectArg = EntitySelection | "*"
 
+/** Whether a selection value asks for the field: `true`, or a non-empty map of attribute names. */
+type Selected<V> = V extends false | undefined ? false : true
+
 /**
  * The result of a selection `S`: an {@link Entity} narrowed to exactly the selected fields (each
- * non-`undefined`). The shape is flat and backwards compatible — e.g. `select({ owner: true })`
- * yields `{ owner: Hex }` accessed as `entity.owner`. Accessing an unselected field is a compile
- * error.
+ * non-`undefined`). The shape is flat — `select({ owner: true })` yields `{ owner: Hex }`, read as
+ * `entity.owner`. Accessing an unselected field is a compile error.
  *
- * The `toText()` / `toJson()` helpers operate on the payload, so they are only present when
- * `payload` was selected — calling them otherwise would always throw.
+ * `toText()` / `toJson()` operate on the payload, so they appear only when `payload` was selected —
+ * calling them otherwise would always throw.
  */
 export type ProjectedEntity<S> = {
-  readonly [K in keyof S as S[K] extends true ? K : never]: K extends keyof Entity
+  readonly [K in keyof S as Selected<S[K]> extends true ? K : never]: K extends keyof Entity
     ? NonNullable<Entity[K]>
     : never
 } & (S extends { payload: true } ? Pick<Entity, "toText" | "toJson"> : unknown)
 
 /** A selection of every field, used to type the result of `select()` / `select("*")`. */
-type AllSelected = { [K in DataKey]: true }
+type AllSelected = { [K in (typeof SELECTION_KEYS)[number]]: true }
 
 /** The projected entity type when everything is selected — every field, plus the methods. */
 export type FullEntity = ProjectedEntity<AllSelected>
 
 /**
- * Converts a {@link SelectArg} into the {@link RpcIncludeData} understood by the query engine.
- * Every field is opt-in — anything not explicitly selected defaults to `false`, including the key.
+ * 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.
  *
- * @param selection - The selection to convert
- * @returns The fully-resolved include-data object for the RPC query
- * @throws If an empty selection object is provided
+ * @throws If the selection asks for nothing.
  *
  * @example
- * selectionToIncludeData() // everything
- * selectionToIncludeData("*") // everything
- * selectionToIncludeData({ key: true }) // only the key
- * selectionToIncludeData({ owner: true }) // only the owner
+ * toRpcSelect()                    // everything
+ * toRpcSelect({ key: true })       // only the key
+ * toRpcSelect({ attributes: { projectId: true } })  // one named attribute
  */
-export function selectionToIncludeData(selection?: SelectArg): RpcIncludeData {
+export function toRpcSelect(selection?: SelectArg): RpcSelect {
   if (selection === undefined || selection === "*") {
-    return {
-      key: true,
-      attributes: true,
-      payload: true,
-      contentType: true,
-      expiration: true,
-      owner: true,
-      creator: true,
-      createdAtBlock: true,
-      lastModifiedAtBlock: true,
-      transactionIndexInBlock: true,
-      operationIndexInTransaction: true,
+    return Object.fromEntries(SELECTION_KEYS.map((field) => [field, true])) as RpcSelect
+  }
+
+  const select: RpcSelect = {}
+  let any = false
+  for (const field of SELECTION_KEYS) {
+    const value = selection[field]
+    if (field === "attributes" && typeof value === "object" && value !== null) {
+      // A named subset. An empty map asks for no attributes at all, which is what `false` means.
+      const names = Object.entries(value).filter(([, wanted]) => wanted)
+      // Checked rather than forwarded: a name outside the grammar cannot exist on any entity, so
+      // asking for one is a typo that would otherwise come back as a silently absent attribute.
+      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
   }
 
-  // At least one field must be opted in. This rejects both `{}` and selections whose fields are
-  // all explicitly `false` (e.g. `select({ key: false })`), which the type system permits.
-  if (!Object.values(selection).some((selected) => selected === true)) {
+  // Rejects both `{}` and a selection whose fields are all explicitly `false` — the type system
+  // permits `select({ key: false })`, and the node would answer it with a page of empty objects.
+  if (!any) {
     throw new Error(
       'select() requires at least one field to be selected. Pass select() or select("*") to select everything.',
     )
   }
-
-  return {
-    key: selection.key ?? false,
-    attributes: selection.attributes ?? false,
-    payload: selection.payload ?? false,
-    contentType: selection.contentType ?? false,
-    // The selection uses the entity field name `expiresAtBlock`; the RPC calls it `expiration`.
-    expiration: selection.expiresAtBlock ?? false,
-    owner: selection.owner ?? false,
-    creator: selection.creator ?? false,
-    createdAtBlock: selection.createdAtBlock ?? false,
-    lastModifiedAtBlock: selection.lastModifiedAtBlock ?? false,
-    transactionIndexInBlock: selection.transactionIndexInBlock ?? false,
-    operationIndexInTransaction: selection.operationIndexInTransaction ?? false,
-  }
+  return select
 }