@arkiv-network/sdk 0.7.0-dev.1 → 0.8.0-advanced.2

package/dist/index-DHDud2hC.d.ts

@@ -0,0 +1,280 @@
+import { R as RpcSelect, i as SelectArg, j as ArkivClient, p as Expression, s as Entity } from "./selection-C4UhsMOO.js";
+import { d as TypeTag } from "./codec-Car3KkFF.js";
+import { Hex } from "viem";
+
+//#region src/query/engine.d.ts
+declare const MAX_LIMIT = 200;
+/** One `arkiv_query` call. */
+type QueryRequest = {
+  /** The query expression, already rendered. */
+  query: string;
+  /** What to return. */
+  select: RpcSelect;
+  /** Page size, up to {@link MAX_LIMIT}. Defaults to the node's own page size. */
+  limit?: number | undefined;
+  /** Cursor from a previous page. */
+  cursor?: string | undefined;
+  /** Block height to read at. Defaults to the head. */
+  atBlock?: bigint | undefined;
+};
+/** One page of results. */
+type QueryResponse = {
+  entities: Entity[];
+  /** The block the page was read at — the same for every page of a paginated query. */
+  blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  cursor: string | undefined;
+};
+/**
+ * Runs one query and decodes the page it returns.
+ *
+ * @throws {QueryError} If the node rejects the query.
+ */
+declare function runQuery(client: ArkivClient, request: QueryRequest): Promise<QueryResponse>;
+//#endregion
+//#region src/query/errors.d.ts
+/**
+ * A predicate asked for an operator the query language does not define for that type.
+ *
+ * The operator × type matrix is part of the language, not a policy: a range comparison on an
+ * equality-only type is a **parse error** at the node, not an empty result. Catching it here turns
+ * a round trip and an RPC error code into a stack trace pointing at the call site.
+ *
+ * | | `=` `!=` | `<` `<=` `>` `>=` | `STARTSWITH` |
+ * | --- | --- | --- | --- |
+ * | `bool` | yes | no | no |
+ * | `i32` `u256` `dec` | yes | yes | no |
+ * | `str` | yes | no | yes |
+ * | `addr` `key` `bytes32` | yes | no | no |
+ */
+declare class UnsupportedOperatorError extends Error {
+  /** The attribute the predicate names. */
+  readonly attributeName: string;
+  /** The operator, as it would have been written in the query. */
+  readonly operator: string;
+  /** The type of the value it was applied to. */
+  readonly tag: TypeTag;
+  constructor(attributeName: string, operator: string, tag: TypeTag, hint?: string);
+}
+/**
+ * A predicate could not be expressed in the query language for a reason other than its operator —
+ * a system attribute that is returned in results but cannot be filtered on, a system attribute
+ * compared against the wrong type, or a combinator with nothing to combine.
+ */
+declare class InvalidPredicateError extends Error {
+  /** The attribute the predicate names, where there is one. */
+  readonly attributeName: string | undefined;
+  constructor(message: string, attributeName?: string);
+}
+/**
+ * What a node rejected a query for. Part of the frozen RPC surface, so it is safe to branch on —
+ * a `"cursor"` failure means start the query again, a `"block"` failure means the node no longer
+ * retains that height, and the rest mean the query itself needs fixing.
+ */
+type QueryErrorKind = /** The query string does not parse. `data` locates it: `{ position, expected, got }`. */
+"parse"
+/** A predicate is well-formed but ill-typed — a range operator on an equality-only type, an unknown tag. */ | "type"
+/** A literal failed validation — an `i32` out of range, a bad EIP-55 checksum, more than 18 decimal places. */ | "literal"
+/** A node budget was exceeded — query length, predicate count, nesting depth, bitmap operations. */ | "limits"
+/** The cursor expired, is malformed, or belongs to a different query, block or selection. */ | "cursor"
+/** `atBlock` is outside the range the node retains. */ | "block";
+/**
+ * The node rejected a query.
+ *
+ * These codes are part of the frozen `arkiv_query` surface, so {@link kind} and {@link data} are
+ * stable enough to branch on — which the underlying JSON-RPC error is not, because the codes
+ * overlap Ethereum's own EIP-1474 numbering and get wrapped accordingly on the way up.
+ *
+ * @example
+ * try {
+ *   await result.next()
+ * } catch (error) {
+ *   if (error instanceof QueryError && error.kind === "cursor") {
+ *     // The page is gone — start the query over.
+ *   }
+ * }
+ */
+declare class QueryError extends Error {
+  /** Which failure this is. */
+  readonly kind: QueryErrorKind;
+  /** The JSON-RPC error code. */
+  readonly code: number;
+  /** The machine-readable detail the node sent, if any — e.g. `{ position, expected, got }`. */
+  readonly data: unknown;
+  /** The query string that was rejected. */
+  readonly query: string;
+  constructor(kind: QueryErrorKind, code: number, query: string, data: unknown, detail?: string);
+}
+//#endregion
+//#region src/query/queryResult.d.ts
+/** Fetches the page a cursor points at. */
+type FetchPage<TEntity> = (cursor: string) => Promise<QueryResult<TEntity>>;
+/**
+ * One page of query results.
+ *
+ * A page is immutable: {@link next} returns the following page rather than mutating this one, so a
+ * page that has been read stays readable.
+ *
+ * @typeParam TEntity - The shape of each entity, inferred from the selection by `client.select()`.
+ *
+ * @example
+ * let page = await client.select({ key: true }).where(eq("category", "docs")).limit(100).fetch()
+ * while (page.hasNextPage()) {
+ *   page = await page.next()
+ * }
+ */
+declare class QueryResult<TEntity = Entity> {
+  /** The entities on this page. */
+  readonly entities: readonly TEntity[];
+  /**
+   * The block this page was read at.
+   *
+   * Every page of one walk reads the same block — the cursor is bound to it — so results cannot
+   * shift under a paginating reader.
+   */
+  readonly blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  readonly cursor: string | undefined;
+  private readonly fetchPage;
+  constructor(entities: readonly TEntity[], blockNumber: bigint, cursor: string | undefined, fetchPage: FetchPage<TEntity>);
+  /**
+   * Whether another page follows.
+   *
+   * The node omits the cursor once nothing remains, so this is an answer rather than the guess a
+   * short final page would be — a full last page is reported correctly.
+   */
+  hasNextPage(): boolean;
+  /**
+   * Fetches the next page.
+   *
+   * @throws {NoMoreResultsError} If this was the last page — check {@link hasNextPage} first.
+   * @throws {QueryError} If the node rejects the request; `kind === "cursor"` means the cursor
+   * expired and the walk has to start again.
+   */
+  next(): Promise<QueryResult<TEntity>>;
+}
+//#endregion
+//#region src/query/queryBuilder.d.ts
+/**
+ * Builds and runs a query.
+ *
+ * The selection is fixed when the builder is created and the filter is added by chaining, so the
+ * result type is known before a single predicate is written. Create one with `client.select(...)`
+ * rather than constructing it directly — that is what infers the entity shape from the selection.
+ *
+ * Every filter added with {@link where}, {@link ownedBy} and {@link createdBy} must hold; use
+ * {@link or} for alternatives inside one call.
+ *
+ * @typeParam TEntity - The projected entity shape, inferred from the selection by `client.select()`.
+ *
+ * @example
+ * import { createPublicClient } from "@arkiv-network/sdk"
+ * import { i32 } from "@arkiv-network/sdk/attr"
+ * import { cheesecake } from "@arkiv-network/sdk/chains"
+ * import { eq, gte, or } from "@arkiv-network/sdk/query"
+ * import { http } from "viem"
+ *
+ * const client = createPublicClient({ chain: cheesecake, transport: http() })
+ *
+ * const page = await client
+ *   .select({ key: true, attributes: true })
+ *   .where(gte("level", i32(10)), or(eq("status", "open"), eq("status", "review")))
+ *   .ownedBy(owner)
+ *   .limit(100)
+ *   .fetch()
+ *
+ * for (const entity of page.entities) console.log(entity.key, entity.attributes)
+ */
+declare class SelectQueryBuilder<TEntity = Entity> {
+  private readonly _client;
+  private readonly _select;
+  private readonly _filters;
+  private _ownedBy;
+  private _createdBy;
+  private _limit;
+  private _cursor;
+  private _atBlock;
+  constructor(client: ArkivClient, selection?: SelectArg);
+  /**
+   * Adds filters. Everything passed here, and across repeated calls, must hold.
+   *
+   * @param expressions - The expressions, as separate arguments or one array.
+   *
+   * @example
+   * builder.where(eq("category", "docs"))
+   * builder.where(gte("level", i32(10)), lt("level", i32(20)))
+   * builder.where(or(eq("status", "open"), not(exists("closedAt"))))
+   */
+  where(expressions: readonly Expression[]): this;
+  where(...expressions: Expression[]): this;
+  /**
+   * Restricts the results to entities this account owns — shorthand for
+   * `where(eq("$owner", addr(owner)))`. Calling it again replaces the filter.
+   *
+   * @example
+   * builder.ownedBy("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+   */
+  ownedBy(owner: Hex): this;
+  /**
+   * Restricts the results to entities this account created — shorthand for
+   * `where(eq("$creator", addr(creator)))`. Calling it again replaces the filter.
+   *
+   * The creator never changes; the owner does, so these differ after a transfer.
+   */
+  createdBy(creator: Hex): this;
+  /**
+   * Sets the page size, up to the node maximum of 200. Without it the node picks the page size.
+   *
+   * @example
+   * builder.limit(100)
+   */
+  limit(limit: number): this;
+  /**
+   * Starts from a cursor returned by an earlier page.
+   *
+   * Pagination normally goes through {@link QueryResult.next}, which carries the cursor for you;
+   * this is for resuming a walk in a later process. A cursor is bound to the query, block and
+   * selection it came from, so it must be used with an identically-built query — {@link atBlock}
+   * set to the `blockNumber` of the page the cursor came from is required (persist the two
+   * together), and a fetch with a cursor but no block rejects locally.
+   */
+  cursor(cursor: string): this;
+  /**
+   * Reads the state as of a given block rather than the head. The block must be within the range
+   * the node retains.
+   *
+   * @example
+   * builder.atBlock(1_297_000n)
+   */
+  atBlock(block: bigint): this;
+  /**
+   * The query string this builder will send — the same text the node parses.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added.
+   */
+  toString(): string;
+  /**
+   * Runs the query and returns the first page.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added.
+   * @throws {QueryError} If the node rejects the query.
+   *
+   * @example
+   * const page = await client.select({ key: true }).where(eq("category", "docs")).fetch()
+   * page.entities        // this page
+   * await page.next()    // the next one
+   */
+  fetch(): Promise<QueryResult<TEntity>>;
+  /**
+   * Walks every page, yielding one entity at a time.
+   *
+   * @example
+   * for await (const entity of client.select({ key: true }).where(eq("category", "docs"))) {
+   *   console.log(entity.key)
+   * }
+   */
+  [Symbol.asyncIterator](): AsyncGenerator<TEntity>;
+}
+//#endregion
+export { QueryErrorKind as a, QueryRequest as c, QueryError as i, QueryResponse as l, QueryResult as n, UnsupportedOperatorError as o, InvalidPredicateError as r, MAX_LIMIT as s, SelectQueryBuilder as t, runQuery as u };
+//# sourceMappingURL=index-DHDud2hC.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-DHDud2hC.d.ts","names":[],"sources":["../src/query/engine.ts","../src/query/errors.ts","../src/query/queryResult.ts","../src/query/queryBuilder.ts"],"sourcesContent":[],"mappings":";;;;;cAUa,SAAA;;AAAA,KAGD,YAAA,GAHU;EAGV;EAcA,KAAA,EAAA,MAAA;EAaU;EAAiB,MAAA,EAvB7B,SAuB6B;EAAsB;EAAuB,KAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAR;EAAO,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;;;ACxBnF;AAMgB,KDKJ,aAAA,GCLI;EAE4C,QAAA,EDIhD,MCJgD,EAAA;EARd;EAAK,WAAA,EAAA,MAAA;EAyBtC;EAgBD,MAAA,EAAA,MAAA,GAAc,SAAA;AAwC1B,CAAA;;;;;;iBDzDsB,QAAA,SAAiB,sBAAsB,eAAe,QAAQ;;;;;;;AA9BpF;AAGA;AAcA;AAaA;;;;;;;cCxBa,wBAAA,SAAiC,KAAA;;EAAjC,SAAA,aAAA,EAAA,MAAyB;EAMtB;EAE4C,SAAA,QAAA,EAAA,MAAA;EARd;EAAK,SAAA,GAAA,EAMnC,OANmC;EAyBtC,WAAA,CAAA,aAAsB,EAAA,MAAA,EAAA,QAAa,EAAA,MAAA,EAAA,GAAA,EAjBY,OAiBZ,EAAA,IAAA,CAAA,EAAA,MAAA;AAgBhD;AAwCA;;;;;cAxDa,qBAAA,SAA8B,KAAA;;;ECrCtC,WAAA,CAAS,OAAA,EAAA,MAAA,EAAA,aAAA,CAAA,EAAA,MAAA;;;;;AAgBd;;AAE8B,KDmClB,cAAA;;+GCSwB;kHAApB;;;ACzBhB,0DAA0C,OAAA;;;;;;;;;;;;;;;;;cFwD7B,UAAA,SAAmB,KAAA;;iBAEf;;;;;;;oBAQG;;;;;KCvGf,yCAAyC,QAAQ,YAAY;;;AFMlE;AAGA;AAcA;AAaA;;;;;;;;;ACxBa,cCIA,WDJyB,CAAA,UCIH,MDJG,CAAA,CAAA;EAMtB;EAE4C,SAAA,QAAA,EAAA,SCF9B,ODE8B,EAAA;EARd;;AAyB9C;AAgBA;AAwCA;;EAUoB,SAAA,WAAA,EAAA,MAAA;EAVY;EAAK,SAAA,MAAA,EAAA,MAAA,GAAA,SAAA;;iCC7Dd,uEAGR,UAAU;;AAtCoB;;;;;EAmBhC,WAAA,CAAA,CAAA,EAAW,OAAA;EAAW;;;;;;;EA8CnB,IAAA,CAAA,CAAA,EAAA,OAAA,CAAQ,WAAR,CAAoB,OAApB,CAAA,CAAA;;;;AFrDhB;AAcA;AAaA;;;;;;;;;ACxBA;;;;;AAyBA;AAgBA;AAwCA;;;;;;;;AChG6C;;;;AAGQ,cCqCxC,kBDrCwC,CAAA,UCqCX,MDrCW,CAAA,CAAA;EAgBxC,iBAAW,OAAA;EAAW,iBAAA,OAAA;EAEL,iBAAA,QAAA;EAcP,QAAA,QAAA;EAGE,QAAA,UAAA;EAAV,QAAA,MAAA;EA2BqB,QAAA,OAAA;EAAZ,QAAA,QAAA;EAAR,WAAA,CAAA,MAAA,ECfM,WDeN,EAAA,SAAA,CAAA,ECf+B,SDe/B;EAAO;;;;ACzBvB;;;;;;EAuCiB,KAAA,CAAA,WAAA,EAAA,SAda,UAcb,EAAA,CAAA,EAAA,IAAA;EAWI,KAAA,CAAA,GAAA,WAAA,EAxBG,UAwBH,EAAA,CAAA,EAAA,IAAA;EAyEgB;;;;;;;iBApFpB;;;;;;;qBAWI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAyEJ,QAAQ,YAAY;;;;;;;;;GAqB3B,MAAA,CAAO,aAAA,KAAkB,eAAe"}

