@arkiv-network/sdk 0.6.8 → 0.7.0

package/src/actions/public/query.ts

@@ -9,6 +9,11 @@ export type QueryOptionsIncludeData = {
   payload?: boolean
   metadata?: boolean
 }
+/**
+ * @deprecated Server-side ordering is not supported by the network. Sort the fetched
+ * entities in JavaScript instead (e.g. `entities.sort(...)`). This type will be removed
+ * in a future release.
+ */
 export type QueryOptionsOrderBy = {
   name: string
   type: "string" | "numeric"
@@ -18,6 +23,11 @@ export type QueryOptionsOrderBy = {
 export type QueryOptions = {
   includeData?: QueryOptionsIncludeData
   atBlock?: bigint
+  /**
+   * @deprecated Server-side ordering is not supported by the network, so this option has no
+   * effect on the returned order. Sort the fetched entities in JavaScript instead
+   * (e.g. `entities.sort(...)`). This option will be removed in a future release.
+   */
   orderBy?: QueryOptionsOrderBy[]
   resultsPerPage?: number | undefined
   cursor?: string | undefined

package/src/actions/wallet/createEntity.ts

@@ -9,14 +9,24 @@ const logger = getLogger("actions:wallet:create-entity")
 /**
  * Parameters for the createEntity function.
  * - payload: The payload of the entity.
- * - attributes: The attributes of the entity.
+ * - attributes: The attributes of the entity. Attribute values may be strings
+ *   or numbers, but numeric values **must be integers**. To store a non-integer,
+ *   scale it to an integer (e.g. `1.5` -> `1500`) to preserve numeric ordering,
+ *   or pass it as a string (e.g. `"1.5"`). A non-integer numeric value throws an
+ *   {@link InvalidAttributeError}.
  * - contentType: The content type of the entity.
- * - expiresIn: The expires in of the entity in seconds.
+ * - expiresIn: How long until the entity expires, in seconds. Because Arkiv
+ *   measures expiration in blocks (1 block = 2 seconds), this **must be a
+ *   positive integer and a multiple of the block time (2 seconds)**
+ *   Invalid values throw an {@link InvalidExpirationError}.
  */
 export type CreateEntityParameters = {
   payload: Uint8Array
+  /** Entity attributes. Numeric values must be integers (scale non-integers, e.g. `1.5` -> `1500`, or use a string). Throws {@link InvalidAttributeError} otherwise. */
   attributes: Attribute[]
   contentType: MimeType | string
+  /** Seconds until expiry. Must be a positive integer and a multiple of the 2s block time.
+   * Throws {@link InvalidExpirationError} otherwise. */
   expiresIn: number
 }
 

package/src/actions/wallet/extendEntity.ts

@@ -9,10 +9,15 @@ const logger = getLogger("actions:wallet:extend-entity")
 /**
  * Parameters for the extendEntity function.
  * - entityKey: The key of the entity to extend.
- * - expiresIn: The expires in of the entity in seconds.
+ * - expiresIn: How long to extend the entity by, in seconds. Because Arkiv
+ *   measures expiration in blocks (1 block = 2 seconds), this **must be a
+ *   positive integer and a multiple of the block time (2 seconds)**.
+ *   Invalid values throw an {@link InvalidExpirationError}.
  */
 export type ExtendEntityParameters = {
   entityKey: Hex
+  /** Seconds to extend by. Must be a positive integer and a multiple of the 2s block time.
+   * Throws {@link InvalidExpirationError} otherwise. */
   expiresIn: number
 }
 

package/src/actions/wallet/updateEntity.ts

@@ -10,15 +10,25 @@ const logger = getLogger("actions:wallet:update-entity")
  * Parameters for the updateEntity function.
  * - entityKey: The key of the entity to update.
  * - payload: The payload of the entity.
- * - attributes: The attributes of the entity.
+ * - attributes: The attributes of the entity. Attribute values may be strings
+ *   or numbers, but numeric values **must be integers**. To store a non-integer,
+ *   scale it to an integer (e.g. `1.5` -> `1500`) to preserve numeric ordering,
+ *   or pass it as a string (e.g. `"1.5"`). A non-integer numeric value throws an
+ *   {@link InvalidAttributeError}.
  * - contentType: The content type of the entity.
- * - expiresIn: The expires in of the entity in seconds.
+ * - expiresIn: How long until the entity expires, in seconds. Because Arkiv
+ *   measures expiration in blocks (1 block = 2 seconds), this **must be a
+ *   positive integer and a multiple of the block time (2 seconds)**.
+ *   Invalid values throw an {@link InvalidExpirationError}.
  */
 export type UpdateEntityParameters = {
   entityKey: Hex
   payload: Uint8Array
+  /** Entity attributes. Numeric values must be integers (scale non-integers, e.g. `1.5` -> `1500`, or use a string). Throws {@link InvalidAttributeError} otherwise. */
   attributes: Attribute[]
   contentType: MimeType | string
+  /** Seconds until expiry. Must be a positive integer and a multiple of the 2s block time.
+   * Throws {@link InvalidExpirationError} otherwise. */
   expiresIn: number
 }
 

package/src/clients/createPublicClient.test.ts

@@ -20,6 +20,8 @@ test("creates", () => {
   expect(typeof client.getEntity).toBe("function")
   expect(client.buildQuery).toBeDefined()
   expect(typeof client.buildQuery).toBe("function")
+  expect(client.select).toBeDefined()
+  expect(typeof client.select).toBe("function")
   expect(client.query).toBeDefined()
   expect(typeof client.query).toBe("function")
   expect(client.getEntityCount).toBeDefined()

package/src/clients/decorators/arkivPublic.ts

@@ -4,7 +4,8 @@ import { getEntity } from "../../actions/public/getEntity"
 import { getEntityCount } from "../../actions/public/getEntityCount"
 import { type QueryOptions, type QueryReturnType, query } from "../../actions/public/query"
 import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
-import { QueryBuilder } from "../../query/queryBuilder"
+import { QueryBuilder, SelectQueryBuilder } from "../../query/queryBuilder"
+import type { EntitySelection, FullEntity, ProjectedEntity, SelectArg } from "../../query/selection"
 import type { Entity } from "../../types/entity"
 import type {
   OnEntityCreatedEvent,
@@ -55,12 +56,76 @@ export type PublicArkivActions<
    */
   getEntity: (key: Hex) => Promise<Entity>
 
+  /**
+   * Returns a SelectQueryBuilder for building and executing queries — the recommended way to
+   * read entities. You declare up front which parts of an entity you want returned, so results
+   * always contain exactly the data you asked for.
+   *
+   * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
+   *
+   * @param selection - What to include in the results. Omit it (or pass `"*"`) to select everything,
+   *   or pass an object to select specific parts (at least one field is required). Every part is
+   *   opt-in, including the `key`. The selection is flat — each field maps to an entity field.
+   *   {@link SelectArg}
+   * @returns A SelectQueryBuilder instance for building and executing queries. {@link SelectQueryBuilder}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { braga } from 'arkiv/chains'
+   * import { eq } from 'arkiv/query'
+   *
+   * const client = createPublicClient({
+   *   chain: braga,
+   *   transport: http(),
+   * })
+   * // select everything
+   * await client.select().where(eq("category", "docs")).fetch()
+   * await client.select("*").where(eq("category", "docs")).fetch()
+   * // only the key
+   * await client.select({ key: true }).where(eq("category", "docs")).fetch()
+   * // select specific fields — result typed { owner: Hex; attributes: Attribute[] }
+   * await client.select({ owner: true, attributes: true }).fetch()
+   * // a single field — result typed { owner: Hex }
+   * await client.select({ owner: true }).fetch()
+   */
+  select: {
+    /** Select every field. Pass nothing or `"*"`; the returned entities contain all fields. */
+    (selection?: "*"): SelectQueryBuilder<FullEntity>
+    /**
+     * Pick the entity fields to return. Set the ones you want to `true` (at least one is required);
+     * the result is typed to exactly those fields, so reading anything else is a compile error.
+     *
+     * Available fields: `key`, `owner`, `creator`, `contentType`, `payload`, `attributes`,
+     * `expiresAtBlock`, `createdAtBlock`, `lastModifiedAtBlock`, `transactionIndexInBlock`,
+     * `operationIndexInTransaction`.
+     *
+     * Pass the selection inline so its fields stay literal `true`. A selection stored in a `let`/
+     * `const` variable widens to `boolean` and the result type can no longer be narrowed — annotate
+     * it `as const` (e.g. `const sel = { owner: true } as const`) in that case.
+     *
+     * @example
+     * client.select({ owner: true, attributes: true }) // entities typed { owner, attributes }
+     * client.select({ key: true, payload: true })       // includes payload → toText()/toJson() too
+     */
+    <const S extends EntitySelection>(selection: S): SelectQueryBuilder<ProjectedEntity<S>>
+    /**
+     * Dynamic selection: accepts a value typed {@link SelectArg} (e.g. built at runtime). The
+     * result cannot be narrowed in this case, so the entities are typed as the full entity.
+     */
+    (selection: SelectArg): SelectQueryBuilder<FullEntity>
+  }
+
   /**
    * Returns a QueryBuilder instance for building and executing queries.
    * The QueryBuilder object follows the Builder pattern, allowing you to chain methods to build a query and then execute it.
    *
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
    *
+   * @deprecated Use {@link select} instead. `buildQuery()` returns only the entity `key` unless
+   * you remember to opt in to data with `withAttributes()`/`withMetadata()`/`withPayload()`, which
+   * is an easy mistake. `select()` makes the selection explicit. This method remains for backwards
+   * compatibility and will be removed in a future release.
+   *
    * @returns A QueryBuilder instance for building and executing queries. {@link QueryBuilder}
    *
    * @example
@@ -100,7 +165,6 @@ export type PublicArkivActions<
    *     payload: true,
    *     metadata: true,
    *   },
-   *   orderBy: [{ name: "key", type: "string", desc: "asc" }],
    *   resultsPerPage: 10,
    *   cursor: undefined,
    *   atBlock: undefined,
@@ -200,6 +264,7 @@ export function publicArkivActions<
     getEntity: (key: Hex) => getEntity(client, key),
     query: (rawQuery: string, queryOptions?: QueryOptions) => query(client, rawQuery, queryOptions),
     buildQuery: () => new QueryBuilder(client),
+    select: (selection?: SelectArg) => new SelectQueryBuilder(client, selection),
     getBlockTiming: () => getBlockTiming(client),
     getEntityCount: () => getEntityCount(client),
     subscribeEntityEvents: (

package/src/clients/decorators/arkivWallet.ts

@@ -56,6 +56,11 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The created entity with transaction hash
      *
+     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
+     * that is a multiple of the block time (2 seconds).
+     * @throws {InvalidAttributeError} If a numeric attribute value is not an
+     * integer.
+     *
      * @example
      * import { createPublicClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'
@@ -91,6 +96,11 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The updated entity with transaction hash
      *
+     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
+     * that is a multiple of the block time (2 seconds).
+     * @throws {InvalidAttributeError} If a numeric attribute value is not an
+     * integer.
+     *
      * @example
      * import { createWalletClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'
@@ -146,6 +156,9 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The updated entity with transaction hash
      *
+     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
+     * that is a multiple of the block time (2 seconds).
+     *
      * @example
      * import { createWalletClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'
@@ -194,6 +207,11 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The mutation result with transaction hash
      *
+     * @throws {InvalidExpirationError} If any create/update/extension `expiresIn`
+     * is not a positive integer that is a multiple of the block time (2 seconds).
+     * @throws {InvalidAttributeError} If a numeric attribute value is not an
+     * integer.
+     *
      * @example
      * import { createWalletClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'

package/src/errors.ts

@@ -1,9 +1,27 @@
+import { BLOCK_TIME } from "./consts"
+
 export class EntityMutationError extends Error {
   constructor(message: string) {
     super(message)
     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 InvalidAttributeError extends Error {
+  constructor(key: string, value: number) {
+    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)}").`,
+    )
+    this.name = "InvalidAttributeError"
+  }
+}
 
 export class NoMoreResultsError extends Error {
   constructor() {

package/src/index.ts

@@ -2,9 +2,6 @@
  * @module main
  */
 
-// Re-export all viem stuff
-export * from "viem"
-
 // export main arkiv stuff
 export type { ArkivClient } from "./clients/baseClient"
 export type { PublicArkivClient } from "./clients/createPublicClient"

package/src/query/engine.ts

@@ -55,6 +55,11 @@ export async function processQuery(
     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 {
@@ -68,6 +73,7 @@ export async function processQuery(
     withAttributes,
     withMetadata,
     withPayload,
+    includeData,
   } = queryParams
 
   logger("Processing query with params %o", {
@@ -81,6 +87,7 @@ export async function processQuery(
     withAttributes,
     withMetadata,
     withPayload,
+    includeData,
   })
 
   let query = processPredicates(predicates)
@@ -98,19 +105,21 @@ export async function processQuery(
   }
 
   const queryOptions: RpcQueryOptions = {
-    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,
+    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),
   }
 
   if (validAtBlock !== undefined) {

package/src/query/index.ts

@@ -1,3 +1,4 @@
 export * from "./predicate"
 export * from "./queryBuilder"
 export * from "./queryResult"
+export * from "./selection"

package/src/query/predicate.test.ts

@@ -244,6 +244,27 @@ describe("Predicate Factory Functions", () => {
       })
     })
 
+    test("creates or predicate from varargs", () => {
+      const result = or(eq("type", "admin"), eq("type", "moderator"))
+
+      expect(result).toEqual({
+        type: "or",
+        predicates: [
+          { type: "eq", key: "type", value: "admin" },
+          { type: "eq", key: "type", value: "moderator" },
+        ],
+      })
+    })
+
+    test("creates or predicate with no arguments", () => {
+      const result = or()
+
+      expect(result).toEqual({
+        type: "or",
+        predicates: [],
+      })
+    })
+
     test("creates or predicate with nested and", () => {
       const nestedAnd = and([eq("verified", 1), gte("age", 18)])
       const predicates = [eq("status", "premium"), nestedAnd]
@@ -314,6 +335,28 @@ describe("Predicate Factory Functions", () => {
       })
     })
 
+    test("creates and predicate from varargs", () => {
+      const result = and(eq("status", "active"), gte("age", 18), not("deleted"))
+
+      expect(result).toEqual({
+        type: "and",
+        predicates: [
+          { type: "eq", key: "status", value: "active" },
+          { type: "gte", key: "age", value: 18 },
+          { type: "not", key: "deleted", value: "" },
+        ],
+      })
+    })
+
+    test("creates and predicate with no arguments", () => {
+      const result = and()
+
+      expect(result).toEqual({
+        type: "and",
+        predicates: [],
+      })
+    })
+
     test("creates and predicate with nested or", () => {
       const nestedOr = or([eq("type", "admin"), eq("type", "moderator")])
       const predicates = [eq("active", 1), nestedOr]

package/src/query/predicate.ts

@@ -14,32 +14,36 @@ export type Predicate =
 
 /**
  * Creates an OR predicate
- * @param predicates - The predicates to combine
+ * @param predicates - The predicates to combine, either as a single array or as separate arguments
  * @returns The OR predicate
  *
  * @example
- * const predicates = [eq("name", "John"), eq("age", 30)]
- * const result = or(predicates)
+ * const result = or(eq("name", "John"), eq("age", 30))
+ * // or equivalently: or([eq("name", "John"), eq("age", 30)])
  * // result = { type: "or", predicates: [eq("name", "John"), eq("age", 30)] }
  *
  */
-export function or(predicates: Predicate[]): Predicate {
-  return { type: "or", predicates }
+export function or(predicates: Predicate[]): Predicate
+export function or(...predicates: Predicate[]): Predicate
+export function or(...predicates: (Predicate | Predicate[])[]): Predicate {
+  return { type: "or", predicates: predicates.flat() }
 }
 
 /**
  * Creates an AND predicate
- * @param predicates - The predicates to combine
+ * @param predicates - The predicates to combine, either as a single array or as separate arguments
  * @returns The AND predicate
  *
  * @example
- * const predicates = [eq("name", "John"), eq("age", 30)]
- * const result = and(predicates)
+ * const result = and(eq("name", "John"), eq("age", 30))
+ * // or equivalently: and([eq("name", "John"), eq("age", 30)])
  * // result = { type: "and", predicates: [eq("name", "John"), eq("age", 30)] }
  *
  */
-export function and(predicates: Predicate[]): Predicate {
-  return { type: "and", predicates }
+export function and(predicates: Predicate[]): Predicate
+export function and(...predicates: Predicate[]): Predicate
+export function and(...predicates: (Predicate | Predicate[])[]): Predicate {
+  return { type: "and", predicates: predicates.flat() }
 }
 
 /**

package/src/query/queryBuilder.test.ts

@@ -78,6 +78,28 @@ describe("QueryBuilder", () => {
       })
     })
 
+    test("adds multiple predicates as varargs", async () => {
+      mockProcessQuery.mockResolvedValue({
+        data: [],
+      })
+
+      const builder = new QueryBuilder(mockClient)
+      await builder.where(eq("name", "test"), gt("age", 18), neq("status", "inactive")).fetch()
+
+      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
+        predicates: [eq("name", "test"), gt("age", 18), neq("status", "inactive")],
+        limit: undefined,
+        offset: undefined,
+        ownedBy: undefined,
+        createdBy: undefined,
+        orderBy: undefined,
+        validBeforeBlock: undefined,
+        withAttributes: undefined,
+        withMetadata: undefined,
+        withPayload: undefined,
+      })
+    })
+
     test("chains multiple where() calls", async () => {
       mockProcessQuery.mockResolvedValue({
         data: [],