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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/README.md +29 -16
  2. package/dist/attr/index.cjs +34 -0
  3. package/dist/attr/index.d.cts +2 -0
  4. package/dist/attr/index.d.ts +2 -0
  5. package/dist/attr/index.js +3 -0
  6. package/dist/attr-BDZ-APg5.js +809 -0
  7. package/dist/attr-BDZ-APg5.js.map +1 -0
  8. package/dist/attr-BvxHN99W.cjs +1029 -0
  9. package/dist/chains/index.cjs +2 -3
  10. package/dist/chains/index.d.cts +39 -77
  11. package/dist/chains/index.d.cts.map +1 -1
  12. package/dist/chains/index.d.ts +22 -60
  13. package/dist/chains/index.d.ts.map +1 -1
  14. package/dist/chains/index.js +2 -2
  15. package/dist/chains-BJrZs6sG.js +57 -0
  16. package/dist/chains-BJrZs6sG.js.map +1 -0
  17. package/dist/chains-BYRTTipa.cjs +73 -0
  18. package/dist/changeOwnership-B7bEgla4.d.cts +509 -0
  19. package/dist/changeOwnership-B7bEgla4.d.cts.map +1 -0
  20. package/dist/changeOwnership-DwgtdSFc.d.ts +509 -0
  21. package/dist/changeOwnership-DwgtdSFc.d.ts.map +1 -0
  22. package/dist/entity/index.cjs +19 -0
  23. package/dist/entity/index.d.cts +4 -0
  24. package/dist/entity/index.d.ts +4 -0
  25. package/dist/entity/index.js +6 -0
  26. package/dist/entity-B0t6sN7F.cjs +71 -0
  27. package/dist/entity-BIp_df9u.js +67 -0
  28. package/dist/entity-BIp_df9u.js.map +1 -0
  29. package/dist/entity-CFhbAv0R.js +70 -0
  30. package/dist/entity-CFhbAv0R.js.map +1 -0
  31. package/dist/entity-wfBnZd91.cjs +98 -0
  32. package/dist/errors-D-eJkGVc.cjs +56 -0
  33. package/dist/errors-DGB8AgT2.js +33 -0
  34. package/dist/errors-DGB8AgT2.js.map +1 -0
  35. package/dist/expiry-BUYIXTGb.cjs +135 -0
  36. package/dist/expiry-BxOlvVWC.d.ts +79 -0
  37. package/dist/expiry-BxOlvVWC.d.ts.map +1 -0
  38. package/dist/expiry-DGRzrSan.js +95 -0
  39. package/dist/expiry-DGRzrSan.js.map +1 -0
  40. package/dist/expiry-DRV29F1r.d.cts +79 -0
  41. package/dist/expiry-DRV29F1r.d.cts.map +1 -0
  42. package/dist/flags-0Vl5rrHq.d.cts +41 -0
  43. package/dist/flags-0Vl5rrHq.d.cts.map +1 -0
  44. package/dist/flags-Ct8k0gpB.cjs +43 -0
  45. package/dist/flags-ZtlvOIIk.js +33 -0
  46. package/dist/flags-ZtlvOIIk.js.map +1 -0
  47. package/dist/flags-wmcMoAnN.d.ts +41 -0
  48. package/dist/flags-wmcMoAnN.d.ts.map +1 -0
  49. package/dist/index-Cgw1u5aY.d.cts +278 -0
  50. package/dist/index-Cgw1u5aY.d.cts.map +1 -0
  51. package/dist/index-ClgIuxJ8.d.ts +159 -0
  52. package/dist/index-ClgIuxJ8.d.ts.map +1 -0
  53. package/dist/index-D0CmtiWT.d.cts +159 -0
  54. package/dist/index-D0CmtiWT.d.cts.map +1 -0
  55. package/dist/index-D8LZt-3J.d.cts +417 -0
  56. package/dist/index-D8LZt-3J.d.cts.map +1 -0
  57. package/dist/index-DVYFaXNV.d.ts +417 -0
  58. package/dist/index-DVYFaXNV.d.ts.map +1 -0
  59. package/dist/index-VCqgn29D.d.ts +278 -0
  60. package/dist/index-VCqgn29D.d.ts.map +1 -0
  61. package/dist/index.cjs +675 -357
  62. package/dist/index.d.cts +251 -203
  63. package/dist/index.d.cts.map +1 -1
  64. package/dist/index.d.ts +251 -203
  65. package/dist/index.d.ts.map +1 -1
  66. package/dist/index.js +626 -355
  67. package/dist/index.js.map +1 -1
  68. package/dist/payload-Bnw1hrvb.cjs +83 -0
  69. package/dist/payload-CIxSn_DW.js +67 -0
  70. package/dist/payload-CIxSn_DW.js.map +1 -0
  71. package/dist/payload-Dgx3PQeK.d.ts +94 -0
  72. package/dist/payload-Dgx3PQeK.d.ts.map +1 -0
  73. package/dist/payload-P0nWyjLg.d.cts +94 -0
  74. package/dist/payload-P0nWyjLg.d.cts.map +1 -0
  75. package/dist/query/index.cjs +24 -149
  76. package/dist/query/index.d.cts +5 -3
  77. package/dist/query/index.d.ts +5 -3
  78. package/dist/query/index.js +6 -137
  79. package/dist/queryBuilder-BXDvX1K_.cjs +1123 -0
  80. package/dist/queryBuilder-CbLL4pG5.js +963 -0
  81. package/dist/queryBuilder-CbLL4pG5.js.map +1 -0
  82. package/dist/selection-BvK6yX0g.d.cts +433 -0
  83. package/dist/selection-BvK6yX0g.d.cts.map +1 -0
  84. package/dist/selection-fpmI3ADQ.d.ts +433 -0
  85. package/dist/selection-fpmI3ADQ.d.ts.map +1 -0
  86. package/dist/types/index.cjs +4 -1
  87. package/dist/types/index.d.cts +7 -2
  88. package/dist/types/index.d.ts +7 -2
  89. package/dist/types/index.js +4 -1
  90. package/dist/utils/index.cjs +4 -17
  91. package/dist/utils/index.d.cts +3 -17
  92. package/dist/utils/index.d.ts +3 -17
  93. package/dist/utils/index.js +4 -18
  94. package/package.json +26 -5
  95. package/src/actions/public/getEntity.ts +27 -43
  96. package/src/actions/public/getEntityNonce.ts +30 -0
  97. package/src/actions/public/predictEntityKeys.test.ts +143 -0
  98. package/src/actions/public/predictEntityKeys.ts +138 -0
  99. package/src/actions/public/query.ts +33 -69
  100. package/src/actions/public/watchEntityEvents.test.ts +414 -0
  101. package/src/actions/public/watchEntityEvents.ts +225 -0
  102. package/src/actions/wallet/changeOwnership.ts +8 -8
  103. package/src/actions/wallet/createEntity.ts +104 -26
  104. package/src/actions/wallet/deleteEntity.ts +2 -3
  105. package/src/actions/wallet/extendEntity.ts +39 -16
  106. package/src/actions/wallet/mutateEntities.test.ts +76 -0
  107. package/src/actions/wallet/mutateEntities.ts +29 -74
  108. package/src/actions/wallet/patchEntity.ts +90 -0
  109. package/src/attr/attributes.test.ts +120 -0
  110. package/src/attr/attributes.ts +190 -0
  111. package/src/attr/codec.test.ts +162 -0
  112. package/src/attr/codec.ts +220 -0
  113. package/src/attr/decimal.ts +86 -0
  114. package/src/attr/errors.ts +145 -0
  115. package/src/attr/index.ts +50 -0
  116. package/src/attr/names.ts +106 -0
  117. package/src/attr/types.ts +150 -0
  118. package/src/attr/values.test.ts +271 -0
  119. package/src/attr/values.ts +502 -0
  120. package/src/chains/cheesecake.ts +22 -0
  121. package/src/chains/index.ts +1 -2
  122. package/src/clients/createPublicClient.test.ts +3 -5
  123. package/src/clients/createPublicClient.ts +5 -4
  124. package/src/clients/createWalletClient.test.ts +2 -2
  125. package/src/clients/createWalletClient.ts +13 -7
  126. package/src/clients/decorators/arkivPublic.ts +160 -139
  127. package/src/clients/decorators/arkivWallet.ts +91 -95
  128. package/src/consts.ts +2 -1
  129. package/src/entity/create.test.ts +184 -0
  130. package/src/entity/errors.ts +38 -0
  131. package/src/entity/events.ts +16 -0
  132. package/src/entity/expiry.test.ts +195 -0
  133. package/src/entity/expiry.ts +181 -0
  134. package/src/entity/flags.ts +65 -0
  135. package/src/entity/index.ts +14 -0
  136. package/src/entity/key.ts +68 -0
  137. package/src/entity/operations.ts +134 -0
  138. package/src/entity/params.ts +15 -0
  139. package/src/errors.ts +33 -28
  140. package/src/index.ts +6 -0
  141. package/src/query/engine.ts +59 -134
  142. package/src/query/errors.ts +151 -0
  143. package/src/query/expression.test.ts +286 -0
  144. package/src/query/expression.ts +493 -0
  145. package/src/query/index.ts +40 -4
  146. package/src/query/injection.test.ts +151 -0
  147. package/src/query/queryBuilder.test.ts +322 -637
  148. package/src/query/queryBuilder.ts +126 -359
  149. package/src/query/queryResult.ts +54 -51
  150. package/src/query/selection.test.ts +48 -98
  151. package/src/query/selection.ts +77 -65
  152. package/src/types/entity.test.ts +44 -155
  153. package/src/types/entity.ts +62 -44
  154. package/src/types/events.ts +64 -23
  155. package/src/types/index.ts +20 -16
  156. package/src/types/rpcSchema.ts +70 -33
  157. package/src/utils/arkivTransactions.test.ts +681 -38
  158. package/src/utils/arkivTransactions.ts +249 -104
  159. package/src/utils/chains.test.ts +21 -24
  160. package/src/utils/compression.ts +1 -1
  161. package/src/utils/entities.test.ts +62 -0
  162. package/src/utils/entities.ts +111 -29
  163. package/src/utils/expirationTime.ts +114 -10
  164. package/src/utils/logger.ts +2 -2
  165. package/src/utils/payload.ts +4 -2
  166. package/src/utils/revert.test.ts +99 -0
  167. package/src/utils/revert.ts +145 -0
  168. package/dist/chains-BifaY04V.cjs +0 -108
  169. package/dist/chains-CrtkVbBh.js +0 -86
  170. package/dist/chains-CrtkVbBh.js.map +0 -1
  171. package/dist/consts-AUoL-v42.cjs +0 -18
  172. package/dist/consts-BV4PR-de.js +0 -7
  173. package/dist/consts-BV4PR-de.js.map +0 -1
  174. package/dist/entity-B6g_EPm1.d.cts +0 -382
  175. package/dist/entity-B6g_EPm1.d.cts.map +0 -1
  176. package/dist/entity-qoLMAuuk.d.ts +0 -382
  177. package/dist/entity-qoLMAuuk.d.ts.map +0 -1
  178. package/dist/index-DdspxNAA.d.ts +0 -481
  179. package/dist/index-DdspxNAA.d.ts.map +0 -1
  180. package/dist/index-Ds9dwqb5.d.cts +0 -481
  181. package/dist/index-Ds9dwqb5.d.cts.map +0 -1
  182. package/dist/payload-B2kFJyah.d.ts +0 -6
  183. package/dist/payload-B2kFJyah.d.ts.map +0 -1
  184. package/dist/payload-CJN8fTvX.d.cts +0 -6
  185. package/dist/payload-CJN8fTvX.d.cts.map +0 -1
  186. package/dist/payload-Claf2jUO.js +0 -13
  187. package/dist/payload-Claf2jUO.js.map +0 -1
  188. package/dist/payload-DpA5PA-w.cjs +0 -23
  189. package/dist/query/index.js.map +0 -1
  190. package/dist/queryBuilder-D2uwP9jI.js +0 -704
  191. package/dist/queryBuilder-D2uwP9jI.js.map +0 -1
  192. package/dist/queryBuilder-UW2MCaX4.cjs +0 -792
  193. package/dist/utils/index.d.cts.map +0 -1
  194. package/dist/utils/index.d.ts.map +0 -1
  195. package/dist/utils/index.js.map +0 -1
  196. package/src/actions/public/buildQuery.ts +0 -10
  197. package/src/actions/public/subscribeEntityEvents.ts +0 -119
  198. package/src/actions/wallet/updateEntity.ts +0 -60
  199. package/src/chains/braga.ts +0 -26
  200. package/src/chains/kaolin.ts +0 -29
  201. package/src/query/engine.test.ts +0 -526
  202. package/src/query/predicate.test.ts +0 -461
  203. package/src/query/predicate.ts +0 -144
  204. package/src/query/queryResult.test.ts +0 -270
  205. package/src/query/selectQueryBuilder.test.ts +0 -210
  206. package/src/types/attributes.ts +0 -16
  207. package/src/utils/validation.test.ts +0 -60
  208. package/src/utils/validation.ts +0 -32
  209. /package/dist/{types-H-TSmRpm.js → types-Bx1EKe0v.js} +0 -0
  210. /package/dist/{types-o3zWarRp.cjs → types-CKPddlfS.cjs} +0 -0
