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

package/dist/{query-BhdmAzYg.d.ts → entity-CHiZ2Qu1.d.ts}

@@ -81,6 +81,30 @@ type GetBlockTimingReturnType = {
   blockDuration: number;
 };
 //#endregion
+//#region src/actions/public/query.d.ts
+type QueryOptionsIncludeData = {
+  attributes?: boolean;
+  payload?: boolean;
+  metadata?: boolean;
+};
+type QueryOptionsOrderBy = {
+  name: string;
+  type: "string" | "numeric";
+  desc: "asc" | "desc";
+};
+type QueryOptions = {
+  includeData?: QueryOptionsIncludeData;
+  atBlock?: bigint;
+  orderBy?: QueryOptionsOrderBy[];
+  resultsPerPage?: number | undefined;
+  cursor?: string | undefined;
+};
+type QueryReturnType = {
+  entities: Entity[];
+  cursor: string | undefined;
+  blockNumber: bigint | undefined;
+};
+//#endregion
 //#region src/actions/wallet/changeOwnership.d.ts
 /**
  * Parameters for the deleteEntity function.
@@ -104,14 +128,24 @@ type ChangeOwnershipReturnType = {
 /**
  * Parameters for the createEntity function.
  * - payload: The payload of the entity.
- * - attributes: The attributes of the entity.
+ * - attributes: The attributes of the entity. Attribute values may be strings
+ *   or numbers, but numeric values **must be integers**. To store a non-integer,
+ *   scale it to an integer (e.g. `1.5` -> `1500`) to preserve numeric ordering,
+ *   or pass it as a string (e.g. `"1.5"`). A non-integer numeric value throws an
+ *   {@link InvalidAttributeError}.
  * - contentType: The content type of the entity.
- * - expiresIn: The expires in of the entity in seconds.
+ * - expiresIn: How long until the entity expires, in seconds. Because Arkiv
+ *   measures expiration in blocks (1 block = 2 seconds), this **must be a
+ *   positive integer and a multiple of the block time (2 seconds)**
+ *   Invalid values throw an {@link InvalidExpirationError}.
  */
 type CreateEntityParameters = {
   payload: Uint8Array;
+  /** Entity attributes. Numeric values must be integers (scale non-integers, e.g. `1.5` -> `1500`, or use a string). Throws {@link InvalidAttributeError} otherwise. */
   attributes: Attribute[];
   contentType: MimeType | string;
+  /** Seconds until expiry. Must be a positive integer and a multiple of the 2s block time.
+   * Throws {@link InvalidExpirationError} otherwise. */
   expiresIn: number;
 };
 /**
@@ -146,10 +180,15 @@ type DeleteEntityReturnType = {
 /**
  * Parameters for the extendEntity function.
  * - entityKey: The key of the entity to extend.
- * - expiresIn: The expires in of the entity in seconds.
+ * - expiresIn: How long to extend the entity by, in seconds. Because Arkiv
+ *   measures expiration in blocks (1 block = 2 seconds), this **must be a
+ *   positive integer and a multiple of the block time (2 seconds)**.
+ *   Invalid values throw an {@link InvalidExpirationError}.
  */
 type ExtendEntityParameters = {
   entityKey: Hex;
+  /** Seconds to extend by. Must be a positive integer and a multiple of the 2s block time.
+   * Throws {@link InvalidExpirationError} otherwise. */
   expiresIn: number;
 };
 /**
@@ -167,15 +206,25 @@ type ExtendEntityReturnType = {
  * Parameters for the updateEntity function.
  * - entityKey: The key of the entity to update.
  * - payload: The payload of the entity.
- * - attributes: The attributes of the entity.
+ * - attributes: The attributes of the entity. Attribute values may be strings
+ *   or numbers, but numeric values **must be integers**. To store a non-integer,
+ *   scale it to an integer (e.g. `1.5` -> `1500`) to preserve numeric ordering,
+ *   or pass it as a string (e.g. `"1.5"`). A non-integer numeric value throws an
+ *   {@link InvalidAttributeError}.
  * - contentType: The content type of the entity.
- * - expiresIn: The expires in of the entity in seconds.
+ * - expiresIn: How long until the entity expires, in seconds. Because Arkiv
+ *   measures expiration in blocks (1 block = 2 seconds), this **must be a
+ *   positive integer and a multiple of the block time (2 seconds)**.
+ *   Invalid values throw an {@link InvalidExpirationError}.
  */
 type UpdateEntityParameters = {
   entityKey: Hex;
   payload: Uint8Array;
+  /** Entity attributes. Numeric values must be integers (scale non-integers, e.g. `1.5` -> `1500`, or use a string). Throws {@link InvalidAttributeError} otherwise. */
   attributes: Attribute[];
   contentType: MimeType | string;
+  /** Seconds until expiry. Must be a positive integer and a multiple of the 2s block time.
+   * Throws {@link InvalidExpirationError} otherwise. */
   expiresIn: number;
 };
 /**
@@ -222,8 +271,20 @@ type MutateEntitiesReturnType = {
 };
 //#endregion
 //#region src/types/attributes.d.ts
+/**
+ * An entity attribute (key/value pair).
+ *
+ * Arkiv supports both string and number values. Numeric values **must be
+ * integers** — passing a non-integer number (e.g. `1.5`) throws an
+ * {@link InvalidAttributeError} at mutation time. To store a non-integer value:
+ * - Scale it to an integer (e.g. `1.5` -> `1500`, dividing by the same factor on
+ *   read) to keep numeric ordering and range queries working.
+ * - Or pass it as a string (e.g. `"1.5"`), which sorts lexicographically and so
+ *   does not support numeric comparisons.
+ */
 type Attribute = {
   key: string;
+  /** Attribute value. A `number` must be an integer (scale non-integers, e.g. `1.5` -> `1500`, or use a string). Throws {@link InvalidAttributeError} otherwise. */
   value: string | number;
 };
 //#endregion
