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

package/src/query/queryBuilder.test.ts

@@ -1,685 +1,390 @@
-import { afterEach, beforeEach, describe, expect, jest, test } from "bun:test"
+import { describe, expect, it, vi } from "bun:test"
+import type { Hex } from "viem"
+import { type Attributes, i32 } from "../attr"
 import type { ArkivClient } from "../clients/baseClient"
-import { Entity } from "../types/entity"
-import * as entitiesUtils from "../utils/entities"
-import * as engine from "./engine"
-import { and, eq, gt, gte, neq, or } from "./predicate"
-import { asc, QueryBuilder } from "./queryBuilder"
-
-describe("QueryBuilder", () => {
-  let mockClient: ArkivClient
-  let mockProcessQuery: any
-  let mockEntityFromRpcResult: any
-
-  beforeEach(() => {
-    // Create a mock client
-    mockClient = {
-      request: jest.fn(),
-    } as unknown as ArkivClient
-
-    // Spy on the functions instead of mocking the module
-    mockProcessQuery = jest.spyOn(engine, "processQuery")
-    mockEntityFromRpcResult = jest.spyOn(entitiesUtils, "entityFromRpcResult")
+import { NoMoreResultsError } from "../errors"
+import type { RpcEntity } from "../types/rpcSchema"
+import { MAX_LIMIT } from "./engine"
+import { InvalidPredicateError, QueryError } from "./errors"
+import { eq, gte, or } from "./expression"
+import { SelectQueryBuilder } from "./queryBuilder"
+import type { ProjectedEntity } from "./selection"
+
+const ACCOUNT = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+const KEY = `0x${"ab".repeat(32)}` as const
+
+type Page = { data: RpcEntity[]; blockNumber: string; cursor?: string }
+
+/** A client whose `arkiv_query` serves the given pages in order. */
+function makeClient(...pages: Page[]) {
+  const served = pages.length > 0 ? pages : [{ data: [], blockNumber: "0x1" }]
+  let index = 0
+  const request = vi.fn(async () => served[Math.min(index++, served.length - 1)])
+  return { client: { request } as unknown as ArkivClient, request }
+}
+
+/** The `[queryString, options]` of the nth `arkiv_query` call. */
+function sent(request: ReturnType<typeof makeClient>["request"], call = 0) {
+  const params = request.mock.calls[call][0] as unknown as {
+    method: string
+    params: [string, Record<string, unknown>]
+  }
+  return { method: params.method, query: params.params[0], options: params.params[1] }
+}
+
+describe("the query it sends", () => {
+  it("ANDs everything across repeated where() calls", async () => {
+    const { client, request } = makeClient()
+    await new SelectQueryBuilder(client, { key: true })
+      .where(gte("level", i32(10)))
+      .where(eq("category", "docs"), or(eq("status", "open"), eq("status", "review")))
+      .fetch()
+
+    expect(sent(request).method).toBe("arkiv_query")
+    expect(sent(request).query).toBe(
+      "level >= i32(10) AND category = str('docs') AND " +
+        "(status = str('open') OR status = str('review'))",
+    )
   })
 
-  afterEach(() => {
-    // Restore all spies to prevent test interference
-    jest.restoreAllMocks()
+  it("takes an array of expressions", async () => {
+    const { client, request } = makeClient()
+    await new SelectQueryBuilder(client, { key: true }).where([eq("a", 1), eq("b", 2)]).fetch()
+    expect(sent(request).query).toBe("a = i32(1) AND b = i32(2)")
   })
 
-  test("creates QueryBuilder with empty predicates", () => {
-    const builder = new QueryBuilder(mockClient)
-    expect(builder).toBeDefined()
+  it("turns ownedBy and createdBy into typed system predicates", async () => {
+    const { client, request } = makeClient()
+    await new SelectQueryBuilder(client, { key: true })
+      .where(eq("category", "docs"))
+      .ownedBy(ACCOUNT)
+      .createdBy(ACCOUNT)
+      .fetch()
+
+    expect(sent(request).query).toBe(
+      `category = str('docs') AND $owner = addr(${ACCOUNT}) AND $creator = addr(${ACCOUNT})`,
+    )
   })
 
-  describe("where() method", () => {
-    test("adds single predicate", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.where(eq("name", "test")).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [eq("name", "test")],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
-
-    test("adds multiple predicates as array", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const predicates = [eq("name", "test"), gt("age", 18)]
-      await builder.where(predicates).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: predicates,
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+  it("replaces rather than ANDs a second ownedBy — two owners would match nothing", async () => {
+    const other = "0x1111111111111111111111111111111111111111"
+    const { client, request } = makeClient()
+    await new SelectQueryBuilder(client, { key: true }).ownedBy(ACCOUNT).ownedBy(other).fetch()
+    expect(sent(request).query).toBe(`$owner = addr(${other})`)
+  })
 
-    test("adds multiple predicates as varargs", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.where(eq("name", "test"), gt("age", 18), neq("status", "inactive")).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [eq("name", "test"), gt("age", 18), neq("status", "inactive")],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+  it("is readable without running anything", () => {
+    const { client } = makeClient()
+    const builder = new SelectQueryBuilder(client, { key: true }).where(eq("a", 1))
+    expect(builder.toString()).toBe("a = i32(1)")
+    expect(`${builder}`).toBe("a = i32(1)")
+  })
 
-    test("chains multiple where() calls", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
+  it("refuses a query with no filter, which the language cannot spell", async () => {
+    const { client, request } = makeClient()
+    const builder = new SelectQueryBuilder(client, { key: true })
+    expect(() => builder.toString()).toThrow(InvalidPredicateError)
+    await expect(builder.fetch()).rejects.toThrow(/at least one filter/)
+    expect(request).not.toHaveBeenCalled()
+  })
+})
 
-      const builder = new QueryBuilder(mockClient)
-      await builder
-        .where(eq("name", "test"))
-        .where(gt("age", 18))
-        .where([neq("status", "inactive"), eq("verified", 1)])
-        .fetch()
+describe("the options it sends", () => {
+  it("sends the resolved selection, and nothing else by default", async () => {
+    const { client, request } = makeClient()
+    await new SelectQueryBuilder(client, { key: true, attributes: true }).where(eq("a", 1)).fetch()
 
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [
-          eq("name", "test"),
-          gt("age", 18),
-          neq("status", "inactive"),
-          eq("verified", 1),
-        ],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+    const { options } = sent(request)
+    expect(options).toEqual({ select: expect.objectContaining({ key: true, attributes: true }) })
+    // No limit, cursor or atBlock unless asked for — the node picks its own page size.
+    expect(Object.keys(options).sort()).toEqual(["select"])
+  })
 
-    test("handles complex predicates with or/and", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const complexPredicate = or([eq("type", "admin"), eq("type", "moderator")])
-      await builder.where(complexPredicate).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [complexPredicate],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
+  it("sends limit, cursor and atBlock as the RPC spells them", async () => {
+    const { client, request } = makeClient()
+    await new SelectQueryBuilder(client, { key: true })
+      .where(eq("a", 1))
+      .limit(100)
+      .cursor("b64:abc")
+      .atBlock(1_297_000n)
+      .fetch()
+
+    const { options } = sent(request)
+    expect(options).toMatchObject({
+      limit: "0x64",
+      cursor: "b64:abc",
+      atBlock: "0x13ca68",
     })
+  })
 
-    test("handles nested or/and predicates", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const nestedPredicate = and([
-        eq("active", 1),
-        or([eq("role", "admin"), eq("role", "moderator")]),
-      ])
-      await builder.where(nestedPredicate).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [nestedPredicate],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+  it("rejects a page size the node would reject", async () => {
+    const { client, request } = makeClient()
+    const query = () => new SelectQueryBuilder(client, { key: true }).where(eq("a", 1))
+    await expect(
+      query()
+        .limit(MAX_LIMIT + 1)
+        .fetch(),
+    ).rejects.toThrow(/exceeds the node maximum/)
+    await expect(query().limit(0).fetch()).rejects.toThrow(/positive integer/)
+    await expect(query().limit(1.5).fetch()).rejects.toThrow(/positive integer/)
+    expect(query().limit(MAX_LIMIT)).toBeDefined()
+    expect(request).not.toHaveBeenCalled()
   })
+})
 
-  describe("builder methods chain correctly", () => {
-    test("ownedBy() sets owner", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const owner = "0x1234567890123456789012345678901234567890" as const
-      await builder.ownedBy(owner).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: owner,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
+describe("decoding", () => {
+  it("builds entities from exactly the fields the row carries", async () => {
+    const { client } = makeClient({
+      blockNumber: "0x8e1ff",
+      data: [
+        {
+          key: KEY,
+          owner: ACCOUNT,
+          expiresAt: "0x92e21",
+          creationFlags: { readonly: false, permissionlessExtension: true, raw: 2 },
+          contentType: "application/json",
+          payload: "0x7b7d",
+          attributeSchema: [{ name: "version", type: "i32" }],
+          attributes: [
+            { name: "projectId", type: "str", value: "alice-123" },
+            { name: "version", type: "i32", value: 4 },
+            { name: "balance", type: "u256", value: "0xf4240" },
+            { name: "score", type: "dec", value: "3.5" },
+          ],
+        },
+      ],
     })
 
-    test("createdBy() sets creator", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const creator = "0x1234567890123456789012345678901234567890" as const
-      await builder.createdBy(creator).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: creator,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+    const page = await new SelectQueryBuilder(client, "*").where(eq("a", 1)).fetch()
+    const entity = page.entities[0]
 
-    test("orderBy() sets orderBy ascending", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.orderBy("name", "string", "asc").fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: [{ name: "name", type: "string", desc: false }],
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
+    expect(entity.key).toBe(KEY)
+    expect(entity.expiresAt).toBe(0x92e21n)
+    expect(entity.creationFlags).toEqual({
+      readonly: false,
+      permissionlessExtension: true,
+      raw: 2,
     })
-
-    test("orderBy() sets orderBy descending", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.orderBy("name", "string", "desc").fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: [{ name: "name", type: "string", desc: true }],
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
+    expect(entity.attributes).toEqual({
+      projectId: { type: "str", value: "alice-123" },
+      version: { type: "i32", value: 4 },
+      balance: { type: "u256", value: 1_000_000n },
+      score: { type: "dec", value: "3.5" },
     })
+    expect(entity.attributeSchema).toEqual({ version: "i32" })
+    expect(entity.toJson()).toEqual({})
+    // Unselected stays undefined rather than becoming an empty value.
+    expect(entity.creator).toBeUndefined()
+    expect(entity.createdAt).toBeUndefined()
+    expect(page.blockNumber).toBe(0x8e1ffn)
+  })
+})
 
-    test("orderBy() with helper function", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.orderBy(asc("name", "string")).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: [{ name: "name", type: "string", desc: false }],
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
-    test("limit() sets limit", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.limit(10).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: 10,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+describe("pagination", () => {
+  const page = (cursor: string | undefined, ...keys: string[]): Page => ({
+    blockNumber: "0x8e1ff",
+    data: keys.map((k) => ({ key: k as `0x${string}` })),
+    ...(cursor !== undefined && { cursor }),
+  })
 
-    test("cursor() sets cursor", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.cursor("0xABC123").fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        cursor: "0xABC123",
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+  it("follows the cursor and stops when the node omits it", async () => {
+    const { client, request } = makeClient(
+      page("b64:1", "0x1", "0x2"),
+      page("b64:2", "0x3"),
+      page(undefined, "0x4"),
+    )
+    const builder = new SelectQueryBuilder(client, { key: true }).where(eq("a", 1)).limit(2)
+
+    const first = await builder.fetch()
+    expect(first.entities).toHaveLength(2)
+    expect(first.hasNextPage()).toBe(true)
+
+    const second = await first.next()
+    expect(sent(request, 1).options).toMatchObject({ cursor: "b64:1" })
+
+    const third = await second.next()
+    expect(sent(request, 2).options).toMatchObject({ cursor: "b64:2" })
+    expect(third.hasNextPage()).toBe(false)
+    await expect(third.next()).rejects.toThrow(NoMoreResultsError)
+  })
 
-    test("withAttributes() sets withAttributes to true by default", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.withAttributes().fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        offset: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: true,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+  it("leaves an already-read page readable", async () => {
+    const { client } = makeClient(page("b64:1", "0x1"), page(undefined, "0x2"))
+    const first = await new SelectQueryBuilder(client, { key: true }).where(eq("a", 1)).fetch()
+    await first.next()
+    // next() returns the following page rather than mutating this one.
+    expect(first.entities).toHaveLength(1)
+    expect(first.cursor).toBe("b64:1")
+  })
 
-    test("withAttributes(false) sets withAttributes to false", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.withAttributes(false).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        cursor: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validBeforeBlock: undefined,
-        withAttributes: false,
-        withMetadata: undefined,
-        withPayload: undefined,
-      })
-    })
+  it("reports a full last page correctly", async () => {
+    // The old heuristic was "fewer rows than the limit means the end", which mistakes a final page
+    // that happens to be exactly full for a middle one. The node omits the cursor instead.
+    const { client } = makeClient(page(undefined, "0x1", "0x2"))
+    const result = await new SelectQueryBuilder(client, { key: true })
+      .where(eq("a", 1))
+      .limit(2)
+      .fetch()
+    expect(result.entities).toHaveLength(2)
+    expect(result.hasNextPage()).toBe(false)
+  })
 
-    test("withMetadata() sets withMetadata to true by default", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.withMetadata().fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        cursor: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: true,
-        withPayload: undefined,
-      })
-    })
+  it("pages the query it started with, not whatever the builder says later", async () => {
+    const { client, request } = makeClient(page("b64:1", "0x1"), page(undefined, "0x2"))
+    const builder = new SelectQueryBuilder(client, { key: true }).where(eq("a", 1))
+
+    const first = await builder.fetch()
+    // The builder stays mutable and reusable. Re-reading it per page would send page 2 under a
+    // different query than the cursor was issued for, which the node answers with a "cursor" error
+    // — or, worse, with rows from another result set.
+    builder.where(eq("b", 2)).limit(50).atBlock(9n)
+    await first.next()
+
+    expect(sent(request, 1).query).toBe("a = i32(1)")
+    expect(sent(request, 1).options).not.toHaveProperty("limit")
+    // The block page 2 reads at is the one page 1 was served from, not the builder's later edit.
+    expect(sent(request, 1).options).toMatchObject({ atBlock: "0x8e1ff" })
+  })
 
-    test("withMetadata(false) sets withMetadata to false", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.withMetadata(false).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        cursor: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: false,
-        withPayload: undefined,
-      })
-    })
+  it("pins the rest of the walk to the block the first page was read at", async () => {
+    const { client, request } = makeClient(
+      page("b64:1", "0x1"),
+      page("b64:2", "0x2"),
+      page(undefined, "0x3"),
+    )
+    // No atBlock on the builder: the first page reads at the head, and every page after it reads
+    // at the block that page came back with. Otherwise a block mined mid-walk moves the head on
+    // and the node rejects a cursor bound to the earlier one.
+    const first = await new SelectQueryBuilder(client, { key: true }).where(eq("a", 1)).fetch()
+    expect(sent(request, 0).options).not.toHaveProperty("atBlock")
+
+    const second = await first.next()
+    expect(sent(request, 1).options).toMatchObject({ cursor: "b64:1", atBlock: "0x8e1ff" })
+
+    await second.next()
+    expect(sent(request, 2).options).toMatchObject({ cursor: "b64:2", atBlock: "0x8e1ff" })
+  })
 
-    test("withPayload() sets withPayload to true by default", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.withPayload().fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        cursor: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        orderBy: undefined,
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: true,
-      })
-    })
+  it("walks every page through the async iterator", async () => {
+    const { client } = makeClient(page("b64:1", "0x1", "0x2"), page(undefined, "0x3"))
+    const keys: unknown[] = []
+    for await (const entity of new SelectQueryBuilder(client, { key: true }).where(eq("a", 1))) {
+      keys.push((entity as { key: string }).key)
+    }
+    expect(keys).toEqual(["0x1", "0x2", "0x3"])
+  })
+})
 
-    test("withPayload(false) sets withPayload to false", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.withPayload(false).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [],
-        limit: undefined,
-        cursor: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        validAtBlock: undefined,
-        withAttributes: undefined,
-        withMetadata: undefined,
-        withPayload: false,
-      })
+describe("node rejections", () => {
+  /** viem wraps the arkiv codes in its own EIP-1474 classes, so the code sits down the chain. */
+  function rpcFailure(code: number, data?: unknown) {
+    const inner = Object.assign(new Error("RPC Request failed."), { code, data })
+    return Object.assign(new Error("Something went wrong."), {
+      shortMessage: "Something went wrong.",
+      cause: inner,
     })
+  }
+
+  it("names the failure and keeps the node's detail", async () => {
+    const { client } = makeClient()
+    const data = { position: 14, expected: "typed literal", got: "3.5" }
+    ;(client.request as ReturnType<typeof vi.fn>).mockRejectedValue(rpcFailure(-32001, data))
+
+    const promise = new SelectQueryBuilder(client, { key: true }).where(eq("a", 1)).fetch()
+    await expect(promise).rejects.toThrow(QueryError)
+
+    const error = (await promise.catch((e) => e)) as QueryError
+    expect(error.kind).toBe("parse")
+    expect(error.code).toBe(-32001)
+    expect(error.data).toEqual(data)
+    expect(error.query).toBe("a = i32(1)")
+    expect(error.message).toContain("Query: a = i32(1)")
+  })
 
-    test("all methods chain together correctly", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const owner = "0x1234567890123456789012345678901234567890" as const
-      await builder
-        .where(eq("name", "test"))
-        .where(gte("age", 18))
-        .ownedBy(owner)
-        .limit(10)
-        .cursor("0xABC123")
-        .withAttributes(true)
-        .withMetadata(true)
-        .withPayload(true)
+  it("maps each code in the frozen range", async () => {
+    const kinds = {
+      [-32001]: "parse",
+      [-32002]: "type",
+      [-32003]: "literal",
+      [-32004]: "limits",
+      [-32005]: "cursor",
+      [-32006]: "block",
+    }
+    for (const [code, kind] of Object.entries(kinds)) {
+      const { client } = makeClient()
+      ;(client.request as ReturnType<typeof vi.fn>).mockRejectedValue(rpcFailure(Number(code)))
+      const error = await new SelectQueryBuilder(client, { key: true })
+        .where(eq("a", 1))
         .fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [eq("name", "test"), gte("age", 18)],
-        limit: 10,
-        cursor: "0xABC123",
-        ownedBy: owner,
-        createdBy: undefined,
-        validAtBlock: undefined,
-        withAttributes: true,
-        withMetadata: true,
-        withPayload: true,
-      })
-    })
+        .catch((e) => e)
+      expect((error as QueryError).kind).toBe(kind as QueryError["kind"])
+    }
   })
 
-  describe("fetch() method", () => {
-    test("calls processQuery and entityFromRpcResult", async () => {
-      const mockQueryResult = {
-        data: [
-          { key: "0xabc" as const, value: "encodedData1" },
-          { key: "0xdef" as const, value: "encodedData2" },
-        ],
-      }
-      const mockEntity1 = new Entity(
-        "0xabc" as const,
-        "application/json" as const,
-        "0x123" as const,
-        1000n,
-        1000n,
-        1000n,
-        1000n,
-        1000n,
-        new Uint8Array(),
-        [],
-      )
-      const mockEntity2 = new Entity(
-        "0xdef" as const,
-        "application/json" as const,
-        "0x456" as const,
-        2000n,
-        2000n,
-        2000n,
-        2000n,
-        2000n,
-        new Uint8Array(),
-        [],
-      )
-
-      mockProcessQuery.mockResolvedValue(mockQueryResult)
-      mockEntityFromRpcResult.mockResolvedValueOnce(mockEntity1).mockResolvedValueOnce(mockEntity2)
-
-      const builder = new QueryBuilder(mockClient)
-      const result = await builder.where(eq("name", "test")).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalled()
-      expect(mockEntityFromRpcResult).toHaveBeenCalled()
-      expect(mockEntityFromRpcResult).toHaveBeenCalledWith({ key: "0xabc", value: "encodedData1" })
-      expect(mockEntityFromRpcResult).toHaveBeenCalledWith({ key: "0xdef", value: "encodedData2" })
-      expect(result.entities).toHaveLength(2)
-      expect(result.entities[0]).toBe(mockEntity1)
-      expect(result.entities[1]).toBe(mockEntity2)
-    })
-
-    test("returns QueryResult with correct properties", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
+  it("leaves anything else alone", async () => {
+    const { client } = makeClient()
+    const transportFailure = new Error("fetch failed")
+    ;(client.request as ReturnType<typeof vi.fn>).mockRejectedValue(transportFailure)
 
-      const builder = new QueryBuilder(mockClient)
-      const result = await builder.limit(10).cursor("0xABC123").fetch()
-
-      expect(result).toBeDefined()
-      expect(result.entities).toEqual([])
-    })
+    const error = await new SelectQueryBuilder(client, { key: true })
+      .where(eq("a", 1))
+      .fetch()
+      .catch((e) => e)
+    expect(error).toBe(transportFailure)
   })
+})
 
-  describe("count() method", () => {
-    test("calls processQuery and returns count", async () => {
-      const mockQueryResult = {
-        data: [
-          { key: "0xabc", value: "data1" },
-          { key: "0xdef", value: "data2" },
-          { key: "0xghi", value: "data3" },
-        ],
-      }
-      mockProcessQuery.mockResolvedValue(mockQueryResult)
-
-      const builder = new QueryBuilder(mockClient)
-      const count = await builder.where(eq("status", "active")).count()
-
-      expect(mockProcessQuery).toHaveBeenCalled()
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [eq("status", "active")],
-        limit: undefined,
-        cursor: undefined,
-        ownedBy: undefined,
-        createdBy: undefined,
-        validAtBlock: undefined,
-        withAttributes: false,
-        withMetadata: false,
-        withPayload: false,
-      })
-      expect(count as number).toEqual(3 as number)
-      // Verify entityFromRpcResult is NOT called for count()
-      expect(mockEntityFromRpcResult).not.toHaveBeenCalled()
-    })
-
-    test("returns 0 for empty results", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const count = await builder.count()
-
-      expect(count as number).toEqual(0 as number)
+describe("the projected type", () => {
+  // Compile-time only: these assertions fail the build, not the run.
+  it("narrows the entity to exactly the selected fields", async () => {
+    const { client } = makeClient({
+      blockNumber: "0x1",
+      data: [{ key: KEY, owner: ACCOUNT, payload: "0x7b7d" }],
     })
 
-    test("count() uses all builder parameters", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const owner = "0x1234567890123456789012345678901234567890" as const
-      await builder
-        .where([eq("active", 1), gte("score", 100)])
-        .ownedBy(owner)
-        .limit(50)
-        .cursor("0xABC123")
-        .validAtBlock(123n)
-        .count()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-        predicates: [eq("active", 1), gte("score", 100)],
-        limit: 50,
-        cursor: "0xABC123",
-        ownedBy: owner,
-        createdBy: undefined,
-        validAtBlock: 123n,
-        withAttributes: false,
-        withMetadata: false,
-        withPayload: false,
-      })
+    const page = await new SelectQueryBuilder<ProjectedEntity<{ key: true; owner: true }>>(client, {
+      key: true,
+      owner: true,
     })
+      .where(eq("a", 1))
+      .fetch()
+
+    const entity = page.entities[0]
+    expectType<Hex>(entity.key)
+    expectType<Hex>(entity.owner)
+    // @ts-expect-error - creator was not selected
+    entity.creator
+    // @ts-expect-error - toJson comes with the payload, which was not selected
+    entity.toJson()
   })
 
-  describe("predicate types", () => {
-    test("passes string values correctly", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.where(eq("name", "john")).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(
-        mockClient,
-        expect.objectContaining({
-          predicates: [eq("name", "john")],
-        }),
-      )
+  it("keeps the payload helpers when the payload is selected", async () => {
+    const { client } = makeClient({ blockNumber: "0x1", data: [{ payload: "0x7b7d" }] })
+    const page = await new SelectQueryBuilder<ProjectedEntity<{ payload: true }>>(client, {
+      payload: true,
     })
+      .where(eq("a", 1))
+      .fetch()
 
-    test("passes numeric values correctly", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      await builder.where(gt("age", 25)).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(
-        mockClient,
-        expect.objectContaining({
-          predicates: [gt("age", 25)],
-        }),
-      )
-    })
+    expect(page.entities[0].toJson()).toEqual({})
+    expectType<Uint8Array>(page.entities[0].payload)
+  })
 
-    test("passes mixed predicates correctly", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [],
-      })
-
-      const builder = new QueryBuilder(mockClient)
-      const predicates = [eq("name", "john"), gt("age", 25), neq("status", "inactive")]
-      await builder.where(predicates).fetch()
-
-      expect(mockProcessQuery).toHaveBeenCalledWith(
-        mockClient,
-        expect.objectContaining({
-          predicates: predicates,
-        }),
-      )
+  it("treats a named attribute subset as a selection of attributes", async () => {
+    const { client } = makeClient({
+      blockNumber: "0x1",
+      data: [{ key: KEY, attributes: [{ name: "version", type: "i32", value: 4 }] }],
     })
+    const page = await new SelectQueryBuilder<
+      ProjectedEntity<{ key: true; attributes: { version: true } }>
+    >(client, { key: true, attributes: { version: true } })
+      .where(eq("a", 1))
+      .fetch()
+
+    expectType<Attributes>(page.entities[0].attributes)
+    expect(page.entities[0].attributes).toEqual({ version: { type: "i32", value: 4 } })
   })
 })
+
+/** Asserts the static type of an expression without touching it at runtime. */
+function expectType<T>(_value: T): void {}