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

package/dist/{queryBuilder-DM-YO1Y7.cjs → queryBuilder-CTPwve9u.cjs}

@@ -1,3 +1,4 @@
+const require_consts = require('./consts-AUoL-v42.cjs');
 let viem = require("viem");
 
 //#region src/utils/logger.ts
@@ -120,6 +121,18 @@ 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 (${require_consts.BLOCK_TIME} seconds), because expiration is measured in whole blocks (1 block = ${require_consts.BLOCK_TIME} seconds).`);
+		this.name = "InvalidExpirationError";
+	}
+};
+var InvalidAttributeError = class extends Error {
+	constructor(key, value) {
+		super(`Invalid numeric value for attribute "${key}": ${String(value)}. Numeric attribute values must be integers. 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)}").`);
+		this.name = "InvalidAttributeError";
+	}
+};
 var NoMoreResultsError = class extends Error {
 	constructor() {
 		super("No more results");
@@ -235,7 +248,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 +259,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 +302,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 +345,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
 /**
@@ -360,20 +427,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 +452,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 +465,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 +495,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 +510,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,10 +524,10 @@ 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) {
@@ -509,10 +538,10 @@ var QueryBuilder = class {
 	* 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)])])
@@ -527,12 +556,12 @@ var QueryBuilder = class {
 		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 +574,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 +586,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,14 +605,134 @@ 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
+Object.defineProperty(exports, 'BaseQueryBuilder', {
+  enumerable: true,
+  get: function () {
+    return BaseQueryBuilder;
+  }
+});
 Object.defineProperty(exports, 'EntityMutationError', {
   enumerable: true,
   get: function () {
     return EntityMutationError;
   }
 });
+Object.defineProperty(exports, 'InvalidAttributeError', {
+  enumerable: true,
+  get: function () {
+    return InvalidAttributeError;
+  }
+});
+Object.defineProperty(exports, 'InvalidExpirationError', {
+  enumerable: true,
+  get: function () {
+    return InvalidExpirationError;
+  }
+});
 Object.defineProperty(exports, 'NoCursorOrLimitError', {
   enumerable: true,
   get: function () {
@@ -616,6 +763,12 @@ Object.defineProperty(exports, 'QueryResult', {
     return QueryResult;
   }
 });
+Object.defineProperty(exports, 'SelectQueryBuilder', {
+  enumerable: true,
+  get: function () {
+    return SelectQueryBuilder;
+  }
+});
 Object.defineProperty(exports, 'asc', {
   enumerable: true,
   get: function () {
@@ -639,4 +792,10 @@ Object.defineProperty(exports, 'getLogger', {
   get: function () {
     return getLogger;
   }
+});
+Object.defineProperty(exports, 'selectionToIncludeData', {
+  enumerable: true,
+  get: function () {
+    return selectionToIncludeData;
+  }
 });