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

package/dist/index-C-mMF5WZ.d.cts

@@ -0,0 +1,735 @@
+import { Address, Hex } from "viem";
+
+//#region src/schema/types.d.ts
+
+/**
+ * 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        | when indexed      |
+ * | --------- | ------ | -------------------- | ----------------- |
+ * | `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` (<= 128 KiB) | never indexed     |
+ * | `str`     | 8      | `string` (<= 128 B)  | equality + prefix |
+ * | `addr`    | 9      | `address`            | equality          |
+ * | `key`     | 10     | `bytes32`            | equality          |
+ *
+ * On the wire the typeId shares its byte with the indexed flag — see {@link INDEXED_FLAG}.
+ */
+declare const TYPE_IDS: {
+  readonly bool: 1;
+  readonly i32: 2;
+  readonly u64: 3;
+  readonly u256: 4;
+  readonly dec: 5;
+  readonly bytes32: 6;
+  readonly bytes: 7;
+  readonly str: 8;
+  readonly addr: 9;
+  readonly key: 10;
+};
+/**
+ * Bit 7 of the `typeId` byte: set when the node should index the attribute. The low seven bits are
+ * the type itself, so `str` travels as `8` unindexed and `0x88` indexed.
+ */
+declare const INDEXED_FLAG = 128;
+/** Every type tag. */
+type TypeTag = keyof typeof TYPE_IDS;
+/**
+ * The tags an attribute may be indexed with — every type except `bytes`, which is stored but never
+ * indexed, and so can never be filtered on.
+ */
+type IndexableTypeTag = Exclude<TypeTag, "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 `i32`, `u256`, `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/schema`.
+ *
+ * @typeParam tag - The type tag, which also discriminates the {@link ArkivValue} union.
+ * @typeParam value - The decoded JavaScript representation.
+ */
+type Value<tag$1 extends TypeTag, value> = {
+  readonly type: tag$1;
+  readonly value: value;
+  readonly [validated]: tag$1;
+};
+/** A boolean. */
+type BoolValue = Value<"bool", boolean>;
+/** A 32-bit signed integer — the default for an untagged number. */
+type I32Value = Value<"i32", number>;
+/**
+ * A 64-bit unsigned integer — block heights, the
+ * entity-nonce and `$expiresAt` are all `u64` */
+type U64Value = Value<"u64", bigint>;
+/** A 256-bit unsigned integer. */
+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.
+ */
+type DecValue = Value<"dec", string>;
+/** 32 opaque bytes, as lowercase `0x` hex. */
+type Bytes32Value = Value<"bytes32", Hex>;
+/** A UTF-8 string of at most 128 bytes, free of C0 control characters and DEL. */
+type StrValue = Value<"str", string>;
+/** A 20-byte Ethereum address, as EIP-55 checksummed hex. */
+type AddrValue = Value<"addr", Address>;
+/** A reference to another entity. Weak by spec: dangling references are permitted. */
+type KeyValue = Value<"key", Hex>;
+/**
+ * Opaque variable-length bytes, as lowercase `0x` hex — a blob. Stored but never indexed, so it can
+ * be selected but not filtered on.
+ */
+type BytesValue = Value<"bytes", Hex>;
+/** Any attribute value. */
+type ArkivValue = BoolValue | I32Value | U64Value | U256Value | DecValue | Bytes32Value | BytesValue | StrValue | AddrValue | KeyValue;
+/** Any value of a type that can be indexed, and so can appear in a query — everything but `bytes`. */
+type IndexableValue = Exclude<ArkivValue, BytesValue>;
+/** The value type for a given tag — e.g. `ValueOf<"u256">` is {@link U256Value}. */
+type ValueOf<tag$1 extends TypeTag> = Extract<ArkivValue, {
+  type: tag$1;
+}>;
+/**
+ * Whether `input` has the *shape* of an {@link ArkivValue} — a known type tag and a value.
+ */
+declare function isArkivValue(input: unknown): input is ArkivValue;
+//#endregion
+//#region src/schema/column.d.ts
+/**
+ * What each type's constructor accepts as a value — `dec("4.1")`, `addr("0x…")`, `bytes(buf)`.
+ * A column's `.default(...)` takes the same thing, or an already-typed value.
+ */
+type ValueArgument<T extends TypeTag> = {
+  bool: boolean;
+  i32: number | bigint;
+  u64: bigint | number | string;
+  u256: bigint | number | string;
+  dec: string | number | bigint;
+  bytes32: Hex | Uint8Array;
+  bytes: Hex | Uint8Array;
+  str: string;
+  addr: string;
+  key: Hex | Uint8Array;
+}[T];
+/**
+ * A column: the declaration of one attribute in a schema — its type, whether the node indexes it,
+ * whether an entity may leave it unset, and the value the SDK writes when a create leaves it out.
+ *
+ * Built by calling a type constructor with no arguments — `str()`, `dec()`, `bytes()` — and refined
+ * by chaining. Every refinement returns a new column; a column is never modified in place.
+ *
+ * @typeParam T - The attribute's type tag.
+ * @typeParam I - Whether the attribute is indexed.
+ * @typeParam O - Whether the attribute may be absent.
+ * @typeParam D - Whether the column has a default.
+ *
+ * @example
+ * str()                          // stored, not indexed, required
+ * str().indexed()                // filterable with eq / ne / startsWith
+ * dec().indexed().optional()     // filterable, and an entity may leave it unset
+ * str().default("text/markdown") // filled in on create when left out
+ * bytes()                        // a blob; bytes has no .indexed()
+ */
+type Column<T extends TypeTag = TypeTag, I extends boolean = boolean, O extends boolean = boolean, D extends boolean = boolean> = ColumnProperties<T, I, O, D> & (T extends IndexableTypeTag ? IndexableColumn<T, O, D> : unknown);
+/**
+ * Any column, whatever its type and flags — the shape a schema is built from. Written out rather
+ * than derived from {@link Column}, whose refinement methods would make every column's type
+ * invariant in its tag.
+ */
+type AnyColumn = {
+  readonly type: TypeTag;
+  readonly isIndexed: boolean;
+  readonly isOptional: boolean;
+  readonly defaultValue: ArkivValue | undefined;
+};
+type ColumnProperties<T extends TypeTag, I extends boolean, O extends boolean, D extends boolean> = {
+  /** The attribute's type tag. */
+  readonly type: T;
+  /** Whether the node indexes the attribute, which is what makes it usable in `where`. */
+  readonly isIndexed: I;
+  /**
+   * Whether an entity may leave the attribute unset. A create may then omit it, a patch may unset
+   * it, and a read gives back `undefined` where it is missing.
+   */
+  readonly isOptional: O;
+  /** The value a create writes when the attribute is left out, if the column has one. */
+  readonly defaultValue: D extends true ? ValueOf<T> : undefined;
+  /** The same column, allowed to be absent. */
+  optional(): Column<T, I, true, D>;
+  /**
+   * The same column, with a value that a create writes whenever the attribute is left out. The
+   * default is applied by the SDK, not the node, and only on create.
+   *
+   * @param value - What the type's constructor would accept — `dec().default("4.1")` — or a value
+   * of the column's type.
+   * @throws {InvalidValueError} If the value does not fit the column's type.
+   */
+  default(value: ValueArgument<T> | ValueOf<T>): Column<T, I, O, true>;
+};
+type IndexableColumn<T extends IndexableTypeTag, O extends boolean, D extends boolean> = {
+  /**
+   * The same column, indexed by the node. Only indexed attributes can be filtered on in `where`;
+   * an unindexed one can be stored and selected, and does not pay for an index.
+   */
+  indexed(): Column<T, true, O, D>;
+};
+/** Resolves the input to `.default(...)` into a value of the column's type. */
+
+/** Whether `input` is a column, as opposed to a value or anything else. */
+declare function isColumn(input: unknown): input is AnyColumn;
+//#endregion
+//#region src/schema/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;
+/**
+ * The longest `bytes` value, in bytes. The cap applies to each `bytes` attribute separately, but
+ * all the `bytes` values of one create or patch also share the `MAX_ENTITY_BYTES` budget.
+ */
+declare const MAX_BYTES_LENGTH: number;
+/** A `bool` column, indexed for equality once `.indexed()`. */
+declare function bool(): Column<"bool", false, false, false>;
+/**
+ * A boolean.
+ *
+ * This is the default type for a bare boolean, so `{ flagged: true }` and
+ * `{ flagged: bool(true) }` are the same value.
+ *
+ * @example
+ * bool(true) // { type: "bool", value: true }
+ */
+declare function bool(value: boolean): BoolValue;
+/** An `i32` column, indexed for equality and range queries once `.indexed()`. */
+declare function i32(): Column<"i32", false, false, false>;
+/**
+ * A 32-bit signed integer. This is the default type for a bare number, so `{ level: 10 }` and
+ * `{ level: i32(10) }` are the same value.
+ *
+ * @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 `u256` column, indexed for equality and range queries once `.indexed()`. */
+declare function u256(): Column<"u256", false, false, false>;
+/**
+ * A 256-bit unsigned integer. 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 `u64` column, indexed for equality and range queries once `.indexed()`. */
+declare function u64(): Column<"u64", false, false, false>;
+/**
+ * A 64-bit unsigned integer.
+ *
+ * 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 `dec` column, indexed for equality and range queries once `.indexed()`. */
+declare function dec(): Column<"dec", false, false, false>;
+/**
+ * A signed fixed-point decimal with exactly 18 decimal places.
+ *
+ * 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 as a number
+ */
+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 `str` column, indexed for equality and prefix (`STARTSWITH`) matching once `.indexed()`. */
+declare function str(): Column<"str", false, false, false>;
+/**
+ * A UTF-8 string of at most 128 bytes.
+ *
+ * The limit is on **bytes**, not characters: a string of 128 emoji does not fit.
+ *
+ * C0 control characters and DEL are rejected: the query language writes a `str` as `str('...')`,
+ * whose only escape is a doubled quote, so a control character could be stored but never queried.
+ *
+ * @throws {InvalidValueError} If the value is not a string, holds a control character, or exceeds
+ * 128 UTF-8 bytes.
+ *
+ * @example
+ * str("Bob")
+ */
+declare function str(value: string): StrValue;
+/** An `addr` column, indexed for equality once `.indexed()`. */
+declare function addr(): Column<"addr", false, false, false>;
+/**
+ * A 20-byte Ethereum address.
+ *
+ * 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 `key` column — a reference to another entity — indexed for equality once `.indexed()`. */
+declare function key(): Column<"key", false, false, false>;
+/**
+ * A reference to another entity.
+ *
+ * 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;
+/** A `bytes32` column, indexed for equality once `.indexed()`. */
+declare function bytes32(): Column<"bytes32", false, false, false>;
+/**
+ * 32 opaque bytes — a hash, a digest, an identifier from another system.
+ *
+ * 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 `bytes` column — a blob. Bytes are stored but never indexed, so a bytes column has no
+ * `.indexed()`: it can be selected, not filtered on. A schema may have several, within the
+ * `MAX_ATTRIBUTES` cap on columns — but the `bytes` values of one create or patch share a single
+ * `MAX_ENTITY_BYTES` budget.
+ */
+declare function bytes(): Column<"bytes", false, false, false>;
+/**
+ * Opaque bytes of any length up to 128 KiB — a document, an image, a serialized object. This is the
+ * default type for a bare `Uint8Array`, so `{ body: buf }` and `{ body: bytes(buf) }` are the same
+ * value.
+ *
+ * @param value - The bytes, raw or as `0x` hex. Hex is taken as the bytes it spells, never as text.
+ * @throws {InvalidValueError} If the value is not bytes or hex, or exceeds 128 KiB.
+ *
+ * @example
+ * bytes(new TextEncoder().encode("# Hello"))
+ * bytes("0xdeadbeef")
+ */
+declare function bytes(value: Hex | Uint8Array): BytesValue;
+/**
+ * A JavaScript value accepted wherever a typed value is expected: either a tagged value, or one of
+ * the five bare forms that map unambiguously onto a single type.
+ *
+ * | bare form    | type    |
+ * | ------------ | ------- |
+ * | `boolean`    | `bool`  |
+ * | `number`     | `i32`   |
+ * | `bigint`     | `u256`  |
+ * | `string`     | `str`   |
+ * | `Uint8Array` | `bytes` |
+ *
+ * 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 a bare value where its
+ * column has another type: a bare `bigint` is a `u256`, not a {@link u64}. Through a schema that is
+ * caught — a write throws `SchemaMismatchError` and a query throws `InvalidPredicateError` — but a
+ * query without a schema sends the predicate as written, and the engine, for which a type mismatch
+ * is not an error, simply matches nothing.
+ */
+type ValueInput = ArkivValue | boolean | number | bigint | string | Uint8Array;
+/**
+ * The type a {@link ValueInput} resolves to — the tag of a tagged value, or the default of a bare
+ * form. `never` for anything else.
+ */
+type TagOf<input> = input extends {
+  readonly type: infer tag extends TypeTag;
+} ? tag : input extends boolean ? "bool" : input extends number ? "i32" : input extends bigint ? "u256" : input extends string ? "str" : input extends Uint8Array ? "bytes" : never;
+/**
+ * The bare JavaScript form that defaults to `tag`, where there is one — `boolean` for `bool`,
+ * `number` for `i32`, `bigint` for `u256`, `string` for `str`, `Uint8Array` for `bytes`. The other
+ * types — `u64`, `dec`, `bytes32`, `addr` and `key` — must be written tagged.
+ */
+type BareOf<tag$1 extends TypeTag> = {
+  bool: boolean;
+  i32: number;
+  u64: never;
+  u256: bigint;
+  dec: never;
+  bytes32: never;
+  bytes: Uint8Array;
+  str: string;
+  addr: never;
+  key: never;
+}[tag$1];
+/**
+ * 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,
+ * string or `Uint8Array`.
+ * @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/schema/schema.d.ts
+/**
+ * The most attributes one entity operation may carry, and so the most columns a schema may have —
+ * one fewer for a named schema, whose tag is one more attribute on every create.
+ */
+declare const MAX_ATTRIBUTES = 32;
+/**
+ * The attribute a named schema tags its entities with: an indexed `str` holding the schema's name.
+ * Creates write it, and `.from(schema)` filters on it, so a query through a schema only ever sees
+ * entities written through it.
+ */
+declare const SCHEMA_ATTRIBUTE = "arkiv.schema";
+/** A schema's columns, keyed by attribute name. */
+type Columns = {
+  readonly [name: string]: AnyColumn;
+};
+/**
+ * A schema: the named, typed attributes an entity of one kind carries, and which of them the node
+ * indexes. Built with {@link defineSchema}.
+ *
+ * A schema is an SDK-side convention. The node sees only attributes, each with a type and an
+ * indexed flag; the schema is what types the SDK's writes and reads, and checks them at runtime.
+ *
+ * A named schema also tags every entity it creates with its name, in the indexed
+ * {@link SCHEMA_ATTRIBUTE} attribute, so that a query through it sees only its own entities.
+ *
+ * @typeParam C - The columns, keyed by attribute name.
+ */
+declare class Schema<C extends Columns = Columns> {
+  /** The name entities are tagged with, or `undefined` for an untagged schema. */
+  readonly name: string | undefined;
+  /** The columns, keyed by attribute name, in the order they were declared. */
+  readonly columns: C;
+  /** The tag every create writes and every query filters on, if the schema is named. */
+  readonly tag: StrValue | undefined;
+  /** Use {@link defineSchema}. */
+  constructor(name: string | undefined, columns: C);
+}
+/**
+ * Declares a schema: the attributes an entity carries, their types, and which of them are indexed.
+ *
+ * Each column is a type constructor called with no arguments — `str()`, `dec()`, `bytes()` —
+ * refined with `.indexed()`, `.optional()` or `.default(...)`. Only indexed columns can be
+ * filtered on; the rest are stored and selectable, and do not pay for an index.
+ *
+ * Give the schema a name to tag its entities: every create then also writes an indexed
+ * `arkiv.schema` attribute holding the name, and `.from(schema)` filters on it — the way a
+ * collection keeps one model's documents apart from another's. Without a name, a query through the
+ * schema sees every entity its `where` matches, whatever wrote it — though the columns it selects
+ * are still checked against the schema, so an entity that does not fit is left out of the page, or
+ * fails the query with `{ onMismatch: "throw" }`.
+ *
+ * @param name - The name entities are tagged with — a `str`, so at most 128 bytes. Optional.
+ * @param columns - The columns, keyed by attribute name.
+ * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+ * @throws {SchemaDefinitionError} If the name is not a valid `str`, an entry is not a column, or a
+ * column is named after the schema tag.
+ * @throws {TooManyAttributesError} If there are more columns than one create can carry — at most
+ * {@link MAX_ATTRIBUTES}, or one fewer for a named schema, whose tag counts as an attribute.
+ *
+ * @example
+ * import { addr, bytes, dec, defineSchema, str } from "@arkiv-network/sdk/schema"
+ *
+ * const Posts = defineSchema("posts", {
+ *   author:    addr().indexed(),
+ *   category:  str().indexed(),
+ *   score:     dec().indexed(),
+ *   title:     str(),                          // stored, not indexed
+ *   body:      bytes(),                        // a blob; bytes can never be indexed
+ *   thumbnail: bytes().optional(),             // bytes columns share one MAX_ENTITY_BYTES budget
+ *   mimeType:  str().default("text/markdown"), // written on create when left out
+ * })
+ */
+declare function defineSchema<const C extends Columns>(name: string, columns: C): Schema<C>;
+declare function defineSchema<const C extends Columns>(columns: C): Schema<C>;
+/** Whether `input` is a schema built with {@link defineSchema}. */
+declare function isSchema(input: unknown): input is Schema;
+/**
+ * The column `name` of `schema`, or `undefined` if it has none. Only the schema's own columns
+ * count, so an inherited key such as `toString` or `__proto__` is not mistaken for one.
+ */
+declare function lookupColumn(schema: Schema, name: string): AnyColumn | undefined;
+/** The schema's column names, for an error message that has to say what would have worked. */
+declare function describeColumns(schema: Schema): string;
+/** The columns of a schema. */
+type ColumnsOf<S extends Schema> = S["columns"];
+/**
+ * What a write accepts for a column of type `T`: a value of that type, or the bare form that
+ * defaults to it — a `string` for `str`, a `Uint8Array` for `bytes`, a `number` for `i32`, a
+ * `bigint` for `u256`, a `boolean` for `bool`. Every other type is written tagged.
+ */
+type ColumnInput<T extends TypeTag> = ValueOf<T> | BareOf<T>;
+/** The columns a create must provide: neither optional nor defaulted. */
+type RequiredColumnName<C extends Columns> = { [K in keyof C]: C[K] extends {
+  readonly isOptional: false;
+  readonly defaultValue: undefined;
+} ? K : never }[keyof C];
+/** The columns an entity may leave unset — which is to say, the ones a patch may unset. */
+type OptionalColumnName<S extends Schema> = { [K in keyof ColumnsOf<S>]: true extends ColumnsOf<S>[K]["isOptional"] ? K : never }[keyof ColumnsOf<S>] & string;
+/** The indexed columns, which are the only ones `where` can filter on. */
+type IndexedColumnName<S extends Schema> = { [K in keyof ColumnsOf<S>]: true extends ColumnsOf<S>[K]["isIndexed"] ? K : never }[keyof ColumnsOf<S>] & string;
+/**
+ * The values a create takes for schema `S`: every required column, plus any optional or
+ * defaulted one. A defaulted column left out is written with its default.
+ *
+ * @example
+ * const values: CreateEntityValues<typeof Posts> = {
+ *   author: addr("0x…"),
+ *   category: "docs",          // bare string -> str
+ *   score: dec("4.1"),
+ *   title: "Cells, not entities",
+ *   body: new Uint8Array(),    // bare Uint8Array -> bytes
+ * }
+ */
+type CreateEntityValues<S extends Schema> = Prettify$1<{ readonly [K in RequiredColumnName<ColumnsOf<S>>]: ColumnInput<ColumnsOf<S>[K]["type"]> } & { readonly [K in Exclude<keyof ColumnsOf<S>, RequiredColumnName<ColumnsOf<S>>>]?: ColumnInput<ColumnsOf<S>[K]["type"]> | undefined }>;
+/**
+ * What a patch writes for schema `S`: any subset of its columns. Defaults do not apply — a patch
+ * changes only what it names — and a column given as `undefined` is left alone, as a create
+ * leaves it out.
+ */
+type PatchEntityValues<S extends Schema> = { readonly [K in keyof ColumnsOf<S>]?: ColumnInput<ColumnsOf<S>[K]["type"]> | undefined };
+type Prettify$1<T> = { [K in keyof T]: T[K] } & {};
+//#endregion
+//#region src/schema/attributes.d.ts
+/**
+ * The most data the `bytes` columns of one create or patch may hold together, in bytes. Each
+ * `bytes` value is also capped on its own, at `MAX_BYTES_LENGTH`.
+ *
+ * Provisional: the protocol has not settled a per-entity cap yet, so this keeps the budget the
+ * single payload had — and an operation much larger than it would not fit in a transaction the
+ * node accepts anyway.
+ */
+declare const MAX_ENTITY_BYTES: number;
+/**
+ * An entity's attributes as a whole — what the `$attributes` selection returns — keyed by name,
+ * every value typed.
+ *
+ * The vocabulary is the same in both directions, so a value read from here drops straight back into
+ * a write — as long as its name is a column of the schema the write goes through.
+ */
+type Attributes = Readonly<Record<string, ArkivValue>>;
+/**
+ * The names, types and indexing of an entity's attributes, with no values — what the
+ * `$attributeSchema` selection returns. `indexed` is `undefined` when the node did not say.
+ *
+ * It is for finding out what entities hold before fetching their values. Values can be large — a
+ * `bytes` attribute holds up to 128 KiB — and an RPC endpoint may cap how big a response it sends,
+ * so a page of 100 entities with every attribute can be more than it will return. The schema is a
+ * few bytes per attribute: select it for a page, then fetch the attributes you need by name, or the
+ * large ones a few entities at a time.
+ *
+ * It also tells apart two entities that use the same name with different types, and shows which
+ * attributes are indexed, and so can be filtered on.
+ */
+type AttributeSchema = Readonly<Record<string, {
+  type: TypeTag;
+  indexed: boolean | undefined;
+}>>;
+//#endregion
+//#region src/schema/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/schema/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 five bare forms
+ * (`boolean`, `number`, `bigint`, `string`, `Uint8Array`).
+ */
+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 rather than to write an empty value — or, to
+ * remove a column from an existing entity, to `unset` it in a patch — so this is called out
+ * separately from {@link UntypedValueError}: the remedy is different.
+ *
+ * `createEntity` and `patchEntity` already treat a column given as `undefined` as left out, so
+ * through them only `null` raises this.
+ */
+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 — raised by `defineSchema` for a
+ * schema with more columns than one create could write.
+ */
+declare class TooManyAttributesError extends Error {
+  /**
+   * @param tagged - Whether `count` includes a named schema's tag, which the message then calls out:
+   * the tag is not among the declared columns, so the count would otherwise look off by one.
+   */
+  constructor(count: number, max: number, tagged?: boolean);
+}
+/** The `bytes` values of one create or patch add up to more than `MAX_ENTITY_BYTES`. */
+declare class EntityTooLargeError extends Error {
+  constructor(total: number, max: number);
+}
+/** A schema, or one of its columns, was defined in a way the SDK or the protocol cannot honour. */
+declare class SchemaDefinitionError extends Error {
+  /** The column at fault, when there is one. */
+  readonly columnName: string | undefined;
+  constructor(reason: string, columnName?: string);
+}
+/**
+ * Data did not fit its schema: a write named a column the schema does not have, left out one it
+ * requires, or gave one a value of the wrong type — or an entity read back through a schema lacks a
+ * required column or holds one with a different type.
+ */
+declare class SchemaMismatchError extends Error {
+  /** The column at fault. */
+  readonly columnName: string;
+  constructor(columnName: string, reason: string);
+}
+/** 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/schema/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, starts with `$` (reserved for system
+ * attributes), too long, uses characters outside the grammar, contains `--` (which opens a query
+ * comment), 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 { u256 as $, describeColumns as A, U64_MAX as B, IndexedColumnName as C, SCHEMA_ATTRIBUTE as D, PatchEntityValues as E, I32_MIN as F, bytes32 as G, addr as H, MAX_BYTES_LENGTH as I, decUnits as J, dec as K, MAX_STRING_BYTES as L, lookupColumn as M, BareOf as N, Schema as O, I32_MAX as P, toValue as Q, TagOf as R, CreateEntityValues as S, OptionalColumnName as T, bool as U, ValueInput as V, bytes as W, key as X, i32 as Y, str as Z, Attributes as _, TypeTag as _t, EntityTooLargeError as a, AddrValue as at, Columns as b, ValueOf as bt, MissingValueError as c, Bytes32Value as ct, TooManyAttributesError as d, I32Value as dt, u64 as et, UnknownAttributeTypeError as f, INDEXED_FLAG as ft, AttributeSchema as g, StrValue as gt, DECIMAL_UNIT as h, KeyValue as ht, ConflictingMutationError as i, isColumn as it, isSchema as j, defineSchema as k, SchemaDefinitionError as l, BytesValue as lt, DECIMAL_SCALE as m, IndexableValue as mt, isValidAttributeName as n, Column as nt, InvalidAttributeNameError as o, ArkivValue as ot, UntypedValueError as p, IndexableTypeTag as pt, decFromUnits as q, validateAttributeName as r, ValueArgument as rt, InvalidValueError as s, BoolValue as st, MAX_NAME_BYTES as t, AnyColumn as tt, SchemaMismatchError as u, DecValue as ut, MAX_ENTITY_BYTES as v, U256Value as vt, MAX_ATTRIBUTES as w, ColumnsOf as x, isArkivValue as xt, ColumnInput as y, U64Value as yt, U256_MAX as z };
+//# sourceMappingURL=index-C-mMF5WZ.d.cts.map