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

package/src/schema/column.ts

@@ -0,0 +1,193 @@
+import type { Hex } from "viem"
+import { SchemaDefinitionError } from "./errors"
+import type { ArkivValue, IndexableTypeTag, TypeTag, ValueOf } from "./types"
+
+/**
+ * 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.
+ */
+export 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()
+ */
+export 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.
+ */
+export 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>
+}
+
+/**
+ * Marks a column. A registry symbol rather than `instanceof`, so a column made by one copy of the
+ * SDK — its ESM build, say — is still recognised by another, such as the CJS build a dependency
+ * loaded.
+ */
+const COLUMN_BRAND = Symbol.for("@arkiv-network/sdk/column")
+
+/** Resolves the input to `.default(...)` into a value of the column's type. */
+type Coerce = (tag: TypeTag, input: unknown) => ArkivValue
+
+class ColumnDefinition {
+  readonly type: TypeTag
+  readonly isIndexed: boolean
+  readonly isOptional: boolean
+  readonly defaultValue: ArkivValue | undefined
+  readonly #coerce: Coerce
+
+  constructor(
+    type: TypeTag,
+    isIndexed: boolean,
+    isOptional: boolean,
+    defaultValue: ArkivValue | undefined,
+    coerce: Coerce,
+  ) {
+    this.type = type
+    this.isIndexed = isIndexed
+    this.isOptional = isOptional
+    this.defaultValue = defaultValue
+    this.#coerce = coerce
+    Object.defineProperty(this, COLUMN_BRAND, { value: true })
+    Object.freeze(this)
+  }
+
+  indexed(): ColumnDefinition {
+    // Unreachable from typed code — a bytes column has no `indexed` — so this is for the callers
+    // the type system does not cover.
+    if (this.type === "bytes") {
+      throw new SchemaDefinitionError(
+        "a bytes column cannot be indexed. Bytes are stored, never indexed, so they can be " +
+          "selected but not filtered on — index a str, bytes32 or key derived from them instead",
+      )
+    }
+    return this.#with({ isIndexed: true })
+  }
+
+  optional(): ColumnDefinition {
+    return this.#with({ isOptional: true })
+  }
+
+  default(...args: unknown[]): ColumnDefinition {
+    // Counted rather than compared to undefined: `.default(undefined)` is a mistake to report, not
+    // a request for no default.
+    if (args.length === 0) {
+      throw new SchemaDefinitionError(
+        `.default() needs a value — e.g. ${this.type}().default(...). Leave .default() off for a ` +
+          "column the create must always provide",
+      )
+    }
+    return this.#with({ defaultValue: this.#coerce(this.type, args[0]) })
+  }
+
+  #with(
+    changes: Partial<Pick<ColumnDefinition, "isIndexed" | "isOptional" | "defaultValue">>,
+  ): ColumnDefinition {
+    return new ColumnDefinition(
+      this.type,
+      changes.isIndexed ?? this.isIndexed,
+      changes.isOptional ?? this.isOptional,
+      changes.defaultValue ?? this.defaultValue,
+      this.#coerce,
+    )
+  }
+}
+
+/**
+ * A fresh column of type `tag`: unindexed, required, no default. Internal seam for the type
+ * constructors, which return one when called with no arguments.
+ */
+export function createColumn<T extends TypeTag>(
+  tag: T,
+  coerce: Coerce,
+): Column<T, false, false, false> {
+  return new ColumnDefinition(tag, false, false, undefined, coerce) as unknown as Column<
+    T,
+    false,
+    false,
+    false
+  >
+}
+
+/** Whether `input` is a column, as opposed to a value or anything else. */
+export function isColumn(input: unknown): input is AnyColumn {
+  return typeof input === "object" && input !== null && COLUMN_BRAND in input
+}

package/src/{attr → schema}/errors.ts

