@arkiv-network/sdk 0.1.1-dev.0 → 0.1.2-dev.0

package/src/query/queryBuilder.ts

@@ -0,0 +1,209 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../clients/baseClient"
+import { entityFromRpcResult } from "../utils/entities"
+import { processQuery } from "./engine"
+import type { Predicate } from "./predicate"
+import { QueryResult } from "./queryResult"
+
+/**
+ * QueryBuilder is a helper class to build queries to the Arkiv DBChains.
+ * It can be used to fetch entities from the Arkiv DBChains. It follows the Builder pattern allowing chaining of methods.
+ * @param client - The Arkiv client
+ * @returns The QueryBuilder instance {@link QueryBuilder}
+ */
+export class QueryBuilder {
+  private _client: ArkivClient
+  private _ownedBy: Hex | undefined
+  private _validAtBlock: bigint | undefined
+  private _withAttributes: boolean | undefined
+  private _withMetadata: boolean | undefined
+  private _withPayload: boolean | undefined
+  private _limit: number | undefined
+  private _cursor: string | undefined
+  private _predicates: Predicate[]
+
+  constructor(client: ArkivClient) {
+    this._client = client
+    this._predicates = []
+  }
+
+  /**
+   * Sets the ownedBy filter
+   * @param ownedBy - The address of the owner
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.ownedBy("0x1234567890123456789012345678901234567890")
+   */
+  ownedBy(ownedBy: Hex) {
+    this._ownedBy = ownedBy
+    return this
+  }
+
+  /**
+   * Sets the withAttributes flag which will return the attributes for the entities if true
+   * @param withAttributes - The boolean value to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.withAttributes(true)
+   */
+  withAttributes(withAttributes: boolean = true) {
+    this._withAttributes = withAttributes
+    return this
+  }
+
+  /**
+   * Sets the withMetadata flag which will return the metadata (like owner, expiredAt, etc.) for the entities if true
+   * @param withMetadata - The boolean value to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.withMetadata(true)
+   */
+  withMetadata(withMetadata: boolean = true) {
+    this._withMetadata = withMetadata
+    return this
+  }
+
+  /**
+   * Sets the withPayload flag which will return the payload for the entities if true
+   * @param withPayload - The boolean value to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.withPayload(true)
+   */
+  withPayload(withPayload: boolean = true) {
+    this._withPayload = withPayload
+    return this
+  }
+
+  /**
+   * Sets the limit for the query
+   * @param limit - The number of entities to return
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.limit(10)
+   */
+  limit(limit: number) {
+    this._limit = limit
+    return this
+  }
+
+  /**
+   * Sets the cursor for the query - it is advances setting which rather shouldn't be used manually but it is provided from query result if limit is used (pagination).
+   * @param cursor - The cursor to set which tells to RPC Query server where to start or continue the query.
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.offset(10)
+   */
+  cursor(cursor: string) {
+    this._cursor = cursor
+    return this
+  }
+
+  /**
+   * Sets the validAtBlock for the query which tells at which block height the state we are intested.
+   * If not set, the latest block is  used.
+   * @param validAtBlock - The block number to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.validAtBlock(10000)
+   */
+  validAtBlock(validAtBlock: bigint) {
+    this._validAtBlock = validAtBlock
+    return this
+  }
+
+  /**
+   * Sets the predicates for the query limiting the results. It can be a single predicate or an array of predicates combined with 'and'.
+   * Predicates can be nested using 'or' and 'and' predicates.
+   * @param predicates - The predicates to set
+   * @returns The QueryBuilder instance
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * builder.where(eq("name", "John"))
+   * builder.where([eq("name", "John"), eq("age", 30)])
+   * builder.where([eq("name", "John"), or([eq("age", 30), eq("age", 31)])])
+   * builder.where([eq("name", "John"), and([eq("age", 30), eq("age", 31)])])
+   * builder.where([eq("name", "John"), or([eq("age", 30), and([eq("age", 31), eq("age", 32)])])])
+   * builder.where([eq("name", "John"), and([eq("age", 30), or([eq("age", 31), eq("age", 32)])])])
+   * builder.where([eq("name", "John"), and([eq("age", 30), or([eq("age", 31), and([eq("age", 32), eq("age", 33)])])])])
+   */
+  where(predicates: Predicate[] | Predicate) {
+    if (Array.isArray(predicates)) {
+      this._predicates.push(...predicates)
+    } else {
+      this._predicates.push(predicates)
+    }
+    return this
+  }
+
+  /**
+   * Fetches the entities from the query. Re
+   * It will return a QueryResult instance which can be used to fetch the next and previous pages.
+   * @returns The QueryResult instance {@link QueryResult}
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * const result = await builder.where(eq("name", "John")).fetch()
+   * // result = { entities: [Entity, Entity, Entity], next: async () => QueryResult, previous: async () => QueryResult }
+   */
+  async fetch() {
+    const queryResult = await processQuery(this._client, {
+      predicates: this._predicates,
+      limit: this._limit,
+      cursor: this._cursor,
+      ownedBy: this._ownedBy,
+      validAtBlock: this._validAtBlock,
+      withAttributes: this._withAttributes,
+      withMetadata: this._withMetadata,
+      withPayload: this._withPayload,
+    })
+
+    const entities = await Promise.all(
+      queryResult.data.map((entity) => entityFromRpcResult(entity)),
+    )
+
+    this.cursor(queryResult.cursor)
+    this.validAtBlock(queryResult.blockNumber)
+
+    return new QueryResult(entities, this, this._cursor, this._limit, this._validAtBlock)
+  }
+
+  /**
+   * Counts the entities from the query.
+   * @returns The number of entities
+   *
+   * @example
+   * const builder = new QueryBuilder(client)
+   * const result = await builder.where(eq("name", "John")).count()
+   * // result = 10
+   */
+  async count() {
+    const queryResult = await processQuery(this._client, {
+      predicates: this._predicates,
+      limit: this._limit,
+      cursor: this._cursor,
+      ownedBy: this._ownedBy,
+      validAtBlock: this._validAtBlock,
+      withAttributes: false,
+      withMetadata: false,
+      withPayload: false,
+    })
+
+    return queryResult.data.length ?? 0
+  }
+}

