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

package/src/query/engine.ts

@@ -1,112 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

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

package/src/query/predicate.ts

@@ -1,140 +0,0 @@
-export type PredicateType = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "not"
-export type PredicateContainerType = "or" | "and"
-
-export type Predicate =
-  | {
-      type: PredicateType
-      key: string
-      value: string | number
-    }
-  | {
-      type: PredicateContainerType
-      predicates: Predicate[]
-    }
-
-/**
- * Creates an OR predicate
- * @param predicates - The predicates to combine
- * @returns The OR predicate
- *
- * @example
- * const predicates = [eq("name", "John"), eq("age", 30)]
- * const result = or(predicates)
- * // result = { type: "or", predicates: [eq("name", "John"), eq("age", 30)] }
- *
- */
-export function or(predicates: Predicate[]): Predicate {
-  return { type: "or", predicates }
-}
-
-/**
- * Creates an AND predicate
- * @param predicates - The predicates to combine
- * @returns The AND predicate
- *
- * @example
- * const predicates = [eq("name", "John"), eq("age", 30)]
- * const result = and(predicates)
- * // result = { type: "and", predicates: [eq("name", "John"), eq("age", 30)] }
- *
- */
-export function and(predicates: Predicate[]): Predicate {
-  return { type: "and", predicates }
-}
-
-/**
- * Creates an equality predicate
- * @param key - The key to compare
- * @param value - The value to compare
- * @returns The equality predicate
- *
- * @example
- * const predicate = eq("name", "John")
- * // result = { type: "eq", key: "name", value: "John" }
- */
-export function eq(key: string, value: string | number): Predicate {
-  return { type: "eq", key, value }
-}
-
-/**
- * Creates a not equal predicate
- * @param key - The key to compare
- * @param value - The value to compare
- * @returns The not equal predicate
- *
- * @example
- * const predicate = neq("name", "John")
- * // result = { type: "neq", key: "name", value: "John" }
- */
-export function neq(key: string, value: string | number): Predicate {
-  return { type: "neq", key, value }
-}
-
-/**
- * Creates a greater than predicate
- * @param key - The key to compare
- * @param value - The value to compare
- * @returns The greater than predicate
- *
- * @example
- * const predicate = gt("name", "John")
- * // result = { type: "gt", key: "name", value: "John" }
- */
-export function gt(key: string, value: string | number): Predicate {
-  return { type: "gt", key, value }
-}
-
-/**
- * Creates a greater than or equal predicate
- * @param key - The key to compare
- * @param value - The value to compare
- * @returns The greater than or equal predicate
- *
- * @example
- * const predicate = gte("name", "John")
- * // result = { type: "gte", key: "name", value: "John" }
- */
-export function gte(key: string, value: string | number): Predicate {
-  return { type: "gte", key, value }
-}
-
-/**
- * Creates a less than predicate
- * @param key - The key to compare
- * @param value - The value to compare
- * @returns The less than predicate
- *
- * @example
- * const predicate = lt("name", "John")
- * // result = { type: "lt", key: "name", value: "John" }
- */
-export function lt(key: string, value: string | number): Predicate {
-  return { type: "lt", key, value }
-}
-
-/**
- * Creates a less than or equal predicate
- * @param key - The key to compare
- * @param value - The value to compare
- * @returns The less than or equal predicate
- *
- * @example
- * const predicate = lte("name", "John")
- * // result = { type: "lte", key: "name", value: "John" }
- */
-export function lte(key: string, value: string | number): Predicate {
-  return { type: "lte", key, value }
-}
-
-/**
- * Creates a not predicate
- * @param key - The key to compare
- * @returns The not predicate
- *
- * @example
- * const predicate = not("name")
- * // result = { type: "not", key: "name", value: "" }
- */
-export function not(key: string): Predicate {
-  return { type: "not", key, value: "" }
-}

package/src/query/queryBuilder.ts

@@ -1,209 +0,0 @@
-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.ts

@@ -1,61 +0,0 @@
-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

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

package/src/types/entity.ts

@@ -1,36 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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

@@ -1,27 +0,0 @@
-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"