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

package/src/query/engine.test.ts

@@ -0,0 +1,288 @@
+import { describe, expect, it, jest } from "bun:test"
+import type { ArkivClient } from "../clients/baseClient"
+import { processQuery } from "./engine"
+import type { Predicate } from "./predicate"
+
+describe("processQuery tests", () => {
+  const client = {
+    request: jest.fn(),
+  } as unknown as ArkivClient
+
+  it("should process single predicate", async () => {
+    const predicates = [{ type: "eq" as const, key: "key", value: "value" }]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+      withPayload: undefined,
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `key = "value"`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+
+  it("should process all simple predicates - flat", async () => {
+    const predicates = [
+      { type: "eq" as const, key: "key", value: "value" },
+      { type: "gt" as const, key: "key2", value: 1 },
+      { type: "gte" as const, key: "key3", value: 2 },
+      { type: "lt" as const, key: "key4", value: 3 },
+      { type: "lte" as const, key: "key5", value: 4 },
+      { type: "neq" as const, key: "key6", value: "value6" },
+    ]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `key = "value" && key2 > 1 && key3 >= 2 && key4 < 3 && key5 <= 4 && key6 != "value6"`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+
+  it("should process multiple predicates - nested with or", async () => {
+    const predicates = [
+      { type: "eq" as const, key: "key", value: "value" },
+      {
+        type: "or" as const,
+        predicates: [
+          { type: "eq" as const, key: "key2", value: "value2" },
+          { type: "eq" as const, key: "key3", value: "value3" },
+        ],
+      },
+    ]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `key = "value" && (key2 = "value2" || key3 = "value3")`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+
+  it("should process multiple predicates - nested with and", async () => {
+    const predicates = [
+      { type: "eq" as const, key: "key", value: "value" },
+      {
+        type: "and" as const,
+        predicates: [
+          { type: "eq" as const, key: "key2", value: "value2" },
+          { type: "eq" as const, key: "key3", value: "value3" },
+        ],
+      },
+    ]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `key = "value" && (key2 = "value2" && key3 = "value3")`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+
+  it("should process multiple predicates - nested with and and or", async () => {
+    const predicates = [
+      { type: "eq" as const, key: "key", value: "value" },
+      {
+        type: "and" as const,
+        predicates: [
+          { type: "eq" as const, key: "key2", value: "value2" },
+          {
+            type: "or" as const,
+            predicates: [
+              { type: "eq" as const, key: "key3", value: "value3" },
+              { type: "eq" as const, key: "key4", value: "value4" },
+            ],
+          },
+        ],
+      },
+    ]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `key = "value" && (key2 = "value2" && (key3 = "value3" || key4 = "value4"))`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+
+  it("should process simple predicates with ownedBy", async () => {
+    const predicates = [{ type: "eq" as const, key: "key", value: "value" }]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: "0x123",
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `key = "value" && $owner=0x123`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+
+  it("should process only ownedBy", async () => {
+    const predicates = [] as Predicate[]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+      ownedBy: "0x123",
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `$owner=0x123`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+
+  it("should process simple predicate with validAtBlock and paging", async () => {
+    const predicates = [{ type: "eq" as const, key: "key", value: "value" }]
+    await processQuery(client, {
+      predicates,
+      limit: 10,
+      cursor: undefined,
+      validAtBlock: 123n,
+      ownedBy: "0x123",
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `key = "value" && $owner=0x123`,
+        {
+          atBlock: 123,
+          resultsPerPage: 10,
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+          },
+        },
+      ],
+    })
+  })
+})

package/src/query/engine.ts

@@ -0,0 +1,112 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../clients/baseClient"
+import type { RpcQueryOptions } from "../types/rpcSchema"
+import type { Predicate } from "./predicate"
+
+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 async function processQuery(
+  client: ArkivClient,
+  queryParams: {
+    predicates: Predicate[]
+    limit: number | undefined
+    cursor: string | undefined
+    ownedBy: Hex | undefined
+    validAtBlock?: bigint | undefined
+    withAttributes?: boolean | undefined
+    withMetadata?: boolean | undefined
+    withPayload?: boolean | undefined
+  },
+) {
+  const {
+    predicates,
+    limit,
+    cursor,
+    ownedBy,
+    validAtBlock,
+    withAttributes,
+    withMetadata,
+    withPayload,
+  } = queryParams
+
+  console.debug(
+    `Processing query with params: predicates: ${predicates}, cursor: ${cursor}, limit: ${limit}, ownedBy: ${ownedBy}, validAtBlock: ${validAtBlock}, withAttributes: ${withAttributes}, withMetadata: ${withMetadata}, withPayload: ${withPayload}`,
+  )
+
+  let query = processPredicates(predicates)
+  if (ownedBy) {
+    query += ` && $owner=${ownedBy}`
+  }
+
+  // remove leading and trailing spaces and leading &&
+  query = query.trim()
+  if (query.startsWith("&& ")) {
+    query = query.slice(3)
+  }
+
+  const queryOptions: RpcQueryOptions = {
+    includeData: {
+      key: true,
+      attributes: withAttributes ?? false,
+      payload: withPayload ?? false,
+      contentType: withMetadata ?? false,
+      expiration: withMetadata ?? false,
+      owner: withMetadata ?? false,
+    },
+  }
+
+  if (validAtBlock !== undefined) {
+    queryOptions.atBlock = Number(validAtBlock)
+  }
+  if (limit !== undefined) {
+    queryOptions.resultsPerPage = limit
+  }
+  if (cursor !== undefined) {
+    queryOptions.cursor = cursor
+  }
+
+  console.debug(
+    `Built query to send: ${query}, queryOptions: ${JSON.stringify({ includeData: queryOptions.includeData, atBlock: queryOptions.atBlock?.toString(), resultsPerPage: queryOptions.resultsPerPage, cursor: queryOptions.cursor })}`,
+  )
+
+  const result = await client.request({
+    method: "arkiv_query",
+    params: [query, queryOptions],
+  })
+  console.debug("Raw result from query: ", result)
+
+  return result
+}

package/src/query/errors.ts

@@ -0,0 +1,23 @@
+export class NoMoreResultsError extends Error {
+  constructor() {
+    super("No more results")
+  }
+}
+
+export class NoCursorOrLimitError extends Error {
+  constructor() {
+    super("Cursor and limit must be defined to fetch next")
+  }
+}
+
+export class OffsetCannotBeLessThanZeroError extends Error {
+  constructor() {
+    super("Offset cannot be less than 0")
+  }
+}
+
+export class NoEntityFoundError extends Error {
+  constructor() {
+    super("No entity found")
+  }
+}

package/src/query/index.ts

@@ -0,0 +1,4 @@
+export * from "./errors"
+export * from "./predicate"
+export * from "./queryBuilder"
+export * from "./queryResult"