@arkiv-network/sdk 0.6.8-dev.1 → 0.6.8-dev.2

package/src/actions/public/buildQuery.ts

@@ -1,6 +1,10 @@
 import type { ArkivClient } from "../../clients/baseClient"
 import { QueryBuilder } from "../../query/queryBuilder"
 
+/**
+ * @deprecated Use `client.select()` (see SelectQueryBuilder) instead. `buildQuery()` returns
+ * only the entity `key` unless data is explicitly opted in to, which is an easy mistake.
+ */
 export async function buildQuery(client: ArkivClient) {
   return new QueryBuilder(client)
 }

package/src/clients/createPublicClient.test.ts

@@ -20,6 +20,8 @@ test("creates", () => {
   expect(typeof client.getEntity).toBe("function")
   expect(client.buildQuery).toBeDefined()
   expect(typeof client.buildQuery).toBe("function")
+  expect(client.select).toBeDefined()
+  expect(typeof client.select).toBe("function")
   expect(client.query).toBeDefined()
   expect(typeof client.query).toBe("function")
   expect(client.getEntityCount).toBeDefined()

package/src/clients/decorators/arkivPublic.ts

@@ -4,7 +4,8 @@ import { getEntity } from "../../actions/public/getEntity"
 import { getEntityCount } from "../../actions/public/getEntityCount"
 import { type QueryOptions, type QueryReturnType, query } from "../../actions/public/query"
 import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
-import { QueryBuilder } from "../../query/queryBuilder"
+import { QueryBuilder, SelectQueryBuilder } from "../../query/queryBuilder"
+import type { EntitySelection, FullEntity, ProjectedEntity, SelectArg } from "../../query/selection"
 import type { Entity } from "../../types/entity"
 import type {
   OnEntityCreatedEvent,
@@ -55,12 +56,76 @@ export type PublicArkivActions<
    */
   getEntity: (key: Hex) => Promise<Entity>
 
+  /**
+   * Returns a SelectQueryBuilder for building and executing queries — the recommended way to
+   * read entities. You declare up front which parts of an entity you want returned, so results
+   * always contain exactly the data you asked for.
+   *
+   * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
+   *
+   * @param selection - What to include in the results. Omit it (or pass `"*"`) to select everything,
+   *   or pass an object to select specific parts (at least one field is required). Every part is
+   *   opt-in, including the `key`. The selection is flat — each field maps to an entity field.
+   *   {@link SelectArg}
+   * @returns A SelectQueryBuilder instance for building and executing queries. {@link SelectQueryBuilder}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { braga } from 'arkiv/chains'
+   * import { eq } from 'arkiv/query'
+   *
+   * const client = createPublicClient({
+   *   chain: braga,
+   *   transport: http(),
+   * })
+   * // select everything
+   * await client.select().where(eq("category", "docs")).fetch()
+   * await client.select("*").where(eq("category", "docs")).fetch()
+   * // only the key
+   * await client.select({ key: true }).where(eq("category", "docs")).fetch()
+   * // select specific fields — result typed { owner: Hex; attributes: Attribute[] }
+   * await client.select({ owner: true, attributes: true }).fetch()
+   * // a single field — result typed { owner: Hex }
+   * await client.select({ owner: true }).fetch()
+   */
+  select: {
+    /** Select every field. Pass nothing or `"*"`; the returned entities contain all fields. */
+    (selection?: "*"): SelectQueryBuilder<FullEntity>
+    /**
+     * Pick the entity fields to return. Set the ones you want to `true` (at least one is required);
+     * the result is typed to exactly those fields, so reading anything else is a compile error.
+     *
+     * Available fields: `key`, `owner`, `creator`, `contentType`, `payload`, `attributes`,
+     * `expiresAtBlock`, `createdAtBlock`, `lastModifiedAtBlock`, `transactionIndexInBlock`,
+     * `operationIndexInTransaction`.
+     *
+     * Pass the selection inline so its fields stay literal `true`. A selection stored in a `let`/
+     * `const` variable widens to `boolean` and the result type can no longer be narrowed — annotate
+     * it `as const` (e.g. `const sel = { owner: true } as const`) in that case.
+     *
+     * @example
+     * client.select({ owner: true, attributes: true }) // entities typed { owner, attributes }
+     * client.select({ key: true, payload: true })       // includes payload → toText()/toJson() too
+     */
+    <const S extends EntitySelection>(selection: S): SelectQueryBuilder<ProjectedEntity<S>>
+    /**
+     * Dynamic selection: accepts a value typed {@link SelectArg} (e.g. built at runtime). The
+     * result cannot be narrowed in this case, so the entities are typed as the full entity.
+     */
+    (selection: SelectArg): SelectQueryBuilder<FullEntity>
+  }
+
   /**
    * Returns a QueryBuilder instance for building and executing queries.
    * The QueryBuilder object follows the Builder pattern, allowing you to chain methods to build a query and then execute it.
    *
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
    *
+   * @deprecated Use {@link select} instead. `buildQuery()` returns only the entity `key` unless
+   * you remember to opt in to data with `withAttributes()`/`withMetadata()`/`withPayload()`, which
+   * is an easy mistake. `select()` makes the selection explicit. This method remains for backwards
+   * compatibility and will be removed in a future release.
+   *
    * @returns A QueryBuilder instance for building and executing queries. {@link QueryBuilder}
    *
    * @example
@@ -200,6 +265,7 @@ export function publicArkivActions<
     getEntity: (key: Hex) => getEntity(client, key),
     query: (rawQuery: string, queryOptions?: QueryOptions) => query(client, rawQuery, queryOptions),
     buildQuery: () => new QueryBuilder(client),
+    select: (selection?: SelectArg) => new SelectQueryBuilder(client, selection),
     getBlockTiming: () => getBlockTiming(client),
     getEntityCount: () => getEntityCount(client),
     subscribeEntityEvents: (

package/src/index.ts

@@ -2,9 +2,6 @@
  * @module main
  */
 
-// Re-export all viem stuff
-export * from "viem"
-
 // export main arkiv stuff
 export type { ArkivClient } from "./clients/baseClient"
 export type { PublicArkivClient } from "./clients/createPublicClient"

package/src/query/engine.ts

@@ -55,6 +55,11 @@ export async function processQuery(
     withAttributes?: boolean | undefined
     withMetadata?: boolean | undefined
     withPayload?: boolean | undefined
+    /**
+     * Fully-resolved include-data for fine-grained selection. When provided it takes
+     * precedence over the `withAttributes`/`withMetadata`/`withPayload` booleans.
+     */
+    includeData?: RpcIncludeData | undefined
   },
 ) {
   const {
@@ -68,6 +73,7 @@ export async function processQuery(
     withAttributes,
     withMetadata,
     withPayload,
+    includeData,
   } = queryParams
 
   logger("Processing query with params %o", {
@@ -81,6 +87,7 @@ export async function processQuery(
     withAttributes,
     withMetadata,
     withPayload,
+    includeData,
   })
 
   let query = processPredicates(predicates)
@@ -98,19 +105,21 @@ export async function processQuery(
   }
 
   const queryOptions: RpcQueryOptions = {
-    includeData: {
-      key: true,
-      attributes: withAttributes ?? false,
-      payload: withPayload ?? false,
-      contentType: withMetadata ?? false,
-      expiration: withMetadata ?? false,
-      owner: withMetadata ?? false,
-      creator: withMetadata ?? false,
-      createdAtBlock: withMetadata ?? false,
-      lastModifiedAtBlock: withMetadata ?? false,
-      transactionIndexInBlock: withMetadata ?? false,
-      operationIndexInTransaction: withMetadata ?? false,
-    } as RpcIncludeData,
+    includeData:
+      includeData ??
+      ({
+        key: true,
+        attributes: withAttributes ?? false,
+        payload: withPayload ?? false,
+        contentType: withMetadata ?? false,
+        expiration: withMetadata ?? false,
+        owner: withMetadata ?? false,
+        creator: withMetadata ?? false,
+        createdAtBlock: withMetadata ?? false,
+        lastModifiedAtBlock: withMetadata ?? false,
+        transactionIndexInBlock: withMetadata ?? false,
+        operationIndexInTransaction: withMetadata ?? false,
+      } as RpcIncludeData),
   }
 
   if (validAtBlock !== undefined) {

package/src/query/index.ts

@@ -1,3 +1,4 @@
 export * from "./predicate"
 export * from "./queryBuilder"
 export * from "./queryResult"
+export * from "./selection"

package/src/query/queryBuilder.ts

@@ -1,10 +1,12 @@
 import type { Hex } from "viem"
 import type { ArkivClient } from "../clients/baseClient"
-import type { RpcOrderByAttribute } from "../types/rpcSchema"
+import type { Entity } from "../types/entity"
+import type { RpcEntity, RpcIncludeData, RpcOrderByAttribute } from "../types/rpcSchema"
 import { entityFromRpcResult } from "../utils/entities"
 import { processQuery } from "./engine"
 import type { Predicate } from "./predicate"
 import { QueryResult } from "./queryResult"
+import { type SelectArg, selectionToIncludeData } from "./selection"
 
 export type OrderByAttribute = {
   name: string
@@ -45,24 +47,37 @@ export function desc(attributeName: string, attributeType: "string" | "number"):
     order: "desc",
   }
 }
+
 /**
- * QueryBuilder is a helper class to build queries to the Arkiv DBChains.
- * It can be used to fetch entities from the Arkiv DBChains. It follows the Builder pattern allowing chaining of methods.
- * @param client - The Arkiv client
- * @returns The QueryBuilder instance {@link QueryBuilder}
+ * Data-selection parameters forwarded to the query engine on each fetch.
+ * Subclasses of {@link BaseQueryBuilder} decide which parts of an entity are fetched.
  */
-export class QueryBuilder {
-  private _client: ArkivClient
-  private _ownedBy: Hex | undefined
-  private _createdBy: Hex | undefined
-  private _orderBy: RpcOrderByAttribute[] | undefined
-  private _validAtBlock: bigint | undefined
-  private _withAttributes: boolean | undefined
-  private _withMetadata: boolean | undefined
-  private _withPayload: boolean | undefined
-  private _limit: number | undefined
-  private _cursor: string | undefined
-  private _predicates: Predicate[]
+type SelectionParams = {
+  withAttributes?: boolean | undefined
+  withMetadata?: boolean | undefined
+  withPayload?: boolean | undefined
+  includeData?: RpcIncludeData | undefined
+}
+
+/**
+ * BaseQueryBuilder holds the query-building logic shared by every query builder
+ * (filtering, ordering, pagination, execution). It follows the Builder pattern,
+ * allowing methods to be chained. Subclasses decide how data selection is expressed
+ * by implementing the protected `selectionParams` method.
+ *
+ * Use {@link SelectQueryBuilder} via `client.select()` to build and execute queries.
+ *
+ * @typeParam TEntity - The shape of each entity produced by {@link BaseQueryBuilder.fetch}.
+ */
+export abstract class BaseQueryBuilder<TEntity> {
+  protected _client: ArkivClient
+  protected _ownedBy: Hex | undefined
+  protected _createdBy: Hex | undefined
+  protected _orderBy: RpcOrderByAttribute[] | undefined
+  protected _validAtBlock: bigint | undefined
+  protected _limit: number | undefined
+  protected _cursor: string | undefined
+  protected _predicates: Predicate[]
 
   constructor(client: ArkivClient) {
     this._client = client
@@ -72,13 +87,13 @@ export class QueryBuilder {
   /**
    * Sets the ownedBy filter
    * @param ownedBy - The address of the owner
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * builder.ownedBy("0x1234567890123456789012345678901234567890")
    */
-  ownedBy(ownedBy: Hex) {
+  ownedBy(ownedBy: Hex): this {
     this._ownedBy = ownedBy
     return this
   }
@@ -86,13 +101,13 @@ export class QueryBuilder {
   /**
    * Sets the createdBy filter
    * @param createdBy - The address of the creator
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * builder.createdBy("0x1234567890123456789012345678901234567890")
    */
-  createdBy(createdBy: Hex) {
+  createdBy(createdBy: Hex): this {
     this._createdBy = createdBy
     return this
   }
@@ -105,10 +120,10 @@ export class QueryBuilder {
    * @param attributeName - The name of the attribute to order by
    * @param attributeType - The type of the attribute to order by (string or number)
    * @param order - The order to set the order by (asc or desc)
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = client.buildQuery()
+   * const builder = client.select()
    * builder.orderBy("name", "string", "desc")
    * builder.orderBy(asc("name", "string"))
    * builder.orderBy(desc("name", "string"))
@@ -119,10 +134,10 @@ export class QueryBuilder {
    * This method takes the OrderByAttribute object as an argument and is mainly
    * used to use the helper functions asc() and desc() to create the OrderByAttribute instances.
    * @param orderByAttribute - The OrderByAttribute instance to set
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * builder.orderBy(asc("name", "string"))
    * builder.orderBy(desc("name", "string"))
    */
@@ -131,7 +146,7 @@ export class QueryBuilder {
     attributeNameOrOrderByAttribute: string | OrderByAttribute,
     attributeType?: "string" | "number",
     order: "asc" | "desc" = "asc",
-  ) {
+  ): this {
     if (!this._orderBy) {
       this._orderBy = []
     }
@@ -160,58 +175,16 @@ export class QueryBuilder {
     return this
   }
 
-  /**
-   * Sets the withAttributes flag which will return the attributes for the entities if true
-   * @param withAttributes - The boolean value to set
-   * @returns The QueryBuilder instance
-   *
-   * @example
-   * const builder = new QueryBuilder(client)
-   * builder.withAttributes(true)
-   */
-  withAttributes(withAttributes: boolean = true) {
-    this._withAttributes = withAttributes
-    return this
-  }
-
-  /**
-   * Sets the withMetadata flag which will return the metadata (like owner, expiredAt, etc.) for the entities if true
-   * @param withMetadata - The boolean value to set
-   * @returns The QueryBuilder instance
-   *
-   * @example
-   * const builder = new QueryBuilder(client)
-   * builder.withMetadata(true)
-   */
-  withMetadata(withMetadata: boolean = true) {
-    this._withMetadata = withMetadata
-    return this
-  }
-
-  /**
-   * Sets the withPayload flag which will return the payload for the entities if true
-   * @param withPayload - The boolean value to set
-   * @returns The QueryBuilder instance
-   *
-   * @example
-   * const builder = new QueryBuilder(client)
-   * builder.withPayload(true)
-   */
-  withPayload(withPayload: boolean = true) {
-    this._withPayload = withPayload
-    return this
-  }
-
   /**
    * Sets the limit for the query
    * @param limit - The number of entities to return
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * builder.limit(10)
    */
-  limit(limit: number) {
+  limit(limit: number): this {
     this._limit = limit
     return this
   }
@@ -219,13 +192,13 @@ export class QueryBuilder {
   /**
    * Sets the cursor for the query - it is advances setting which rather shouldn't be used manually but it is provided from query result if limit is used (pagination).
    * @param cursor - The cursor to set which tells to RPC Query server where to start or continue the query.
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
-   * builder.offset(10)
+   * const builder = client.select()
+   * builder.cursor("0xABC123")
    */
-  cursor(cursor: string) {
+  cursor(cursor: string): this {
     this._cursor = cursor
     return this
   }
@@ -234,13 +207,13 @@ export class QueryBuilder {
    * Sets the validAtBlock for the query which tells at which block height the state we are intested.
    * If not set, the latest block is  used.
    * @param validAtBlock - The block number to set
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * builder.validAtBlock(10000)
    */
-  validAtBlock(validAtBlock: bigint) {
+  validAtBlock(validAtBlock: bigint): this {
     this._validAtBlock = validAtBlock
     return this
   }
@@ -249,10 +222,10 @@ export class QueryBuilder {
    * Sets the predicates for the query limiting the results. It can be a single predicate or an array of predicates combined with 'and'.
    * Predicates can be nested using 'or' and 'and' predicates.
    * @param predicates - The predicates to set
-   * @returns The QueryBuilder instance
+   * @returns The query builder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * builder.where(eq("name", "John"))
    * builder.where([eq("name", "John"), eq("age", 30)])
    * builder.where([eq("name", "John"), or([eq("age", 30), eq("age", 31)])])
@@ -261,7 +234,7 @@ export class QueryBuilder {
    * builder.where([eq("name", "John"), and([eq("age", 30), or([eq("age", 31), eq("age", 32)])])])
    * builder.where([eq("name", "John"), and([eq("age", 30), or([eq("age", 31), and([eq("age", 32), eq("age", 33)])])])])
    */
-  where(predicates: Predicate[] | Predicate) {
+  where(predicates: Predicate[] | Predicate): this {
     if (Array.isArray(predicates)) {
       this._predicates.push(...predicates)
     } else {
@@ -271,16 +244,28 @@ export class QueryBuilder {
   }
 
   /**
-   * Fetches the entities from the query. Re
+   * Returns the data-selection parameters forwarded to the query engine.
+   * Subclasses decide which parts of an entity are fetched.
+   */
+  protected abstract selectionParams(): SelectionParams
+
+  /**
+   * Builds a single result entity from a raw RPC entity. Subclasses decide the produced shape
+   * (a full {@link Entity}, or a projected object inferred from the selection).
+   */
+  protected abstract projectEntity(rpcEntity: RpcEntity): TEntity | Promise<TEntity>
+
+  /**
+   * Fetches the entities from the query.
    * It will return a QueryResult instance which can be used to fetch the next and previous pages.
    * @returns The QueryResult instance {@link QueryResult}
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * const result = await builder.where(eq("name", "John")).fetch()
    * // result = { entities: [Entity, Entity, Entity], next: async () => QueryResult, previous: async () => QueryResult }
    */
-  async fetch() {
+  async fetch(): Promise<QueryResult<TEntity>> {
     const queryResult = await processQuery(this._client, {
       predicates: this._predicates,
       limit: this._limit,
@@ -289,19 +274,15 @@ export class QueryBuilder {
       createdBy: this._createdBy,
       orderBy: this._orderBy,
       validAtBlock: this._validAtBlock,
-      withAttributes: this._withAttributes,
-      withMetadata: this._withMetadata,
-      withPayload: this._withPayload,
+      ...this.selectionParams(),
     })
 
-    const entities = await Promise.all(
-      queryResult.data.map((entity) => entityFromRpcResult(entity)),
-    )
+    const entities = await Promise.all(queryResult.data.map((entity) => this.projectEntity(entity)))
 
     this.cursor(queryResult.cursor)
     this.validAtBlock(BigInt(queryResult.blockNumber ?? 0))
 
-    return new QueryResult(entities, this, this._cursor, this._limit, this._validAtBlock)
+    return new QueryResult<TEntity>(entities, this, this._cursor, this._limit, this._validAtBlock)
   }
 
   /**
@@ -309,7 +290,7 @@ export class QueryBuilder {
    * @returns The number of entities
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.select()
    * const result = await builder.where(eq("name", "John")).count()
    * // result = 10
    */
@@ -330,3 +311,117 @@ export class QueryBuilder {
     return queryResult.data.length ?? 0
   }
 }
+
+/**
+ * QueryBuilder is a helper class to build queries to the Arkiv DBChains.
+ * It can be used to fetch entities from the Arkiv DBChains. It follows the Builder pattern allowing chaining of methods.
+ *
+ * By default the result includes only the entity `key`. Additional data is opt-in through
+ * `withAttributes()`, `withMetadata()` and `withPayload()`.
+ *
+ * @deprecated Use {@link SelectQueryBuilder} via `client.select()` instead. Declaring the
+ * selection up front avoids the common mistake of forgetting to opt in to data and getting back
+ * entities with only their `key` populated. This class remains for backwards compatibility and
+ * will be removed in a future release.
+ *
+ * @param client - The Arkiv client
+ * @returns The QueryBuilder instance {@link QueryBuilder}
+ */
+export class QueryBuilder extends BaseQueryBuilder<Entity> {
+  private _withAttributes: boolean | undefined
+  private _withMetadata: boolean | undefined
+  private _withPayload: boolean | undefined
+
+  /**
+   * Sets the withAttributes flag which will return the attributes for the entities if true
+   * @param withAttributes - The boolean value to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = client.buildQuery()
+   * builder.withAttributes(true)
+   */
+  withAttributes(withAttributes: boolean = true): this {
+    this._withAttributes = withAttributes
+    return this
+  }
+
+  /**
+   * Sets the withMetadata flag which will return the metadata (like owner, expiredAt, etc.) for the entities if true
+   * @param withMetadata - The boolean value to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = client.buildQuery()
+   * builder.withMetadata(true)
+   */
+  withMetadata(withMetadata: boolean = true): this {
+    this._withMetadata = withMetadata
+    return this
+  }
+
+  /**
+   * Sets the withPayload flag which will return the payload for the entities if true
+   * @param withPayload - The boolean value to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = client.buildQuery()
+   * builder.withPayload(true)
+   */
+  withPayload(withPayload: boolean = true): this {
+    this._withPayload = withPayload
+    return this
+  }
+
+  protected selectionParams(): SelectionParams {
+    return {
+      withAttributes: this._withAttributes,
+      withMetadata: this._withMetadata,
+      withPayload: this._withPayload,
+    }
+  }
+
+  protected projectEntity(rpcEntity: RpcEntity): Promise<Entity> {
+    return entityFromRpcResult(rpcEntity)
+  }
+}
+
+/**
+ * SelectQueryBuilder is the recommended query builder. It requires the selection to be declared
+ * up front, so results always contain exactly the data you asked for — and the type of each
+ * returned entity is narrowed to exactly the selected fields.
+ *
+ * The selection is fixed at construction time and is flat — each field maps to an entity field.
+ * Create one via `client.select(...)` rather than constructing it directly, so the result type is
+ * inferred from the selection.
+ *
+ * @typeParam TEntity - The projected entity shape, inferred from the selection by `client.select()`.
+ *
+ * @example
+ * // everything
+ * await client.select().where(eq("name", "John")).fetch()
+ * await client.select("*").where(eq("name", "John")).fetch()
+ * // specific fields
+ * await client.select({ owner: true, attributes: true }).fetch()
+ * // a single field — result is typed (flat) { owner: Hex }
+ * await client.select({ owner: true }).fetch()
+ */
+export class SelectQueryBuilder<TEntity> extends BaseQueryBuilder<TEntity> {
+  private _includeData: RpcIncludeData
+
+  constructor(client: ArkivClient, selection?: SelectArg) {
+    super(client)
+    this._includeData = selectionToIncludeData(selection)
+  }
+
+  protected selectionParams(): SelectionParams {
+    return { includeData: this._includeData }
+  }
+
+  protected async projectEntity(rpcEntity: RpcEntity): Promise<TEntity> {
+    // The runtime value is a full Entity (with methods); the static type is narrowed to the
+    // selected fields via `client.select()`'s inference.
+    return (await entityFromRpcResult(rpcEntity)) as unknown as TEntity
+  }
+}

package/src/query/queryResult.ts

@@ -1,20 +1,26 @@
 import { NoCursorOrLimitError, NoMoreResultsError } from "../errors"
 import type { Entity } from "../types/entity"
 import { getLogger } from "../utils/logger"
-import type { QueryBuilder } from "./queryBuilder"
+import type { BaseQueryBuilder } from "./queryBuilder"
 
 const logger = getLogger("query:result")
 
-export class QueryResult {
-  entities: Entity[]
+/**
+ * The result of a query. Holds the fetched entities and supports cursor-based pagination.
+ *
+ * @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).
+ */
+export class QueryResult<TEntity = Entity> {
+  entities: TEntity[]
   private _endOfIteration: boolean
   private _cursor: string | undefined
   private _limit: number | undefined
   private _validAtBlock: bigint | undefined
-  private _queryBuilder: QueryBuilder
+  private _queryBuilder: BaseQueryBuilder<TEntity>
 
   // Public getters for internal state
-  get queryBuilder(): QueryBuilder {
+  get queryBuilder(): BaseQueryBuilder<TEntity> {
     return this._queryBuilder
   }
 
@@ -23,8 +29,8 @@ export class QueryResult {
   }
 
   constructor(
-    entities: Entity[],
-    queryBuilder: QueryBuilder,
+    entities: TEntity[],
+    queryBuilder: BaseQueryBuilder<TEntity>,
     cursor: string | undefined,
     limit: number | undefined,
     validAtBlock: bigint | undefined,