package/src/query/queryResult.test.ts

@@ -0,0 +1,270 @@
+import { beforeEach, describe, expect, jest, test } from "bun:test"
+import { Entity } from "../types/entity"
+import { NoCursorOrLimitError, NoMoreResultsError } from "./errors"
+import type { QueryBuilder } from "./queryBuilder"
+import { QueryResult } from "./queryResult"
+
+describe("QueryResult", () => {
+  let mockQueryBuilder: QueryBuilder
+  let mockEntities: Entity[]
+
+  beforeEach(() => {
+    // Create mock entities
+    mockEntities = [
+      new Entity("0x1" as const, "0xowner1" as const, 1000n, new Uint8Array([1]), []),
+      new Entity("0x2" as const, "0xowner2" as const, 2000n, new Uint8Array([2]), []),
+      new Entity("0x3" as const, "0xowner3" as const, 3000n, new Uint8Array([3]), []),
+    ]
+
+    // Create mock query builder
+    mockQueryBuilder = {
+      cursor: jest.fn().mockReturnThis(),
+      fetch: jest.fn(),
+    } as unknown as QueryBuilder
+  })
+
+  describe("constructor", () => {
+    test("creates QueryResult with entities and query builder", () => {
+      const result = new QueryResult(
+        mockEntities,
+        mockQueryBuilder,
+        undefined,
+        undefined,
+        undefined,
+      )
+
+      expect(result.entities).toEqual(mockEntities)
+      expect(result.entities).toHaveLength(3)
+    })
+
+    test("creates QueryResult with limit and cursor", () => {
+      const result = new QueryResult(mockEntities, mockQueryBuilder, "0xABC123", 10, undefined)
+
+      expect(result.entities).toEqual(mockEntities)
+    })
+
+    test("creates QueryResult with undefined limit and cursor", () => {
+      const result = new QueryResult(
+        mockEntities,
+        mockQueryBuilder,
+        undefined,
+        undefined,
+        undefined,
+      )
+
+      expect(result.entities).toEqual(mockEntities)
+    })
+
+    test("creates QueryResult with empty entities array", () => {
+      const result = new QueryResult([], mockQueryBuilder, "0xABC123", 10, undefined)
+
+      expect(result.entities).toEqual([])
+      expect(result.entities).toHaveLength(0)
+    })
+  })
+
+  describe("next()", () => {
+    test("throws NoCursorOrLimitError when cursor is undefined", async () => {
+      const result = new QueryResult(mockEntities, mockQueryBuilder, undefined, 10, undefined)
+
+      await expect(result.next()).rejects.toThrow(NoCursorOrLimitError)
+      await expect(result.next()).rejects.toThrow("Cursor and limit must be defined to fetch next")
+    })
+
+    test("throws NoCursorOrLimitError when limit is undefined", async () => {
+      const result = new QueryResult(
+        mockEntities,
+        mockQueryBuilder,
+        "0xABC123",
+        undefined,
+        undefined,
+      )
+
+      await expect(result.next()).rejects.toThrow(NoCursorOrLimitError)
+      await expect(result.next()).rejects.toThrow("Cursor and limit must be defined to fetch next")
+    })
+
+    test("throws NoCursorOrLimitError when both cursor and limit are undefined", async () => {
+      const result = new QueryResult(
+        mockEntities,
+        mockQueryBuilder,
+        undefined,
+        undefined,
+        undefined,
+      )
+
+      await expect(result.next()).rejects.toThrow(NoCursorOrLimitError)
+    })
+
+    test("throws NoMoreResultsError when limit > entities.length", async () => {
+      // limit is 4 but we have 3 entities, so limit > entities.length triggers error
+      const result = new QueryResult(mockEntities, mockQueryBuilder, "0xABC123", 4, 123n)
+
+      await expect(result.next()).rejects.toThrow(NoMoreResultsError)
+    })
+
+    test("fetches next page when limit equals entities length", async () => {
+      const newEntities = [
+        new Entity("0x4" as const, "0xowner4" as const, 4000n, new Uint8Array([4]), []),
+        new Entity("0x5" as const, "0xowner5" as const, 5000n, new Uint8Array([5]), []),
+        new Entity("0x6" as const, "0xowner6" as const, 6000n, new Uint8Array([6]), []),
+      ]
+
+      const mockFetch = jest.fn().mockResolvedValue({
+        entities: newEntities,
+      })
+
+      mockQueryBuilder.fetch = mockFetch
+      mockQueryBuilder.cursor = jest.fn().mockReturnValue(mockQueryBuilder)
+
+      // limit is 3 and we have 3 entities, so there might be more
+      const result = new QueryResult(mockEntities, mockQueryBuilder, "0xABC123", 3, undefined)
+
+      await result.next()
+
+      expect(mockQueryBuilder.cursor).toHaveBeenCalledWith("0xABC123")
+      expect(mockFetch).toHaveBeenCalled()
+      expect(result.entities).toEqual(newEntities)
+    })
+
+    test("updates offset correctly for multiple next calls", async () => {
+      const initialEntities = [
+        new Entity("0x1" as const, "0xowner1" as const, 1000n, new Uint8Array([1]), []),
+        new Entity("0x2" as const, "0xowner2" as const, 2000n, new Uint8Array([2]), []),
+        new Entity("0x3" as const, "0xowner3" as const, 3000n, new Uint8Array([3]), []),
+      ]
+
+      const newEntities1 = [
+        new Entity("0x4" as const, "0xowner4" as const, 4000n, new Uint8Array([4]), []),
+        new Entity("0x5" as const, "0xowner5" as const, 5000n, new Uint8Array([5]), []),
+        new Entity("0x6" as const, "0xowner6" as const, 6000n, new Uint8Array([6]), []),
+      ]
+
+      const newEntities2 = [
+        new Entity("0x7" as const, "0xowner7" as const, 7000n, new Uint8Array([7]), []),
+        new Entity("0x8" as const, "0xowner8" as const, 8000n, new Uint8Array([8]), []),
+        new Entity("0x9" as const, "0xowner9" as const, 9000n, new Uint8Array([9]), []),
+      ]
+
+      const mockCursor = jest.fn().mockReturnValue(mockQueryBuilder)
+      const mockFetch = jest
+        .fn()
+        .mockResolvedValueOnce({
+          entities: newEntities1,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        })
+        .mockResolvedValueOnce({
+          entities: newEntities2,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        })
+
+      mockQueryBuilder.cursor = mockCursor
+      mockQueryBuilder.fetch = mockFetch
+
+      // limit = 3, entities.length = 3, so 3 < 3 is false (won't throw)
+      const result = new QueryResult(initialEntities, mockQueryBuilder, "0xABC123", 3, undefined)
+
+      // First next call - offset should be 0 + 3 = 3
+      await result.next()
+      expect(mockCursor).toHaveBeenCalledWith("0xABC123")
+      expect(result.entities).toEqual(newEntities1)
+
+      // Second next call - offset should be 3 + 3 = 6
+      await result.next()
+      expect(mockCursor).toHaveBeenCalledWith("0xABC123")
+      expect(result.entities).toEqual(newEntities2)
+    })
+
+    test("fetches next page when limit is greater than entities length", async () => {
+      // limit is 5 but only 3 entities (5 > 3) so there is no more results
+      // so NoMoreResultsError is thrown
+      const result = new QueryResult(mockEntities, mockQueryBuilder, "0xABC123", 5, undefined)
+
+      await expect(result.next()).rejects.toThrow(NoMoreResultsError)
+    })
+  })
+
+  describe("pagination flow", () => {
+    test("simulates complete pagination: next -> next -> previous -> previous", async () => {
+      const page1 = [
+        new Entity("0x1" as const, "0xowner1" as const, 1000n, new Uint8Array([1]), []),
+      ]
+      const page2 = [
+        new Entity("0x2" as const, "0xowner2" as const, 2000n, new Uint8Array([2]), []),
+      ]
+      const page3 = [
+        new Entity("0x3" as const, "0xowner3" as const, 3000n, new Uint8Array([3]), []),
+      ]
+
+      const mockCursor = jest.fn().mockReturnValue(mockQueryBuilder)
+      const mockFetch = jest
+        .fn()
+        .mockResolvedValueOnce({
+          entities: page2,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        }) // first next
+        .mockResolvedValueOnce({
+          entities: page3,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        }) // second next
+        .mockResolvedValueOnce({
+          entities: page2,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        }) // first previous
+        .mockResolvedValueOnce({
+          entities: page1,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        }) // second previous
+
+      mockQueryBuilder.cursor = mockCursor
+      mockQueryBuilder.fetch = mockFetch
+
+      const result = new QueryResult(page1, mockQueryBuilder, "0xABC123", 1, undefined)
+
+      // Start at page 1 (offset 0)
+      expect(result.entities).toEqual(page1)
+
+      // Next to page 2 (offset 1)
+      await result.next()
+      expect(mockCursor).toHaveBeenCalledWith("0xABC123")
+      expect(result.entities).toEqual(page2)
+
+      // Next to page 3 (offset 2)
+      await result.next()
+      expect(mockCursor).toHaveBeenCalledWith("0xABC123")
+      expect(result.entities).toEqual(page3)
+    })
+
+    test("There is another page to fetch when limit < entities.length", async () => {
+      // limit is 2 but 3 entities, so 2 < 3 there is another page to fetch
+      const mockCursor = jest.fn().mockReturnValue(mockQueryBuilder)
+      const mockFetch = jest
+        .fn()
+        .mockResolvedValueOnce({
+          entities: mockEntities,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        })
+        .mockResolvedValueOnce({
+          entities: mockEntities,
+          queryBuilder: mockQueryBuilder,
+          cursor: "0xABC123",
+        })
+
+      mockQueryBuilder.cursor = mockCursor
+      mockQueryBuilder.fetch = mockFetch
+
+      const result = new QueryResult(mockEntities, mockQueryBuilder, "0xABC123", 2, undefined)
+
+      await result.next()
+      expect(mockCursor).toHaveBeenCalledWith("0xABC123")
+      expect(result.entities).toEqual(mockEntities)
+    })
+  })
+})

