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

package/src/attr/decimal.ts

@@ -0,0 +1,86 @@
+import { InvalidValueError } from "./errors"
+
+/**
+ * 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.
+ */
+export const DECIMAL_SCALE = 18
+
+/** 10 ** {@link DECIMAL_SCALE} — the scaling factor between a `dec` and its integer units. */
+export const DECIMAL_UNIT = 10n ** BigInt(DECIMAL_SCALE)
+
+/** The widest scaled value an `int256` holds. */
+const INT256_MAX = 2n ** 255n - 1n
+/** The narrowest scaled value an `int256` holds. */
+const INT256_MIN = -(2n ** 255n)
+
+/**
+ * A decimal literal: an optional sign, at least one integer digit, and an optional fraction of at
+ * most {@link DECIMAL_SCALE} digits. Exponents are not part of the grammar — `1e18` is a parse
+ * error rather than a silent reinterpretation.
+ */
+const DECIMAL_RE = /^([+-]?)(\d+)(?:\.(\d+))?$/
+
+/**
+ * Parses a decimal literal into its scaled integer units.
+ *
+ * Excess fractional precision is an **error, never a rounding**: the protocol stores exactly 18
+ * decimal places, and silently dropping the 19th digit would make a stored value differ from the
+ * one that was written.
+ *
+ * @param input - The decimal literal, e.g. `"3.5"` or `"-0.000001"`.
+ * @returns The value scaled by 10 ** 18.
+ * @throws {InvalidValueError} If the literal is malformed, too precise, or out of `int256` range.
+ */
+export function decimalToUnits(input: string): bigint {
+  const match = DECIMAL_RE.exec(input)
+  if (!match) {
+    throw new InvalidValueError(
+      "dec",
+      input,
+      "not a decimal literal",
+      'Write it as sign, digits, and an optional "." with up to 18 fractional digits — e.g. ' +
+        'dec("3.5") or dec("-0.25"). Exponents such as "1e18" are not accepted.',
+    )
+  }
+
+  const [, sign, whole, fraction = ""] = match
+  if (fraction.length > DECIMAL_SCALE) {
+    throw new InvalidValueError(
+      "dec",
+      input,
+      `${fraction.length} fractional digits exceeds the ${DECIMAL_SCALE} the protocol stores`,
+      "Round it yourself before storing — a dec is never rounded for you, so that what you " +
+        "write is exactly what is stored.",
+    )
+  }
+
+  const digits = BigInt(whole + fraction.padEnd(DECIMAL_SCALE, "0"))
+  const units = sign === "-" ? -digits : digits
+  if (units > INT256_MAX || units < INT256_MIN) {
+    throw new InvalidValueError("dec", input, "exceeds the int256 range a dec is stored in")
+  }
+  return units
+}
+
+/**
+ * Renders scaled integer units back as a canonical decimal string: no leading zeros, no trailing
+ * fractional zeros, no `-0`. Parsing the result yields the same units, so this is the inverse of
+ * {@link decimalToUnits} on every value it accepts.
+ *
+ * @param units - The value scaled by 10 ** 18.
+ * @returns The canonical decimal string, e.g. `"3.5"`.
+ * @throws {InvalidValueError} If the units are outside the `int256` range.
+ */
+export function unitsToDecimal(units: bigint): string {
+  if (units > INT256_MAX || units < INT256_MIN) {
+    throw new InvalidValueError("dec", units, "exceeds the int256 range a dec is stored in")
+  }
+  const negative = units < 0n
+  const magnitude = negative ? -units : units
+  const whole = magnitude / DECIMAL_UNIT
+  const fraction = (magnitude % DECIMAL_UNIT).toString().padStart(DECIMAL_SCALE, "0")
+  const trimmed = fraction.replace(/0+$/, "")
+  const sign = negative ? "-" : ""
+  return trimmed ? `${sign}${whole}.${trimmed}` : `${sign}${whole}`
+}

package/src/attr/errors.ts

