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

package/dist/index.js

@@ -1,13 +1,12 @@
 import { t as chains_exports } from "./chains-DmrgfF3p.js";
-import { A as DECIMAL_UNIT, C as str, E as u64, F as TooManyAttributesError, I as UnknownAttributeTypeError, L as UntypedValueError, M as InvalidAttributeNameError, N as InvalidValueError, O as isArkivValue, P as MissingValueError, S as key, T as u256, _ as bytes32, a as MAX_NAME_BYTES, b as decUnits, d as I32_MIN, f as MAX_STRING_BYTES, g as bool, h as addr, i as encodeMutations, j as ConflictingMutationError, k as DECIMAL_SCALE, m as U64_MAX, n as MAX_PAYLOAD_BYTES, o as isValidAttributeName, p as U256_MAX, r as encodeAttributes, s as validateAttributeName, t as MAX_ATTRIBUTES, u as I32_MAX, v as dec, w as toValue, x as i32, y as decFromUnits } from "./attr-tmyREHtw.js";
-import { C as EntityMutationError, D as getLogger, E as NoMoreResultsError, S as EmptyPatchError, T as NoEntityFoundError, a as eq, r as toRpcSelect, t as SelectQueryBuilder, v as runQuery, w as InvalidContentTypeError } from "./query-Ber-lOJQ.js";
+import { D as SYSTEM_FIELDS, E as encodeCreationFlags, F as getLogger, M as EntityMutationError, N as NoEntityFoundError, O as projectSelection, P as NoMoreResultsError, T as decodeCreationFlags, b as runQuery, j as EmptyPatchError, k as toRow, r as CountQueryBuilder, t as SelectQueryBuilder, w as entityFromRpcResult } from "./query-DpRDozmj.js";
+import { A as key, B as DECIMAL_SCALE, C as bool, D as decFromUnits, E as dec, F as isColumn, G as InvalidValueError, H as ConflictingMutationError, I as INDEXED_FLAG, J as SchemaMismatchError, K as MissingValueError, M as toValue, N as u256, O as decUnits, P as u64, R as isArkivValue, S as addr, T as bytes32, U as EntityTooLargeError, V as DECIMAL_UNIT, W as InvalidAttributeNameError, X as UnknownAttributeTypeError, Y as TooManyAttributesError, Z as UntypedValueError, _ as I32_MIN, a as SCHEMA_ATTRIBUTE, b as U256_MAX, c as isSchema, d as isValidAttributeName, f as validateAttributeName, g as I32_MAX, h as decodeTypeId, i as MAX_ATTRIBUTES, j as str, k as i32, l as lookupColumn, n as encodeCreate, o as defineSchema, q as SchemaDefinitionError, r as encodePatch, s as describeColumns, t as MAX_ENTITY_BYTES, u as MAX_NAME_BYTES, v as MAX_BYTES_LENGTH, w as bytes, x as U64_MAX, y as MAX_STRING_BYTES } from "./schema-DY4sqehl.js";
 import { i as NoRandomSourceError, n as InvalidExpiryError, r as InvalidSaltError, t as InvalidCreationFlagsError } from "./errors-D2E1GRjw.js";
-import { n as encodeCreationFlags, t as decodeCreationFlags } from "./flags-DUT2gHEU.js";
-import { t as Entity } from "./entity-BIp_df9u.js";
-import { a as OperationType, i as MAX_EXPIRES_AT, n as resolveExpiry, o as ARKIV_ADDRESS, r as toBlocks, s as BLOCK_TIME } from "./expiry-Cgdb_dbq.js";
-import { a as randomSalt, i as predictEntityKey, n as MAX_SALT, o as resolveSalt, r as NO_SALT, t as ENTITY_EVENTS_ABI } from "./entity-CniBgBSd.js";
+import { t as Entity } from "./entity-CFAI1KyG.js";
+import { i as BLOCK_TIME, n as OperationType, r as ARKIV_ADDRESS, t as MAX_EXPIRES_AT } from "./params-DDJOnsNi.js";
+import { a as randomSalt, i as predictEntityKey, n as MAX_SALT, o as resolveSalt, r as NO_SALT, t as ENTITY_EVENTS_ABI } from "./entity-CGqx_AU0.js";
+import { n as resolveExpiry, t as ExpirationTime } from "./expirationTime-UKPuA-LM.js";
 import "./types-Bx1EKe0v.js";