@@ -307,29 +368,5 @@ declare class Entity {
   toJson(): any;
 }
 //#endregion
-//#region src/actions/public/query.d.ts
-type QueryOptionsIncludeData = {
-  attributes?: boolean;
-  payload?: boolean;
-  metadata?: boolean;
-};
-type QueryOptionsOrderBy = {
-  name: string;
-  type: "string" | "numeric";
-  desc: "asc" | "desc";
-};
-type QueryOptions = {
-  includeData?: QueryOptionsIncludeData;
-  atBlock?: bigint;
-  orderBy?: QueryOptionsOrderBy[];
-  resultsPerPage?: number | undefined;
-  cursor?: string | undefined;
-};
-type QueryReturnType = {
-  entities: Entity[];
-  cursor: string | undefined;
-  blockNumber: bigint | undefined;
-};
-//#endregion
-export { RpcIncludeData as A, CreateEntityReturnType as C, ArkivClient as D, GetBlockTimingReturnType as E, RpcQueryOptions as M, MimeType as N, ArkivRpcSchema as O, CreateEntityParameters as S, ChangeOwnershipReturnType as T, UpdateEntityReturnType as _, Entity as a, DeleteEntityParameters as b, OnEntityDeletedEvent as c, OnEntityOwnerChangedEvent as d, OnEntityUpdatedEvent as f, UpdateEntityParameters as g, MutateEntitiesReturnType as h, QueryReturnType as i, RpcOrderByAttribute as j, RpcEntity as k, OnEntityExpiredEvent as l, MutateEntitiesParameters as m, QueryOptionsIncludeData as n, TxParams as o, Attribute as p, QueryOptionsOrderBy as r, OnEntityCreatedEvent as s, QueryOptions as t, OnEntityExpiresInExtendedEvent as u, ExtendEntityParameters as v, ChangeOwnershipParameters as w, DeleteEntityReturnType as x, ExtendEntityReturnType as y };
-//# sourceMappingURL=query-BhdmAzYg.d.ts.map
+export { RpcIncludeData as A, QueryOptionsIncludeData as C, ArkivClient as D, GetBlockTimingReturnType as E, RpcQueryOptions as M, MimeType as N, ArkivRpcSchema as O, QueryOptions as S, QueryReturnType as T, DeleteEntityReturnType as _, OnEntityExpiredEvent as a, ChangeOwnershipParameters as b, OnEntityUpdatedEvent as c, MutateEntitiesReturnType as d, UpdateEntityParameters as f, DeleteEntityParameters as g, ExtendEntityReturnType as h, OnEntityDeletedEvent as i, RpcOrderByAttribute as j, RpcEntity as k, Attribute as l, ExtendEntityParameters as m, TxParams as n, OnEntityExpiresInExtendedEvent as o, UpdateEntityReturnType as p, OnEntityCreatedEvent as r, OnEntityOwnerChangedEvent as s, Entity as t, MutateEntitiesParameters as u, CreateEntityParameters as v, QueryOptionsOrderBy as w, ChangeOwnershipReturnType as x, CreateEntityReturnType as y };
+//# sourceMappingURL=entity-CHiZ2Qu1.d.ts.map