@@ -0,0 +1,145 @@
+import type { TypeTag } from "./types"
+
+/**
+ * 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.
+ */
+export 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) {
+    super(`Invalid ${tag} value ${describe(input)}: ${reason}.${hint ? ` ${hint}` : ""}`)
+    this.name = "InvalidValueError"
+    this.tag = tag
+    this.input = input
+  }
+}
+
+/**
+ * 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`).
+ */
+export class UntypedValueError extends Error {
+  readonly input: unknown
+
+  constructor(input: unknown) {
+    super(
+      `Cannot infer an Arkiv type for ${describe(input)}. ` +
+        "Attribute values must be a tagged value (i32, u256, dec, str, addr, key, bytes32, bool) " +
+        "or a bare boolean, number, bigint or string.",
+    )
+    this.name = "UntypedValueError"
+    this.input = input
+  }
+}
+
+/**
+ * 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.
+ */
+export 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) {
+    const subject = attributeName ? `attribute "${attributeName}"` : "attribute value"
+    super(
+      `The ${subject} is ${input === null ? "null" : "undefined"}. An attribute is either set ` +
+        "with a value and a type or not set at all, so there is nothing to write here. " +
+        (attributeName
+          ? `Omit "${attributeName}" from the attributes instead — e.g. build the map ` +
+            "conditionally, or drop the key when the value is absent."
+          : "Omit the attribute instead of giving it an empty value."),
+    )
+    this.name = "MissingValueError"
+    this.attributeName = attributeName
+  }
+}
+
+/** An attribute name violated the on-chain name grammar. */
+export class InvalidAttributeNameError extends Error {
+  readonly attributeName: string
+
+  constructor(attributeName: string, reason: string) {
+    super(
+      `Invalid attribute name "${attributeName}": ${reason}. Names must be 1-32 bytes, start with ` +
+        'a letter, and contain only A-Z, a-z, 0-9, ".", "-" or "_". Names are case-sensitive.',
+    )
+    this.name = "InvalidAttributeNameError"
+    this.attributeName = attributeName
+  }
+}
+
+/**
+ * One patch tried to both write and remove the same attribute.
+ */
+export class ConflictingMutationError extends Error {
+  readonly attributeName: string
+
+  constructor(attributeName: string) {
+    super(
+      `The patch both sets and unsets "${attributeName}". A patch applies one mutation per ` +
+        'attribute, so say which you mean: drop it from "unset" to write the value, or from ' +
+        '"set" to remove the attribute.',
+    )
+    this.name = "ConflictingMutationError"
+    this.attributeName = attributeName
+  }
+}
+
+/** More attributes were supplied than an entity operation can carry. */
+export class TooManyAttributesError extends Error {
+  constructor(count: number, max: number) {
+    super(`An entity may carry at most ${max} attributes, got ${count}.`)
+    this.name = "TooManyAttributesError"
+  }
+}
+
+/** The node sent back an attribute this SDK cannot decode. */
+export 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) {
+    super(
+      `Unknown attribute type ${describe(type)}. The node is using a type this SDK version does ` +
+        "not know about — upgrade @arkiv-network/sdk.",
+    )
+    this.name = "UnknownAttributeTypeError"
+    this.type = type
+  }
+}
+
+/** Renders an arbitrary input for an error message, without ever throwing. */
+function describe(input: unknown): string {
+  switch (typeof input) {
+    case "string":
+      return JSON.stringify(input.length > 64 ? `${input.slice(0, 61)}...` : input)
+    case "bigint":
+      return `${input}n`
+    case "object":
+      return input === null ? "null" : safeJson(input)
+    case "undefined":
+      return "undefined"
+    default:
+      return String(input)
+  }
+}
+
+function safeJson(input: object): string {
+  try {
+    return JSON.stringify(input) ?? String(input)
+  } catch {
+    return Object.prototype.toString.call(input)
+  }
+}

package/src/attr/index.ts

@@ -0,0 +1,50 @@
+export type { AttributeInputs, AttributeSchema, Attributes } from "./attributes"
+export { MAX_ATTRIBUTES, MAX_PAYLOAD_BYTES } from "./attributes"
+export { DECIMAL_SCALE, DECIMAL_UNIT } from "./decimal"
+export {
+  ConflictingMutationError,
+  InvalidAttributeNameError,
+  InvalidValueError,
+  MissingValueError,
+  TooManyAttributesError,
+  UnknownAttributeTypeError,
+  UntypedValueError,
+} from "./errors"
+export { isValidAttributeName, MAX_NAME_BYTES, validateAttributeName } from "./names"
+export type {
+  AddrValue,
+  AnyArkivValue,
+  ArkivValue,
+  BoolValue,
+  Bytes32Value,
+  BytesValue,
+  DecValue,
+  I32Value,
+  KeyValue,
+  StrValue,
+  TypeTag,
+  U64Value,
+  U256Value,
+  UserTypeTag,
+} from "./types"
+export { isArkivValue } from "./types"
+export type { ValueInput } from "./values"
+export {
+  addr,
+  bool,
+  bytes32,
+  dec,
+  decFromUnits,
+  decUnits,
+  I32_MAX,
+  I32_MIN,
+  i32,
+  key,
+  MAX_STRING_BYTES,
+  str,
+  toValue,
+  U64_MAX,
+  U256_MAX,
+  u64,
+  u256,
+} from "./values"

package/src/attr/names.ts

