@arkiv-network/sdk 0.7.0-dev.1 → 0.8.0-dev.1

package/src/query/queryResult.test.ts

@@ -1,270 +0,0 @@
-import { beforeEach, describe, expect, jest, test } from "bun:test"
-import { NoCursorOrLimitError, NoMoreResultsError } from "../errors"
-import { Entity } from "../types/entity"
-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/selectQueryBuilder.test.ts

@@ -1,213 +0,0 @@
-import { afterEach, beforeEach, describe, expect, jest, test } from "bun:test"
-import type { ArkivClient } from "../clients/baseClient"
-import type { Entity } from "../types/entity"
-import { RpcAttributeValueType } from "../types/rpcSchema"
-import * as entitiesUtils from "../utils/entities"
-import * as engine from "./engine"
-import { eq, gte } from "./predicate"
-import { SelectQueryBuilder } from "./queryBuilder"
-import { selectionToIncludeData } from "./selection"
-
-describe("SelectQueryBuilder", () => {
-  let mockClient: ArkivClient
-  let mockProcessQuery: any
-
-  beforeEach(() => {
-    mockClient = {
-      request: jest.fn(),
-    } as unknown as ArkivClient
-
-    mockProcessQuery = jest.spyOn(engine, "processQuery")
-    jest.spyOn(entitiesUtils, "entityFromRpcResult")
-  })
-
-  afterEach(() => {
-    jest.restoreAllMocks()
-  })
-
-  test("select() with no argument forwards include-data for everything", async () => {
-    mockProcessQuery.mockResolvedValue({ data: [] })
-
-    await new SelectQueryBuilder(mockClient).where(eq("name", "test")).fetch()
-
-    expect(mockProcessQuery).toHaveBeenCalledWith(
-      mockClient,
-      expect.objectContaining({
-        predicates: [eq("name", "test")],
-        includeData: selectionToIncludeData(),
-      }),
-    )
-  })
-
-  test('select("*") forwards include-data for everything', async () => {
-    mockProcessQuery.mockResolvedValue({ data: [] })
-
-    await new SelectQueryBuilder(mockClient, "*").fetch()
-
-    expect(mockProcessQuery).toHaveBeenCalledWith(
-      mockClient,
-      expect.objectContaining({
-        includeData: selectionToIncludeData("*"),
-      }),
-    )
-  })
-
-  test("select({ owner: true, attributes: true }) forwards the resolved include-data", async () => {
-    mockProcessQuery.mockResolvedValue({ data: [] })
-
-    await new SelectQueryBuilder(mockClient, { owner: true, attributes: true }).fetch()
-
-    expect(mockProcessQuery).toHaveBeenCalledWith(
-      mockClient,
-      expect.objectContaining({
-        includeData: selectionToIncludeData({ owner: true, attributes: true }),
-      }),
-    )
-  })
-
-  test("select({ owner: true }) forwards narrowed include-data", async () => {
-    mockProcessQuery.mockResolvedValue({ data: [] })
-
-    await new SelectQueryBuilder(mockClient, { owner: true }).fetch()
-
-    const call = mockProcessQuery.mock.calls[0][1]
-    expect(call.includeData).toEqual(selectionToIncludeData({ owner: true }))
-    expect(call.includeData.owner).toBe(true)
-    expect(call.includeData.creator).toBe(false)
-    // key is opt-in: not selected here, so it is excluded
-    expect(call.includeData.key).toBe(false)
-  })
-
-  test("does not forward the with* boolean flags", async () => {
-    mockProcessQuery.mockResolvedValue({ data: [] })
-
-    await new SelectQueryBuilder(mockClient, { attributes: true }).fetch()
-
-    const call = mockProcessQuery.mock.calls[0][1]
-    expect(call.withAttributes).toBeUndefined()
-    expect(call.withMetadata).toBeUndefined()
-    expect(call.withPayload).toBeUndefined()
-  })
-
-  test("shares the filtering/ordering/pagination chain methods", async () => {
-    mockProcessQuery.mockResolvedValue({ data: [] })
-
-    const owner = "0x1234567890123456789012345678901234567890" as const
-    await new SelectQueryBuilder(mockClient, { attributes: true })
-      .where(eq("name", "test"))
-      .where(gte("age", 18))
-      .ownedBy(owner)
-      .createdBy(owner)
-      .orderBy("name", "string", "desc")
-      .limit(10)
-      .cursor("0xABC123")
-      .validAtBlock(123n)
-      .fetch()
-
-    expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-      predicates: [eq("name", "test"), gte("age", 18)],
-      limit: 10,
-      cursor: "0xABC123",
-      ownedBy: owner,
-      createdBy: owner,
-      orderBy: [{ name: "name", type: "string", desc: true }],
-      validAtBlock: 123n,
-      includeData: selectionToIncludeData({ attributes: true }),
-    })
-  })
-
-  test("count() ignores the selection and requests no data", async () => {
-    mockProcessQuery.mockResolvedValue({
-      data: [
-        { key: "0xabc", value: "data1" },
-        { key: "0xdef", value: "data2" },
-      ],
-    })
-
-    const count = await new SelectQueryBuilder(mockClient, "*")
-      .where(eq("status", "active"))
-      .count()
-
-    expect(count).toBe(2)
-    expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
-      predicates: [eq("status", "active")],
-      limit: undefined,
-      cursor: undefined,
-      ownedBy: undefined,
-      createdBy: undefined,
-      orderBy: undefined,
-      validAtBlock: undefined,
-      withAttributes: false,
-      withMetadata: false,
-      withPayload: false,
-    })
-  })
-
-  describe("result entities", () => {
-    test("fetch returns flat Entity instances with the selected data and methods", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [
-          {
-            key: "0xabc",
-            owner: "0xowner",
-            value: "0x68656c6c6f", // "hello"
-            attributes: [
-              { key: "category", value: "docs", valueType: RpcAttributeValueType.String },
-              { key: "score", value: "0x2a", valueType: RpcAttributeValueType.Uint },
-            ],
-          },
-        ],
-        cursor: "",
-        blockNumber: "0x1",
-      })
-
-      const result = await new SelectQueryBuilder(mockClient, {
-        key: true,
-        owner: true,
-        attributes: true,
-        payload: true,
-      }).fetch()
-
-      expect(result.entities).toHaveLength(1)
-      const entity = result.entities[0] as unknown as Entity
-      // flat, backwards-compatible field access
-      expect(entity.key).toBe("0xabc")
-      expect(entity.owner).toBe("0xowner")
-      expect(entity.attributes).toEqual([
-        { key: "category", value: "docs" },
-        { key: "score", value: 42 },
-      ])
-      // entity methods are preserved on the result
-      expect(typeof entity.toText).toBe("function")
-      expect(entity.toText()).toBe("hello")
-    })
-
-    test("toJson decodes a JSON payload", async () => {
-      mockProcessQuery.mockResolvedValue({
-        data: [{ key: "0xabc", value: "0x7b2261223a317d" }], // {"a":1}
-        cursor: "",
-        blockNumber: "0x1",
-      })
-
-      const result = await new SelectQueryBuilder(mockClient, { payload: true }).fetch()
-      const entity = result.entities[0] as unknown as Entity
-      expect(entity.toJson()).toEqual({ a: 1 })
-    })
-
-    test("fields the RPC omits (because they were not selected) are undefined at runtime", async () => {
-      // The RPC honours includeData and returns only the key.
-      mockProcessQuery.mockResolvedValue({
-        data: [{ key: "0xabc" }],
-        cursor: "",
-        blockNumber: "0x1",
-      })
-
-      const result = await new SelectQueryBuilder(mockClient, { key: true }).fetch()
-      const entity = result.entities[0] as unknown as Entity
-      expect(entity.key).toBe("0xabc")
-      expect(entity.owner).toBeUndefined()
-      expect(entity.payload).toBeUndefined()
-      expect(entity.attributes).toEqual([])
-    })
-  })
-})