package/dist/entity-CHiZ2Qu1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-CHiZ2Qu1.d.ts","names":[],"sources":["../src/types/mimeTypes.ts","../src/types/rpcSchema.ts","../src/clients/baseClient.ts","../src/actions/public/getBlockTiming.ts","../src/actions/public/query.ts","../src/actions/wallet/changeOwnership.ts","../src/actions/wallet/createEntity.ts","../src/actions/wallet/deleteEntity.ts","../src/actions/wallet/extendEntity.ts","../src/actions/wallet/updateEntity.ts","../src/actions/wallet/mutateEntities.ts","../src/types/attributes.ts","../src/types/events.ts","../src/types/txParams.ts","../src/types/entity.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/{queryBuilder-BvoQXa_u.d.ts → index-CzqHiUAo.d.ts}

@@ -1,4 +1,4 @@
-import { D as ArkivClient, a as Entity } from "./query-BhdmAzYg.js";
+import { A as RpcIncludeData, D as ArkivClient, j as RpcOrderByAttribute, k as RpcEntity, t as Entity } from "./entity-CHiZ2Qu1.js";
 import { Hex } from "viem";
 
 //#region src/query/predicate.d.ts
@@ -114,20 +114,79 @@ declare function lte(key: string, value: string | number): Predicate;
 declare function not(key: string): Predicate;
 //#endregion
 //#region src/query/queryResult.d.ts
-declare 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).
+ */
+declare class QueryResult<TEntity = Entity> {
+  entities: TEntity[];
   private _endOfIteration;
   private _cursor;
   private _limit;
   private _validAtBlock;
   private _queryBuilder;
-  get queryBuilder(): QueryBuilder;
+  get queryBuilder(): BaseQueryBuilder<TEntity>;
   get cursor(): string | undefined;
-  constructor(entities: Entity[], queryBuilder: QueryBuilder, cursor: string | undefined, limit: number | undefined, validAtBlock: bigint | undefined);
+  constructor(entities: TEntity[], queryBuilder: BaseQueryBuilder<TEntity>, cursor: string | undefined, limit: number | undefined, validAtBlock: bigint | undefined);
   next(): Promise<void>;
   hasNextPage(): boolean;
 }
 //#endregion