-import { n as stringToPayload, r as ExpirationTime, t as jsonToPayload } from "./payload-DE7wMztL.js";
 import { BaseError, ContractFunctionExecutionError, ContractFunctionRevertedError, TransactionExecutionError, createClient, decodeEventLog, encodeAbiParameters, hexToString, parseAbi, parseAbiParameters, publicActions, walletActions } from "viem";
 import { getChainId, readContract } from "viem/actions";
 
@@ -28,35 +27,15 @@ async function getBlockTiming(client) {
 
 //#endregion
 //#region src/actions/public/getEntity.ts
-/**
-* Reads one entity by key, with every field selected.
-*
-* Returns a {@link FullEntity} rather than an {@link Entity}: the selection is fixed at `"*"`, so
-* every field is populated and none of them needs a `?` at the call site. The bare `Entity` type
-* has every field optional because a `select()` result carries only what it asked for.
-*
-* @throws {InvalidValueError} If the key is not 32 bytes.
-* @throws {NoEntityFoundError} If no live entity has that key — it never existed, or it was
-* deleted or has expired.
-*/
-async function getEntity(client, entityKey) {
-	const { entities } = await runQuery(client, {
-		query: eq("$key", key(entityKey)).toString(),
-		select: toRpcSelect("*"),
-		limit: 1
-	});
-	const entity = entities[0];
-	if (entity === void 0) throw new NoEntityFoundError(entityKey);
-	return entity;
-}
-
-//#endregion
-//#region src/actions/public/getEntityCount.ts
-async function getEntityCount(client) {
-	return await client.request({
-		method: "arkiv_getEntityCount",
-		params: []
+async function getEntity(client, entityKey, schema) {
+	if (schema !== void 0 && !isSchema(schema)) throw new SchemaDefinitionError("getEntity() takes a schema built with defineSchema(...)");
+	const projection = projectSelection("*", schema);
+	const rpcEntity = await client.request({
+		method: "arkiv_getEntity",
+		params: [key(entityKey).value]
 	});
+	if (rpcEntity === null) throw new NoEntityFoundError(entityKey);
+	return toRow(entityFromRpcResult(rpcEntity), projection);
 }
 
 //#endregion
@@ -189,18 +168,19 @@ async function getEntityNonce(client, owner) {
 * @returns One `{ key, salt }` pair per create, in batch order. {@link PredictEntityKeysReturnType}
 *
 * @example A batch whose second entity points at its first.
-* import { key } from "@arkiv-network/sdk/attr"
+* import { defineSchema, key, str } from "@arkiv-network/sdk/schema"
+*
+* const Nodes = defineSchema("nodes", { name: str(), parent: key().indexed().optional() })
 *
 * const [parent, child] = await client.predictEntityKeys({ owner: account.address, count: 2 })
-* await client.executeBatch({
+* await wallet.executeBatch({
 *   creates: [
-*     { payload, contentType, expires, salt: parent.salt },
+*     { schema: Nodes, values: { name: "root" }, expiration, salt: parent.salt },
 *     {
-*       payload,
-*       contentType,
-*       expires,
+*       schema: Nodes,
+*       values: { name: "leaf", parent: key(parent.key) },
+*       expiration,
 *       salt: child.salt,
-*       attributes: { parent: key(parent.key) },
 *     },
 *   ],
 * })
@@ -235,20 +215,31 @@ function resolveSalts(count, salts) {
 /**
 * Runs a single query and returns one page, with no builder in between.
 *
+* The selection means what it does in `select()`, and each result is the same flat row a query
+* without a schema returns — typed from the selection, with every attribute an `ArkivValue` or
+* `undefined`.
+*
 * Takes either an {@link Expression} or a raw query string. The string form is an escape hatch for
 * a query built elsewhere — it goes to the node exactly as written, with none of the name, type or
 * operator checks the expression combinators apply.
 *
+* @throws If the selection asks for nothing, or names an attribute outside the name grammar.
 * @throws {QueryError} If the node rejects the query.
 */
-function query(client, query$1, options = {}) {
-	return runQuery(client, {
+async function query(client, query$1, options = {}) {
+	const projection = projectSelection(options.select);
+	const page = await runQuery(client, {
 		query: query$1.toString(),
-		select: toRpcSelect(options.select),
+		select: projection.select,
 		limit: options.limit,
 		cursor: options.cursor,
-		atBlock: options.atBlock
+		atBlock: options.atBlock,
+		count: options.count
 	});
+	return {
+		...page,
+		entities: page.entities.map((entity) => toRow(entity, projection))
+	};
 }
 
 //#endregion
@@ -406,11 +397,11 @@ function toEntityEvent(topics, data, context) {
 //#region src/clients/decorators/arkivPublic.ts
 function publicArkivActions(client) {
 	return {
-		getEntity: (key$1) => getEntity(client, key$1),
-		query: (rawQuery, queryOptions) => query(client, rawQuery, queryOptions),
-		select: (selection) => new SelectQueryBuilder(client, selection),
+		getEntity: ((key$1, schema) => getEntity(client, key$1, schema)),
+		query: ((rawQuery, queryOptions) => query(client, rawQuery, queryOptions)),
+		select: ((selection) => new SelectQueryBuilder(client, selection)),
+		count: () => new CountQueryBuilder(client),
 		getBlockTiming: () => getBlockTiming(client),
-		getEntityCount: () => getEntityCount(client),
 		getEntityNonce: (owner) => getEntityNonce(client, owner),
 		predictEntityKeys: (parameters) => predictEntityKeys(client, parameters),
 		watchEntityEvents: (parameters) => watchEntityEvents(client, parameters)
@@ -479,10 +470,10 @@ function explain(name, args) {
 			return `an attribute name holds ${printable(String(args[1] ?? "0x00"))} at byte ${position}, which is outside the name charset (${CHARSET})`;
 		}
 		case "Ident32Empty": return "an attribute name is empty";
-		case "SystemAttributeNotWritable": return `"${identName(args[0])}" is owned by the engine and cannot be written. Only $payload and \$contentType are yours to set`;
+		case "SystemAttributeNotWritable": return `"${identName(args[0])}" is owned by the engine and cannot be written. Names starting with "\$" are reserved for system attributes`;
 		case "TombstoneInCreate": return `a create cannot unset "${identName(args[0])}" — nothing exists yet, so leave the name out instead`;
 		case "TombstoneValueNotEmpty": return `the tombstone for "${identName(args[0])}" carries a value; unsetting takes no value`;
-		case "InvalidValueType": return `"${identName(args[0])}" names type id ${String(args[1])}, which is not a known type`;
+		case "InvalidValueType": return describeInvalidType(identName(args[0]), Number(args[1]));
 		case "AttributesNotSorted": return "attributes must be strictly ascending by name, which also makes each name unique";
 		case "TooManyAttributes": return `${String(args[0])} attributes exceeds the limit of ${String(args[1])}`;
 		case "EmptyMutations": return `the patch of ${short(args[0])} has no mutations, so it would do nothing`;
@@ -501,6 +492,19 @@ function explain(name, args) {
 		default: return;
 	}
 }
+/**
+* Why the engine refused a `typeId` — an indexed `bytes`, a known type it would not take (most
+* likely the indexed flag, on a node that predates it), or a type it does not know.
+*/
+function describeInvalidType(name, typeId) {
+	try {
+		const { tag, indexed } = decodeTypeId(typeId);
+		if (tag === "bytes" && indexed) return `"${name}" is a bytes attribute flagged as indexed, and bytes are stored but never indexed`;
+		if (indexed) return `"${name}" has type ${tag} and is flagged as indexed (type id ${typeId}), which the node does not accept. The node may not support the indexed flag yet`;
+		return `"${name}" has type ${tag} (type id ${typeId}), which the node does not accept`;
+	} catch {}
+	return `"${name}" names type id ${typeId}, which is not a known type`;
+}
 /** A `bytes32` Ident32 cell as the name it holds — left-aligned, null-padded. */
 function identName(raw) {
 	if (typeof raw !== "string") return String(raw);
@@ -525,10 +529,6 @@ function printable(byte) {
 //#endregion
 //#region src/utils/arkivTransactions.ts
 const logger$6 = getLogger("utils:arkiv-transactions");
-const MIME_REGEX = /^[a-z][a-z0-9!#$&\-^_]*\/[a-z0-9][a-z0-9!#$&\-^_.+]*$/;
-function validateContentType(contentType) {
-	if (!MIME_REGEX.test(contentType)) throw new InvalidContentTypeError(contentType);
-}
 const ENTITY_ERRORS_ABI = parseAbi([
 	"error EmptyBatch()",
 	"error InvalidOpType(uint8 operation)",
@@ -558,30 +558,29 @@ async function sendArkivTransaction(client, ops, txParams) {
 	if (!client.chain) throw new Error("Chain required");
 	const walletClient = client;
 	const { creates, patches, deletes, extensions, ownershipChanges } = ops;
-	const expiryContext = { currentBlock: creates?.length || extensions?.length ? await walletClient.getBlockNumber() : 0n };
-	const createOps = (creates ?? []).map((item) => {
-		validateContentType(item.contentType);
-		return createOperation({
-			salt: item.salt === void 0 ? randomSalt() : resolveSalt(item.salt),
-			expiry: resolveExpiry(item.expires, expiryContext),
-			creationFlags: encodeCreationFlags(item.flags),
-			attributes: encodeAttributes(item.attributes, {
-				payload: item.payload,
-				contentType: item.contentType
-			})
-		});
-	});
+	const encodedCreates = (creates ?? []).map((item) => ({
+		item,
+		attributes: encodeCreate(item.schema, item.values)
+	}));
 	const patchOps = (patches ?? []).map((item) => {
-		if (item.contentType !== void 0) validateContentType(item.contentType);
-		const mutations = encodeMutations(item);
+		const mutations = encodePatch(item.schema, item);
 		if (mutations.length === 0) throw new EmptyPatchError(item.entityKey);
 		return patchOperation({
 			entityKey: item.entityKey,
 			mutations
 		});
 	});
+	const expiryContext = { currentBlock: creates?.length || extensions?.length ? await walletClient.getBlockNumber() : 0n };
+	const createOps = encodedCreates.map(({ item, attributes }) => {
+		return createOperation({
+			salt: item.salt === void 0 ? randomSalt() : resolveSalt(item.salt),
+			expiry: resolveExpiry(item.expiration, expiryContext),
+			creationFlags: encodeCreationFlags(item.flags),
+			attributes
+		});
+	});
 	const extendOps = (extensions ?? []).map((item) => {
-		const expiry = resolveExpiry(item.expires, expiryContext);
+		const expiry = resolveExpiry(item.expiration, expiryContext);
 		return extendExpiryOperation({
 			entityKey: item.entityKey,
 			expiry
@@ -716,9 +715,13 @@ async function changeOwnership(client, data, txParams) {
 //#endregion
 //#region src/actions/wallet/createEntity.ts
 const logger$4 = getLogger("actions:wallet:create-entity");
-async function createEntity(client, data, txParams) {
-	logger$4("createEntity %o", data);
-	const { receipt, createdEntityKeys, createdExpiries } = await sendArkivTransaction(client, { creates: [data] }, txParams);
+async function createEntity(client, schema, values, options, txParams) {
+	logger$4("createEntity %o", values);
+	const { receipt, createdEntityKeys, createdExpiries } = await sendArkivTransaction(client, { creates: [{
+		...options,
+		schema,
+		values
+	}] }, txParams);
 	logger$4("Receipt from createEntity %o", receipt);
 	const [entityKey] = createdEntityKeys;
 	const [expiresAt] = createdExpiries;
@@ -778,13 +781,17 @@ async function extendEntity(client, data, txParams) {
 //#endregion
 //#region src/actions/wallet/patchEntity.ts
 const logger = getLogger("actions:wallet:patch-entity");
-async function patchEntity(client, data, txParams) {
-	logger("patchEntity %o", data);
-	const { receipt } = await sendArkivTransaction(client, { patches: [data] }, txParams);
+async function patchEntity(client, schema, entityKey, changes, txParams) {
+	logger("patchEntity %s %o", entityKey, changes);
+	const { receipt } = await sendArkivTransaction(client, { patches: [{
+		...changes,
+		schema,
+		entityKey
+	}] }, txParams);
 	logger("Receipt from patchEntity %o", receipt);
 	return {
 		txHash: receipt.transactionHash,
-		entityKey: data.entityKey
+		entityKey
 	};
 }
 
@@ -792,8 +799,8 @@ async function patchEntity(client, data, txParams) {
 //#region src/clients/decorators/arkivWallet.ts
 function walletArkivActions(client) {
 	return {
-		createEntity: (data, txParams) => createEntity(client, data, txParams),
-		patchEntity: (data, txParams) => patchEntity(client, data, txParams),
+		createEntity: (schema, values, options, txParams) => createEntity(client, schema, values, options, txParams),
+		patchEntity: (schema, entityKey, changes, txParams) => patchEntity(client, schema, entityKey, changes, txParams),
 		deleteEntity: (data, txParams) => deleteEntity(client, data, txParams),
 		extendEntity: (data, txParams) => extendEntity(client, data, txParams),
 		changeOwnership: (data, txParams) => changeOwnership(client, data, txParams),
@@ -809,7 +816,10 @@ function walletArkivActions(client) {
 *
 * A Wallet Client signs and sends transactions, so it carries an `account` and exposes everything
 * that mutates state — `createEntity`, `patchEntity`, `deleteEntity`, `extendEntity`,
-* `changeOwnership` and `executeBatch` — on top of the read actions a Public Client has.
+* `changeOwnership` and `executeBatch` — alongside the viem actions those need, such as
+* `getBlockNumber`, `readContract` and `waitForTransactionReceipt`. It does not have the Arkiv
+* read actions (`getEntity`, `query`, `select`, `watchEntityEvents`, `predictEntityKeys`); read
+* through a Public Client from `createPublicClient` for those.
 *
 * @param parameters - Configuration object for the wallet client (chain, transport, account, etc.)
 * @returns An Arkiv Wallet Client. {@link WalletArkivClient}
@@ -851,5 +861,5 @@ function chainFromName(name) {
 }
 
 //#endregion
-export { ConflictingMutationError, DECIMAL_SCALE, DECIMAL_UNIT, ENTITY_EVENTS_ABI, EmptyPatchError, Entity, EntityMutationError, ExpirationTime, I32_MAX, I32_MIN, InvalidAttributeNameError, InvalidContentTypeError, InvalidCreationFlagsError, InvalidExpiryError, InvalidSaltError, InvalidValueError, MAX_ATTRIBUTES, MAX_EXPIRES_AT, MAX_NAME_BYTES, MAX_PAYLOAD_BYTES, MAX_SALT, MAX_STRING_BYTES, MissingValueError, NO_SALT, NoEntityFoundError, NoMoreResultsError, NoRandomSourceError, OperationType, SelectQueryBuilder, TooManyAttributesError, U256_MAX, U64_MAX, UnknownAttributeTypeError, UntypedValueError, addr, bool, bytes32, chainFromName, createPublicClient, createWalletClient, dec, decFromUnits, decUnits, decodeCreationFlags, encodeCreationFlags, i32, isArkivValue, isValidAttributeName, jsonToPayload, key, predictEntityKey, randomSalt, resolveExpiry, str, stringToPayload, toBlocks, toValue, u256, u64, validateAttributeName };
+export { ConflictingMutationError, CountQueryBuilder, DECIMAL_SCALE, DECIMAL_UNIT, ENTITY_EVENTS_ABI, EmptyPatchError, Entity, EntityMutationError, EntityTooLargeError, ExpirationTime, I32_MAX, I32_MIN, INDEXED_FLAG, InvalidAttributeNameError, InvalidCreationFlagsError, InvalidExpiryError, InvalidSaltError, InvalidValueError, MAX_ATTRIBUTES, MAX_BYTES_LENGTH, MAX_ENTITY_BYTES, MAX_EXPIRES_AT, MAX_NAME_BYTES, MAX_SALT, MAX_STRING_BYTES, MissingValueError, NO_SALT, NoEntityFoundError, NoMoreResultsError, NoRandomSourceError, SCHEMA_ATTRIBUTE, SYSTEM_FIELDS, SchemaDefinitionError, SchemaMismatchError, SelectQueryBuilder, TooManyAttributesError, U256_MAX, U64_MAX, UnknownAttributeTypeError, UntypedValueError, addr, bool, bytes, bytes32, chainFromName, createPublicClient, createWalletClient, dec, decFromUnits, decUnits, defineSchema, describeColumns, i32, isArkivValue, isColumn, isSchema, isValidAttributeName, key, lookupColumn, predictEntityKey, randomSalt, str, toValue, u256, u64, validateAttributeName };
 //# sourceMappingURL=index.js.map