@arkiv-network/sdk 0.5.0-dev.1 → 0.5.0-dev.3

package/dist/{queryBuilder-Cy7vf54g.js → queryBuilder-DMzL_J5-.js}

@@ -1,9 +1,116 @@
 import { bytesToString, toBytes } from "viem";
-import createDebug from "debug";
 
 //#region src/utils/logger.ts
 const ROOT_NAMESPACE = "arkiv";
-const getLogger = (scope) => createDebug(`${ROOT_NAMESPACE}:${scope}`);
+function getDebugEnv() {
+	if (typeof process !== "undefined") {
+		const debugEnv = process?.env?.DEBUG;
+		if (debugEnv) return debugEnv;
+	}
+	if (typeof globalThis !== "undefined" && "localStorage" in globalThis) try {
+		return globalThis.localStorage?.getItem("DEBUG") || "";
+	} catch {}
+	return "";
+}
+function matchesPattern(namespace, pattern) {
+	if (pattern === namespace) return true;
+	if (pattern.endsWith("*")) {
+		const prefix = pattern.slice(0, -1);
+		return namespace.startsWith(prefix);
+	}
+	if (pattern.startsWith("-")) return !matchesPattern(namespace, pattern.slice(1));
+	return false;
+}
+function isEnabled(namespace) {
+	const debugEnv = getDebugEnv();
+	if (!debugEnv) return false;
+	const patterns = debugEnv.split(/[\s,]+/).filter((p) => p.length > 0);
+	if (patterns.length === 0) return false;
+	let enabled = false;
+	for (const pattern of patterns) if (pattern.startsWith("-")) {
+		if (matchesPattern(namespace, pattern)) return false;
+	} else if (matchesPattern(namespace, pattern)) enabled = true;
+	return enabled;
+}
+const enabledNamespaces = /* @__PURE__ */ new Set();
+const disabledNamespaces = /* @__PURE__ */ new Set();
+const COLOR_PALETTE = [
+	"#0000FF",
+	"#008000",
+	"#FF0000",
+	"#FF00FF",
+	"#FFA500",
+	"#800080",
+	"#00CED1",
+	"#FF1493",
+	"#32CD32",
+	"#1E90FF",
+	"#FF4500",
+	"#9370DB",
+	"#00FA9A",
+	"#FFD700",
+	"#DC143C",
+	"#00BFFF",
+	"#FF69B4",
+	"#20B2AA",
+	"#DA70D6",
+	"#4682B4"
+];
+const isNode = typeof process !== "undefined" && process.versions?.node != null;
+const ANSI_COLORS = [
+	"\x1B[94m",
+	"\x1B[92m",
+	"\x1B[91m",
+	"\x1B[95m",
+	"\x1B[93m",
+	"\x1B[96m",
+	"\x1B[35m",
+	"\x1B[36m",
+	"\x1B[32m",
+	"\x1B[34m",
+	"\x1B[33m",
+	"\x1B[31m",
+	"\x1B[90m",
+	"\x1B[37m",
+	"\x1B[1m"
+];
+const ANSI_RESET = "\x1B[0m";
+const ANSI_BOLD = "\x1B[1m";
+const namespaceColors = /* @__PURE__ */ new Map();
+function getColorForNamespace(namespace) {
+	const cachedColor = namespaceColors.get(namespace);
+	if (cachedColor) return cachedColor;
+	let hash = 0;
+	for (let i = 0; i < namespace.length; i++) {
+		const char = namespace.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	const colorIndex = Math.abs(hash) % COLOR_PALETTE.length;
+	const color = {
+		css: COLOR_PALETTE[colorIndex],
+		ansi: ANSI_COLORS[colorIndex % ANSI_COLORS.length]
+	};
+	namespaceColors.set(namespace, color);
+	return color;
+}
+function createDebugLogger(namespace) {
+	const colors = getColorForNamespace(namespace);
+	return (...args) => {
+		const envEnabled = isEnabled(namespace);
+		const progEnabled = enabledNamespaces.has(namespace) && !disabledNamespaces.has(namespace);
+		if (envEnabled || progEnabled) if (isNode) {
+			const coloredNamespace = `${ANSI_BOLD}${colors.ansi}${namespace}${ANSI_RESET}`;
+			console.log(coloredNamespace, ...args);
+		} else {
+			const style1 = `color: ${colors.css}; font-weight: bold`;
+			console.log(`%c${namespace}%c`, style1, "color: inherit; font-weight: normal", ...args);
+		}
+	};
+}
+const getLogger = (scope) => {
+	return createDebugLogger(`${ROOT_NAMESPACE}:${scope}`);
+};
 
 //#endregion
 //#region src/query/errors.ts
@@ -17,11 +124,6 @@ var NoCursorOrLimitError = class extends Error {
 		super("Cursor and limit must be defined to fetch next");
 	}
 };