package/src/types/attributes.ts

@@ -1,28 +0,0 @@
-import type { Hex } from "viem"
-
-/**
- * An entity attribute (key/value pair).
- *
- * Arkiv supports string, Hex and number values.
- *
- * Hex values are stored as the on-chain `EntityKey` type **only when they are
- * exactly 32 bytes** (66 characters, e.g. an entity key). Hex-looking strings
- * of any other length are stored as plain strings: they round-trip unchanged
- * and compare lexicographically, not as hex.
- *
- * Numeric values **must be non-negative integers** (they are stored on-chain
- * as unsigned 256-bit) — passing a non-integer (e.g. `1.5`) or negative number
- * throws an {@link InvalidAttributeError} at mutation time. To store a
- * non-integer value:
- * - Scale it to an integer (e.g. `1.5` -> `1500`, dividing by the same factor on
- *   read) to keep numeric ordering and range queries working.
- * - Or pass it as a string (e.g. `"1.5"`), which sorts lexicographically and so
- *   does not support numeric comparisons.
- *
- * To store a negative value, offset it into the non-negative range (subtracting
- * the offset on read) or store it as a string.
- */
-export type Attribute = {
-  key: string
-  value: number | string | Hex
-}

package/src/utils/validation.test.ts

@@ -1,106 +0,0 @@
-import { describe, expect, it } from "bun:test"
-import { BLOCK_TIME } from "../consts"
-import { InvalidAttributeError, InvalidAttributeKeyError, InvalidExpirationError } from "../errors"
-import { validateAttribute, validateAttributeKey, validateExpiresIn } from "./validation"
-
-describe("validateExpiresIn", () => {
-  it("accepts positive integers that are a multiple of the block time", () => {
-    expect(() => validateExpiresIn(BLOCK_TIME)).not.toThrow()
-    expect(() => validateExpiresIn(1000)).not.toThrow()
-    expect(() => validateExpiresIn(BLOCK_TIME * 12345)).not.toThrow()
-  })
-
-  it("throws for non-integer values", () => {
-    expect(() => validateExpiresIn(51.5)).toThrow(InvalidExpirationError)
-    expect(() => validateExpiresIn(1.5)).toThrow(InvalidExpirationError)
-  })
-
-  it("throws for values that are not a multiple of the block time", () => {
-    expect(() => validateExpiresIn(51)).toThrow(InvalidExpirationError)
-    expect(() => validateExpiresIn(999)).toThrow(InvalidExpirationError)
-    expect(() => validateExpiresIn(1)).toThrow(InvalidExpirationError)
-  })
-
-  it("throws for zero and negative values", () => {
-    expect(() => validateExpiresIn(0)).toThrow(InvalidExpirationError)
-    expect(() => validateExpiresIn(-1000)).toThrow(InvalidExpirationError)
-  })
-
-  it("throws for NaN and non-finite values", () => {
-    expect(() => validateExpiresIn(Number.NaN)).toThrow(InvalidExpirationError)
-    expect(() => validateExpiresIn(Number.POSITIVE_INFINITY)).toThrow(InvalidExpirationError)
-  })
-
-  it("includes the offending value in the error message", () => {
-    expect(() => validateExpiresIn(51)).toThrow(/51/)
-  })
-})
-
-describe("validateAttribute", () => {
-  it("accepts string values", () => {
-    expect(() => validateAttribute({ key: "k", value: "1.5" })).not.toThrow()
-    expect(() => validateAttribute({ key: "k", value: "anything" })).not.toThrow()
-  })
-
-  it("accepts non-negative integer numeric values", () => {
-    expect(() => validateAttribute({ key: "k", value: 0 })).not.toThrow()
-    expect(() => validateAttribute({ key: "k", value: 123 })).not.toThrow()
-  })
-
-  it("throws for non-integer numeric values", () => {
-    expect(() => validateAttribute({ key: "k", value: 1.5 })).toThrow(InvalidAttributeError)
-    expect(() => validateAttribute({ key: "k", value: Number.NaN })).toThrow(InvalidAttributeError)
-  })
-
-  it("throws for negative numeric values", () => {
-    expect(() => validateAttribute({ key: "k", value: -5 })).toThrow(InvalidAttributeError)
-    expect(() => validateAttribute({ key: "k", value: -0.5 })).toThrow(InvalidAttributeError)
-  })
-
-  it("includes the attribute key and value in the error message", () => {
-    expect(() => validateAttribute({ key: "my_key", value: 1.5 })).toThrow(/my_key/)
-    expect(() => validateAttribute({ key: "my_key", value: 1.5 })).toThrow(/1\.5/)
-  })
-})
-
-describe("validateAttributeKey", () => {
-  it("accepts valid Ident32 keys", () => {
-    expect(() => validateAttributeKey("a")).not.toThrow()
-    expect(() => validateAttributeKey("tag")).not.toThrow()
-    expect(() => validateAttributeKey("num_attr")).not.toThrow()
-    expect(() => validateAttributeKey("a.b-c_d9")).not.toThrow()
-    expect(() => validateAttributeKey("a".repeat(32))).not.toThrow()
-  })
-
-  it("throws for an empty key", () => {
-    expect(() => validateAttributeKey("")).toThrow(InvalidAttributeKeyError)
-  })
-
-  it("throws when the key does not start with a lowercase letter", () => {
-    expect(() => validateAttributeKey("Tag")).toThrow(InvalidAttributeKeyError)
-    expect(() => validateAttributeKey("1tag")).toThrow(InvalidAttributeKeyError)
-    expect(() => validateAttributeKey("_tag")).toThrow(InvalidAttributeKeyError)
-    expect(() => validateAttributeKey(".tag")).toThrow(InvalidAttributeKeyError)
-  })
-
-  it("throws for invalid characters after the first", () => {
-    expect(() => validateAttributeKey("strAttr")).toThrow(InvalidAttributeKeyError)
-    expect(() => validateAttributeKey("has space")).toThrow(InvalidAttributeKeyError)
-    expect(() => validateAttributeKey("has:colon")).toThrow(InvalidAttributeKeyError)
-    expect(() => validateAttributeKey("héllo")).toThrow(InvalidAttributeKeyError)
-  })
-
-  it("throws for keys longer than 32 bytes", () => {
-    expect(() => validateAttributeKey("a".repeat(33))).toThrow(InvalidAttributeKeyError)
-  })
-
-  it("names the offending character and position", () => {
-    expect(() => validateAttributeKey("strAttr")).toThrow(/"A" at position 3/)
-  })
-
-  it("is applied by validateAttribute", () => {
-    expect(() => validateAttribute({ key: "strAttr", value: "x" })).toThrow(
-      InvalidAttributeKeyError,
-    )
-  })
-})