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

package/src/schema/schema.ts

@@ -0,0 +1,250 @@
+import { type AnyColumn, isColumn } from "./column"
+import { InvalidValueError, SchemaDefinitionError, TooManyAttributesError } from "./errors"
+import { validateAttributeName } from "./names"
+import { type ArkivValue, isArkivValue, type StrValue, type TypeTag, type ValueOf } from "./types"
+import { type BareOf, str } from "./values"
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export const SCHEMA_ATTRIBUTE = "arkiv.schema"
+
+/**
+ * Marks a schema. A registry symbol rather than `instanceof`, so a schema defined through one copy
+ * of the SDK — its CJS build, say — is still recognised by another, such as the ESM build an app
+ * loaded.
+ */
+const SCHEMA_BRAND = Symbol.for("@arkiv-network/sdk/schema")
+
+/** A schema's columns, keyed by attribute name. */
+export 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.
+ */
+export 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) {
+    this.tag = name === undefined ? undefined : validateName(name)
+    validateColumns(columns, name !== undefined)
+    this.name = name
+    this.columns = Object.freeze({ ...columns })
+    Object.defineProperty(this, SCHEMA_BRAND, { value: true })
+    Object.freeze(this)
+  }
+}
+
+/**
+ * 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
+ * })
+ */
+export function defineSchema<const C extends Columns>(name: string, columns: C): Schema<C>
+export function defineSchema<const C extends Columns>(columns: C): Schema<C>
+export function defineSchema<const C extends Columns>(
+  ...args: [name: string, columns: C] | [columns: C]
+): Schema<C> {
+  return args.length === 2 ? new Schema(args[0], args[1]) : new Schema(undefined, args[0])
+}
+
+function validateName(name: string): StrValue {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new SchemaDefinitionError(
+      "a schema name must be a non-empty string — leave it out for an untagged schema",
+    )
+  }
+  try {
+    return str(name)
+  } catch (error) {
+    if (!(error instanceof InvalidValueError)) throw error
+    throw new SchemaDefinitionError(`the name is not a valid str tag. ${error.message}`)
+  }
+}
+
+function validateColumns(columns: Columns, tagged: boolean): void {
+  if (typeof columns !== "object" || columns === null || Array.isArray(columns)) {
+    throw new SchemaDefinitionError("defineSchema takes an object of columns keyed by name")
+  }
+  const entries = Object.entries(columns)
+  // The tag is one more attribute on every create, so it counts against the same cap.
+  const attributes = entries.length + (tagged ? 1 : 0)
+  if (attributes > MAX_ATTRIBUTES) {
+    throw new TooManyAttributesError(attributes, MAX_ATTRIBUTES, tagged)
+  }
+  for (const [name, column] of entries) {
+    validateAttributeName(name)
+    if (name === SCHEMA_ATTRIBUTE) {
+      throw new SchemaDefinitionError(
+        `"${name}" is the attribute a named schema tags its entities with, so a column cannot ` +
+          "use it. Pick another name",
+        name,
+      )
+    }
+    if (!isColumn(column)) throw notAColumn(name, column)
+  }
+}
+
+/** Whether `input` is a schema built with {@link defineSchema}. */
+export function isSchema(input: unknown): input is Schema {
+  return typeof input === "object" && input !== null && SCHEMA_BRAND in input
+}
+
+/**
+ * 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.
+ */
+export function lookupColumn(schema: Schema, name: string): AnyColumn | undefined {
+  return Object.hasOwn(schema.columns, name) ? schema.columns[name] : undefined
+}
+
+/** The schema's column names, for an error message that has to say what would have worked. */
+export function describeColumns(schema: Schema): string {
+  return Object.keys(schema.columns).join(", ") || "(none)"
+}
+
+function notAColumn(name: string, input: unknown): SchemaDefinitionError {
+  if (isArkivValue(input)) {
+    return new SchemaDefinitionError(
+      `got a ${input.type} value where a column belongs. Did you mean ` +
+        `${input.type}().default(${defaultArgument(input)})? Called with a value, ${input.type}(...) ` +
+        `makes a value; called with none, ${input.type}() declares a column`,
+      name,
+    )
+  }
+  return new SchemaDefinitionError(
+    "not a column. Declare it with a type constructor called with no arguments, e.g. str() or " +
+      "dec().indexed()",
+    name,
+  )
+}
+
+/** A value spelled as the argument its constructor would take, for an error message. */
+function defaultArgument(value: ArkivValue): string {
+  switch (value.type) {
+    case "bool":
+    case "i32":
+      return String(value.value)
+    case "u64":
+    case "u256":
+      return `${value.value}n`
+    default:
+      return JSON.stringify(value.value)
+  }
+}
+
+/** The columns of a schema. */
+export 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.
+ */
+export 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. */
+export 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. */
+export 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
+ * }
+ */
+export type CreateEntityValues<S extends Schema> = Prettify<
+  {
+    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.
+ */
+export type PatchEntityValues<S extends Schema> = {
+  readonly [K in keyof ColumnsOf<S>]?: ColumnInput<ColumnsOf<S>[K]["type"]> | undefined
+}
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {}

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

@@ -9,18 +9,20 @@ import type { decUnits } from "./values"
  * 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          |
+ * | 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}.
  */
 export const TYPE_IDS = {
   bool: 1,
@@ -35,20 +37,23 @@ export const TYPE_IDS = {
   key: 10,
 } as const
 
-/** Every type tag, including the system-only `bytes`. */
-export type TypeTag = keyof typeof TYPE_IDS
+/**
+ * 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.
+ */
+export const INDEXED_FLAG = 0x80
 
-/** Every typeId, including the system-only `7` (`bytes`). */
-export type TypeId = (typeof TYPE_IDS)[TypeTag]
+/** Every type tag. */
+export type TypeTag = keyof typeof TYPE_IDS
 
 /**
- * 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.
+ * 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.
  */
-export type UserTypeTag = Exclude<TypeTag, "bytes">
+export type IndexableTypeTag = Exclude<TypeTag, "bytes">
 
-/** Whether a client may set an attribute of this type — everything except `bytes`. */
-export function isUserSettable(tag: TypeTag): tag is UserTypeTag {
+/** Whether attributes of this type may be indexed — everything except `bytes`. */
+export function isIndexable(tag: TypeTag): tag is IndexableTypeTag {
   return tag !== "bytes"
 }
 
@@ -61,7 +66,7 @@ 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`.
+ * 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.
@@ -96,12 +101,12 @@ 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.
+ * Opaque variable-length bytes, as lowercase `0x` hex — a blob. Stored but never indexed, so it can
+ * be selected but not filtered on.
  */
 export type BytesValue = Value<"bytes", Hex>
 
-/** Any value a client may set on an attribute. */
+/** Any attribute value. */
 export type ArkivValue =
   | BoolValue
   | I32Value
@@ -109,18 +114,19 @@ export type ArkivValue =
   | U256Value
   | DecValue
   | Bytes32Value
+  | BytesValue
   | StrValue
   | AddrValue
   | KeyValue
 
-/** Any value that can come back from the node, including the system-only `bytes`. */
-export type AnyArkivValue = ArkivValue | BytesValue
+/** Any value of a type that can be indexed, and so can appear in a query — everything but `bytes`. */
+export type IndexableValue = Exclude<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 }>
+export type ValueOf<tag extends TypeTag> = Extract<ArkivValue, { type: tag }>
 
 /** The JavaScript representation carried by a value — e.g. `Decoded<U256Value>` is `bigint`. */
-export type Decoded<value extends AnyArkivValue> = value["value"]
+export type Decoded<value extends ArkivValue> = value["value"]
 
 /**
  * Builds a validated value. Module-internal: the constructors in `values.ts` call this **after**
@@ -136,7 +142,7 @@ export function makeValue<tag extends TypeTag>(
 /**
  * Whether `input` has the *shape* of an {@link ArkivValue} — a known type tag and a value.
  */
-export function isArkivValue(input: unknown): input is AnyArkivValue {
+export function isArkivValue(input: unknown): input is ArkivValue {
   return (
     typeof input === "object" &&
     input !== null &&

package/src/{attr → schema}/values.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from "bun:test"
+import { isColumn } from "./column"
 import { InvalidValueError, MissingValueError, UntypedValueError } from "./errors"
 import { TYPE_IDS } from "./types"
 import {
   addr,
   bool,
+  bytes,
   bytes32,
   dec,
   decFromUnits,
@@ -12,6 +14,7 @@ import {
   I32_MIN,
   i32,
   key,
+  MAX_BYTES_LENGTH,
   str,
   toValue,
   U64_MAX,
@@ -196,12 +199,60 @@ describe("key and bytes32", () => {
   })
 })
 
+describe("bytes", () => {
+  it("accepts raw bytes or hex, and holds lowercase hex", () => {
+    expect(bytes(new Uint8Array([0xde, 0xad])).value).toBe("0xdead")
+    expect(bytes("0xDEAD").value).toBe("0xdead")
+    expect(bytes(new Uint8Array()).value).toBe("0x")
+  })
+
+  it("takes hex as the bytes it spells, never as text", () => {
+    expect(bytes("0xab").value).toBe("0xab")
+  })
+
+  it("rejects text, odd-length hex, and anything over 128 KiB", () => {
+    expect(() => bytes("hello" as `0x${string}`)).toThrow(/not 0x-prefixed hex/)
+    expect(() => bytes("0xabc")).toThrow(/odd number of hex digits/)
+    expect(bytes(new Uint8Array(MAX_BYTES_LENGTH)).type).toBe("bytes")
+    expect(() => bytes(new Uint8Array(MAX_BYTES_LENGTH + 1))).toThrow(/131073 bytes exceeds/)
+  })
+})
+
+describe("dual-mode constructors", () => {
+  const constructors = { bool, i32, u64, u256, dec, bytes32, bytes, str, addr, key } as const
+
+  it("describe a column when called with no arguments", () => {
+    for (const [tag, construct] of Object.entries(constructors)) {
+      const column = (construct as () => unknown)()
+      expect(isColumn(column)).toBe(true)
+      expect(column).toMatchObject({ type: tag, isIndexed: false, isOptional: false })
+    }
+  })
+
+  it("throw for an explicit undefined rather than silently making a column", () => {
+    for (const construct of Object.values(constructors)) {
+      expect(() => (construct as (value: unknown) => unknown)(undefined)).toThrow(InvalidValueError)
+    }
+  })
+
+  it("make a value, not a column, when given one", () => {
+    expect(isColumn(dec("4.1"))).toBe(false)
+    expect(dec("4.1")).toEqual(dec("4.10"))
+  })
+})
+
 describe("toValue", () => {
   it("gives each bare form its unambiguous default type", () => {
     expect(toValue(true)).toEqual(bool(true))
     expect(toValue(10)).toEqual(i32(10))
     expect(toValue(10n)).toEqual(u256(10n))
     expect(toValue("hello")).toEqual(str("hello"))
+    expect(toValue(new Uint8Array([1]))).toEqual(bytes("0x01"))
+  })
+
+  it("rejects a column where a value belongs, saying which call was meant", () => {
+    expect(() => toValue(dec() as unknown as string)).toThrow(/a column, not a value/)
+    expect(() => toValue(dec() as unknown as string)).toThrow(/dec\(\.\.\.\) with an argument/)
   })
 
   it("leaves a hex-looking string a string, rather than guessing at a key", () => {
@@ -209,7 +260,15 @@ describe("toValue", () => {
   })
 
   it("leaves a tagged value's type and value alone", () => {
-    for (const tagged of [dec("3.5"), i32(-42), u256(10n), str("hi"), bool(true), key(KEY)]) {
+    for (const tagged of [
+      dec("3.5"),
+      i32(-42),
+      u256(10n),
+      str("hi"),
+      bool(true),
+      key(KEY),
+      bytes(KEY),
+    ]) {
       expect(toValue(tagged)).toEqual(tagged)
     }
   })
@@ -239,7 +298,7 @@ describe("toValue", () => {
     expect(() => toValue({ type: "nope", value: 1 } as unknown as string)).toThrow(
       UntypedValueError,
     )
-    expect(() => toValue(new Uint8Array(32) as unknown as string)).toThrow(UntypedValueError)
+    expect(() => toValue(new ArrayBuffer(32) as unknown as string)).toThrow(UntypedValueError)
     // `in` would have walked the prototype chain and accepted these as type tags.
     for (const inherited of ["constructor", "toString", "valueOf", "hasOwnProperty"]) {
       expect(() => toValue({ type: inherited, value: 1 } as unknown as string)).toThrow(
@@ -253,7 +312,7 @@ describe("toValue", () => {
     // runtime — from a spread of an optional-shaped object, or from data that never saw a type.
     for (const absent of [undefined, null]) {
       expect(() => toValue(absent as unknown as string)).toThrow(MissingValueError)
-      expect(() => toValue(absent as unknown as string, "score")).toThrow(/Omit "score"/)
+      expect(() => toValue(absent as unknown as string, "score")).toThrow(/Leave "score" out/)
     }
     expect(() => toValue(undefined as unknown as string, "score")).toThrow(
       /attribute "score" is undefined/,