-var OffsetCannotBeLessThanZeroError = class extends Error {
-	constructor() {
-		super("Offset cannot be less than 0");
-	}
-};
 var NoEntityFoundError = class extends Error {
 	constructor() {
 		super("No entity found");
@@ -192,7 +294,7 @@ var QueryResult = class {
 * Helper function to create an ascending order by attribute
 * @param attributeName - The name of the attribute to order by
 * @param attributeType - The type of the attribute to order by (string or number)
-* @returns The OrderByAttribute instance
+* @returns Input for orderBy method
 *
 * @example
 * const ascAttribute = asc("name", "string")
@@ -208,7 +310,7 @@ function asc(attributeName, attributeType) {
 * Helper function to create a descending order by attribute
 * @param attributeName - The name of the attribute to order by
 * @param attributeType - The type of the attribute to order by (string or number)
-* @returns The OrderByAttribute instance
+* @returns Input for orderBy method
 *
 * @example
 * const descAttribute = desc("name", "string")
@@ -425,5 +527,5 @@ var QueryBuilder = class {
 };
 
 //#endregion
-export { entityFromRpcResult as a, NoMoreResultsError as c, QueryResult as i, OffsetCannotBeLessThanZeroError as l, asc as n, NoCursorOrLimitError as o, desc as r, NoEntityFoundError as s, QueryBuilder as t, getLogger as u };
-//# sourceMappingURL=queryBuilder-Cy7vf54g.js.map
+export { entityFromRpcResult as a, NoMoreResultsError as c, QueryResult as i, getLogger as l, asc as n, NoCursorOrLimitError as o, desc as r, NoEntityFoundError as s, QueryBuilder as t };
+//# sourceMappingURL=queryBuilder-DMzL_J5-.js.map

package/dist/queryBuilder-DMzL_J5-.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryBuilder-DMzL_J5-.js","names":["enabledNamespaces: Set<string>","disabledNamespaces: Set<string>","logger","logger","predicate","queryOptions: RpcQueryOptions","order"],"sources":["../src/utils/logger.ts","../src/query/errors.ts","../src/types/entity.ts","../src/utils/entities.ts","../src/query/engine.ts","../src/query/queryResult.ts","../src/query/queryBuilder.ts"],"sourcesContent":["const ROOT_NAMESPACE = \"arkiv\"\n\n// Debug logger type - returns a function that can be called to log messages\ntype DebugLogger = (...args: unknown[]) => void\n\n// Get DEBUG environment variable (works in both Node.js and browser)\nfunction getDebugEnv(): string {\n  if (typeof process !== \"undefined\") {\n    const debugEnv = process?.env?.DEBUG\n    if (debugEnv) {\n      return debugEnv\n    }\n  }\n  // Browser: check localStorage\n  if (typeof globalThis !== \"undefined\" && \"localStorage\" in globalThis) {\n    try {\n      const storage = (globalThis as { localStorage?: Storage }).localStorage\n      return storage?.getItem(\"DEBUG\") || \"\"\n    } catch {\n      // localStorage might not be available\n    }\n  }\n  return \"\"\n}\n\n// Parse debug patterns and check if a namespace matches\nfunction matchesPattern(namespace: string, pattern: string): boolean {\n  // Exact match\n  if (pattern === namespace) return true\n\n  // Wildcard match: \"arkiv:*\" matches \"arkiv:query\", \"arkiv:rpc\", etc.\n  if (pattern.endsWith(\"*\")) {\n    const prefix = pattern.slice(0, -1)\n    return namespace.startsWith(prefix)\n  }\n\n  // Negative match: \"-arkiv:query\" excludes \"arkiv:query\"\n  if (pattern.startsWith(\"-\")) {\n    const excludePattern = pattern.slice(1)\n    return !matchesPattern(namespace, excludePattern)\n  }\n\n  return false\n}\n\n// Check if a namespace is enabled for debugging\nfunction isEnabled(namespace: string): boolean {\n  const debugEnv = getDebugEnv()\n  if (!debugEnv) return false\n\n  // Split by comma/space and check each pattern\n  const patterns = debugEnv.split(/[\\s,]+/).filter((p) => p.length > 0)\n\n  // If no patterns, nothing is enabled\n  if (patterns.length === 0) return false\n\n  // Check if any pattern matches (or if explicitly excluded)\n  let enabled = false\n  for (const pattern of patterns) {\n    if (pattern.startsWith(\"-\")) {\n      // Exclude pattern - if it matches, disable\n      if (matchesPattern(namespace, pattern)) {\n        return false\n      }\n    } else if (matchesPattern(namespace, pattern)) {\n      enabled = true\n    }\n  }\n\n  return enabled\n}\n\n// Store enabled namespaces (for programmatic enable/disable)\nconst enabledNamespaces: Set<string> = new Set()\nconst disabledNamespaces: Set<string> = new Set()\n\n// Color palette for namespace coloring (distinct, readable colors)\nconst COLOR_PALETTE = [\n  \"#0000FF\", // blue\n  \"#008000\", // green\n  \"#FF0000\", // red\n  \"#FF00FF\", // magenta\n  \"#FFA500\", // orange\n  \"#800080\", // purple\n  \"#00CED1\", // dark turquoise\n  \"#FF1493\", // deep pink\n  \"#32CD32\", // lime green\n  \"#1E90FF\", // dodger blue\n  \"#FF4500\", // orange red\n  \"#9370DB\", // medium purple\n  \"#00FA9A\", // medium spring green\n  \"#FFD700\", // gold\n  \"#DC143C\", // crimson\n  \"#00BFFF\", // deep sky blue\n  \"#FF69B4\", // hot pink\n  \"#20B2AA\", // light sea green\n  \"#DA70D6\", // orchid\n  \"#4682B4\", // steel blue\n]\n\n// Detect if we're in Node.js (for ANSI colors) or browser (for CSS colors)\nconst isNode = typeof process !== \"undefined\" && process.versions?.node != null\n\n// ANSI color codes for Node.js (bright, distinct colors)\nconst ANSI_COLORS = [\n  \"\\x1b[94m\", // bright blue\n  \"\\x1b[92m\", // bright green\n  \"\\x1b[91m\", // bright red\n  \"\\x1b[95m\", // bright magenta\n  \"\\x1b[93m\", // bright yellow\n  \"\\x1b[96m\", // bright cyan\n  \"\\x1b[35m\", // magenta\n  \"\\x1b[36m\", // cyan\n  \"\\x1b[32m\", // green\n  \"\\x1b[34m\", // blue\n  \"\\x1b[33m\", // yellow\n  \"\\x1b[31m\", // red\n  \"\\x1b[90m\", // bright black (gray)\n  \"\\x1b[37m\", // white\n  \"\\x1b[1m\", // bold (as a color option)\n]\n\nconst ANSI_RESET = \"\\x1b[0m\"\nconst ANSI_BOLD = \"\\x1b[1m\"\n\n// Cache colors for namespaces (same namespace = same color)\nconst namespaceColors = new Map<string, { css: string; ansi: string }>()\n\n// Generate a consistent color for a namespace based on its hash\nfunction getColorForNamespace(namespace: string): { css: string; ansi: string } {\n  // Check cache first\n  const cachedColor = namespaceColors.get(namespace)\n  if (cachedColor) {\n    return cachedColor\n  }\n\n  // Simple hash function to convert string to number\n  let hash = 0\n  for (let i = 0; i < namespace.length; i++) {\n    const char = namespace.charCodeAt(i)\n    hash = (hash << 5) - hash + char\n    hash = hash & hash // Convert to 32-bit integer\n  }\n\n  // Use absolute value and modulo to get index\n  const colorIndex = Math.abs(hash) % COLOR_PALETTE.length\n  const cssColor = COLOR_PALETTE[colorIndex]\n  const ansiColor = ANSI_COLORS[colorIndex % ANSI_COLORS.length]\n\n  const color = { css: cssColor, ansi: ansiColor }\n\n  // Cache the color\n  namespaceColors.set(namespace, color)\n\n  return color\n}\n\n// Create a debug logger function\nfunction createDebugLogger(namespace: string): DebugLogger {\n  // Get the color for this namespace (consistent across calls)\n  const colors = getColorForNamespace(namespace)\n\n  return (...args: unknown[]) => {\n    // Check if enabled via environment variable or programmatically\n    const envEnabled = isEnabled(namespace)\n    const progEnabled = enabledNamespaces.has(namespace) && !disabledNamespaces.has(namespace)\n\n    if (envEnabled || progEnabled) {\n      if (isNode) {\n        // Node.js: use ANSI color codes\n        const coloredNamespace = `${ANSI_BOLD}${colors.ansi}${namespace}${ANSI_RESET}`\n        console.log(coloredNamespace, ...args)\n      } else {\n        // Browser: use CSS styling with %c\n        // The format is: console.log(\"%cstyled%cnormal\", style1, style2, ...args)\n        // This colors the namespace, then resets for the rest\n        const style1 = `color: ${colors.css}; font-weight: bold`\n        const style2 = \"color: inherit; font-weight: normal\"\n        // Combine namespace with a space, then log with styles\n        console.log(`%c${namespace}%c`, style1, style2, ...args)\n      }\n    }\n  }\n}\n\nexport const getLogger = (scope: string): DebugLogger => {\n  const namespace = `${ROOT_NAMESPACE}:${scope}`\n  return createDebugLogger(namespace)\n}\n\nexport const enableDebug = (namespaces: string): void => {\n  // Parse and add namespaces to enabled set\n  const patterns = namespaces.split(/[\\s,]+/).filter((p) => p.length > 0)\n  for (const pattern of patterns) {\n    if (pattern.startsWith(\"-\")) {\n      // Remove from enabled, add to disabled\n      const namespace = pattern.slice(1)\n      enabledNamespaces.delete(namespace)\n      disabledNamespaces.add(namespace)\n    } else {\n      enabledNamespaces.add(pattern)\n      disabledNamespaces.delete(pattern)\n    }\n  }\n}\n\nexport const disableDebug = (): void => {\n  enabledNamespaces.clear()\n  disabledNamespaces.clear()\n}\n","export class NoMoreResultsError extends Error {\n  constructor() {\n    super(\"No more results\")\n  }\n}\n\nexport class NoCursorOrLimitError extends Error {\n  constructor() {\n    super(\"Cursor and limit must be defined to fetch next\")\n  }\n}\n\nexport class NoEntityFoundError extends Error {\n  constructor() {\n    super(\"No entity found\")\n  }\n}\n","import { bytesToString, type Hex } from \"viem\"\nimport type { MimeType } from \"../types\"\nimport type { Attribute } from \"./attributes\"\n\nexport class Entity {\n  key: Hex\n  contentType: MimeType | undefined\n  owner: Hex | undefined\n  expiresAtBlock: bigint | undefined\n  createdAtBlock: bigint | undefined\n  lastModifiedAtBlock: bigint | undefined\n  transactionIndexInBlock: bigint | undefined\n  operationIndexInTransaction: bigint | undefined\n  payload: Uint8Array | undefined\n  attributes: Attribute[]\n\n  constructor(\n    key: Hex,\n    contentType: MimeType | undefined = undefined,\n    owner: Hex | undefined = undefined,\n    expiresAtBlock: bigint | undefined = undefined,\n    createdAtBlock: bigint | undefined = undefined,\n    lastModifiedAtBlock: bigint | undefined = undefined,\n    transactionIndexInBlock: bigint | undefined = undefined,\n    operationIndexInTransaction: bigint | undefined = undefined,\n    payload: Uint8Array | undefined = undefined,\n    attributes: Attribute[],\n  ) {\n    this.key = key\n    this.owner = owner\n    this.expiresAtBlock = expiresAtBlock\n    this.createdAtBlock = createdAtBlock\n    this.lastModifiedAtBlock = lastModifiedAtBlock\n    this.transactionIndexInBlock = transactionIndexInBlock\n    this.operationIndexInTransaction = operationIndexInTransaction\n    this.payload = payload\n    this.attributes = attributes\n    this.contentType = contentType\n  }\n\n  toText(): string {\n    return this.payload ? bytesToString(this.payload) : \"\"\n  }\n\n  toJson(): any {\n    return this.payload ? JSON.parse(bytesToString(this.payload)) : {}\n  }\n}\n","import { toBytes } from \"viem\"\nimport { Entity } from \"../types/entity\"\nimport type { RpcEntity } from \"../types/rpcSchema\"\nimport { getLogger } from \"./logger\"\n\nconst logger = getLogger(\"utils:entities\")\n\nexport async function entityFromRpcResult(rpcEntity: RpcEntity) {\n  logger(\"entityFromRpcResult %o\", rpcEntity)\n\n  return new Entity(\n    rpcEntity.key,\n    rpcEntity.contentType,\n    rpcEntity.owner,\n    rpcEntity.expiresAt !== undefined ? BigInt(rpcEntity.expiresAt) : undefined,\n    rpcEntity.createdAtBlock !== undefined ? BigInt(rpcEntity.createdAtBlock) : undefined,\n    rpcEntity.lastModifiedAtBlock !== undefined ? BigInt(rpcEntity.lastModifiedAtBlock) : undefined,\n    rpcEntity.transactionIndexInBlock !== undefined\n      ? BigInt(rpcEntity.transactionIndexInBlock)\n      : undefined,\n    rpcEntity.operationIndexInTransaction !== undefined\n      ? BigInt(rpcEntity.operationIndexInTransaction)\n      : undefined,\n    rpcEntity.value !== undefined ? toBytes(rpcEntity.value) : undefined,\n    [\n      ...(rpcEntity.stringAttributes ?? []).map(({ key, value }) => ({\n        key,\n        value,\n      })),\n      ...(rpcEntity.numericAttributes ?? []).map(({ key, value }) => ({\n        key,\n        value: Number(value),\n      })),\n    ],\n  )\n}\n","import type { Hex } from \"viem\"\nimport type { ArkivClient } from \"../clients/baseClient\"\nimport type { RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions } from \"../types/rpcSchema\"\nimport { getLogger } from \"../utils/logger\"\nimport type { Predicate } from \"./predicate\"\n\nconst logger = getLogger(\"query:engine\")\n\nfunction processPredicates(predicates: Predicate[]): string {\n  const processValue = (value: string | number) => {\n    if (typeof value === \"string\") {\n      return `\"${value}\"`\n    }\n    return value\n  }\n  return predicates\n    .map((predicate) => {\n      switch (predicate.type) {\n        case \"eq\":\n          return `${predicate.key} = ${processValue(predicate.value)}`\n        case \"neq\":\n          return `${predicate.key} != ${processValue(predicate.value)}`\n        case \"gt\":\n          return `${predicate.key} > ${processValue(predicate.value)}`\n        case \"gte\":\n          return `${predicate.key} >= ${processValue(predicate.value)}`\n        case \"lt\":\n          return `${predicate.key} < ${processValue(predicate.value)}`\n        case \"lte\":\n          return `${predicate.key} <= ${processValue(predicate.value)}`\n        case \"not\":\n          return `!${predicate.key}`\n        case \"or\":\n          return `(${predicate.predicates.map((predicate) => processPredicates([predicate])).join(\" || \")})`\n        case \"and\":\n          return `(${predicate.predicates.map((predicate) => processPredicates([predicate])).join(\" && \")})`\n        default:\n          return \"\"\n      }\n    })\n    .join(\" && \")\n}\n\nexport async function processQuery(\n  client: ArkivClient,\n  queryParams: {\n    predicates: Predicate[]\n    limit: number | undefined\n    cursor: string | undefined\n    ownedBy: Hex | undefined\n    orderBy: RpcOrderByAttribute[] | undefined\n    validAtBlock?: bigint | undefined\n    withAttributes?: boolean | undefined\n    withMetadata?: boolean | undefined\n    withPayload?: boolean | undefined\n  },\n) {\n  const {\n    predicates,\n    limit,\n    cursor,\n    ownedBy,\n    orderBy,\n    validAtBlock,\n    withAttributes,\n    withMetadata,\n    withPayload,\n  } = queryParams\n\n  logger(\"Processing query with params %o\", {\n    predicates,\n    cursor,\n    limit,\n    ownedBy,\n    orderBy,\n    validAtBlock,\n    withAttributes,\n    withMetadata,\n    withPayload,\n  })\n\n  let query = processPredicates(predicates)\n  if (ownedBy) {\n    query += ` && $owner=${ownedBy}`\n  }\n\n  // remove leading and trailing spaces and leading &&\n  query = query.trim()\n  if (query.startsWith(\"&& \")) {\n    query = query.slice(3)\n  }\n\n  const queryOptions: RpcQueryOptions = {\n    includeData: {\n      key: true,\n      attributes: withAttributes ?? false,\n      payload: withPayload ?? false,\n      contentType: withMetadata ?? false,\n      expiration: withMetadata ?? false,\n      owner: withMetadata ?? false,\n      createdAtBlock: withMetadata ?? false,\n      lastModifiedAtBlock: withMetadata ?? false,\n      transactionIndexInBlock: withMetadata ?? false,\n      operationIndexInTransaction: withMetadata ?? false,\n    } as RpcIncludeData,\n  }\n\n  if (validAtBlock !== undefined) {\n    queryOptions.atBlock = Number(validAtBlock)\n  }\n  if (limit !== undefined) {\n    queryOptions.resultsPerPage = limit\n  }\n  if (cursor !== undefined) {\n    queryOptions.cursor = cursor\n  }\n  if (orderBy !== undefined) {\n    queryOptions.orderBy = orderBy\n  }\n\n  logger(\"Built query to send %s %o\", query, {\n    includeData: queryOptions.includeData,\n    atBlock: queryOptions.atBlock?.toString(),\n    orderBy: queryOptions.orderBy,\n    resultsPerPage: queryOptions.resultsPerPage,\n    cursor: queryOptions.cursor,\n  })\n\n  const result = await client.request({\n    method: \"arkiv_query\",\n    params: [query, queryOptions],\n  })\n  logger(\"Raw result from query %o\", result)\n\n  return result\n}\n","import type { Entity } from \"../types/entity\"\nimport { getLogger } from \"../utils/logger\"\nimport { NoCursorOrLimitError, NoMoreResultsError } from \"./errors\"\nimport type { QueryBuilder } from \"./queryBuilder\"\n\nconst logger = getLogger(\"query:result\")\n\nexport class QueryResult {\n  entities: Entity[]\n  private _endOfIteration: boolean\n  private _cursor: string | undefined\n  private _limit: number | undefined\n  private _validAtBlock: bigint | undefined\n  private _queryBuilder: QueryBuilder\n\n  // Public getters for internal state\n  get queryBuilder(): QueryBuilder {\n    return this._queryBuilder\n  }\n\n  get cursor(): string | undefined {\n    return this._cursor\n  }\n\n  constructor(\n    entities: Entity[],\n    queryBuilder: QueryBuilder,\n    cursor: string | undefined,\n    limit: number | undefined,\n    validAtBlock: bigint | undefined,\n  ) {\n    this.entities = entities\n    this._queryBuilder = queryBuilder\n    this._endOfIteration = !limit || entities.length < limit\n    this._cursor = cursor\n    this._limit = limit\n    this._validAtBlock = validAtBlock\n  }\n\n  async next() {\n    if (this._cursor === undefined || this._limit === undefined) {\n      throw new NoCursorOrLimitError()\n    }\n    if (this._endOfIteration) {\n      throw new NoMoreResultsError()\n    }\n    this._queryBuilder.cursor(this._cursor)\n    const result = await this._queryBuilder.fetch()\n    this.entities = result.entities\n    // Update the query builder reference\n    this._queryBuilder = result.queryBuilder\n    // Check if we've reached the end (no more cursor or we got fewer entities than limit)\n    this._endOfIteration = !result.cursor || result.entities.length < this._limit\n    // Update the cursor\n    this._cursor = result.cursor\n\n    // TODO check current block height and if it is not too old\n    logger(\"Current block height for next page %s\", this._validAtBlock?.toString() ?? \"unknown\")\n  }\n\n  hasNextPage() {\n    return !this._endOfIteration\n  }\n}\n","import type { Hex } from \"viem\"\nimport type { ArkivClient } from \"../clients/baseClient\"\nimport type { RpcOrderByAttribute } from \"../types/rpcSchema\"\nimport { entityFromRpcResult } from \"../utils/entities\"\nimport { processQuery } from \"./engine\"\nimport type { Predicate } from \"./predicate\"\nimport { QueryResult } from \"./queryResult\"\n\nexport type OrderByAttribute = {\n  name: string\n  type: \"string\" | \"number\"\n  order: \"asc\" | \"desc\"\n}\n\n/**\n * Helper function to create an ascending order by attribute\n * @param attributeName - The name of the attribute to order by\n * @param attributeType - The type of the attribute to order by (string or number)\n * @returns Input for orderBy method\n *\n * @example\n * const ascAttribute = asc(\"name\", \"string\")\n */\nexport function asc(attributeName: string, attributeType: \"string\" | \"number\"): OrderByAttribute {\n  return {\n    name: attributeName,\n    type: attributeType,\n    order: \"asc\",\n  }\n}\n\n/**\n * Helper function to create a descending order by attribute\n * @param attributeName - The name of the attribute to order by\n * @param attributeType - The type of the attribute to order by (string or number)\n * @returns Input for orderBy method\n *\n * @example\n * const descAttribute = desc(\"name\", \"string\")\n */\nexport function desc(attributeName: string, attributeType: \"string\" | \"number\"): OrderByAttribute {\n  return {\n    name: attributeName,\n    type: attributeType,\n    order: \"desc\",\n  }\n}\n/**\n * QueryBuilder is a helper class to build queries to the Arkiv DBChains.\n * It can be used to fetch entities from the Arkiv DBChains. It follows the Builder pattern allowing chaining of methods.\n * @param client - The Arkiv client\n * @returns The QueryBuilder instance {@link QueryBuilder}\n */\nexport class QueryBuilder {\n  private _client: ArkivClient\n  private _ownedBy: Hex | undefined\n  private _orderBy: RpcOrderByAttribute[] | undefined\n  private _validAtBlock: bigint | undefined\n  private _withAttributes: boolean | undefined\n  private _withMetadata: boolean | undefined\n  private _withPayload: boolean | undefined\n  private _limit: number | undefined\n  private _cursor: string | undefined\n  private _predicates: Predicate[]\n\n  constructor(client: ArkivClient) {\n    this._client = client\n    this._predicates = []\n  }\n\n  /**\n   * Sets the ownedBy filter\n   * @param ownedBy - The address of the owner\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.ownedBy(\"0x1234567890123456789012345678901234567890\")\n   */\n  ownedBy(ownedBy: Hex) {\n    this._ownedBy = ownedBy\n    return this\n  }\n\n  /**\n   * Sets the orderBy for the query.\n   * It can be called multiple times to order by multiple attributes.\n   * The order of the attributes is important. The first attribute is the primary order by attribute.\n   * You can use the helper functions asc() and desc() as input for this method.\n   * @param attributeName - The name of the attribute to order by\n   * @param attributeType - The type of the attribute to order by (string or number)\n   * @param order - The order to set the order by (asc or desc)\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = client.buildQuery()\n   * builder.orderBy(\"name\", \"string\", \"desc\")\n   * builder.orderBy(asc(\"name\", \"string\"))\n   * builder.orderBy(desc(\"name\", \"string\"))\n   */\n  orderBy(attributeName: string, attributeType: \"string\" | \"number\", order?: \"asc\" | \"desc\"): this\n  /**\n   * Sets the orderBy for the query.\n   * This method takes the OrderByAttribute object as an argument and is mainly\n   * used to use the helper functions asc() and desc() to create the OrderByAttribute instances.\n   * @param orderByAttribute - The OrderByAttribute instance to set\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.orderBy(asc(\"name\", \"string\"))\n   * builder.orderBy(desc(\"name\", \"string\"))\n   */\n  orderBy(orderByAttribute: OrderByAttribute): this\n  orderBy(\n    attributeNameOrOrderByAttribute: string | OrderByAttribute,\n    attributeType?: \"string\" | \"number\",\n    order: \"asc\" | \"desc\" = \"asc\",\n  ) {\n    if (!this._orderBy) {\n      this._orderBy = []\n    }\n\n    const pushOrderByAttribute = ({ name, type, order }: OrderByAttribute) => {\n      this._orderBy?.push({\n        name,\n        type: type === \"number\" ? \"numeric\" : type,\n        desc: order === \"desc\",\n      })\n    }\n\n    if (typeof attributeNameOrOrderByAttribute === \"string\") {\n      if (!attributeType) {\n        throw new Error(\"attributeType is required when using positional orderBy arguments\")\n      }\n      pushOrderByAttribute({\n        name: attributeNameOrOrderByAttribute,\n        type: attributeType,\n        order,\n      })\n    } else {\n      pushOrderByAttribute(attributeNameOrOrderByAttribute)\n    }\n\n    return this\n  }\n\n  /**\n   * Sets the withAttributes flag which will return the attributes for the entities if true\n   * @param withAttributes - The boolean value to set\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.withAttributes(true)\n   */\n  withAttributes(withAttributes: boolean = true) {\n    this._withAttributes = withAttributes\n    return this\n  }\n\n  /**\n   * Sets the withMetadata flag which will return the metadata (like owner, expiredAt, etc.) for the entities if true\n   * @param withMetadata - The boolean value to set\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.withMetadata(true)\n   */\n  withMetadata(withMetadata: boolean = true) {\n    this._withMetadata = withMetadata\n    return this\n  }\n\n  /**\n   * Sets the withPayload flag which will return the payload for the entities if true\n   * @param withPayload - The boolean value to set\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.withPayload(true)\n   */\n  withPayload(withPayload: boolean = true) {\n    this._withPayload = withPayload\n    return this\n  }\n\n  /**\n   * Sets the limit for the query\n   * @param limit - The number of entities to return\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.limit(10)\n   */\n  limit(limit: number) {\n    this._limit = limit\n    return this\n  }\n\n  /**\n   * 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).\n   * @param cursor - The cursor to set which tells to RPC Query server where to start or continue the query.\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.offset(10)\n   */\n  cursor(cursor: string) {\n    this._cursor = cursor\n    return this\n  }\n\n  /**\n   * Sets the validAtBlock for the query which tells at which block height the state we are intested.\n   * If not set, the latest block is  used.\n   * @param validAtBlock - The block number to set\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.validAtBlock(10000)\n   */\n  validAtBlock(validAtBlock: bigint) {\n    this._validAtBlock = validAtBlock\n    return this\n  }\n\n  /**\n   * Sets the predicates for the query limiting the results. It can be a single predicate or an array of predicates combined with 'and'.\n   * Predicates can be nested using 'or' and 'and' predicates.\n   * @param predicates - The predicates to set\n   * @returns The QueryBuilder instance\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * builder.where(eq(\"name\", \"John\"))\n   * builder.where([eq(\"name\", \"John\"), eq(\"age\", 30)])\n   * builder.where([eq(\"name\", \"John\"), or([eq(\"age\", 30), eq(\"age\", 31)])])\n   * builder.where([eq(\"name\", \"John\"), and([eq(\"age\", 30), eq(\"age\", 31)])])\n   * builder.where([eq(\"name\", \"John\"), or([eq(\"age\", 30), and([eq(\"age\", 31), eq(\"age\", 32)])])])\n   * builder.where([eq(\"name\", \"John\"), and([eq(\"age\", 30), or([eq(\"age\", 31), eq(\"age\", 32)])])])\n   * builder.where([eq(\"name\", \"John\"), and([eq(\"age\", 30), or([eq(\"age\", 31), and([eq(\"age\", 32), eq(\"age\", 33)])])])])\n   */\n  where(predicates: Predicate[] | Predicate) {\n    if (Array.isArray(predicates)) {\n      this._predicates.push(...predicates)\n    } else {\n      this._predicates.push(predicates)\n    }\n    return this\n  }\n\n  /**\n   * Fetches the entities from the query. Re\n   * It will return a QueryResult instance which can be used to fetch the next and previous pages.\n   * @returns The QueryResult instance {@link QueryResult}\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * const result = await builder.where(eq(\"name\", \"John\")).fetch()\n   * // result = { entities: [Entity, Entity, Entity], next: async () => QueryResult, previous: async () => QueryResult }\n   */\n  async fetch() {\n    const queryResult = await processQuery(this._client, {\n      predicates: this._predicates,\n      limit: this._limit,\n      cursor: this._cursor,\n      ownedBy: this._ownedBy,\n      orderBy: this._orderBy,\n      validAtBlock: this._validAtBlock,\n      withAttributes: this._withAttributes,\n      withMetadata: this._withMetadata,\n      withPayload: this._withPayload,\n    })\n\n    const entities = await Promise.all(\n      queryResult.data.map((entity) => entityFromRpcResult(entity)),\n    )\n\n    this.cursor(queryResult.cursor)\n    this.validAtBlock(queryResult.blockNumber)\n\n    return new QueryResult(entities, this, this._cursor, this._limit, this._validAtBlock)\n  }\n\n  /**\n   * Counts the entities from the query.\n   * @returns The number of entities\n   *\n   * @example\n   * const builder = new QueryBuilder(client)\n   * const result = await builder.where(eq(\"name\", \"John\")).count()\n   * // result = 10\n   */\n  async count() {\n    const queryResult = await processQuery(this._client, {\n      predicates: this._predicates,\n      limit: this._limit,\n      cursor: this._cursor,\n      ownedBy: this._ownedBy,\n      orderBy: undefined,\n      validAtBlock: this._validAtBlock,\n      withAttributes: false,\n      withMetadata: false,\n      withPayload: false,\n    })\n\n    return queryResult.data.length ?? 0\n  }\n}\n"],"mappings":"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"}

package/dist/types/index.d.cts

@@ -1,2 +1,3 @@
-import { _ as ArkivRpcSchema, a as MutateEntitiesReturnType, b as RpcQueryOptions, c as ExtendEntityParameters, d as DeleteEntityReturnType, f as CreateEntityParameters, h as ChangeOwnershipReturnType, i as MutateEntitiesParameters, l as ExtendEntityReturnType, m as ChangeOwnershipParameters, n as TxParams, o as UpdateEntityParameters, p as CreateEntityReturnType, r as Attribute, s as UpdateEntityReturnType, t as Entity, u as DeleteEntityParameters, v as RpcEntity, x as MimeType, y as RpcIncludeData } from "../entity-BNSCqNpu.cjs";
-export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, RpcEntity, RpcIncludeData, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };
+import { $ as RpcIncludeData, A as CreateEntityParameters, C as MutateEntitiesReturnType, D as ExtendEntityReturnType, E as ExtendEntityParameters, J as QueryOptionsIncludeData, M as ChangeOwnershipParameters, N as ChangeOwnershipReturnType, O as DeleteEntityParameters, P as GetBlockTimingReturnType, Q as RpcEntity, S as MutateEntitiesParameters, T as UpdateEntityReturnType, Y as QueryOptionsOrderBy, Z as ArkivRpcSchema, _ as OnEntityExpiredEvent, b as OnEntityUpdatedEvent, et as RpcOrderByAttribute, g as OnEntityDeletedEvent, h as OnEntityCreatedEvent, j as CreateEntityReturnType, k as DeleteEntityReturnType, m as TxParams, nt as MimeType, p as Entity, q as QueryOptions, tt as RpcQueryOptions, v as OnEntityExpiresInExtendedEvent, w as UpdateEntityParameters, x as Attribute, y as OnEntityOwnerChangedEvent } from "../index-DQGx5KZ6.cjs";
+import "../payload-D3fyOBWn.cjs";
+export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, GetBlockTimingReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, OnEntityCreatedEvent, OnEntityDeletedEvent, OnEntityExpiredEvent, OnEntityExpiresInExtendedEvent, OnEntityOwnerChangedEvent, OnEntityUpdatedEvent, QueryOptions, QueryOptionsIncludeData, QueryOptionsOrderBy, RpcEntity, RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };

package/dist/types/index.d.ts

@@ -1,2 +1,3 @@
-import { _ as ArkivRpcSchema, a as MutateEntitiesReturnType, b as RpcQueryOptions, c as ExtendEntityParameters, d as DeleteEntityReturnType, f as CreateEntityParameters, h as ChangeOwnershipReturnType, i as MutateEntitiesParameters, l as ExtendEntityReturnType, m as ChangeOwnershipParameters, n as TxParams, o as UpdateEntityParameters, p as CreateEntityReturnType, r as Attribute, s as UpdateEntityReturnType, t as Entity, u as DeleteEntityParameters, v as RpcEntity, x as MimeType, y as RpcIncludeData } from "../entity-D7fzI0Hc.js";
-export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, RpcEntity, RpcIncludeData, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };
+import { $ as RpcIncludeData, A as CreateEntityParameters, C as MutateEntitiesReturnType, D as ExtendEntityReturnType, E as ExtendEntityParameters, J as QueryOptionsIncludeData, M as ChangeOwnershipParameters, N as ChangeOwnershipReturnType, O as DeleteEntityParameters, P as GetBlockTimingReturnType, Q as RpcEntity, S as MutateEntitiesParameters, T as UpdateEntityReturnType, Y as QueryOptionsOrderBy, Z as ArkivRpcSchema, _ as OnEntityExpiredEvent, b as OnEntityUpdatedEvent, et as RpcOrderByAttribute, g as OnEntityDeletedEvent, h as OnEntityCreatedEvent, j as CreateEntityReturnType, k as DeleteEntityReturnType, m as TxParams, nt as MimeType, p as Entity, q as QueryOptions, tt as RpcQueryOptions, v as OnEntityExpiresInExtendedEvent, w as UpdateEntityParameters, x as Attribute, y as OnEntityOwnerChangedEvent } from "../index-B801JxcV.js";
+import "../payload-BI2NXPDf.js";
+export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, GetBlockTimingReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, OnEntityCreatedEvent, OnEntityDeletedEvent, OnEntityExpiredEvent, OnEntityExpiresInExtendedEvent, OnEntityOwnerChangedEvent, OnEntityUpdatedEvent, QueryOptions, QueryOptionsIncludeData, QueryOptionsOrderBy, RpcEntity, RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };

package/dist/utils/index.cjs

@@ -1,4 +1,4 @@
-const require_payload = require('../payload-eB1a8vZH.cjs');
+const require_payload = require('../payload-vwU3Rc6P.cjs');
 
 //#region src/utils/expirationTime.ts
 const ExpirationTime = {

package/dist/utils/index.d.cts

@@ -1,4 +1,4 @@
-import { n as stringToPayload, t as jsonToPayload } from "../payload-CJN8fTvX.cjs";
+import { n as stringToPayload, t as jsonToPayload } from "../payload-D3fyOBWn.cjs";
 export * from "viem/utils";
 
 //#region src/utils/expirationTime.d.ts

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { n as stringToPayload, t as jsonToPayload } from "../payload-Da9gJMG5.js";
+import { n as stringToPayload, t as jsonToPayload } from "../payload-BI2NXPDf.js";
 export * from "viem/utils";
 
 //#region src/utils/expirationTime.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkiv-network/sdk",
-  "version": "0.5.0-dev.1",
+  "version": "0.5.0-dev.3",
   "description": "TypeScript client library for Arkiv's blockchains interactions",
   "type": "module",
   "target": "esnext",
@@ -73,6 +73,7 @@
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "test:unit": "bun test src/**/*",
+    "docs": "bunx typedoc --plugin typedoc-plugin-markdown",
     "package": "rimraf arkiv-network-sdk-*.tgz && bun run build && bun pm pack --no-cache",
     "package:test": "bun run package && mv arkiv-network-sdk-*.tgz arkiv-network-sdk-latest.tgz",
     "prepublishOnly": "bun run build && bun run package && mv arkiv-network-sdk-*.tgz arkiv-network-sdk-latest.tgz",
@@ -84,11 +85,11 @@
     "publish-dev:dry": "npm publish ./arkiv-network-sdk-latest.tgz --access public --tag dev --dry-run"
   },
   "devDependencies": {
-    "@types/debug": "^4.1.12",
     "@biomejs/biome": "2.2.4",
     "@types/bun": "latest",
     "rimraf": "^6.0.1",
-    "tsdown": "^0.16.0"
+    "tsdown": "^0.16.0",
+    "typedoc": "^0.28.14"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"
@@ -117,7 +118,7 @@
   "homepage": "https://arkiv.network",
   "dependencies": {
     "brotli-wasm": "^3.0.1",
-    "viem": "^2.38.2",
-    "debug": "^4.3.7"
+    "typedoc-plugin-markdown": "^4.9.0",
+    "viem": "^2.38.2"
   }
 }