package/src/query/queryResult.ts

@@ -0,0 +1,61 @@
+import type { Entity } from "../types/entity"
+import { NoCursorOrLimitError, NoMoreResultsError } from "./errors"
+import type { QueryBuilder } from "./queryBuilder"
+
+export class QueryResult {
+  entities: Entity[]
+  private _endOfIteration: boolean
+  private _cursor: string | undefined
+  private _limit: number | undefined
+  private _validAtBlock: bigint | undefined
+  private _queryBuilder: QueryBuilder
+
+  // Public getters for internal state
+  get queryBuilder(): QueryBuilder {
+    return this._queryBuilder
+  }
+
+  get cursor(): string | undefined {
+    return this._cursor
+  }
+
+  constructor(
+    entities: Entity[],
+    queryBuilder: QueryBuilder,
+    cursor: string | undefined,
+    limit: number | undefined,
+    validAtBlock: bigint | undefined,
+  ) {
+    this.entities = entities
+    this._queryBuilder = queryBuilder
+    this._endOfIteration = !limit || entities.length < limit
+    this._cursor = cursor
+    this._limit = limit
+    this._validAtBlock = validAtBlock
+  }
+
+  async next() {
+    if (this._cursor === undefined || this._limit === undefined) {
+      throw new NoCursorOrLimitError()
+    }
+    if (this._endOfIteration) {
+      throw new NoMoreResultsError()
+    }
+    this._queryBuilder.cursor(this._cursor)
+    const result = await this._queryBuilder.fetch()
+    this.entities = result.entities
+    // Update the query builder reference
+    this._queryBuilder = result.queryBuilder
+    // Check if we've reached the end (no more cursor or we got fewer entities than limit)
+    this._endOfIteration = !result.cursor || result.entities.length < this._limit
+    // Update the cursor
+    this._cursor = result.cursor
+
+    // TODO check current block height and if it is not too old
+    console.debug("Current block height for next page: ", this._validAtBlock)
+  }
+
+  hasNextPage() {
+    return !this._endOfIteration
+  }
+}

