@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/src/entity/create.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from "bun:test"
 import { decodeAbiParameters, parseAbiParameters, toHex } from "viem"
-import { encodeAttributes } from "../attr/attributes"
-import { dec, i32, str, u256 } from "../attr/values"
+import { encodeCreate } from "../schema/attributes"
+import { defineSchema } from "../schema/schema"
+import { bytes, dec, i32, str, u256 } from "../schema/values"
 import { InvalidCreationFlagsError } from "./errors"
 import { decodeCreationFlags, encodeCreationFlags } from "./flags"
 import { MAX_SALT, NO_SALT, predictEntityKey, randomSalt, resolveSalt, validateSalt } from "./key"
@@ -148,9 +149,10 @@ describe("the Create operation", () => {
   })
 
   it("carries attributes as (name, typeId, bytes), sorted ascending by name", () => {
+    const schema = defineSchema({ zebra: i32(), apple: str(), mango: u256() })
     const create = decodeCreate(
       build({
-        attributes: encodeAttributes({ zebra: i32(1), apple: str("x"), mango: u256(2n) }),
+        attributes: encodeCreate(schema, { zebra: i32(1), apple: str("x"), mango: u256(2n) }),
       }).operationData,
     )
     const names = create.attributes.map((a) => a.name)
@@ -158,38 +160,40 @@ describe("the Create operation", () => {
     expect(create.attributes.map((a) => a.typeId)).toEqual([8, 4, 2]) // apple str, mango u256, zebra i32
   })
 
-  it("sends the payload and content type as system cells, ahead of user attributes", () => {
+  it("sets bit 7 of the typeId on indexed columns, and only on them", () => {
+    const schema = defineSchema({ level: i32().indexed(), note: str(), body: bytes() })
     const create = decodeCreate(
       build({
-        attributes: encodeAttributes(
-          { level: i32(10) },
-          { payload: new Uint8Array([0xde, 0xad]), contentType: "application/json" },
-        ),
+        attributes: encodeCreate(schema, {
+          level: 10,
+          note: "hi",
+          body: new Uint8Array([0xde, 0xad]),
+        }),
       }).operationData,
     )
     const byName = Object.fromEntries(create.attributes.map((a) => [a.name, a]))
-
-    // "$" sorts below every letter, so the system cells lead.
-    expect(create.attributes[0].name).toBe(toHex("$contentType", { size: 32 }))
-    expect(create.attributes[1].name).toBe(toHex("$payload", { size: 32 }))
-
-    expect(byName[toHex("$payload", { size: 32 })]).toMatchObject({ typeId: 7, value: "0xdead" })
-    expect(byName[toHex("$contentType", { size: 32 })].typeId).toBe(8)
-    expect(byName[toHex("level", { size: 32 })].typeId).toBe(2)
+    expect(byName[toHex("level", { size: 32 })].typeId).toBe(0x80 | 2)
+    expect(byName[toHex("note", { size: 32 })].typeId).toBe(8)
+    expect(byName[toHex("body", { size: 32 })]).toMatchObject({ typeId: 7, value: "0xdead" })
   })
 
-  it("omits the system cells entirely when there is no payload or content type", () => {
+  it("carries no cells at all for an entity with no columns", () => {
     const create = decodeCreate(
-      build({ attributes: encodeAttributes({ level: i32(10) }) }).operationData,
+      build({ attributes: encodeCreate(defineSchema({}), {}) }).operationData,
     )
-    expect(create.attributes).toHaveLength(1)
-    expect(create.attributes[0].name).toBe(toHex("level", { size: 32 }))
+    expect(create.attributes).toHaveLength(0)
   })
 
   it("encodes each value type at its documented width", () => {
+    const schema = defineSchema({ n: i32(), big: u256(), d: dec(), s: str() })
     const create = decodeCreate(
       build({
-        attributes: encodeAttributes({ n: i32(-42), big: u256(1n), d: dec("1.5"), s: str("hi") }),
+        attributes: encodeCreate(schema, {
+          n: i32(-42),
+          big: u256(1n),
+          d: dec("1.5"),
+          s: str("hi"),
+        }),
       }).operationData,
     )
     const byName = Object.fromEntries(create.attributes.map((a) => [a.name, a.value]))

package/src/entity/expiry.ts

@@ -50,7 +50,7 @@ export function makeExpiry(minLifetime: bigint, expiresAt: bigint | Date): Expir
   return { minLifetime, expiresAt } as Expiry
 }
 
-/** The two `uint256` values the ABI carries, with every `Date` already placed. */
+/** The two `uint64` values the ABI carries, with every `Date` already placed. */
 export type EncodedExpiry = {
   /** Absolute target block height, or `0n` for a purely relative lifetime. */
   expiresAt: bigint
@@ -72,10 +72,12 @@ export type ExpiryContext = {
 /**
  * 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.
+ * A duration arrives here already in blocks — {@link ExpirationTime} converted it at the nominal
+ * `BLOCK_TIME` (2 seconds) through {@link toBlocks} — and a `Date` deadline is placed against
+ * `currentBlock` at that same block time here. Both are **approximate**: block production is not a
+ * clock, so a lifetime asked for in days drifts if the chain runs fast or slow. The block the
+ * expiry resolves to against `currentBlock` 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.
@@ -85,7 +87,7 @@ export function resolveExpiry(expiry: Expiry, context: ExpiryContext): ResolvedE
 
   if (typeof expiry?.minLifetime !== "bigint" || expiry.expiresAt === undefined) {
     throw new InvalidExpiryError(
-      "expires must be built with ExpirationTime, e.g. ExpirationTime.fromDays(30) or " +
+      "expiration must be built with ExpirationTime, e.g. ExpirationTime.fromDays(30) or " +
         "ExpirationTime.atBlock(1_200_000n)",
     )
   }

package/src/entity/flags.ts

@@ -12,7 +12,7 @@ const PERMISSIONLESS_EXTENSION_BIT = 0b0000_0010
  */
 export type CreationFlags = {
   /**
-   * The entity's attributes and payload can never be changed — only its expiry extended, its
+   * The entity's attributes can never be changed — only its expiry extended, its
    * ownership transferred, and the entity deleted.
    */
   readonly?: boolean

package/src/entity/index.ts

@@ -6,10 +6,8 @@ export {
 } from "./errors"
 export type { EntityEventName } from "./events"
 export { ENTITY_EVENTS_ABI } from "./events"
-export type { EncodedExpiry, Expiry, ExpiryContext, Lifetime, ResolvedExpiry } from "./expiry"
-export { resolveExpiry, toBlocks } from "./expiry"
+export type { Expiry, Lifetime } from "./expiry"
 export type { CreationFlags, ResolvedCreationFlags } from "./flags"
-export { decodeCreationFlags, encodeCreationFlags } from "./flags"
 export type { SaltInput } from "./key"
 export { MAX_SALT, NO_SALT, predictEntityKey, randomSalt } from "./key"
-export { MAX_EXPIRES_AT, OperationType } from "./params"
+export { MAX_EXPIRES_AT } from "./params"

package/src/entity/key.ts

@@ -1,5 +1,5 @@
 import { type Address, encodePacked, type Hex, keccak256 } from "viem"
-import type { CreateEntityParameters } from "../actions/wallet/createEntity"
+import type { CreateEntityOptions } from "../actions/wallet/createEntity"
 import { ARKIV_ADDRESS } from "../consts"
 import { InvalidSaltError, NoRandomSourceError } from "./errors"
 
@@ -7,7 +7,7 @@ import { InvalidSaltError, NoRandomSourceError } from "./errors"
 export const MAX_SALT = 2n ** 128n - 1n
 
 /**
- * Opts a create out of salting, as {@link CreateEntityParameters.salt}: the key is then derived
+ * Opts a create out of salting, as {@link CreateEntityOptions.salt}: the key is then derived
  * from the owner and its nonce alone, so anyone who knows both can work it out before the create
  * lands.
  */
@@ -19,7 +19,7 @@ export const NO_SALT = Symbol("NO_SALT")
 export type SaltInput = bigint | typeof NO_SALT
 
 /**
- * A cryptographically random 128-bit salt — what {@link CreateEntityParameters.salt} defaults to.
+ * A cryptographically random 128-bit salt — what {@link CreateEntityOptions.salt} defaults to.
  *
  * The salt exists for unpredictability, not uniqueness: the per-owner nonce already guarantees
  * distinct keys. Random bits mean only the creator can predict the key of an entity they are about

package/src/entity/operations.ts

@@ -1,5 +1,5 @@
 import { type Address, encodeAbiParameters, type Hex, parseAbi, parseAbiParameters } from "viem"
-import type { AbiAttribute } from "../attr/codec"
+import type { AbiAttribute } from "../schema/codec"
 import type { EncodedExpiry } from "./expiry"
 import type { predictEntityKey } from "./key"
 import { OperationType } from "./params"

package/src/errors.ts

@@ -37,19 +37,10 @@ export class EmptyPatchError extends Error {
 
   constructor(entityKey: string) {
     super(
-      `The patch for entity ${entityKey} has nothing to apply. Pass "set" to write attributes, ` +
-        '"unset" to remove them, or "payload"/"contentType" to replace the contents.',
+      `The patch for entity ${entityKey} has nothing to apply. Pass "set" to write columns, or ` +
+        '"unset" to remove optional ones.',
     )
     this.name = "EmptyPatchError"
     this.entityKey = entityKey
   }
 }
-
-export class InvalidContentTypeError extends Error {
-  constructor(contentType: string) {
-    super(
-      `Invalid content type "${contentType}". Must follow RFC 2045 MIME grammar and be lowercase only (e.g. "text/plain").`,
-    )
-    this.name = "InvalidContentTypeError"
-  }
-}

package/src/index.ts

@@ -2,8 +2,6 @@
  * @module main
  */
 
-// the attribute type system
-export * from "./attr"
 // export main arkiv stuff
 export type { ArkivClient } from "./clients/baseClient"
 export type { PublicArkivClient } from "./clients/createPublicClient"
@@ -19,18 +17,32 @@ export * from "./errors"
 // types referenced by the public client, must be reachable from the package root
 // see #106
 export type {
-  EntitySelection,
+  AttributeRef,
+  DynamicSelection,
   Expression,
+  FromOptions,
   FullEntity,
-  ProjectedEntity,
+  FullRow,
+  KnownSystemFields,
+  NonEmptySelection,
+  PartialRow,
+  QueryBuilderBase,
   QueryResult,
+  ResultOf,
+  Row,
+  SchemaRef,
   SelectArg,
+  Selected,
+  Selection,
+  SelectionOf,
+  SystemField,
 } from "./query"
-export { SelectQueryBuilder } from "./query"
+export { CountQueryBuilder, SelectQueryBuilder, SYSTEM_FIELDS } from "./query"
+// schemas and the attribute type system
+export * from "./schema"
 // re-export arkiv types in main index file
 export * from "./types"
 // re-export chosen utils
 export { chainFromName } from "./utils/chains"
 // every create needs an expiry, and this is the only way to build one
 export { type DeadlineOptions, ExpirationTime } from "./utils/expirationTime"
-export { jsonToPayload, stringToPayload } from "./utils/payload"

package/src/query/builderBase.ts

@@ -0,0 +1,166 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../clients/baseClient"
+import { addr, type ColumnsOf, SCHEMA_ATTRIBUTE, type Schema } from "../schema"
+import { InvalidPredicateError } from "./errors"
+import {
+  and,
+  checkAgainstSchema,
+  type Expression,
+  eq,
+  type RefsOf,
+  type SchemaRef,
+} from "./expression"
+
+/** The expressions in a `where` call — passed one by one, or as one array. */
+type WhereExpressions<E extends readonly (Expression | readonly Expression[])[]> =
+  E[number] extends infer X ? (X extends readonly Expression[] ? X[number] : X) : never
+
+/**
+ * Human-readable messages for compile-time errors when a filter does not fit the schema.
+ */
+type FilterProblem<R, S extends Schema> = R extends {
+  readonly name: infer N extends string
+  readonly type: infer T extends string
+}
+  ? R extends SchemaRef<S>
+    ? never
+    : N extends SchemaRef<S>["name"]
+      ? `"${N}" has type ${Extract<SchemaRef<S>, { name: N }>["type"]}, but is compared against a value of type ${T}`
+      : N extends keyof ColumnsOf<S>
+        ? ColumnsOf<S>[N]["type"] extends "bytes"
+          ? `"${N}" is a bytes column, and bytes are never indexed, so it cannot be filtered on. Index a str, bytes32 or key derived from it instead`
+          : `"${N}" is not indexed, so it cannot be filtered on. Declare it ${ColumnsOf<S>[N]["type"]}().indexed() to filter on it`
+        : `"${N}" is not a column of this schema`
+  : never
+
+/**
+ * `where`'s check that every filter fits the schema — `unknown` when it does, or when there is no
+ * schema, and otherwise an object whose one property is named after the problem. No expression has
+ * that property, so the compiler reports the sentence as the property it is missing.
+ */
+type FilterCheck<
+  E extends readonly (Expression | readonly Expression[])[],
+  TSchema,
+> = TSchema extends Schema
+  ? [FilterProblem<RefsOf<WhereExpressions<E>>, TSchema>] extends [infer P extends string]
+    ? [P] extends [never]
+      ? unknown
+      : { [K in P]: never }
+    : unknown
+  : unknown
+
+/**
+ * What every query builder shares: the client, the filters — `where`, `ownedBy`, `createdBy` and a
+ * named schema's tag — and the block to read at. `client.select()` and `client.count()` build on it,
+ * so the same filters always send the same query string, whichever of them runs it.
+ *
+ * Not constructed directly: create a builder with `client.select(...)` or `client.count()`.
+ *
+ * @typeParam TSchema - The schema named with `from()`, if any, which `where` is checked against.
+ */
+export abstract class QueryBuilderBase<TSchema extends Schema | undefined = undefined> {
+  protected readonly _client: ArkivClient
+  protected _schema: Schema | undefined
+  protected readonly _filters: Expression[] = []
+  protected _ownedBy: Expression | undefined
+  protected _createdBy: Expression | undefined
+  protected _atBlock: bigint | undefined
+
+  constructor(client: ArkivClient) {
+    this._client = client
+  }
+
+  /**
+   * This builder's state in a new builder of the same class, re-typed by the caller. Every field is
+   * carried over, so one a subclass adds is not dropped by `from()`; the filter list, which is
+   * mutated in place, is copied rather than shared.
+   *
+   * A copy, not `this` re-typed: a builder typed for one schema must never be the same object as
+   * one typed for another, or `base.from(Posts)` and `base.from(Users)` would share their state.
+   */
+  protected copy<B extends QueryBuilderBase<Schema | undefined>>(): B {
+    const copy = Object.create(Object.getPrototypeOf(this)) as B
+    return Object.assign(copy, this, { _filters: [...this._filters] })
+  }
+
+  /**
+   * Adds filters. Everything passed here, and across repeated calls, must hold.
+   *
+   * After `from()`, every attribute a filter names must be an indexed column of the schema,
+   * compared against a value of its type — anything else is a compile error.
+   *
+   * @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<const E extends readonly (Expression | readonly Expression[])[]>(
+    ...expressions: E & FilterCheck<E, TSchema>
+  ): this {
+    this._filters.push(...expressions.flat())
+    return this
+  }
+
+  /**
+   * Restricts the query 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 {
+    this._ownedBy = eq("$owner", addr(owner))
+    return this
+  }
+
+  /**
+   * Restricts the query 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 {
+    this._createdBy = eq("$creator", addr(creator))
+    return this
+  }
+
+  /**
+   * Reads the state as of a given block rather than the head. The block must be within the range
+   * the node retains.
+   *
+   * @example
+   * builder.atBlock(1_297_000n)
+   */
+  atBlock(block: bigint): this {
+    this._atBlock = block
+    return this
+  }
+
+  /**
+   * The query string this builder will send — the same text the node parses: its filters,
+   * `ownedBy` and `createdBy`, and a named schema's tag, ANDed.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added, or — after `from()` — a filter
+   * does not fit the schema. A named schema's own tag filter counts as a filter.
+   */
+  toString(): string {
+    const filters = [...this._filters]
+    if (this._ownedBy) filters.push(this._ownedBy)
+    if (this._createdBy) filters.push(this._createdBy)
+    const schema = this._schema
+    if (schema !== undefined) {
+      for (const filter of filters) checkAgainstSchema(filter, schema)
+      // Added after the check: the tag is not a column, and the caller never wrote this filter.
+      if (schema.tag !== undefined) filters.unshift(eq(SCHEMA_ATTRIBUTE, schema.tag))
+    }
+    if (filters.length === 0) {
+      throw new InvalidPredicateError(
+        "A query needs at least one filter — the language has no spelling for 'match every " +
+          "entity'. Add a where(...) predicate, or narrow by ownedBy(...) / createdBy(...).",
+      )
+    }
+    return and(filters).toString()
+  }
+}

package/src/query/countBuilder.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it, vi } from "bun:test"
+import type { ArkivClient } from "../clients/baseClient"
+import { dec, defineSchema, str } from "../schema"
+import { CountQueryBuilder } from "./countBuilder"
+import { InvalidPredicateError } from "./errors"
+import { eq, gt } from "./expression"
+
+const ACCOUNT = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" as const
+const Posts = defineSchema("my-app.posts", { category: str().indexed(), score: dec().indexed() })
+
+/** A client whose `arkiv_query` answers with `result`. */
+function makeClient(result: unknown = { data: [], blockNumber: "0x5", count: "0x2a" }) {
+  const request = vi.fn(async () => result)
+  return { client: { request } as unknown as ArkivClient, request }
+}
+
+/** The `[queryString, options]` of the first `arkiv_query` call. */
+function sent(request: ReturnType<typeof makeClient>["request"]) {
+  const [[call]] = request.mock.calls as unknown as [
+    [{ method: string; params: [string, Record<string, unknown>] }],
+  ]
+  return { method: call.method, query: call.params[0], options: call.params[1] }
+}
+
+describe("CountQueryBuilder", () => {
+  it("asks for the count alone and resolves to it", async () => {
+    const { client, request } = makeClient()
+    const total = await new CountQueryBuilder(client).where(eq("category", "news")).fetch()
+
+    expect(total).toBe(42n)
+    expect(sent(request).method).toBe("arkiv_query")
+    expect(sent(request).query).toBe("category = str('news')")
+    // Nothing but the count is selected, so the node sends no rows and no cursor.
+    expect(sent(request).options).toEqual({ select: { count: true } })
+  })
+
+  it("filters as select() does: schema tag, where, owner, creator and block", async () => {
+    const { client, request } = makeClient()
+    await new CountQueryBuilder(client)
+      .from(Posts)
+      .where(gt("score", dec("4")))
+      .ownedBy(ACCOUNT)
+      .createdBy(ACCOUNT)
+      .atBlock(5n)
+      .fetch()
+
+    expect(sent(request).query).toBe(
+      "arkiv.schema = str('my-app.posts') AND score > dec(4) AND " +
+        `$owner = addr(${ACCOUNT}) AND $creator = addr(${ACCOUNT})`,
+    )
+    expect(sent(request).options).toEqual({ select: { count: true }, atBlock: "0x5" })
+  })
+
+  it("needs no other filter through a named schema", async () => {
+    const { client, request } = makeClient()
+    await new CountQueryBuilder(client).from(Posts).fetch()
+    expect(sent(request).query).toBe("arkiv.schema = str('my-app.posts')")
+  })
+
+  it("checks filters against the schema, at compile time and when it runs", async () => {
+    const { client } = makeClient()
+    // @ts-expect-error - score is a dec column
+    const wrongType = new CountQueryBuilder(client).from(Posts).where(eq("score", 5))
+    await expect(wrongType.fetch()).rejects.toThrow(InvalidPredicateError)
+  })
+
+  it("rejects a count with no filter at all", async () => {
+    const { client, request } = makeClient()
+    await expect(new CountQueryBuilder(client).fetch()).rejects.toThrow(InvalidPredicateError)
+    expect(request).not.toHaveBeenCalled()
+  })
+
+  it("fails rather than guessing when the node sends no count", async () => {
+    const { client } = makeClient({ data: [], blockNumber: "0x1" })
+    await expect(new CountQueryBuilder(client).where(eq("a", 1)).fetch()).rejects.toThrow(
+      /returned no count/,
+    )
+  })
+
+  it("leaves the builder from() was called on without the schema", async () => {
+    const { client, request } = makeClient()
+    const base = new CountQueryBuilder(client).where(eq("category", "news"))
+    await base.from(Posts).fetch()
+    await base.fetch()
+    const [, second] = request.mock.calls as unknown as [
+      unknown,
+      [{ params: [string, Record<string, unknown>] }],
+    ]
+    expect(second[0].params[0]).toBe("category = str('news')")
+  })
+})

package/src/query/countBuilder.ts

@@ -0,0 +1,67 @@
+import { isSchema, type Schema, SchemaDefinitionError } from "../schema"
+import { QueryBuilderBase } from "./builderBase"
+import { runQuery } from "./engine"
+
+/**
+ * Builds and runs a count: how many entities a query matches, without fetching any of them.
+ *
+ * It filters exactly as `client.select()` does — {@link from}, `where`, `ownedBy`, `createdBy` and
+ * `atBlock` are the same methods, from the same base — but has nothing to select and no pages, so
+ * {@link fetch} resolves to a `bigint`. Create one with `client.count()`.
+ *
+ * To show the total next to a page of rows, use `select(...).withCount()` instead, which counts in
+ * the same request.
+ *
+ * @typeParam TSchema - The schema named with {@link from}, if any.
+ *
+ * @example
+ * const total = await client.count().from(Posts).ownedBy(account.address).fetch()
+ */
+export class CountQueryBuilder<
+  TSchema extends Schema | undefined = undefined,
+> extends QueryBuilderBase<TSchema> {
+  /**
+   * Counts through a schema: `where` is checked against its indexed columns, and a named schema
+   * counts only entities tagged with its name — so it needs no other filter.
+   *
+   * Returns a new builder, carrying whatever this one already holds; this one is left as it was.
+   *
+   * @throws {SchemaDefinitionError} If `schema` was not built with `defineSchema`.
+   *
+   * @example
+   * client.count().from(Posts)   // every post
+   */
+  from<S extends Schema>(schema: S): CountQueryBuilder<S> {
+    if (!isSchema(schema)) {
+      throw new SchemaDefinitionError("from() takes a schema built with defineSchema(...)")
+    }
+    const typed = this.copy<CountQueryBuilder<S>>()
+    typed._schema = schema
+    return typed
+  }
+
+  /**
+   * Runs the count.
+   *
+   * Counts every entity the filters match at the block, whether or not it fits the schema — what
+   * `select().from(schema)` leaves out of its pages is still counted.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added, or a filter does not fit the
+   * schema.
+   * @throws {QueryError} If the node rejects the query.
+   * @throws If the node returns no count — it predates the count projection.
+   */
+  async fetch(): Promise<bigint> {
+    // Nothing but the count is selected, so the node returns no rows and no cursor.
+    const response = await runQuery(this._client, {
+      query: this.toString(),
+      select: {},
+      atBlock: this._atBlock,
+      count: true,
+    })
+    if (response.count === undefined) {
+      throw new Error("The node returned no count. It may predate the count projection.")
+    }
+    return response.count
+  }
+}

package/src/query/engine.ts

@@ -8,7 +8,7 @@ import { asQueryError } from "./errors"
 
 const logger = getLogger("query:engine")
 
-export const MAX_LIMIT = 200
+export const MAX_LIMIT = 100
 
 /** One `arkiv_query` call. */
 export type QueryRequest = {
@@ -22,6 +22,8 @@ export type QueryRequest = {
   cursor?: string | undefined
   /** Block height to read at. Defaults to the head. */
   atBlock?: bigint | undefined
+  /** Whether to also count every entity the query matches. */
+  count?: boolean | undefined
 }
 
 /** One page of results. */
@@ -31,15 +33,18 @@ export type QueryResponse = {
   blockNumber: bigint
   /** The cursor for the next page, or `undefined` when this was the last one. */
   cursor: string | undefined
+  /** How many entities the query matches, if the request asked to count them. */
+  count: bigint | undefined
 }
 
 /**
  * Runs one query and decodes the page it returns.
  *
+ * @throws If `limit` is not an integer from 1 to {@link MAX_LIMIT}.
  * @throws {QueryError} If the node rejects the query.
  */
 export async function runQuery(client: ArkivClient, request: QueryRequest): Promise<QueryResponse> {
-  const { query, select, limit, cursor, atBlock } = request
+  const { query, select, limit, cursor, atBlock, count } = request
 
   if (limit !== undefined) {
     if (!Number.isInteger(limit) || limit < 1) {
@@ -54,7 +59,7 @@ export async function runQuery(client: ArkivClient, request: QueryRequest): Prom
   }
 
   const queryOptions: RpcQueryOptions = {
-    select,
+    select: count ? { ...select, count: true } : select,
     ...(atBlock !== undefined && { atBlock: numberToHex(atBlock) }),
     ...(limit !== undefined && { limit: numberToHex(limit) }),
     ...(cursor !== undefined && { cursor }),
@@ -74,5 +79,6 @@ export async function runQuery(client: ArkivClient, request: QueryRequest): Prom
     entities: result.data.map((rpcEntity) => entityFromRpcResult(rpcEntity)),
     blockNumber: BigInt(result.blockNumber),
     cursor: result.cursor,
+    count: result.count === undefined ? undefined : BigInt(result.count),
   }
 }