@@ -0,0 +1,417 @@
1
+ import { Address, Hex } from "viem";
2
+
3
+ //#region src/attr/types.d.ts
4
+
5
+ /**
6
+ * The protocol's attribute type vocabulary, mapping each short **tag** (the name used by the
7
+ * client, the query language and this SDK) to its **typeId** (the byte carried on the wire and in
8
+ * the entity record).
9
+ *
10
+ * The typeIds are consensus-critical: they are written into entity records and mixed into index
11
+ * keys, so this table must never drift from the node's `AttributeType`.
12
+ *
13
+ * | tag | typeId | ABI wire type | indexing |
14
+ * | --------- | ------ | ------------------- | ----------------- |
15
+ * | `bool` | 1 | `bool` | equality |
16
+ * | `i32` | 2 | `int32` | equality + range |
17
+ * | `u64` | 3 | `uint64` | equality + range |
18
+ * | `u256` | 4 | `uint256` | equality + range |
19
+ * | `dec` | 5 | `int256` (18 dp) | equality + range |
20
+ * | `bytes32` | 6 | `bytes32` | equality |
21
+ * | `bytes` | 7 | `bytes` | none — system-only |
22
+ * | `str` | 8 | `string` (<= 128 B) | equality + prefix |
23
+ * | `addr` | 9 | `address` | equality |
24
+ * | `key` | 10 | `bytes32` | equality |
25
+ */
26
+ declare const TYPE_IDS: {
27
+ readonly bool: 1;
28
+ readonly i32: 2;
29
+ readonly u64: 3;
30
+ readonly u256: 4;
31
+ readonly dec: 5;
32
+ readonly bytes32: 6;
33
+ readonly bytes: 7;
34
+ readonly str: 8;
35
+ readonly addr: 9;
36
+ readonly key: 10;
37
+ };
38
+ /** Every type tag, including the system-only `bytes`. */
39
+ type TypeTag = keyof typeof TYPE_IDS;
40
+ /**
41
+ * The tags a client may set on an attribute. `bytes` is excluded: it backs the system `$payload`
42
+ * cell, which travels in its own operation field and is never carried in an attribute array.
43
+ */
44
+ type UserTypeTag = Exclude<TypeTag, "bytes">;
45
+ /**
46
+ * Marks a value as having passed its constructor's validation. The symbol is module-private, so a
47
+ * hand-written object literal is not assignable to {@link ArkivValue} — every value crossing the
48
+ * wire has been range-, length- and format-checked by {@link i32}, {@link u256}, {@link dec}, and
49
+ * friends.
50
+ */
51
+ declare const validated: unique symbol;
52
+ /**
53
+ * A typed attribute value: the tag it was created with, plus the JavaScript representation of that
54
+ * type. Constructed only by the tagged constructors in `@arkiv-network/sdk/attr`.
55
+ *
56
+ * @typeParam tag - The type tag, which also discriminates the {@link ArkivValue} union.
57
+ * @typeParam value - The decoded JavaScript representation.
58
+ */
59
+ type Value<tag extends TypeTag, value> = {
60
+ readonly type: tag;
61
+ readonly value: value;
62
+ readonly [validated]: tag;
63
+ };
64
+ /** A boolean. */
65
+ type BoolValue = Value<"bool", boolean>;
66
+ /** A 32-bit signed integer — the default for an untagged number. */
67
+ type I32Value = Value<"i32", number>;
68
+ /**
69
+ * A 64-bit unsigned integer — block heights, the
70
+ * entity-nonce and `$expiresAt` are all `u64` */
71
+ type U64Value = Value<"u64", bigint>;
72
+ /** A 256-bit unsigned integer. */
73
+ type U256Value = Value<"u256", bigint>;
74
+ /**
75
+ * A fixed-point decimal with 18 decimal places, held as its canonical decimal string (`"3.5"`).
76
+ * Use {@link decUnits} for the exact scaled integer when you need to do arithmetic.
77
+ */
78
+ type DecValue = Value<"dec", string>;
79
+ /** 32 opaque bytes, as lowercase `0x` hex. */
80
+ type Bytes32Value = Value<"bytes32", Hex>;
81
+ /** A UTF-8 string of at most 128 bytes. */
82
+ type StrValue = Value<"str", string>;
83
+ /** A 20-byte Ethereum address, as EIP-55 checksummed hex. */
84
+ type AddrValue = Value<"addr", Address>;
85
+ /** A reference to another entity. Weak by spec: dangling references are permitted. */
86
+ type KeyValue = Value<"key", Hex>;
87
+ /**
88
+ * Opaque variable-length bytes, as lowercase `0x` hex. System-only — it backs `$payload` and is
89
+ * never settable as an attribute, so it is produced by decoding but has no constructor.
90
+ */
91
+ type BytesValue = Value<"bytes", Hex>;
92
+ /** Any value a client may set on an attribute. */
93
+ type ArkivValue = BoolValue | I32Value | U64Value | U256Value | DecValue | Bytes32Value | StrValue | AddrValue | KeyValue;
94
+ /** Any value that can come back from the node, including the system-only `bytes`. */
95
+ type AnyArkivValue = ArkivValue | BytesValue;
96
+ /**
97
+ * Whether `input` has the *shape* of an {@link ArkivValue} — a known type tag and a value.
98
+ */
99
+ declare function isArkivValue(input: unknown): input is AnyArkivValue;
100
+ //#endregion
101
+ //#region src/attr/values.d.ts
102
+ /** The widest `i32`. */
103
+ declare const I32_MAX = 2147483647;
104
+ /** The narrowest `i32`. */
105
+ declare const I32_MIN = -2147483648;
106
+ /** The widest `u64`. */
107
+ declare const U64_MAX: bigint;
108
+ /** The widest `u256`. */
109
+ declare const U256_MAX: bigint;
110
+ /**
111
+ * The longest `str`, in UTF-8 bytes
112
+ */
113
+ declare const MAX_STRING_BYTES = 128;
114
+ /**
115
+ * A boolean.
116
+ *
117
+ * `bool` is the one type that may also be written bare — `{ flagged: true }` and
118
+ * `{ flagged: bool(true) }` are the same attribute.
119
+ *
120
+ * @example
121
+ * bool(true) // { type: "bool", value: true }
122
+ */
123
+ declare function bool(value: boolean): BoolValue;
124
+ /**
125
+ * A 32-bit signed integer, indexed for equality and range queries. This is the default type for a
126
+ * bare number, so `{ level: 10 }` and `{ level: i32(10) }` are the same attribute.
127
+ *
128
+ * @param value - An integer in [-2147483648, 2147483647].
129
+ * @throws {InvalidValueError} If the value is not an integer, or does not fit an `i32`.
130
+ *
131
+ * @example
132
+ * i32(10) // { type: "i32", value: 10 }
133
+ * i32(-42) // negative values are fine — i32 is the signed integer
134
+ */
135
+ declare function i32(value: number | bigint): I32Value;
136
+ /**
137
+ * A 256-bit unsigned integer, indexed for equality and range queries. The type for token amounts
138
+ * and anything else that can outgrow 2⁶⁴ — reach for {@link u64} first for counters, timestamps
139
+ * and block heights.
140
+ *
141
+ * @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
142
+ * string.
143
+ * @throws {InvalidValueError} If the value is negative, non-integral, or wider than 256 bits.
144
+ *
145
+ * @example
146
+ * u256(1_000_000n)
147
+ * u256(Date.now()) // safe integers are accepted
148
+ * u256("0xf4240") // hex, as it comes back over JSON-RPC
149
+ */
150
+ declare function u256(value: bigint | number | string): U256Value;
151
+ /**
152
+ * A 64-bit unsigned integer, indexed for equality and range queries.
153
+ *
154
+ * This is the width the protocol counts in: block heights, `$expiresAt` and the entity-nonce are
155
+ * all `u64`, so it is the type to reach for when a value has to line up with one of them. Use
156
+ * {@link u256} for token amounts and anything else that can exceed 2⁶⁴.
157
+ *
158
+ * @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
159
+ * string.
160
+ * @throws {InvalidValueError} If the value is negative, non-integral, or wider than 64 bits.
161
+ *
162
+ * @example
163
+ * u64(1_200_000n) // a block height
164
+ * u64(Date.now()) // safe integers are accepted
165
+ * u64("0x124f80") // hex, as it comes back over JSON-RPC
166
+ */
167
+ declare function u64(value: bigint | number | string): U64Value;
168
+ /**
169
+ * A signed fixed-point decimal with exactly 18 decimal places, indexed for equality and range
170
+ * queries.
171
+ *
172
+ * Pass fractional values as **strings**. A JavaScript number cannot represent most decimals
173
+ * exactly, so accepting `dec(0.1 + 0.2)` would quietly store `0.30000000000000004`; requiring the
174
+ * string keeps what you write and what is stored the same thing. Excess precision is likewise an
175
+ * error rather than a rounding.
176
+ *
177
+ * @param value - A decimal string, or an integral `number` / `bigint`.
178
+ * @throws {InvalidValueError} If the value is malformed, has more than 18 fractional digits, or
179
+ * falls outside the `int256` range.
180
+ *
181
+ * @example
182
+ * dec("3.5")
183
+ * dec("-0.000000000000000001") // the smallest step
184
+ * dec(5) // integers may be passed bare
185
+ */
186
+ declare function dec(value: string | number | bigint): DecValue;
187
+ /**
188
+ * The exact scaled integer behind a `dec` — the value multiplied by 10 ** 18, which is what the
189
+ * protocol stores and compares. Use it when you need exact arithmetic; JavaScript has no native
190
+ * decimal type, so the SDK carries the canonical string and leaves the maths to you.
191
+ *
192
+ * @example
193
+ * decUnits(dec("3.5")) // 3500000000000000000n
194
+ */
195
+ declare function decUnits(value: DecValue): bigint;
196
+ /**
197
+ * A `dec` built from its scaled integer units — the inverse of {@link decUnits}.
198
+ *
199
+ * @example
200
+ * decFromUnits(3_500_000_000_000_000_000n) // dec("3.5")
201
+ */
202
+ declare function decFromUnits(units: bigint): DecValue;
203
+ /**
204
+ * A UTF-8 string of at most 128 bytes, indexed for equality and prefix (`STARTSWITH`) matching.
205
+ *
206
+ * The limit is on **bytes**, not characters: a string of 128 emoji does not fit.
207
+ *
208
+ * @throws {InvalidValueError} If the string exceeds 128 UTF-8 bytes.
209
+ *
210
+ * @example
211
+ * str("Bob")
212
+ */
213
+ declare function str(value: string): StrValue;
214
+ /**
215
+ * A 20-byte Ethereum address, indexed for equality.
216
+ *
217
+ * All-lowercase and all-uppercase input carries no checksum and is accepted as-is; mixed-case
218
+ * input is checked against its EIP-55 checksum, so a mistyped address is caught here rather than
219
+ * being written to a wrong account. The stored value is always EIP-55 checksummed.
220
+ *
221
+ * @throws {InvalidValueError} If the value is not 20 hex bytes, or fails its EIP-55 checksum.
222
+ *
223
+ * @example
224
+ * addr("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
225
+ */
226
+ declare function addr(value: string): AddrValue;
227
+ /**
228
+ * A reference to another entity, indexed for equality.
229
+ *
230
+ * References are **weak**: nothing checks that the target exists when you write it, and a
231
+ * reference to a deleted or expired entity is allowed to dangle.
232
+ *
233
+ * @param value - A 32-byte entity key, as `0x` hex or raw bytes.
234
+ * @throws {InvalidValueError} If the value is not exactly 32 bytes.
235
+ *
236
+ * @example
237
+ * key(parentEntityKey)
238
+ */
239
+ declare function key(value: Hex | Uint8Array): KeyValue;
240
+ /**
241
+ * 32 opaque bytes — a hash, a digest, an identifier from another system — indexed for equality.
242
+ *
243
+ * Use {@link key} instead when the bytes are an Arkiv entity key: same wire width, but the
244
+ * distinct type makes the reference visible to readers and to the query language.
245
+ *
246
+ * @param value - 32 bytes, as `0x` hex or raw bytes.
247
+ * @throws {InvalidValueError} If the value is not exactly 32 bytes.
248
+ *
249
+ * @example
250
+ * bytes32(keccak256(toBytes("hello")))
251
+ */
252
+ declare function bytes32(value: Hex | Uint8Array): Bytes32Value;
253
+ /**
254
+ * A JavaScript value accepted wherever a typed value is expected: either a tagged value, or one of
255
+ * the four bare forms that map unambiguously onto a single type.
256
+ *
257
+ * | bare form | type |
258
+ * | --------- | ------- |
259
+ * | `boolean` | `bool` |
260
+ * | `number` | `i32` |
261
+ * | `bigint` | `u256` |
262
+ * | `string` | `str` |
263
+ *
264
+ * Anything else — a large number, a decimal, an address, an entity key — must name its type, which
265
+ * is what keeps `"0x1234..."` a string rather than silently becoming a key.
266
+ *
267
+ * These defaults apply identically when writing and when querying, so a value written bare and
268
+ * queried bare always agrees with itself. The mismatch to watch for is mixing the two: an attribute
269
+ * written as {@link u64} does not match a bare `bigint` predicate, because that predicate asserts
270
+ * `u256`. A type mismatch is not an error to the engine — it simply matches nothing.
271
+ */
272
+ type ValueInput = ArkivValue | boolean | number | bigint | string;
273
+ /**
274
+ * Resolves a {@link ValueInput} to a typed value, applying the bare-form defaults above. Tagged
275
+ * values pass through untouched.
276
+ *
277
+ * @param input - The value to resolve.
278
+ * @param attributeName - The attribute this value belongs to, used to make errors name it.
279
+ *
280
+ * @throws {MissingValueError} If the input is `undefined` or `null` — an attribute is either set
281
+ * with a value and a type, or not set at all.
282
+ * @throws {UntypedValueError} If the input is not a tagged value or a bare boolean, number, bigint
283
+ * or string.
284
+ * @throws {InvalidValueError} If a bare value does not fit the type it defaults to.
285
+ *
286
+ * @example
287
+ * toValue(10) // i32(10)
288
+ * toValue(10n) // u256(10n)
289
+ * toValue("hello") // str("hello")
290
+ * toValue(dec("3.5")) // unchanged
291
+ */
292
+ declare function toValue(input: ValueInput, attributeName?: string): ArkivValue;
293
+ //#endregion
294
+ //#region src/attr/attributes.d.ts
295
+ /**
296
+ * The most attribute cells one operation may carry.
297
+ */
298
+ declare const MAX_ATTRIBUTES = 32;
299
+ declare const MAX_PAYLOAD_BYTES: number;
300
+ /**
301
+ * The attributes written on an entity, as a plain object keyed by attribute name.
302
+ *
303
+ * Values may be tagged ({@link ValueInput}) or bare where the type is unambiguous — see
304
+ * {@link toValue} for the bare-form defaults.
305
+ *
306
+ * @example
307
+ * const attributes = {
308
+ * level: i32(10),
309
+ * balance: u256(1_000_000n),
310
+ * score: dec("3.5"),
311
+ * parent: key(parentKey),
312
+ * name: "Bob", // bare string -> str
313
+ * flagged: true, // bare boolean -> bool
314
+ * } satisfies AttributeInputs
315
+ */
316
+ type AttributeInputs = Readonly<Record<string, ValueInput>>;
317
+ /**
318
+ * The attributes read back from an entity: the same shape, with every value typed.
319
+ *
320
+ * A value read from here drops straight back into an {@link AttributeInputs} — the vocabulary is the
321
+ * same in both directions.
322
+ */
323
+ type Attributes = Readonly<Record<string, AnyArkivValue>>;
324
+ /**
325
+ * The names and types of an entity's attributes, with no values — what the `attributeSchema`
326
+ * projection returns.
327
+ *
328
+ * Useful for asking what shape the data has without paying to transfer it, and for telling apart
329
+ * two entities that use the same name with different types.
330
+ */
331
+ type AttributeSchema = Readonly<Record<string, TypeTag>>;
332
+ //#endregion
333
+ //#region src/attr/decimal.d.ts
334
+ /**
335
+ * Decimal places a `dec` value is scaled by. Fixed by the protocol, so any two decimals are
336
+ * directly comparable — and range-indexable — as plain integers.
337
+ */
338
+ declare const DECIMAL_SCALE = 18;
339
+ /** 10 ** {@link DECIMAL_SCALE} — the scaling factor between a `dec` and its integer units. */
340
+ declare const DECIMAL_UNIT: bigint;
341
+ //#endregion
342
+ //#region src/attr/errors.d.ts
343
+ /**
344
+ * A value was rejected by its tagged constructor — out of range, wrong length, bad checksum, too
345
+ * much precision, and so on.
346
+ *
347
+ * The message names the offending value and, where there is one, the type that *would* hold it, so
348
+ * the fix is in the error rather than in the docs.
349
+ */
350
+ declare class InvalidValueError extends Error {
351
+ /** The type tag whose constructor rejected the value. */
352
+ readonly tag: TypeTag;
353
+ /** The rejected input, as given. */
354
+ readonly input: unknown;
355
+ constructor(tag: TypeTag, input: unknown, reason: string, hint?: string);
356
+ }
357
+ /**
358
+ * A bare JavaScript value could not be given a type. Raised when an attribute or predicate is
359
+ * handed something that is neither a tagged value nor one of the four bare forms
360
+ * (`boolean`, `number`, `bigint`, `string`).
361
+ */
362
+ declare class UntypedValueError extends Error {
363
+ readonly input: unknown;
364
+ constructor(input: unknown);
365
+ }
366
+ /**
367
+ * An attribute was given `undefined` or `null` as its value.
368
+ *
369
+ * There is no such thing as an attribute with no value: an attribute either exists with a type, or
370
+ * is not set. The fix is always to leave the name out of the map rather than to write an empty
371
+ * value, so this is called out separately from {@link UntypedValueError} — the remedy is different.
372
+ */
373
+ declare class MissingValueError extends Error {
374
+ /** The attribute whose value was missing, when raised from an attribute map. */
375
+ readonly attributeName: string | undefined;
376
+ constructor(input: null | undefined, attributeName?: string);
377
+ }
378
+ /** An attribute name violated the on-chain name grammar. */
379
+ declare class InvalidAttributeNameError extends Error {
380
+ readonly attributeName: string;
381
+ constructor(attributeName: string, reason: string);
382
+ }
383
+ /**
384
+ * One patch tried to both write and remove the same attribute.
385
+ */
386
+ declare class ConflictingMutationError extends Error {
387
+ readonly attributeName: string;
388
+ constructor(attributeName: string);
389
+ }
390
+ /** More attributes were supplied than an entity operation can carry. */
391
+ declare class TooManyAttributesError extends Error {
392
+ constructor(count: number, max: number);
393
+ }
394
+ /** The node sent back an attribute this SDK cannot decode. */
395
+ declare class UnknownAttributeTypeError extends Error {
396
+ /** The type as the node named it — a tag over JSON-RPC, a typeId on the wire. */
397
+ readonly type: string | number;
398
+ constructor(type: string | number);
399
+ }
400
+ //#endregion
401
+ //#region src/attr/names.d.ts
402
+ /** The longest attribute name, in bytes — the width of the on-chain `Ident32` name cell. */
403
+ declare const MAX_NAME_BYTES = 32;
404
+ /**
405
+ * Validates an attribute name against the engine's `Ident32` grammar and the query language's
406
+ * reserved words.
407
+ *
408
+ * @param name - The attribute name.
409
+ * @throws {InvalidAttributeNameError} If the name is empty, too long, uses characters outside the
410
+ * grammar, or collides with a reserved word.
411
+ */
412
+ declare function validateAttributeName(name: string): void;
413
+ /** Whether `name` is a valid attribute name — the non-throwing form of {@link validateAttributeName}. */
414
+ declare function isValidAttributeName(name: string): boolean;
415
+ //#endregion
416
+ export { i32 as A, Bytes32Value as B, ValueInput as C, dec as D, bytes32 as E, u64 as F, StrValue as G, DecValue as H, AddrValue as I, U64Value as J, TypeTag as K, AnyArkivValue as L, str as M, toValue as N, decFromUnits as O, u256 as P, ArkivValue as R, U64_MAX as S, bool as T, I32Value as U, BytesValue as V, KeyValue as W, isArkivValue as X, UserTypeTag as Y, 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, U256Value as q, 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, BoolValue as z };
417
+ //# sourceMappingURL=index-DVYFaXNV.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index-DVYFaXNV.d.ts","names":[],"sources":["../src/attr/types.ts","../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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"}