@arkiv-network/sdk 0.7.0 → 0.8.0-advanced.3

package/src/entity/params.ts

@@ -0,0 +1,15 @@
+/**
+ * Max uint64 value
+ */
+export const MAX_EXPIRES_AT = 2n ** 64n - 1n
+
+/** The operation tags of the `execute` ABI's tagged union. */
+export const OperationType = {
+  Create: 1,
+  Patch: 2,
+  ExtendExpiry: 3,
+  TransferOwnership: 4,
+  Delete: 5,
+} as const
+
+export type OperationType = (typeof OperationType)[keyof typeof OperationType]

package/src/errors.ts

@@ -1,45 +1,50 @@
-import { BLOCK_TIME } from "./consts"
-
 export class EntityMutationError extends Error {
-  constructor(message: string) {
-    super(message)
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
     this.name = "EntityMutationError"
   }
 }
-export class InvalidExpirationError extends Error {
-  constructor(expiresIn: unknown) {
-    super(
-      `Invalid expiresIn: ${String(expiresIn)}. expiresIn must be a positive integer and a multiple of the Arkiv block time (${BLOCK_TIME} seconds), because expiration is measured in whole blocks (1 block = ${BLOCK_TIME} seconds).`,
-    )
-    this.name = "InvalidExpirationError"
+export class NoMoreResultsError extends Error {
+  constructor() {
+    super("No more results — the last page carried no cursor. Check hasNextPage() before next().")
+    this.name = "NoMoreResultsError"
   }
 }
-export class InvalidAttributeError extends Error {
-  constructor(key: string, value: number) {
+
+export class NoEntityFoundError extends Error {
+  /** The key that matched nothing, when the lookup was by key. */
+  readonly entityKey: string | undefined
+
+  constructor(entityKey?: string) {
     super(
-      `Invalid numeric value for attribute "${key}": ${String(value)}. Numeric attribute values must be integers. To keep numeric ordering/range queries, scale it to an integer (e.g. Math.round(${String(value)} * 1000), dividing by 1000 on read); otherwise store it as a string (e.g. "${String(value)}").`,
+      entityKey === undefined
+        ? "No entity found"
+        : `No live entity with key ${entityKey}. It was never created, or it has been deleted or ` +
+            "has expired.",
     )
-    this.name = "InvalidAttributeError"
+    this.name = "NoEntityFoundError"
+    this.entityKey = entityKey
   }
 }
 
-export class NoMoreResultsError extends Error {
-  constructor() {
-    super("No more results")
-    this.name = "NoMoreResultsError"
-  }
-}
+export class EmptyPatchError extends Error {
+  readonly entityKey: string
 
-export class NoCursorOrLimitError extends Error {
-  constructor() {
-    super("Cursor and limit must be defined to fetch next")
-    this.name = "NoCursorOrLimitError"
+  constructor(entityKey: string) {
+    super(
+      `The patch for entity ${entityKey} has nothing to apply. Pass "set" to write attributes, ` +
+        '"unset" to remove them, or "payload"/"contentType" to replace the contents.',
+    )
+    this.name = "EmptyPatchError"
+    this.entityKey = entityKey
   }
 }
 
-export class NoEntityFoundError extends Error {
-  constructor() {
-    super("No entity found")
-    this.name = "NoEntityFoundError"
+export class InvalidContentTypeError extends Error {
+  constructor(contentType: string) {
+    super(
+      `Invalid content type "${contentType}". Must follow RFC 2045 MIME grammar and be lowercase only (e.g. "text/plain").`,
+    )
+    this.name = "InvalidContentTypeError"
   }
 }

package/src/index.ts

@@ -2,18 +2,37 @@
  * @module main
  */
 
+// the advanced path: build, send, ping and read mutation results as separate minimal-RPC steps
+export * from "./actions/advanced"
+// the attribute type system
+export * from "./attr"
 // export main arkiv stuff
 export type { ArkivClient } from "./clients/baseClient"
 export type { PublicArkivClient } from "./clients/createPublicClient"
 export { createPublicClient } from "./clients/createPublicClient"
 export type { WalletArkivClient } from "./clients/createWalletClient"
 export { createWalletClient } from "./clients/createWalletClient"
+export type {
+  PublicAdvancedActions,
+  WalletAdvancedActions,
+} from "./clients/decorators/arkivAdvanced"
 export type { PublicArkivActions } from "./clients/decorators/arkivPublic"
 export type { WalletArkivActions } from "./clients/decorators/arkivWallet"
+// entity lifetimes, flags, keys and the protocol parameters behind them
+export * from "./entity"
 // re-export errors
 export * from "./errors"
 // re-export arkiv types in main index file
 export * from "./types"
+// the building blocks behind the advanced path, for callers that go even lower
+export type { EntityMutationOps, MutationEvents } from "./utils/arkivTransactions"
+export {
+  buildEntityOperations,
+  collectMutationEvents,
+  mutationNeedsBlockNumber,
+} from "./utils/arkivTransactions"
 // re-export chosen utils
 export { chainFromName } from "./utils/chains"
+// every create needs an expiry, and this is the only way to build one
+export { type DeadlineOptions, ExpirationTime } from "./utils/expirationTime"
 export { jsonToPayload, stringToPayload } from "./utils/payload"

package/src/query/engine.ts

@@ -1,153 +1,89 @@
-import type { Hex } from "viem"
-import { hexToNumber, numberToHex } from "viem"
+import { numberToHex } from "viem"
 import type { ArkivClient } from "../clients/baseClient"
-import type { RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions } from "../types/rpcSchema"
+import type { Entity } from "../types/entity"
+import type { RpcQueryOptions, RpcSelect } from "../types/rpcSchema"
+import { entityFromRpcResult } from "../utils/entities"
 import { getLogger } from "../utils/logger"
-import type { Predicate } from "./predicate"
+import { asQueryError } from "./errors"
 
 const logger = getLogger("query:engine")
 
-function processPredicates(predicates: Predicate[]): string {
-  const processValue = (value: string | number) => {
-    if (typeof value === "string") {
-      return `"${value}"`
-    }
-    return value
-  }
-  return predicates
-    .map((predicate) => {
-      switch (predicate.type) {
-        case "eq":
-          return `${predicate.key} = ${processValue(predicate.value)}`
-        case "neq":
-          return `${predicate.key} != ${processValue(predicate.value)}`
-        case "gt":
-          return `${predicate.key} > ${processValue(predicate.value)}`
-        case "gte":
-          return `${predicate.key} >= ${processValue(predicate.value)}`
-        case "lt":
-          return `${predicate.key} < ${processValue(predicate.value)}`
-        case "lte":
-          return `${predicate.key} <= ${processValue(predicate.value)}`
-        case "not":
-          return `!${predicate.key}`
-        case "or":
-          return `(${predicate.predicates.map((predicate) => processPredicates([predicate])).join(" || ")})`
-        case "and":
-          return `(${predicate.predicates.map((predicate) => processPredicates([predicate])).join(" && ")})`
-        default:
-          return ""
-      }
-    })
-    .join(" && ")
+export const MAX_LIMIT = 200
+
+/** One `arkiv_query` call. */
+export type QueryRequest = {
+  /** The query expression, already rendered. */
+  query: string
+  /** What to return. */
+  select: RpcSelect
+  /** Page size, up to {@link MAX_LIMIT}. Defaults to the node's own page size. */
+  limit?: number | undefined
+  /** Cursor from a previous page. */
+  cursor?: string | undefined
+  /** Block height to read at. Defaults to the head. */
+  atBlock?: bigint | undefined
 }
 
-export async function processQuery(
-  client: ArkivClient,
-  queryParams: {
-    predicates: Predicate[]
-    limit: number | undefined
-    cursor: string | undefined
-    ownedBy: Hex | undefined
-    createdBy: Hex | undefined
-    orderBy: RpcOrderByAttribute[] | undefined
-    validAtBlock?: bigint | undefined
-    withAttributes?: boolean | undefined
-    withMetadata?: boolean | undefined
-    withPayload?: boolean | undefined
-    /**
-     * Fully-resolved include-data for fine-grained selection. When provided it takes
-     * precedence over the `withAttributes`/`withMetadata`/`withPayload` booleans.
-     */
-    includeData?: RpcIncludeData | undefined
-  },
-) {
-  const {
-    predicates,
-    limit,
-    cursor,
-    ownedBy,
-    createdBy,
-    orderBy,
-    validAtBlock,
-    withAttributes,
-    withMetadata,
-    withPayload,
-    includeData,
-  } = queryParams
+/** One page of results. */
+export type QueryResponse = {
+  entities: Entity[]
+  /** The block the page was read at — the same for every page of a paginated query. */
+  blockNumber: bigint
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  cursor: string | undefined
+}
 
-  logger("Processing query with params %o", {
-    predicates,
-    cursor,
-    limit,
-    ownedBy,
-    createdBy,
-    orderBy,
-    validAtBlock,
-    withAttributes,
-    withMetadata,
-    withPayload,
-    includeData,
-  })
+/**
+ * Runs one query and decodes the page it returns.
+ *
+ * @throws {QueryError} If the node rejects the query.
+ */
+export async function runQuery(client: ArkivClient, request: QueryRequest): Promise<QueryResponse> {
+  const { query, select, limit, cursor, atBlock } = request
 
-  let query = processPredicates(predicates)
-  if (ownedBy) {
-    query += ` && $owner=${ownedBy}`
-  }
-  if (createdBy) {
-    query += ` && $creator=${createdBy}`
+  // A cursor is bound to the block it was issued at; without a block the node reads at the head,
+  // and the resume breaks whenever a block has landed in between — an intermittent failure this
+  // turns into a deterministic one. (Pages chained through `QueryResult.next` inherit the block
+  // automatically; this catches a cursor resumed by hand.)
+  if (cursor !== undefined && atBlock === undefined) {
+    throw new Error(
+      "a cursor must be resumed with `atBlock` set to the `blockNumber` of the page it came " +
+        "from — persist the two together.",
+    )
   }
 
-  // remove leading and trailing spaces and leading &&
-  query = query.trim()
-  if (query.startsWith("&& ")) {
-    query = query.slice(3)
+  if (limit !== undefined) {
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new Error(`limit must be a positive integer, got ${limit}.`)
+    }
+    if (limit > MAX_LIMIT) {
+      throw new Error(
+        `limit ${limit} exceeds the node maximum of ${MAX_LIMIT}. Page through the results with ` +
+          "the cursor instead.",
+      )
+    }
   }
 
   const queryOptions: RpcQueryOptions = {
-    includeData:
-      includeData ??
-      ({
-        key: true,
-        attributes: withAttributes ?? false,
-        payload: withPayload ?? false,
-        contentType: withMetadata ?? false,
-        expiration: withMetadata ?? false,
-        owner: withMetadata ?? false,
-        creator: withMetadata ?? false,
-        createdAtBlock: withMetadata ?? false,
-        lastModifiedAtBlock: withMetadata ?? false,
-        transactionIndexInBlock: withMetadata ?? false,
-        operationIndexInTransaction: withMetadata ?? false,
-      } as RpcIncludeData),
+    select,
+    ...(atBlock !== undefined && { atBlock: numberToHex(atBlock) }),
+    ...(limit !== undefined && { limit: numberToHex(limit) }),
+    ...(cursor !== undefined && { cursor }),
   }
 
-  if (validAtBlock !== undefined) {
-    queryOptions.atBlock = numberToHex(validAtBlock)
-  }
-  if (limit !== undefined) {
-    queryOptions.resultsPerPage = numberToHex(limit)
-  }
-  if (cursor !== undefined) {
-    queryOptions.cursor = cursor
-  }
-  if (orderBy !== undefined) {
-    queryOptions.orderBy = orderBy
-  }
+  logger("arkiv_query %s %o", query, queryOptions)
 
-  logger("Built query to send %s %o", query, {
-    includeData: queryOptions.includeData,
-    atBlock: queryOptions.atBlock ? hexToNumber(queryOptions.atBlock) : undefined,
-    orderBy: queryOptions.orderBy,
-    resultsPerPage: queryOptions.resultsPerPage,
-    cursor: queryOptions.cursor,
-  })
+  const result = await client
+    .request({ method: "arkiv_query", params: [query, queryOptions] })
+    .catch((error: unknown) => {
+      throw asQueryError(error, query) ?? error
+    })
 
-  const result = await client.request({
-    method: "arkiv_query",
-    params: [query, queryOptions],
-  })
   logger("Raw result from query %o", result)
 
-  return result
+  return {
+    entities: result.data.map((rpcEntity) => entityFromRpcResult(rpcEntity)),
+    blockNumber: BigInt(result.blockNumber),
+    cursor: result.cursor,
+  }
 }

package/src/query/errors.ts

@@ -0,0 +1,151 @@
+import type { TypeTag } from "../attr"
+
+/**
+ * A predicate asked for an operator the query language does not define for that type.
+ *
+ * The operator × type matrix is part of the language, not a policy: a range comparison on an
+ * equality-only type is a **parse error** at the node, not an empty result. Catching it here turns
+ * a round trip and an RPC error code into a stack trace pointing at the call site.
+ *
+ * | | `=` `!=` | `<` `<=` `>` `>=` | `STARTSWITH` |
+ * | --- | --- | --- | --- |
+ * | `bool` | yes | no | no |
+ * | `i32` `u64` `u256` `dec` | yes | yes | no |
+ * | `str` | yes | no | yes |
+ * | `addr` `key` `bytes32` | yes | no | no |
+ */
+export class UnsupportedOperatorError extends Error {
+  /** The attribute the predicate names. */
+  readonly attributeName: string
+  /** The operator, as it would have been written in the query. */
+  readonly operator: string
+  /** The type of the value it was applied to. */
+  readonly tag: TypeTag
+
+  constructor(attributeName: string, operator: string, tag: TypeTag, hint?: string) {
+    super(
+      `The query language does not define ${operator} for a ${tag}, so "${attributeName} ` +
+        `${operator} ..." cannot be expressed.${hint ? ` ${hint}` : ""}`,
+    )
+    this.name = "UnsupportedOperatorError"
+    this.attributeName = attributeName
+    this.operator = operator
+    this.tag = tag
+  }
+}
+
+/**
+ * A predicate could not be expressed in the query language for a reason other than its operator —
+ * a system attribute that is returned in results but cannot be filtered on, a system attribute
+ * compared against the wrong type, or a combinator with nothing to combine.
+ */
+export class InvalidPredicateError extends Error {
+  /** The attribute the predicate names, where there is one. */
+  readonly attributeName: string | undefined
+
+  constructor(message: string, attributeName?: string) {
+    super(message)
+    this.name = "InvalidPredicateError"
+    this.attributeName = attributeName
+  }
+}
+
+/**
+ * What a node rejected a query for. Part of the frozen RPC surface, so it is safe to branch on —
+ * a `"cursor"` failure means start the query again, a `"block"` failure means the node no longer
+ * retains that height, and the rest mean the query itself needs fixing.
+ */
+export type QueryErrorKind =
+  /** The query string does not parse. `data` locates it: `{ position, expected, got }`. */
+  | "parse"
+  /** A predicate is well-formed but ill-typed — a range operator on an equality-only type, an unknown tag. */
+  | "type"
+  /** A literal failed validation — an `i32` out of range, a bad EIP-55 checksum, more than 18 decimal places. */
+  | "literal"
+  /** A node budget was exceeded — query length, predicate count, nesting depth, bitmap operations. */
+  | "limits"
+  /** The cursor expired, is malformed, or belongs to a different query, block or selection. */
+  | "cursor"
+  /** `atBlock` is outside the range the node retains. */
+  | "block"
+
+/** The JSON-RPC error codes `arkiv_query` answers with, and what each one means. */
+const QUERY_ERROR_KINDS: Readonly<Record<number, QueryErrorKind>> = {
+  [-32001]: "parse",
+  [-32002]: "type",
+  [-32003]: "literal",
+  [-32004]: "limits",
+  [-32005]: "cursor",
+  [-32006]: "block",
+}
+
+/**
+ * The node rejected a query.
+ *
+ * These codes are part of the frozen `arkiv_query` surface, so {@link kind} and {@link data} are
+ * stable enough to branch on — which the underlying JSON-RPC error is not, because the codes
+ * overlap Ethereum's own EIP-1474 numbering and get wrapped accordingly on the way up.
+ *
+ * @example
+ * try {
+ *   await result.next()
+ * } catch (error) {
+ *   if (error instanceof QueryError && error.kind === "cursor") {
+ *     // The page is gone — start the query over.
+ *   }
+ * }
+ */
+export class QueryError extends Error {
+  /** Which failure this is. */
+  readonly kind: QueryErrorKind
+  /** The JSON-RPC error code. */
+  readonly code: number
+  /** The machine-readable detail the node sent, if any — e.g. `{ position, expected, got }`. */
+  readonly data: unknown
+  /** The query string that was rejected. */
+  readonly query: string
+
+  constructor(kind: QueryErrorKind, code: number, query: string, data: unknown, detail?: string) {
+    super(`Query rejected (${kind}, ${code})${detail ? `: ${detail}` : ""}. Query: ${query}`, {
+      cause: data,
+    })
+    this.name = "QueryError"
+    this.kind = kind
+    this.code = code
+    this.data = data
+    this.query = query
+  }
+}
+
+/**
+ * Recognises an `arkiv_query` failure in whatever the transport threw.
+ *
+ * The codes are dug out of the error chain rather than read off the top: viem maps this range onto
+ * its own EIP-1474 error classes (`-32001` is its "resource not found"), so by the time an error
+ * surfaces the Arkiv meaning is one or more `cause` links down.
+ *
+ * @returns The typed error, or `undefined` if this was not a query rejection.
+ */
+export function asQueryError(error: unknown, query: string): QueryError | undefined {
+  let code: number | undefined
+  let data: unknown
+  let detail: string | undefined
+
+  let current: unknown = error
+  for (let depth = 0; current != null && depth < 8; depth++) {
+    const link = current as {
+      code?: unknown
+      data?: unknown
+      shortMessage?: unknown
+      cause?: unknown
+    }
+    if (code === undefined && typeof link.code === "number") code = link.code
+    if (data === undefined && link.data !== undefined) data = link.data
+    if (detail === undefined && typeof link.shortMessage === "string") detail = link.shortMessage
+    current = link.cause
+  }
+
+  const kind = code === undefined ? undefined : QUERY_ERROR_KINDS[code]
+  if (kind === undefined || code === undefined) return undefined
+  return new QueryError(kind, code, query, data, detail)
+}