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

package/dist/{queryBuilder-DonAg1aq.js → queryBuilder-BE_XhLLa.js}

@@ -1,4 +1,6 @@
-import { bytesToString, hexToNumber, numberToHex, toBytes } from "viem";
+import { n as BLOCK_TIME } from "./consts-Bz0LZQZY.js";
+import { t as Entity } from "./entity-DGfVyB-a.js";
+import { hexToNumber, isHex, numberToHex, toBytes } from "viem";
 
 //#region src/utils/logger.ts
 const ROOT_NAMESPACE = "arkiv";
@@ -120,6 +122,31 @@ var EntityMutationError = class extends Error {
 		this.name = "EntityMutationError";
 	}
 };
+var InvalidExpirationError = class extends Error {
+	constructor(expiresIn) {
+		super(`Invalid expiresIn: ${String(expiresIn)}. expiresIn must be a positive integer and a multiple of the Arkiv block time (${BLOCK_TIME} seconds), because expiration is measured in whole blocks (1 block = ${BLOCK_TIME} seconds).`);
+		this.name = "InvalidExpirationError";
+	}
+};
+var InvalidAttributeError = class extends Error {
+	constructor(key, value) {
+		const remedy = Number.isInteger(value) ? `Offset it into the non-negative range (e.g. store ${String(value)} + OFFSET, subtracting OFFSET on read) to keep numeric ordering/range queries; otherwise store it as a string (e.g. "${String(value)}")` : `To keep numeric ordering/range queries, scale it to an integer (e.g. Math.round(${String(value)} * 1000), dividing by 1000 on read); otherwise store it as a string (e.g. "${String(value)}")`;
+		super(`Invalid numeric value for attribute "${key}": ${String(value)}. Numeric attribute values must be non-negative integers (stored on-chain as unsigned 256-bit). ${remedy}.`);
+		this.name = "InvalidAttributeError";
+	}
+};
+var InvalidAttributeKeyError = class extends Error {
+	constructor(key, reason) {
+		super(`Invalid attribute key "${key}": ${reason}. Keys must be 1-32 bytes, start with a lowercase letter (a-z), and contain only a-z, 0-9, ".", "-" or "_".`);
+		this.name = "InvalidAttributeKeyError";
+	}
+};
+var DuplicateAttributeError = class extends Error {
+	constructor(key) {
+		super(`Duplicate attribute key "${key}". Attribute keys must be unique per entity.`);
+		this.name = "DuplicateAttributeError";
+	}
+};
 var NoMoreResultsError = class extends Error {
 	constructor() {
 		super("No more results");
@@ -138,85 +165,102 @@ var NoEntityFoundError = class extends Error {
 		this.name = "NoEntityFoundError";
 	}
 };
-
-//#endregion
-//#region src/types/entity.ts
-var Entity = class {
-	key;
-	contentType;
-	owner;
-	creator;
-	expiresAtBlock;
-	createdAtBlock;
-	lastModifiedAtBlock;
-	transactionIndexInBlock;
-	operationIndexInTransaction;
-	payload;
-	attributes;
-	constructor(key, contentType = void 0, owner = void 0, creator = void 0, expiresAtBlock = void 0, createdAtBlock = void 0, lastModifiedAtBlock = void 0, transactionIndexInBlock = void 0, operationIndexInTransaction = void 0, payload = void 0, attributes) {
-		this.key = key;
-		this.owner = owner;
-		this.creator = creator;
-		this.expiresAtBlock = expiresAtBlock;
-		this.createdAtBlock = createdAtBlock;
-		this.lastModifiedAtBlock = lastModifiedAtBlock;
-		this.transactionIndexInBlock = transactionIndexInBlock;
-		this.operationIndexInTransaction = operationIndexInTransaction;
-		this.payload = payload;
-		this.attributes = attributes;
-		this.contentType = contentType;
-	}
-	/**
-	* Converts the entity payload from bytes to a string and returns it.
-	* Throws an error if the payload is undefined, which may occur if the entity was not queried with the withPayload option.
-	* Throws an error if the conversion from bytes to string fails.
-	* @returns The entity payload as a string.
-	*/
-	toText() {
-		if (this.payload === void 0) throw new Error("Entity has no payload – it was probably queried without withPayload(true) via QueryBuilder");
-		try {
-			return bytesToString(this.payload);
-		} catch (e) {
-			throw new Error(`Failed to convert entity payload to text: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
-		}
-	}
-	/**
-	* Parses the entity payload as JSON and returns the resulting object.
-	* Throws an error if the payload is undefined, which may occur if the entity was not queried with the withPayload option.
-	* Throws an error if the payload is empty or cannot be parsed as JSON.
-	* @returns The parsed JSON object from the entity payload.
-	*/
-	toJson() {
-		const text = this.toText();
-		if (!text) throw new Error("Entity has empty payload, cannot parse as JSON");
-		try {
-			return JSON.parse(text);
-		} catch (e) {
-			throw new Error(`Failed to parse entity payload as JSON: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
-		}
+var InvalidContentTypeError = class extends Error {
+	constructor(contentType) {
+		super(`Invalid content type "${contentType}". Must follow RFC 2045 MIME grammar and be lowercase only (e.g. "text/plain").`);
+		this.name = "InvalidContentTypeError";
 	}
 };
 
+//#endregion
+//#region src/types/rpcSchema.ts
+let RpcAttributeValueType = /* @__PURE__ */ function(RpcAttributeValueType$1) {
+	RpcAttributeValueType$1[RpcAttributeValueType$1["Uint"] = 1] = "Uint";
+	RpcAttributeValueType$1[RpcAttributeValueType$1["String"] = 2] = "String";
+	RpcAttributeValueType$1[RpcAttributeValueType$1["EntityKey"] = 3] = "EntityKey";
+	return RpcAttributeValueType$1;
+}({});
+
 //#endregion
 //#region src/utils/entities.ts
+function decodeAttributeValue(value, valueType) {
+	switch (valueType) {
+		case RpcAttributeValueType.Uint: return Number(BigInt(value));
+		case RpcAttributeValueType.EntityKey: return value;
+		case RpcAttributeValueType.String:
+		default: return value;
+	}
+}
 const logger$2 = getLogger("utils:entities");
 async function entityFromRpcResult(rpcEntity) {
 	logger$2("entityFromRpcResult %o", rpcEntity);
-	return new Entity(rpcEntity.key, rpcEntity.contentType, rpcEntity.owner, rpcEntity.creator, rpcEntity.expiresAt !== void 0 ? BigInt(rpcEntity.expiresAt) : void 0, rpcEntity.createdAtBlock !== void 0 ? BigInt(rpcEntity.createdAtBlock) : void 0, rpcEntity.lastModifiedAtBlock !== void 0 ? BigInt(rpcEntity.lastModifiedAtBlock) : void 0, rpcEntity.transactionIndexInBlock !== void 0 ? BigInt(rpcEntity.transactionIndexInBlock) : void 0, rpcEntity.operationIndexInTransaction !== void 0 ? BigInt(rpcEntity.operationIndexInTransaction) : void 0, rpcEntity.value !== void 0 ? toBytes(rpcEntity.value) : void 0, [...(rpcEntity.stringAttributes ?? []).map(({ key, value }) => ({
-		key,
-		value
-	})), ...(rpcEntity.numericAttributes ?? []).map(({ key, value }) => ({
+	return new Entity(rpcEntity.key, rpcEntity.contentType, rpcEntity.owner, rpcEntity.creator, rpcEntity.expiresAt !== void 0 ? BigInt(rpcEntity.expiresAt) : void 0, rpcEntity.createdAtBlock !== void 0 ? BigInt(rpcEntity.createdAtBlock) : void 0, rpcEntity.lastModifiedAtBlock !== void 0 ? BigInt(rpcEntity.lastModifiedAtBlock) : void 0, rpcEntity.transactionIndexInBlock !== void 0 ? BigInt(rpcEntity.transactionIndexInBlock) : void 0, rpcEntity.operationIndexInTransaction !== void 0 ? BigInt(rpcEntity.operationIndexInTransaction) : void 0, rpcEntity.value !== void 0 ? toBytes(rpcEntity.value) : void 0, [...(rpcEntity.attributes ?? []).map(({ key, value, valueType }) => ({
 		key,
-		value: Number(value)
+		value: decodeAttributeValue(value, valueType)
 	}))]);
 }
 
+//#endregion
+//#region src/utils/validation.ts
+/**
+* True only for hex strings that are exactly 32 bytes (an entity key). This is
+* the single rule deciding whether an attribute string value is stored as the
+* on-chain `EntityKey` type or as a plain string — the query engine applies
+* the same rule, so equality comparisons agree with storage on both paths.
+* Hex-looking strings of any other length are treated as ordinary strings.
+*/
+function isEntityKey(value) {
+	return isHex(value) && value.length === 66;
+}
+/**
+* Expiration on Arkiv is measured in blocks (1 block =
+* 2 seconds), so the value must be a positive integer that is
+* a multiple of the block time.
+*
+* @param expiresIn - The expiration in seconds.
+* @throws {InvalidExpirationError} If the value is not a positive integer that
+* is a multiple of the block time.
+*/
+function validateExpiresIn(expiresIn) {
+	if (!Number.isInteger(expiresIn) || expiresIn <= 0 || expiresIn % BLOCK_TIME !== 0) throw new InvalidExpirationError(expiresIn);
+}
+/**
+* Validates an attribute key against the on-chain `Ident32` rules (mirrors
+* `Ident32.sol` / `validate_ident32_bytes` in the node): non-empty, at most
+* 32 bytes, leading character `a-z`, remaining characters `a-z 0-9 . - _`.
+*
+* @param key - The attribute key to validate.
+* @throws {InvalidAttributeKeyError} If the key violates the `Ident32` rules.
+*/
+function validateAttributeKey(key) {
+	if (key.length === 0) throw new InvalidAttributeKeyError(key, "key is empty");
+	if (!/^[a-z]/.test(key)) throw new InvalidAttributeKeyError(key, `key starts with "${key[0]}"`);
+	const invalid = key.match(/[^a-z0-9._-]/);
+	if (invalid) throw new InvalidAttributeKeyError(key, `key contains "${invalid[0]}" at position ${invalid.index}`);
+	if (key.length > 32) throw new InvalidAttributeKeyError(key, `key is ${key.length} bytes long`);
+}
+/**
+* Validates a single attribute. Keys must follow the on-chain `Ident32` rules
+* (see {@link validateAttributeKey}). Arkiv supports string and number
+* attribute values, but numeric values must be non-negative integers — they
+* are stored on-chain as unsigned 256-bit values.
+*
+* @param attribute - The attribute to validate.
+* @throws {InvalidAttributeKeyError} If the key violates the `Ident32` rules.
+* @throws {InvalidAttributeError} If the attribute has a non-integer or
+* negative numeric value.
+*/
+function validateAttribute(attribute) {
+	validateAttributeKey(attribute.key);
+	if (typeof attribute.value === "number" && (!Number.isInteger(attribute.value) || attribute.value < 0)) throw new InvalidAttributeError(attribute.key, attribute.value);
+}
+
 //#endregion
 //#region src/query/engine.ts
 const logger$1 = getLogger("query:engine");
 function processPredicates(predicates) {
 	const processValue = (value) => {
-		if (typeof value === "string") return `"${value}"`;
+		if (typeof value === "string") return isEntityKey(value) ? value : `"${value}"`;
 		return value;
 	};
 	return predicates.map((predicate) => {
@@ -235,7 +279,7 @@ function processPredicates(predicates) {
 	}).join(" && ");
 }
 async function processQuery(client, queryParams) {
-	const { predicates, limit, cursor, ownedBy, createdBy, orderBy, validAtBlock, withAttributes, withMetadata, withPayload } = queryParams;
+	const { predicates, limit, cursor, ownedBy, createdBy, orderBy, validAtBlock, withAttributes, withMetadata, withPayload, includeData } = queryParams;
 	logger$1("Processing query with params %o", {
 		predicates,
 		cursor,
@@ -246,14 +290,15 @@ async function processQuery(client, queryParams) {
 		validAtBlock,
 		withAttributes,
 		withMetadata,
-		withPayload
+		withPayload,
+		includeData
 	});
 	let query = processPredicates(predicates);
 	if (ownedBy) query += ` && $owner=${ownedBy}`;
 	if (createdBy) query += ` && $creator=${createdBy}`;
 	query = query.trim();
 	if (query.startsWith("&& ")) query = query.slice(3);
-	const queryOptions = { includeData: {
+	const queryOptions = { includeData: includeData ?? {
 		key: true,
 		attributes: withAttributes ?? false,
 		payload: withPayload ?? false,
@@ -288,6 +333,12 @@ async function processQuery(client, queryParams) {
 //#endregion
 //#region src/query/queryResult.ts
 const logger = getLogger("query:result");
+/**
+* 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).
+*/
 var QueryResult = class {
 	entities;
 	_endOfIteration;
@@ -325,6 +376,53 @@ var QueryResult = class {
 	}
 };
 
+//#endregion
+//#region src/query/selection.ts
+/**
+* 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
+*/
+function selectionToIncludeData(selection) {
+	if (selection === void 0 || selection === "*") return {
+		key: true,
+		attributes: true,
+		payload: true,
+		contentType: true,
+		expiration: true,
+		owner: true,
+		creator: true,
+		createdAtBlock: true,
+		lastModifiedAtBlock: true,
+		transactionIndexInBlock: true,
+		operationIndexInTransaction: true
+	};
+	if (!Object.values(selection).some((selected) => selected === true)) throw new Error("select() requires at least one field to be selected. Pass select() or select(\"*\") to select everything.");
+	return {
+		key: selection.key ?? false,
+		attributes: selection.attributes ?? false,
+		payload: selection.payload ?? false,
+		contentType: selection.contentType ?? false,
+		expiration: selection.expiresAtBlock ?? false,
+		owner: selection.owner ?? false,
+		creator: selection.creator ?? false,
+		createdAtBlock: selection.createdAtBlock ?? false,
+		lastModifiedAtBlock: selection.lastModifiedAtBlock ?? false,
+		transactionIndexInBlock: selection.transactionIndexInBlock ?? false,
+		operationIndexInTransaction: selection.operationIndexInTransaction ?? false
+	};
+}
+
 //#endregion
 //#region src/query/queryBuilder.ts
 /**
@@ -333,6 +431,10 @@ var QueryResult = class {
 * @param attributeType - The type of the attribute to order by (string or number)
 * @returns Input for orderBy method
 *
+* @deprecated Server-side ordering is not supported by the network, so `orderBy` (and this
+* helper) have no effect on the returned order. Sort the fetched entities in JavaScript
+* instead (e.g. `entities.sort(...)`). This function will be removed in a future release.
+*
 * @example
 * const ascAttribute = asc("name", "string")
 */
@@ -349,6 +451,10 @@ function asc(attributeName, attributeType) {
 * @param attributeType - The type of the attribute to order by (string or number)
 * @returns Input for orderBy method
 *
+* @deprecated Server-side ordering is not supported by the network, so `orderBy` (and this
+* helper) have no effect on the returned order. Sort the fetched entities in JavaScript
+* instead (e.g. `entities.sort(...)`). This function will be removed in a future release.
+*
 * @example
 * const descAttribute = desc("name", "string")
 */
@@ -360,20 +466,21 @@ function desc(attributeName, attributeType) {
 	};
 }
 /**
-* 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}
+* 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}.
 */
-var QueryBuilder = class {
+var BaseQueryBuilder = class {
 	_client;
 	_ownedBy;
 	_createdBy;
 	_orderBy;
 	_validAtBlock;
-	_withAttributes;
-	_withMetadata;
-	_withPayload;
 	_limit;
 	_cursor;
 	_predicates;
@@ -384,10 +491,10 @@ var QueryBuilder = class {
 	/**
 	* 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) {
@@ -397,10 +504,10 @@ var QueryBuilder = class {
 	/**
 	* 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) {
@@ -427,51 +534,12 @@ var QueryBuilder = class {
 		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 = 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 = 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 = 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) {
@@ -481,11 +549,11 @@ var QueryBuilder = class {
 	/**
 	* 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) {
 		this._cursor = cursor;
@@ -495,44 +563,27 @@ var QueryBuilder = class {
 	* 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) {
 		this._validAtBlock = validAtBlock;
 		return this;
 	}
-	/**
-	* 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
-	*
-	* @example
-	* const builder = new QueryBuilder(client)
-	* 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)])])
-	* builder.where([eq("name", "John"), and([eq("age", 30), eq("age", 31)])])
-	* builder.where([eq("name", "John"), or([eq("age", 30), and([eq("age", 31), eq("age", 32)])])])
-	* 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) {
-		if (Array.isArray(predicates)) this._predicates.push(...predicates);
-		else this._predicates.push(predicates);
+	where(...predicates) {
+		this._predicates.push(...predicates.flat());
 		return this;
 	}
 	/**
-	* Fetches the entities from the query. Re
+	* 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 }
 	*/
@@ -545,11 +596,9 @@ var QueryBuilder = class {
 			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);
@@ -559,7 +608,7 @@ var QueryBuilder = class {
 	* @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
 	*/
@@ -578,7 +627,109 @@ var QueryBuilder = class {
 		})).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}
+*/
+var QueryBuilder = class extends BaseQueryBuilder {
+	_withAttributes;
+	_withMetadata;
+	_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 = 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 = client.buildQuery()
+	* builder.withMetadata(true)
+	*/
+	withMetadata(withMetadata = 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 = client.buildQuery()
+	* builder.withPayload(true)
+	*/
+	withPayload(withPayload = true) {
+		this._withPayload = withPayload;
+		return this;
+	}
+	selectionParams() {
+		return {
+			withAttributes: this._withAttributes,
+			withMetadata: this._withMetadata,
+			withPayload: this._withPayload
+		};
+	}
+	projectEntity(rpcEntity) {
+		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()
+*/
+var SelectQueryBuilder = class extends BaseQueryBuilder {
+	_includeData;
+	constructor(client, selection) {
+		super(client);
+		this._includeData = selectionToIncludeData(selection);
+	}
+	selectionParams() {
+		return { includeData: this._includeData };
+	}
+	async projectEntity(rpcEntity) {
+		return await entityFromRpcResult(rpcEntity);
+	}
+};
 
 //#endregion
-export { entityFromRpcResult as a, NoEntityFoundError as c, QueryResult as i, NoMoreResultsError as l, asc as n, EntityMutationError as o, desc as r, NoCursorOrLimitError as s, QueryBuilder as t, getLogger as u };
-//# sourceMappingURL=queryBuilder-DonAg1aq.js.map
+export { getLogger as S, InvalidContentTypeError as _, desc as a, NoEntityFoundError as b, isEntityKey as c, entityFromRpcResult as d, RpcAttributeValueType as f, InvalidAttributeKeyError as g, InvalidAttributeError as h, asc as i, validateAttribute as l, EntityMutationError as m, QueryBuilder as n, selectionToIncludeData as o, DuplicateAttributeError as p, SelectQueryBuilder as r, QueryResult as s, BaseQueryBuilder as t, validateExpiresIn as u, InvalidExpirationError as v, NoMoreResultsError as x, NoCursorOrLimitError as y };
+//# sourceMappingURL=queryBuilder-BE_XhLLa.js.map