+//#region src/query/selection.d.ts
+/** 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";
+/**
+ * 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.
+ */
+type SelectionFields = { [K in DataKey]?: boolean };
+/**
+ * Requires at least one property of `T` to be present.
+ * `{}` is not assignable, which is how `select({})` is rejected at compile time.
+ */
+type AtLeastOne<T, K$1 extends keyof T = keyof T> = { [P in K$1]: Required<Pick<T, P>> & Partial<Omit<T, P>> }[K$1];
+/**
+ * A non-empty entity selection — the object form accepted by `select()`. At least one field must be
+ * selected.
+ */
+type EntitySelection = AtLeastOne<SelectionFields>;
+/** Argument accepted by `select()` — a non-empty {@link EntitySelection}, or `"*"` for everything. */
+type SelectArg = EntitySelection | "*";
+/**
+ * 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.
+ *
+ * The `toText()` / `toJson()` helpers operate on the payload, so they are only present when
+ * `payload` was selected — calling them otherwise would always throw.
+ */
+type ProjectedEntity<S> = { readonly [K in keyof S as 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 };
+/** The projected entity type when everything is selected — every field, plus the methods. */
+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.
+ * `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
+ *
+ * @example
+ * selectionToIncludeData() // everything
+ * selectionToIncludeData("*") // everything
+ * selectionToIncludeData({ key: true }) // only the key
+ * selectionToIncludeData({ owner: true }) // only the owner
+ */
+declare function selectionToIncludeData(selection?: SelectArg): RpcIncludeData;
+//#endregion
 //#region src/query/queryBuilder.d.ts
 type OrderByAttribute = {
   name: string;
@@ -155,41 +214,52 @@ declare function asc(attributeName: string, attributeType: "string" | "number"):
  */
 declare function desc(attributeName: string, attributeType: "string" | "number"): OrderByAttribute;
 /**
- * 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.
  */
-declare class QueryBuilder {
-  private _client;
-  private _ownedBy;
-  private _createdBy;
-  private _orderBy;
-  private _validAtBlock;
-  private _withAttributes;
-  private _withMetadata;
-  private _withPayload;
-  private _limit;
-  private _cursor;
-  private _predicates;
+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}.
+ */
+declare 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);
   /**
    * 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): this;
   /**
    * 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): this;
@@ -201,10 +271,10 @@ declare 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"))
@@ -215,72 +285,42 @@ declare 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"))
    */
   orderBy(orderByAttribute: OrderByAttribute): 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): 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): 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): 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): this;
   /**
    * 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): this;
   /**
    * 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): this;
@@ -288,10 +328,10 @@ declare 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)])])
@@ -302,27 +342,115 @@ declare class QueryBuilder {
    */
   where(predicates: Predicate[] | Predicate): this;
   /**
-   * 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 }
    */
-  fetch(): Promise<QueryResult>;
+  fetch(): Promise<QueryResult<TEntity>>;
   /**
    * Counts the entities from the query.
    * @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
    */
   count(): Promise<number>;
 }
+/**
+ * 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}
+ */
+declare class QueryBuilder extends BaseQueryBuilder<Entity> {
+  private _withAttributes;
+  private _withMetadata;
+  private _withPayload;
+  /**
+   * 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): 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): 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): this;
+  protected selectionParams(): SelectionParams;
+  protected projectEntity(rpcEntity: RpcEntity): Promise<Entity>;
+}
+/**
+ * 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()
+ */
+declare class SelectQueryBuilder<TEntity> extends BaseQueryBuilder<TEntity> {
+  private _includeData;
+  constructor(client: ArkivClient, selection?: SelectArg);
+  protected selectionParams(): SelectionParams;
+  protected projectEntity(rpcEntity: RpcEntity): Promise<TEntity>;
+}
 //#endregion
-export { or as _, QueryResult as a, PredicateType as c, gt as d, gte as f, not as g, neq as h, desc as i, and as l, lte as m, QueryBuilder as n, Predicate as o, lt as p, asc as r, PredicateContainerType as s, OrderByAttribute as t, eq as u };
-//# sourceMappingURL=queryBuilder-BvoQXa_u.d.ts.map
+export { neq as C, lte as S, or as T, and as _, asc as a, gte as b, FullEntity as c, SelectionFields as d, selectionToIncludeData as f, PredicateType as g, PredicateContainerType as h, SelectQueryBuilder as i, ProjectedEntity as l, Predicate as m, OrderByAttribute as n, desc as o, QueryResult as p, QueryBuilder as r, EntitySelection as s, BaseQueryBuilder as t, SelectArg as u, eq as v, not as w, lt as x, gt as y };
+//# sourceMappingURL=index-CzqHiUAo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-CzqHiUAo.d.ts","names":[],"sources":["../src/query/predicate.ts","../src/query/queryResult.ts","../src/query/selection.ts","../src/query/queryBuilder.ts"],"sourcesContent":[],"mappings":"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"}