@@ -0,0 +1,106 @@
+import { InvalidAttributeNameError } from "./errors"
+
+/** The longest attribute name, in bytes — the width of the on-chain `Ident32` name cell. */
+export const MAX_NAME_BYTES = 32
+
+/**
+ * The attribute-name grammar (`Ident32`): a leading letter, then letters, digits, `.`, `-` or `_`.
+ *
+ * Names are **case-sensitive** — `Level` and `level` are two different attributes.
+ *
+ * The charset is ASCII-only, so a name's length in characters is also its length in bytes.
+ */
+const NAME_RE = /^[A-Za-z][A-Za-z0-9._-]*$/
+
+/**
+ * Words the query language reserves. They are rejected as attribute names because an attribute
+ * named `not` or `str` could be written but never queried — the parser would read the name as an
+ * operator or a type tag.
+ *
+ * Matched **case-insensitively**: query keywords are case-insensitive, so `NOT` and `not` are the
+ * same operator, and the type tags are held to the same rule so that what is reserved does not
+ * depend on how you happen to capitalise it.
+ */
+const RESERVED = new Set([
+  // operators and keywords
+  "and",
+  "or",
+  "not",
+  "true",
+  "false",
+  "startswith",
+  "exists",
+  "typeof",
+  // type tags
+  "bool",
+  "i32",
+  "u64",
+  "u256",
+  "dec",
+  "bytes32",
+  "bytes",
+  "str",
+  "addr",
+  "key",
+])
+
+/**
+ * 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.
+ */
+export function validateAttributeName(name: string): void {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new InvalidAttributeNameError(String(name), "the name is empty")
+  }
+  if (name.startsWith("$")) {
+    throw new InvalidAttributeNameError(
+      name,
+      '"$" is reserved for system attributes, which the engine sets and you cannot write',
+    )
+  }
+  if (!NAME_RE.test(name)) {
+    const chars = [...name]
+    const at = chars.findIndex(
+      (char, index) => !(index === 0 ? /[A-Za-z]/ : /[A-Za-z0-9._-]/).test(char),
+    )
+    throw new InvalidAttributeNameError(
+      name,
+      at === 0
+        ? `it starts with "${chars[0]}" rather than a letter`
+        : `it contains "${chars[at]}" at position ${at}`,
+    )
+  }
+  if (name.length > MAX_NAME_BYTES) {
+    throw new InvalidAttributeNameError(name, `the name is ${name.length} bytes long`)
+  }
+  // `-` is a legal name character and `--` opens a comment that runs to the end of the line, so a
+  // name containing one renders a query whose whole remainder is discarded
+  if (name.includes("--")) {
+    throw new InvalidAttributeNameError(
+      name,
+      '"--" opens a comment in the query language, so everything after it in a query would be ' +
+        "discarded — an attribute with this name could be written but never safely queried",
+    )
+  }
+  if (RESERVED.has(name.toLowerCase())) {
+    throw new InvalidAttributeNameError(
+      name,
+      `"${name}" is reserved by the query language, so an attribute with this name could never ` +
+        "be queried",
+    )
+  }
+}
+
+/** Whether `name` is a valid attribute name — the non-throwing form of {@link validateAttributeName}. */
+export function isValidAttributeName(name: string): boolean {
+  try {
+    validateAttributeName(name)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/attr/types.ts

@@ -0,0 +1,150 @@
+import type { Address, Hex } from "viem"
+
+/**
+ * The protocol's attribute type vocabulary, mapping each short **tag** (the name used by the
+ * client, the query language and this SDK) to its **typeId** (the byte carried on the wire and in
+ * the entity record).
+ *
+ * The typeIds are consensus-critical: they are written into entity records and mixed into index
+ * keys, so this table must never drift from the node's `AttributeType`.
+ *
+ * | tag       | typeId | ABI wire type       | indexing          |
+ * | --------- | ------ | ------------------- | ----------------- |
+ * | `bool`    | 1      | `bool`              | equality          |
+ * | `i32`     | 2      | `int32`             | equality + range  |
+ * | `u64`     | 3      | `uint64`            | equality + range  |
+ * | `u256`    | 4      | `uint256`           | equality + range  |
+ * | `dec`     | 5      | `int256` (18 dp)    | equality + range  |
+ * | `bytes32` | 6      | `bytes32`           | equality          |
+ * | `bytes`   | 7      | `bytes`             | none — system-only |
+ * | `str`     | 8      | `string` (<= 128 B) | equality + prefix |
+ * | `addr`    | 9      | `address`           | equality          |
+ * | `key`     | 10     | `bytes32`           | equality          |
+ */
+export const TYPE_IDS = {
+  bool: 1,
+  i32: 2,
+  u64: 3,
+  u256: 4,
+  dec: 5,
+  bytes32: 6,
+  bytes: 7,
+  str: 8,
+  addr: 9,
+  key: 10,
+} as const
+
+/** Every type tag, including the system-only `bytes`. */
+export type TypeTag = keyof typeof TYPE_IDS
+
+/** Every typeId, including the system-only `7` (`bytes`). */
+export type TypeId = (typeof TYPE_IDS)[TypeTag]
+
+/**
+ * The tags a client may set on an attribute. `bytes` is excluded: it backs the system `$payload`
+ * cell, which travels in its own operation field and is never carried in an attribute array.
+ */
+export type UserTypeTag = Exclude<TypeTag, "bytes">
+
+/** Whether a client may set an attribute of this type — everything except `bytes`. */
+export function isUserSettable(tag: TypeTag): tag is UserTypeTag {
+  return tag !== "bytes"
+}
+
+/**
+ * Marks a value as having passed its constructor's validation. The symbol is module-private, so a
+ * hand-written object literal is not assignable to {@link ArkivValue} — every value crossing the
+ * wire has been range-, length- and format-checked by {@link i32}, {@link u256}, {@link dec}, and
+ * friends.
+ */
+declare const validated: unique symbol
+
+/**
+ * A typed attribute value: the tag it was created with, plus the JavaScript representation of that
+ * type. Constructed only by the tagged constructors in `@arkiv-network/sdk/attr`.
+ *
+ * @typeParam tag - The type tag, which also discriminates the {@link ArkivValue} union.
+ * @typeParam value - The decoded JavaScript representation.
+ */
+export type Value<tag extends TypeTag, value> = {
+  readonly type: tag
+  readonly value: value
+  readonly [validated]: tag
+}
+
+/** A boolean. */
+export type BoolValue = Value<"bool", boolean>
+/** A 32-bit signed integer — the default for an untagged number. */
+export type I32Value = Value<"i32", number>
+/**
+ * A 64-bit unsigned integer — block heights, the
+ * entity-nonce and `$expiresAt` are all `u64` */
+export type U64Value = Value<"u64", bigint>
+/** A 256-bit unsigned integer. */
+export type U256Value = Value<"u256", bigint>
+/**
+ * A fixed-point decimal with 18 decimal places, held as its canonical decimal string (`"3.5"`).
+ * Use {@link decUnits} for the exact scaled integer when you need to do arithmetic.
+ */
+export type DecValue = Value<"dec", string>
+/** 32 opaque bytes, as lowercase `0x` hex. */
+export type Bytes32Value = Value<"bytes32", Hex>
+/** A UTF-8 string of at most 128 bytes. */
+export type StrValue = Value<"str", string>
+/** A 20-byte Ethereum address, as EIP-55 checksummed hex. */
+export type AddrValue = Value<"addr", Address>
+/** A reference to another entity. Weak by spec: dangling references are permitted. */
+export type KeyValue = Value<"key", Hex>
+/**
+ * Opaque variable-length bytes, as lowercase `0x` hex. System-only — it backs `$payload` and is
+ * never settable as an attribute, so it is produced by decoding but has no constructor.
+ */
+export type BytesValue = Value<"bytes", Hex>
+
+/** Any value a client may set on an attribute. */
+export type ArkivValue =
+  | BoolValue
+  | I32Value
+  | U64Value
+  | U256Value
+  | DecValue
+  | Bytes32Value
+  | StrValue
+  | AddrValue
+  | KeyValue
+
+/** Any value that can come back from the node, including the system-only `bytes`. */
+export type AnyArkivValue = ArkivValue | BytesValue
+
+/** The value type for a given tag — e.g. `ValueOf<"u256">` is {@link U256Value}. */
+export type ValueOf<tag extends TypeTag> = Extract<AnyArkivValue, { type: tag }>
+
+/** The JavaScript representation carried by a value — e.g. `Decoded<U256Value>` is `bigint`. */
+export type Decoded<value extends AnyArkivValue> = value["value"]
+
+/**
+ * Builds a validated value. Module-internal: the constructors in `values.ts` call this **after**
+ * validating, which is what makes the {@link validated} brand meaningful.
+ */
+export function makeValue<tag extends TypeTag>(
+  type: tag,
+  value: Decoded<ValueOf<tag>>,
+): ValueOf<tag> {
+  return { type, value } as unknown as ValueOf<tag>
+}
+
+/**
+ * Whether `input` has the *shape* of an {@link ArkivValue} — a known type tag and a value.
+ */
+export function isArkivValue(input: unknown): input is AnyArkivValue {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    "type" in input &&
+    "value" in input &&
+    typeof (input as { type: unknown }).type === "string" &&
+    // `Object.hasOwn`, not `in`: `in` walks the prototype chain, so `{ type: "constructor" }` would
+    // be accepted as a typed value and then decode to nothing.
+    Object.hasOwn(TYPE_IDS, (input as { type: string }).type)
+  )
+}