package/dist/index-DvYvrkdk.d.ts

@@ -0,0 +1,320 @@
+import { a as Bytes32Value, c as I32Value, d as TypeTag, f as U256Value, i as BoolValue, l as KeyValue, n as AnyArkivValue, p as U64Value, r as ArkivValue, s as DecValue, t as AddrValue, u as StrValue } from "./codec-Car3KkFF.js";
+import { Hex } from "viem";
+
+//#region src/attr/values.d.ts
+/** The widest `i32`. */
+declare const I32_MAX = 2147483647;
+/** The narrowest `i32`. */
+declare const I32_MIN = -2147483648;
+/** The widest `u64`. */
+declare const U64_MAX: bigint;
+/** The widest `u256`. */
+declare const U256_MAX: bigint;
+/**
+ * The longest `str`, in UTF-8 bytes
+ */
+declare const MAX_STRING_BYTES = 128;
+/**
+ * A boolean.
+ *
+ * `bool` is the one type that may also be written bare — `{ flagged: true }` and
+ * `{ flagged: bool(true) }` are the same attribute.
+ *
+ * @example
+ * bool(true) // { type: "bool", value: true }
+ */
+declare function bool(value: boolean): BoolValue;
+/**
+ * A 32-bit signed integer, indexed for equality and range queries. This is the default type for a
+ * bare number, so `{ level: 10 }` and `{ level: i32(10) }` are the same attribute.
+ *
+ * @param value - An integer in [-2147483648, 2147483647].
+ * @throws {InvalidValueError} If the value is not an integer, or does not fit an `i32`.
+ *
+ * @example
+ * i32(10)   // { type: "i32", value: 10 }
+ * i32(-42)  // negative values are fine — i32 is the signed integer
+ */
+declare function i32(value: number | bigint): I32Value;
+/**
+ * A 256-bit unsigned integer, indexed for equality and range queries. The type for token amounts
+ * and anything else that can outgrow 2⁶⁴ — reach for {@link u64} first for counters, timestamps
+ * and block heights.
+ *
+ * @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
+ * string.
+ * @throws {InvalidValueError} If the value is negative, non-integral, or wider than 256 bits.
+ *
+ * @example
+ * u256(1_000_000n)
+ * u256(Date.now())        // safe integers are accepted
+ * u256("0xf4240")         // hex, as it comes back over JSON-RPC
+ */
+declare function u256(value: bigint | number | string): U256Value;
+/**
+ * A 64-bit unsigned integer, indexed for equality and range queries.
+ *
+ * This is the width the protocol counts in: block heights, `$expiresAt` and the entity-nonce are
+ * all `u64`, so it is the type to reach for when a value has to line up with one of them. Use
+ * {@link u256} for token amounts and anything else that can exceed 2⁶⁴.
+ *
+ * @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
+ * string.
+ * @throws {InvalidValueError} If the value is negative, non-integral, or wider than 64 bits.
+ *
+ * @example
+ * u64(1_200_000n)     // a block height
+ * u64(Date.now())     // safe integers are accepted
+ * u64("0x124f80")     // hex, as it comes back over JSON-RPC
+ */
+declare function u64(value: bigint | number | string): U64Value;
+/**
+ * A signed fixed-point decimal with exactly 18 decimal places, indexed for equality and range
+ * queries.
+ *
+ * Pass fractional values as **strings**. A JavaScript number cannot represent most decimals
+ * exactly, so accepting `dec(0.1 + 0.2)` would quietly store `0.30000000000000004`; requiring the
+ * string keeps what you write and what is stored the same thing. Excess precision is likewise an
+ * error rather than a rounding.
+ *
+ * @param value - A decimal string, or an integral `number` / `bigint`.
+ * @throws {InvalidValueError} If the value is malformed, has more than 18 fractional digits, or
+ * falls outside the `int256` range.
+ *
+ * @example
+ * dec("3.5")
+ * dec("-0.000000000000000001")  // the smallest step
+ * dec(5)                        // integers may be passed bare
+ */
+declare function dec(value: string | number | bigint): DecValue;
+/**
+ * The exact scaled integer behind a `dec` — the value multiplied by 10 ** 18, which is what the
+ * protocol stores and compares. Use it when you need exact arithmetic; JavaScript has no native
+ * decimal type, so the SDK carries the canonical string and leaves the maths to you.
+ *
+ * @example
+ * decUnits(dec("3.5"))  // 3500000000000000000n
+ */
+declare function decUnits(value: DecValue): bigint;
+/**
+ * A `dec` built from its scaled integer units — the inverse of {@link decUnits}.
+ *
+ * @example
+ * decFromUnits(3_500_000_000_000_000_000n)  // dec("3.5")
+ */
+declare function decFromUnits(units: bigint): DecValue;
+/**
+ * A UTF-8 string of at most 128 bytes, indexed for equality and prefix (`STARTSWITH`) matching.
+ *
+ * The limit is on **bytes**, not characters: a string of 128 emoji does not fit.
+ *
+ * @throws {InvalidValueError} If the string exceeds 128 UTF-8 bytes.
+ *
+ * @example
+ * str("Bob")
+ */
+declare function str(value: string): StrValue;
+/**
+ * A 20-byte Ethereum address, indexed for equality.
+ *
+ * All-lowercase and all-uppercase input carries no checksum and is accepted as-is; mixed-case
+ * input is checked against its EIP-55 checksum, so a mistyped address is caught here rather than
+ * being written to a wrong account. The stored value is always EIP-55 checksummed.
+ *
+ * @throws {InvalidValueError} If the value is not 20 hex bytes, or fails its EIP-55 checksum.
+ *
+ * @example
+ * addr("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+ */
+declare function addr(value: string): AddrValue;
+/**
+ * A reference to another entity, indexed for equality.
+ *
+ * References are **weak**: nothing checks that the target exists when you write it, and a
+ * reference to a deleted or expired entity is allowed to dangle.
+ *
+ * @param value - A 32-byte entity key, as `0x` hex or raw bytes.
+ * @throws {InvalidValueError} If the value is not exactly 32 bytes.
+ *
+ * @example
+ * key(parentEntityKey)
+ */
+declare function key(value: Hex | Uint8Array): KeyValue;
+/**
+ * 32 opaque bytes — a hash, a digest, an identifier from another system — indexed for equality.
+ *
+ * Use {@link key} instead when the bytes are an Arkiv entity key: same wire width, but the
+ * distinct type makes the reference visible to readers and to the query language.
+ *
+ * @param value - 32 bytes, as `0x` hex or raw bytes.
+ * @throws {InvalidValueError} If the value is not exactly 32 bytes.
+ *
+ * @example
+ * bytes32(keccak256(toBytes("hello")))
+ */
+declare function bytes32(value: Hex | Uint8Array): Bytes32Value;
+/**
+ * A JavaScript value accepted wherever a typed value is expected: either a tagged value, or one of
+ * the four bare forms that map unambiguously onto a single type.
+ *
+ * | bare form | type    |
+ * | --------- | ------- |
+ * | `boolean` | `bool`  |
+ * | `number`  | `i32`   |
+ * | `bigint`  | `u256`  |
+ * | `string`  | `str`   |
+ *
+ * Anything else — a large number, a decimal, an address, an entity key — must name its type, which
+ * is what keeps `"0x1234..."` a string rather than silently becoming a key.
+ *
+ * These defaults apply identically when writing and when querying, so a value written bare and
+ * queried bare always agrees with itself. The mismatch to watch for is mixing the two: an attribute
+ * written as {@link u64} does not match a bare `bigint` predicate, because that predicate asserts
+ * `u256`. A type mismatch is not an error to the engine — it simply matches nothing.
+ */
+type ValueInput = ArkivValue | boolean | number | bigint | string;
+/**
+ * Resolves a {@link ValueInput} to a typed value, applying the bare-form defaults above. Tagged
+ * values pass through untouched.
+ *
+ * @param input - The value to resolve.
+ * @param attributeName - The attribute this value belongs to, used to make errors name it.
+ *
+ * @throws {MissingValueError} If the input is `undefined` or `null` — an attribute is either set
+ * with a value and a type, or not set at all.
+ * @throws {UntypedValueError} If the input is not a tagged value or a bare boolean, number, bigint
+ * or string.
+ * @throws {InvalidValueError} If a bare value does not fit the type it defaults to.
+ *
+ * @example
+ * toValue(10)          // i32(10)
+ * toValue(10n)         // u256(10n)
+ * toValue("hello")     // str("hello")
+ * toValue(dec("3.5"))  // unchanged
+ */
+declare function toValue(input: ValueInput, attributeName?: string): ArkivValue;
+//#endregion
+//#region src/attr/attributes.d.ts
+/**
+ * The most attribute cells one operation may carry.
+ */
+declare const MAX_ATTRIBUTES = 32;
+declare const MAX_PAYLOAD_BYTES: number;
+/**
+ * The attributes written on an entity, as a plain object keyed by attribute name.
+ *
+ * Values may be tagged ({@link ValueInput}) or bare where the type is unambiguous — see
+ * {@link toValue} for the bare-form defaults.
+ *
+ * @example
+ * const attributes = {
+ *   level:   i32(10),
+ *   balance: u256(1_000_000n),
+ *   score:   dec("3.5"),
+ *   parent:  key(parentKey),
+ *   name:    "Bob",   // bare string -> str
+ *   flagged: true,    // bare boolean -> bool
+ * } satisfies AttributeInputs
+ */
+type AttributeInputs = Readonly<Record<string, ValueInput>>;
+/**
+ * The attributes read back from an entity: the same shape, with every value typed.
+ *
+ * A value read from here drops straight back into an {@link AttributeInputs} — the vocabulary is the
+ * same in both directions.
+ */
+type Attributes = Readonly<Record<string, AnyArkivValue>>;
+/**
+ * The names and types of an entity's attributes, with no values — what the `attributeSchema`
+ * projection returns.
+ *
+ * Useful for asking what shape the data has without paying to transfer it, and for telling apart
+ * two entities that use the same name with different types.
+ */
+type AttributeSchema = Readonly<Record<string, TypeTag>>;
+//#endregion
+//#region src/attr/decimal.d.ts
+/**
+ * Decimal places a `dec` value is scaled by. Fixed by the protocol, so any two decimals are
+ * directly comparable — and range-indexable — as plain integers.
+ */
+declare const DECIMAL_SCALE = 18;
+/** 10 ** {@link DECIMAL_SCALE} — the scaling factor between a `dec` and its integer units. */
+declare const DECIMAL_UNIT: bigint;
+//#endregion
+//#region src/attr/errors.d.ts
+/**
+ * A value was rejected by its tagged constructor — out of range, wrong length, bad checksum, too
+ * much precision, and so on.
+ *
+ * The message names the offending value and, where there is one, the type that *would* hold it, so
+ * the fix is in the error rather than in the docs.
+ */
+declare class InvalidValueError extends Error {
+  /** The type tag whose constructor rejected the value. */
+  readonly tag: TypeTag;
+  /** The rejected input, as given. */
+  readonly input: unknown;
+  constructor(tag: TypeTag, input: unknown, reason: string, hint?: string);
+}
+/**
+ * A bare JavaScript value could not be given a type. Raised when an attribute or predicate is
+ * handed something that is neither a tagged value nor one of the four bare forms
+ * (`boolean`, `number`, `bigint`, `string`).
+ */
+declare class UntypedValueError extends Error {
+  readonly input: unknown;
+  constructor(input: unknown);
+}
+/**
+ * An attribute was given `undefined` or `null` as its value.
+ *
+ * There is no such thing as an attribute with no value: an attribute either exists with a type, or
+ * is not set. The fix is always to leave the name out of the map rather than to write an empty
+ * value, so this is called out separately from {@link UntypedValueError} — the remedy is different.
+ */
+declare class MissingValueError extends Error {
+  /** The attribute whose value was missing, when raised from an attribute map. */
+  readonly attributeName: string | undefined;
+  constructor(input: null | undefined, attributeName?: string);
+}
+/** An attribute name violated the on-chain name grammar. */
+declare class InvalidAttributeNameError extends Error {
+  readonly attributeName: string;
+  constructor(attributeName: string, reason: string);
+}
+/**
+ * One patch tried to both write and remove the same attribute.
+ */
+declare class ConflictingMutationError extends Error {
+  readonly attributeName: string;
+  constructor(attributeName: string);
+}
+/** More attributes were supplied than an entity operation can carry. */
+declare class TooManyAttributesError extends Error {
+  constructor(count: number, max: number);
+}
+/** The node sent back an attribute this SDK cannot decode. */
+declare class UnknownAttributeTypeError extends Error {
+  /** The type as the node named it — a tag over JSON-RPC, a typeId on the wire. */
+  readonly type: string | number;
+  constructor(type: string | number);
+}
+//#endregion
+//#region src/attr/names.d.ts
+/** The longest attribute name, in bytes — the width of the on-chain `Ident32` name cell. */
+declare const MAX_NAME_BYTES = 32;
+/**
+ * Validates an attribute name against the engine's `Ident32` grammar and the query language's
+ * reserved words.
+ *
+ * @param name - The attribute name.
+ * @throws {InvalidAttributeNameError} If the name is empty, too long, uses characters outside the
+ * grammar, or collides with a reserved word.
+ */
+declare function validateAttributeName(name: string): void;
+/** Whether `name` is a valid attribute name — the non-throwing form of {@link validateAttributeName}. */
+declare function isValidAttributeName(name: string): boolean;
+//#endregion
+export { i32 as A, ValueInput as C, dec as D, bytes32 as E, u64 as F, str as M, toValue as N, decFromUnits as O, u256 as P, U64_MAX as S, bool as T, MAX_PAYLOAD_BYTES as _, InvalidAttributeNameError as a, MAX_STRING_BYTES as b, TooManyAttributesError as c, DECIMAL_SCALE as d, DECIMAL_UNIT as f, MAX_ATTRIBUTES as g, Attributes as h, ConflictingMutationError as i, key as j, decUnits as k, UnknownAttributeTypeError as l, AttributeSchema as m, isValidAttributeName as n, InvalidValueError as o, AttributeInputs as p, validateAttributeName as r, MissingValueError as s, MAX_NAME_BYTES as t, UntypedValueError as u, I32_MAX as v, addr as w, U256_MAX as x, I32_MIN as y };
+//# sourceMappingURL=index-DvYvrkdk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-DvYvrkdk.d.ts","names":[],"sources":["../src/attr/values.ts","../src/attr/attributes.ts","../src/attr/decimal.ts","../src/attr/errors.ts","../src/attr/names.ts"],"sourcesContent":[],"mappings":"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"}