package/src/types/attributes.ts

@@ -0,0 +1,4 @@
+export type Attribute = {
+  key: string
+  value: string | number
+}

package/src/types/entity.ts

@@ -0,0 +1,36 @@
+import { bytesToString, type Hex } from "viem"
+import type { MimeType } from "../types"
+import type { Attribute } from "./attributes"
+
+export class Entity {
+  key: Hex
+  owner: Hex
+  expiresAtBlock: bigint
+  payload: Uint8Array
+  attributes: Attribute[]
+  contentType: MimeType
+
+  constructor(
+    key: Hex,
+    contentType: MimeType,
+    owner: Hex,
+    expiresAtBlock: bigint,
+    payload: Uint8Array,
+    attributes: Attribute[],
+  ) {
+    this.key = key
+    this.owner = owner
+    this.expiresAtBlock = expiresAtBlock
+    this.payload = payload
+    this.attributes = attributes
+    this.contentType = contentType
+  }
+
+  toText(): string {
+    return bytesToString(this.payload)
+  }
+
+  toJson(): any {
+    return JSON.parse(bytesToString(this.payload))
+  }
+}

package/src/types/events.ts

@@ -0,0 +1,34 @@
+import type { Hex } from "viem"
+
+export type OnEntityCreatedEvent = {
+  entityKey: Hex
+  owner: Hex
+  expirationBlock: number
+  cost: bigint
+}
+
+export type OnEntityUpdatedEvent = {
+  entityKey: Hex
+  owner: Hex
+  oldExpirationBlock: number
+  newExpirationBlock: number
+  cost: bigint
+}
+
+export type OnEntityDeletedEvent = {
+  entityKey: Hex
+  owner: Hex
+}
+
+export type OnEntityExpiredEvent = {
+  entityKey: Hex
+  owner: Hex
+}
+
+export type OnEntityExpiresInExtendedEvent = {
+  entityKey: Hex
+  owner: Hex
+  oldExpirationBlock: number
+  newExpirationBlock: number
+  cost: bigint
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export type { Attribute } from "./attributes"
+export type { Entity } from "./entity"
+export type { MimeType } from "./mimeTypes"
+export type { TxParams } from "./txParams"

package/src/types/mimeTypes.ts

@@ -0,0 +1,27 @@
+export type MimeType =
+  | "text/plain"
+  | "text/html"
+  | "text/css"
+  | "text/csv"
+  | "text/xml"
+  | "text/javascript"
+  | "application/json"
+  | "application/xml"
+  | "application/pdf"
+  | "application/zip"
+  | "application/gzip"
+  | "application/octet-stream"
+  | "application/javascript"
+  | "application/x-www-form-urlencoded"
+  | "image/png"
+  | "image/jpeg"
+  | "image/webp"
+  | "image/gif"
+  | "image/svg+xml"
+  | "audio/mpeg"
+  | "audio/wav"
+  | "audio/ogg"
+  | "video/mp4"
+  | "video/webm"
+  | "video/ogg"
+  | "multipart/form-data"