@@ -23,8 +23,8 @@ export class InvalidValueError extends Error {
 
 /**
  * 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`).
+ * handed something that is neither a tagged value nor one of the five bare forms
+ * (`boolean`, `number`, `bigint`, `string`, `Uint8Array`).
  */
 export class UntypedValueError extends Error {
   readonly input: unknown
@@ -33,7 +33,7 @@ export class UntypedValueError extends Error {
     super(
       `Cannot infer an Arkiv type for ${describe(input)}. ` +
         "Attribute values must be a tagged value (i32, u64, u256, dec, str, addr, key, bytes32, " +
-        "bool) or a bare boolean, number, bigint or string.",
+        "bytes, bool) or a bare boolean, number, bigint, string or Uint8Array.",
     )
     this.name = "UntypedValueError"
     this.input = input
@@ -44,8 +44,12 @@ export class UntypedValueError extends Error {
  * 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.
+ * 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.
  */
 export class MissingValueError extends Error {
   /** The attribute whose value was missing, when raised from an attribute map. */
@@ -57,8 +61,9 @@ export class MissingValueError extends Error {
       `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."
+          ? `Leave "${attributeName}" out of the values (or a patch's "set") instead — e.g. ` +
+            "build the object conditionally, or drop the key when the value is absent. To remove " +
+            `the column from an existing entity, list it in a patch's "unset".`
           : "Omit the attribute instead of giving it an empty value."),
     )
     this.name = "MissingValueError"
@@ -97,14 +102,66 @@ export class ConflictingMutationError extends Error {
   }
 }
 
-/** More attributes were supplied than an entity operation can carry. */
+/**
+ * More attributes were supplied than an entity operation can carry — raised by `defineSchema` for a
+ * schema with more columns than one create could write.
+ */
 export class TooManyAttributesError extends Error {
-  constructor(count: number, max: number) {
-    super(`An entity may carry at most ${max} attributes, got ${count}.`)
+  /**
+   * @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 = false) {
+    super(
+      `An entity may carry at most ${max} attributes, got ${count}.` +
+        (tagged
+          ? ` A named schema's tag counts as one of them, so it may declare at most ${max - 1} ` +
+            "columns."
+          : ""),
+    )
     this.name = "TooManyAttributesError"
   }
 }
 
+/** The `bytes` values of one create or patch add up to more than `MAX_ENTITY_BYTES`. */
+export class EntityTooLargeError extends Error {
+  constructor(total: number, max: number) {
+    super(
+      `The bytes columns of one create or patch may hold at most ${max} bytes in total, got ` +
+        `${total}. Split the data across entities, or store it elsewhere and keep a reference`,
+    )
+    this.name = "EntityTooLargeError"
+  }
+}
+
+/** A schema, or one of its columns, was defined in a way the SDK or the protocol cannot honour. */
+export class SchemaDefinitionError extends Error {
+  /** The column at fault, when there is one. */
+  readonly columnName: string | undefined
+
+  constructor(reason: string, columnName?: string) {
+    super(`Invalid schema${columnName === undefined ? "" : ` column "${columnName}"`}: ${reason}.`)
+    this.name = "SchemaDefinitionError"
+    this.columnName = columnName
+  }
+}
+
+/**
+ * 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.
+ */
+export class SchemaMismatchError extends Error {
+  /** The column at fault. */
+  readonly columnName: string
+
+  constructor(columnName: string, reason: string) {
+    super(`Column "${columnName}": ${reason}.`)
+    this.name = "SchemaMismatchError"
+    this.columnName = columnName
+  }
+}
+
 /** 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. */

package/src/schema/index.ts

@@ -0,0 +1,76 @@
+export type { AttributeSchema, Attributes } from "./attributes"
+export { MAX_ENTITY_BYTES } from "./attributes"
+export type { AnyColumn, Column, ValueArgument } from "./column"
+export { isColumn } from "./column"
+export { DECIMAL_SCALE, DECIMAL_UNIT } from "./decimal"
+export {
+  ConflictingMutationError,
+  EntityTooLargeError,
+  InvalidAttributeNameError,
+  InvalidValueError,
+  MissingValueError,
+  SchemaDefinitionError,
+  SchemaMismatchError,
+  TooManyAttributesError,
+  UnknownAttributeTypeError,
+  UntypedValueError,
+} from "./errors"
+export { isValidAttributeName, MAX_NAME_BYTES, validateAttributeName } from "./names"
+export type {
+  ColumnInput,
+  Columns,
+  ColumnsOf,
+  CreateEntityValues,
+  IndexedColumnName,
+  OptionalColumnName,
+  PatchEntityValues,
+  Schema,
+} from "./schema"
+export {
+  defineSchema,
+  describeColumns,
+  isSchema,
+  lookupColumn,
+  MAX_ATTRIBUTES,
+  SCHEMA_ATTRIBUTE,
+} from "./schema"
+export type {
+  AddrValue,
+  ArkivValue,
+  BoolValue,
+  Bytes32Value,
+  BytesValue,
+  DecValue,
+  I32Value,
+  IndexableTypeTag,
+  IndexableValue,
+  KeyValue,
+  StrValue,
+  TypeTag,
+  U64Value,
+  U256Value,
+  ValueOf,
+} from "./types"
+export { INDEXED_FLAG, isArkivValue } from "./types"
+export type { BareOf, TagOf, ValueInput } from "./values"
+export {
+  addr,
+  bool,
+  bytes,
+  bytes32,
+  dec,
+  decFromUnits,
+  decUnits,
+  I32_MAX,
+  I32_MIN,
+  i32,
+  key,
+  MAX_BYTES_LENGTH,
+  MAX_STRING_BYTES,
+  str,
+  toValue,
+  U64_MAX,
+  U256_MAX,
+  u64,
+  u256,
+} from "./values"

package/src/{attr → schema}/names.ts

@@ -28,6 +28,7 @@ const RESERVED = new Set([
   "not",
   "true",
   "false",
+  "between",
   "startswith",
   "exists",
   "typeof",
@@ -49,8 +50,9 @@ const RESERVED = new Set([
  * 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.
+ * @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.
  */
 export function validateAttributeName(name: string): void {
   if (typeof name !== "string" || name.length === 0) {

package/src/schema/schema.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "bun:test"
+import { isColumn } from "./column"
+import {
+  InvalidAttributeNameError,
+  InvalidValueError,
+  SchemaDefinitionError,
+  TooManyAttributesError,
+} from "./errors"
+import { defineSchema, isSchema, MAX_ATTRIBUTES, SCHEMA_ATTRIBUTE } from "./schema"
+import { addr, bytes, dec, i32, str, u64 } from "./values"
+
+describe("columns", () => {
+  it("start unindexed, required and without a default", () => {
+    expect(str()).toMatchObject({
+      type: "str",
+      isIndexed: false,
+      isOptional: false,
+      defaultValue: undefined,
+    })
+  })
+
+  it("refine by returning a new column, leaving the original alone", () => {
+    const base = dec()
+    const refined = base.indexed().optional()
+    expect(refined).toMatchObject({ type: "dec", isIndexed: true, isOptional: true })
+    expect(base).toMatchObject({ isIndexed: false, isOptional: false })
+    expect(Object.isFrozen(refined)).toBe(true)
+  })
+
+  it("keep every refinement, whatever order they are chained in", () => {
+    const a = i32().default(3).indexed().optional()
+    const b = i32().optional().indexed().default(3)
+    for (const column of [a, b]) {
+      expect(column).toMatchObject({ isIndexed: true, isOptional: true, defaultValue: i32(3) })
+    }
+  })
+
+  it("take a default as the constructor's argument, or as a value of the column's type", () => {
+    expect(dec().default("4.1").defaultValue).toEqual(dec("4.1"))
+    expect(dec().default(dec("4.1")).defaultValue).toEqual(dec("4.1"))
+    expect(u64().default(5).defaultValue).toEqual(u64(5n))
+    expect(bytes().default(new Uint8Array([1])).defaultValue?.value).toBe("0x01")
+  })
+
+  it("validate a default when it is declared, not when it is first written", () => {
+    expect(() => dec().default("4.1.1")).toThrow(InvalidValueError)
+    expect(() => u64().default(-1)).toThrow(/negative/)
+    // A value of another type is not silently converted.
+    expect(() => dec().default(i32(4) as never)).toThrow(/i32 value, not a dec/)
+  })
+
+  it("reject a default that is missing or undefined", () => {
+    expect(() => (str() as unknown as { default(): unknown }).default()).toThrow(
+      SchemaDefinitionError,
+    )
+    expect(() => str().default(undefined as unknown as string)).toThrow(InvalidValueError)
+  })
+
+  it("never index bytes, even past the type system", () => {
+    const column = bytes() as unknown as { indexed(): unknown }
+    expect(() => column.indexed()).toThrow(/bytes column cannot be indexed/)
+  })
+})
+
+describe("defineSchema", () => {
+  it("keeps the columns, in the order they were declared", () => {
+    const Posts = defineSchema({ title: str(), score: dec().indexed(), body: bytes() })
+    expect(isSchema(Posts)).toBe(true)
+    expect(Object.keys(Posts.columns)).toEqual(["title", "score", "body"])
+    expect(isColumn(Posts.columns.score)).toBe(true)
+    expect(Object.isFrozen(Posts.columns)).toBe(true)
+  })
+
+  it("rejects a value where a column belongs, suggesting the default it may have meant", () => {
+    const define = () => defineSchema({ score: dec("4.1") } as never)
+    expect(define).toThrow(SchemaDefinitionError)
+    expect(define).toThrow(/did you mean dec\(\)\.default\("4\.1"\)/i)
+    expect(() => defineSchema({ n: u64(5n) } as never)).toThrow(/u64\(\)\.default\(5n\)/)
+  })
+
+  it("rejects anything else that is not a column", () => {
+    expect(() => defineSchema({ title: "str" } as never)).toThrow(/not a column/)
+    expect(() => defineSchema({ title: str } as never)).toThrow(/not a column/)
+    expect(() => defineSchema([] as never)).toThrow(SchemaDefinitionError)
+  })
+
+  it("holds column names to the attribute-name grammar", () => {
+    expect(() => defineSchema({ "1st": str() })).toThrow(InvalidAttributeNameError)
+    expect(() => defineSchema({ $owner: addr() })).toThrow(/reserved for system attributes/)
+  })
+
+  it("lets a column take a name an entity field has without the $, which a row keeps apart", () => {
+    for (const name of ["owner", "creator", "createdAt", "expiresAt", "attributes"]) {
+      expect(() => defineSchema({ [name]: str() })).not.toThrow()
+    }
+  })
+
+  it("caps the number of columns at what one operation can carry", () => {
+    const columns = (count: number) =>
+      Object.fromEntries(Array.from({ length: count }, (_, i) => [`c${i}`, i32()]))
+    expect(() => defineSchema(columns(MAX_ATTRIBUTES))).not.toThrow()
+    expect(() => defineSchema(columns(MAX_ATTRIBUTES + 1))).toThrow(TooManyAttributesError)
+  })
+
+  it("accepts a schema with no columns", () => {
+    expect(defineSchema({}).columns).toEqual({})
+  })
+})
+
+describe("named schemas", () => {
+  it("carry their name, and the str tag their entities are marked with", () => {
+    const Posts = defineSchema("posts", { title: str() })
+    expect(Posts.name).toBe("posts")
+    expect(Posts.tag).toEqual(str("posts"))
+    expect(Object.keys(Posts.columns)).toEqual(["title"])
+  })
+
+  it("leave an unnamed schema untagged", () => {
+    const Posts = defineSchema({ title: str() })
+    expect(Posts.name).toBeUndefined()
+    expect(Posts.tag).toBeUndefined()
+  })
+
+  it("reject a name that is not a valid str", () => {
+    expect(() => defineSchema("", { title: str() })).toThrow(/non-empty string/)
+    expect(() => defineSchema("a\nb", { title: str() })).toThrow(SchemaDefinitionError)
+    expect(() => defineSchema("x".repeat(129), { title: str() })).toThrow(/not a valid str tag/)
+  })
+
+  it("reserve the tag's attribute name, named or not", () => {
+    expect(() => defineSchema({ [SCHEMA_ATTRIBUTE]: str() })).toThrow(
+      /the attribute a named schema tags its entities with/,
+    )
+    expect(() => defineSchema("posts", { [SCHEMA_ATTRIBUTE]: str() })).toThrow(
+      SchemaDefinitionError,
+    )
+  })
+
+  it("count the tag against the attribute cap", () => {
+    const columns = Object.fromEntries(
+      Array.from({ length: MAX_ATTRIBUTES }, (_, i) => [`c${i}`, i32()]),
+    )
+    expect(() => defineSchema(columns)).not.toThrow()
+    expect(() => defineSchema("full", columns)).toThrow(/at most 32 attributes, got 33/)
+    expect(() => defineSchema("full", columns)).toThrow(/tag counts as one of them/)
+  })
+})
+
+describe("recognising schemas and columns", () => {
+  it("goes by a registry brand, so another copy of the SDK recognises them too", () => {
+    // What a schema built by a second copy of this module — the CJS build next to the ESM one —
+    // looks like from here: same shape, same registry symbol, a different class.
+    const foreign = Object.freeze(
+      Object.defineProperty(
+        { name: undefined, tag: undefined, columns: {} },
+        Symbol.for("@arkiv-network/sdk/schema"),
+        { value: true },
+      ),
+    )
+    expect(isSchema(foreign)).toBe(true)
+    expect(isSchema(defineSchema({ title: str() }))).toBe(true)
+    expect(
+      isColumn(Object.defineProperty({}, Symbol.for("@arkiv-network/sdk/column"), { value: true })),
+    ).toBe(true)
+  })
+
+  it("does not take a look-alike without the brand", () => {
+    expect(isSchema({ columns: {} })).toBe(false)
+    expect(isColumn({ type: "str", isIndexed: false, isOptional: false })).toBe(false)
+  })
+})