package/src/actions/public/query.ts

@@ -1,10 +1,57 @@
 import type { ArkivClient } from "../../clients/baseClient"
+import type { RpcQueryOptions } from "../../types/rpcSchema"
 import { entityFromRpcResult } from "../../utils/entities"
 
-export async function query(client: ArkivClient, query: string) {
+export type QueryOptionsIncludeData = {
+  attributes?: boolean
+  payload?: boolean
+  metadata?: boolean
+}
+export type QueryOptionsOrderBy = {
+  name: string
+  type: "string" | "numeric"
+  desc: "asc" | "desc"
+}
+
+export type QueryOptions = {
+  includeData?: QueryOptionsIncludeData
+  atBlock?: bigint
+  orderBy?: QueryOptionsOrderBy[]
+  resultsPerPage?: number | undefined
+  cursor?: string | undefined
+}
+
+export async function query(client: ArkivClient, query: string, queryOptions?: QueryOptions) {
+  const rpcQueryOptions: RpcQueryOptions = {
+    includeData: {
+      key: true,
+      payload: queryOptions?.includeData?.payload ?? true,
+      attributes: queryOptions?.includeData?.attributes ?? false,
+      contentType: queryOptions?.includeData?.metadata ?? false,
+      expiration: queryOptions?.includeData?.metadata ?? false,
+      owner: queryOptions?.includeData?.metadata ?? false,
+      createdAtBlock: queryOptions?.includeData?.metadata ?? false,
+      lastModifiedAtBlock: queryOptions?.includeData?.metadata ?? false,
+      transactionIndexInBlock: queryOptions?.includeData?.metadata ?? false,
+      operationIndexInTransaction: queryOptions?.includeData?.metadata ?? false,
+    },
+    ...(queryOptions?.atBlock !== undefined && { atBlock: Number(queryOptions.atBlock) }),
+    ...(queryOptions?.orderBy && {
+      orderBy: queryOptions?.orderBy.map((order) => ({
+        name: order.name,
+        type: order.type,
+        desc: order.desc === "desc",
+      })),
+    }),
+    ...(queryOptions?.resultsPerPage !== undefined && {
+      resultsPerPage: queryOptions.resultsPerPage,
+    }),
+    ...(queryOptions?.cursor !== undefined && { cursor: queryOptions?.cursor }),
+  }
+
   const result = await client.request({
     method: "arkiv_query",
-    params: [query],
+    params: [query, rpcQueryOptions],
   })
 
   const entities = await Promise.all(result.data.map((entity) => entityFromRpcResult(entity)))

package/src/actions/public/subscribeEntityEvents.ts

@@ -1,4 +1,4 @@
-import { decodeEventLog, parseAbi, toHex } from "viem"
+import { decodeEventLog, type Hex, parseAbi, toHex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { PublicArkivClient } from "../../clients/createPublicClient"
 import type {
@@ -53,7 +53,7 @@ export async function subscribeEntityEvents(
       for (const log of logs) {
         const event = decodeEventLog({
           abi: arkivABI,
-          topics: log.topics as [string, string, string] | [string, string, string, string],
+          topics: log.topics as [Hex, ...Hex[]] | [],
           data: log.data,
         })
         logger("event from subscribeEntityEvents %o", event)

package/src/clients/createPublicClient.ts

@@ -29,7 +29,7 @@ export type PublicArkivClient<
  *
  * A Public Client is an interface to "public" [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/), [Arkiv JSON-RPC API](https://docs.arkiv.network/json-rpc/), and [Kaolin JSON-RPC API](https://kaolin.holesky.arkiv.network/rpc) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
  *
- * @param config - {@link PublicClientConfig}
+ * @param parameters - Configuration object for the public client (chain, transport, etc.)
  * @returns A Arkiv Public Client. {@link PublicArkivClient}
  *
  * @example

package/src/clients/createWalletClient.ts

@@ -29,8 +29,8 @@ export type WalletArkivClient<
  *
  * A Public Client is an interface to "public" [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/), [Arkiv JSON-RPC API](https://docs.arkiv.network/json-rpc/), and [Kaolin JSON-RPC API](https://kaolin.holesky.arkiv.network/rpc) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
  *
- * @param config - {@link PublicClientConfig}
- * @returns A Arkiv Public Client. {@link PublicArkivClient}
+ * @param parameters - Configuration object for the wallet client (chain, transport, account, etc.)
+ * @returns A Arkiv Wallet Client. {@link WalletArkivClient}
  *
  * @example
  * import { createPublicClient, http } from 'arkiv'

package/src/clients/decorators/arkivPublic.ts

@@ -2,7 +2,7 @@ import type { Account, Chain, Client, Hex, PublicActions, Transport } from "viem
 import { getBlockTiming } from "../../actions/public/getBlockTiming"
 import { getEntity } from "../../actions/public/getEntity"
 import { getEntityCount } from "../../actions/public/getEntityCount"
-import { query } from "../../actions/public/query"
+import { type QueryOptions, query } from "../../actions/public/query"
 import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
 import { QueryBuilder } from "../../query/queryBuilder"
 import type { Entity } from "../../types/entity"
@@ -36,7 +36,7 @@ export type PublicArkivActions<
    *
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/getEntity
    *
-   * @param args - {entityKey}
+   * @param key - The entity key (hex string)
    * @returns The entity with the given key. {@link Entity}
    *
    * @example
@@ -79,7 +79,10 @@ export type PublicArkivActions<
 
   /**
    * Returns a QueryResult instance for fetching the results of a raw query.
-   * @returns A QueryResult instance for fetching the results of a raw query. {@link QueryResult}
+   * If no query options are provided, all payload is included, but no metadata (like owner, expiredAt, etc.) and attributes.
+   * @param query - The raw query string
+   * @param queryOptions - The optional query options - {@link QueryOptions}
+   * @returns An array of entities matching the query. {@link Entity}
    *
    * @example
    * import { createPublicClient, http } from 'arkiv'
@@ -90,13 +93,25 @@ export type PublicArkivActions<
    *   transport: http(),
    * })
    * const queryResult = client.query('key = value && $owner = 0x123')
-   *
+   * // queryResult = [{ key: "0x123", value: "0x123" }]
+   * const queryResultWithOptions = client.query('key = value && $owner = 0x123', {
+   *   includeData: {
+   *     attributes: false,
+   *     payload: true,
+   *     metadata: true,
+   *   },
+   *   orderBy: [{ name: "key", type: "string", desc: "asc" }],
+   *   resultsPerPage: 10,
+   *   cursor: undefined,
+   *   atBlock: undefined,
+   * })
+   * // queryResultWithOptions = [{ key: "0x123", value: "0x123" }]
    */
-  query: (query: string) => Promise<Entity[]>
+  query: (query: string, queryOptions?: QueryOptions) => Promise<Entity[]>
 
   /**
    * Returns the number of entities in the DBChain.
-   * @returns The number of entities in the DBChain. {@link number}
+   * @returns The number of entities in the DBChain
    *
    * @example
    * import { createPublicClient, http } from 'arkiv'
@@ -138,10 +153,10 @@ export type PublicArkivActions<
 
   /**
    * Subscribes to entity events.
-   * @param events to watch - {onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpiresInExtended}
-   * @param pollingInterval - The polling interval in milliseconds. {@link number}
-   * @param fromBlock - The block number to start from. {@link bigint}
-   * @returns A function to unsubscribe from the events. {() => void}
+   * Takes an object with event handlers: {onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpiresInExtended}
+   * @param pollingInterval - The polling interval in milliseconds
+   * @param fromBlock - The block number to start from
+   * @returns A function to unsubscribe from the events
    *
    * @example
    * import { createPublicClient, http } from 'arkiv'
@@ -183,7 +198,7 @@ export function publicArkivActions<
 >(client: Client<transport, chain, account>) {
   return {
     getEntity: (key: Hex) => getEntity(client, key),
-    query: (rawQuery: string) => query(client, rawQuery),
+    query: (rawQuery: string, queryOptions?: QueryOptions) => query(client, rawQuery, queryOptions),
     buildQuery: () => new QueryBuilder(client),
     getBlockTiming: () => getBlockTiming(client),
     getEntityCount: () => getEntityCount(client),

package/src/clients/decorators/arkivWallet.ts

@@ -29,7 +29,7 @@ import type {
   UpdateEntityReturnType,
 } from "../../actions/wallet/updateEntity"
 import { updateEntity } from "../../actions/wallet/updateEntity"
-import type { Entity, TxParams } from "../../types"
+import type { TxParams } from "../../types"
 
 export type WalletArkivActions<
   transport extends Transport = Transport,
@@ -47,13 +47,14 @@ export type WalletArkivActions<
     | "signTransaction"
   > & {
     /**
-     * Returns the entity with the given key.
+     * Creates a new entity.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/getEntity
+     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/createEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity creation parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The created entity with transaction hash
      *
      * @example
      * import { createPublicClient, http } from 'arkiv'
@@ -86,8 +87,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/updateEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey, data}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity update parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The updated entity with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'
@@ -109,8 +111,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/deleteEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity deletion parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The deleted entity with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'
@@ -139,8 +142,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/extendEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey, data}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity update parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The updated entity with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'
@@ -171,8 +175,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/changeOwnership
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey, newOwner}
-     * @returns The entity with the given address. {@link Entity}
+     * @param data - The ownership change parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The entity with updated ownership and transaction hash
      */
     changeOwnership: (
       data: ChangeOwnershipParameters,
@@ -185,8 +190,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/mutateEntities
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {data}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The mutation parameters (creates, updates, deletes, extensions)
+     * @param txParams - Optional transaction parameters
+     * @returns The mutation result with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'

package/src/index.ts

@@ -1,3 +1,7 @@
+/**
+ * @module main
+ */
+
 // Re-export all viem stuff
 export * from "viem"
 
@@ -7,6 +11,8 @@ export type { PublicArkivClient } from "./clients/createPublicClient"
 export { createPublicClient } from "./clients/createPublicClient"
 export type { WalletArkivClient } from "./clients/createWalletClient"
 export { createWalletClient } from "./clients/createWalletClient"
+export type { PublicArkivActions } from "./clients/decorators/arkivPublic"
+export type { WalletArkivActions } from "./clients/decorators/arkivWallet"
 
 // re-export arkiv types in main index file
 export * from "./types"

package/src/query/errors.ts

@@ -10,12 +10,6 @@ export class NoCursorOrLimitError extends Error {
   }
 }
 
-export class OffsetCannotBeLessThanZeroError extends Error {
-  constructor() {
-    super("Offset cannot be less than 0")
-  }
-}
-
 export class NoEntityFoundError extends Error {
   constructor() {
     super("No entity found")