Added useFlowQueryRaw hook

.changeset/wicked-bikes-peel.md

@@ -0,0 +1,7 @@
+---
+"@onflow/fcl-core": minor
+"@onflow/fcl": minor
+"@onflow/kit": minor
+---
+
+Added useFlowQueryRaw hook to execute a query and get non-decoded data as result.

packages/fcl-core/src/exec/query-raw.ts

@@ -0,0 +1,55 @@
+import * as sdk from "@onflow/sdk"
+import type {ArgsFn} from "./args"
+import {normalizeArgs} from "./utils/normalize-args"
+import {preQuery} from "./utils/pre"
+import {prepTemplateOpts} from "./utils/prep-template-opts"
+
+export interface QueryOptions {
+  cadence?: string
+  args?: ArgsFn
+  template?: any
+  isSealed?: boolean
+  limit?: number
+}
+
+/**
+ * @description Allows you to submit scripts to query the blockchain and get raw response data.
+ *
+ * @param opts Query Options and configuration
+ * @param opts.cadence Cadence Script used to query Flow
+ * @param opts.args Arguments passed to cadence script
+ * @param opts.template Interaction Template for a script
+ * @param opts.isSealed Block Finality
+ * @param opts.limit Compute Limit for Query
+ * @returns A promise that resolves to the raw query result
+ *
+ * @example
+ *    const cadence = `
+ *      cadence: `
+ *        access(all) fun main(a: Int, b: Int, c: Address): Int {
+ *          log(c)
+ *          return a + b
+ *        }
+ *    `.trim()
+ *
+ *    const args = (arg, t) => [
+ *      arg(5, t.Int),
+ *      arg(7, t.Int),
+ *      arg("0xb2db43ad6bc345fec9", t.Address),
+ *    ]
+ *
+ *    await queryRaw({ cadence, args })
+ */
+export async function queryRaw(opts: QueryOptions = {}): Promise<any> {
+  await preQuery(opts)
+  opts = await prepTemplateOpts(opts)
+
+  return sdk.send([
+    sdk.script(opts.cadence!),
+    sdk.args(normalizeArgs(opts.args || [])),
+    sdk.atLatestBlock(opts.isSealed ?? false),
+    opts.limit &&
+      typeof opts.limit === "number" &&
+      (sdk.limit(opts.limit!) as any),
+  ])
+}

packages/fcl-core/src/exec/query.ts

@@ -0,0 +1,34 @@
+import * as sdk from "@onflow/sdk"
+import {QueryOptions, queryRaw} from "./query-raw"
+
+/**
+ * @description Allows you to submit scripts to query the blockchain.
+ *
+ * @param opts Query Options and configuration
+ * @param opts.cadence Cadence Script used to query Flow
+ * @param opts.args Arguments passed to cadence script
+ * @param opts.template Interaction Template for a script
+ * @param opts.isSealed Block Finality
+ * @param opts.limit Compute Limit for Query
+ * @returns A promise that resolves to the query result
+ *
+ * @example
+ *    const cadence = `
+ *      cadence: `
+ *        access(all) fun main(a: Int, b: Int, c: Address): Int {
+ *          log(c)
+ *          return a + b
+ *        }
+ *    `.trim()
+ *
+ *    const args = (arg, t) => [
+ *      arg(5, t.Int),
+ *      arg(7, t.Int),
+ *      arg("0xb2db43ad6bc345fec9", t.Address),
+ *    ]
+ *
+ *    await query({ cadence, args })
+ */
+export async function query(opts: QueryOptions = {}): Promise<any> {
+  return queryRaw(opts).then(sdk.decode)
+}

packages/fcl-core/src/fcl-core.ts

@@ -1,5 +1,6 @@
 export {VERSION} from "./VERSION"
 export {query} from "./exec/query"
+export {queryRaw} from "./exec/query-raw"
 export {verifyUserSignatures} from "./exec/verify"
 export {serialize} from "./serialize"
 export {transaction as tx, TransactionError} from "./transaction"

packages/fcl-core/src/interaction-template-utils/get-interaction-template-audits.js

@@ -1,6 +1,6 @@
 import {config, invariant} from "@onflow/sdk"
 import {log, LEVELS} from "@onflow/util-logger"
-import {query} from "../exec/query.js"
+import {query} from "../exec/query"
 import {generateTemplateId} from "./generate-template-id/generate-template-id.js"
 import {getChainId} from "../utils"
 

packages/fcl/src/fcl.ts

@@ -1,6 +1,7 @@
 export {
   VERSION,
   query,
+  queryRaw,
   verifyUserSignatures,
   serialize,
   tx,

packages/kit/src/__mocks__/fcl.ts

@@ -17,6 +17,7 @@ export default {
   events: jest.fn(),
   mutate: jest.fn(),
   query: jest.fn(),
+  queryRaw: jest.fn(),
   tx: jest.fn(),
   config: () => ({
     subscribe: sharedSubscribe,

packages/kit/src/hooks/index.ts

@@ -5,6 +5,7 @@ export {useFlowConfig} from "./useFlowConfig"
 export {useFlowEvents} from "./useFlowEvents"
 export {useFlowMutate} from "./useFlowMutate"
 export {useFlowQuery} from "./useFlowQuery"
+export {useFlowQueryRaw} from "./useFlowQueryRaw"
 export {useFlowRevertibleRandom} from "./useFlowRevertibleRandom"
 export {useCrossVmBatchTransaction} from "./useCrossVmBatchTransaction"
 export {useCrossVmTokenBalance} from "./useCrossVmTokenBalance"

packages/kit/src/hooks/useFlowQuery.test.ts

@@ -1,7 +1,7 @@
 import {renderHook, act, waitFor} from "@testing-library/react"
 import * as fcl from "@onflow/fcl"
 import {FlowProvider} from "../provider"
-import {useFlowQuery} from "./useFlowQuery"
+import {useFlowQuery, encodeQueryArgs} from "./useFlowQuery"
 
 jest.mock("@onflow/fcl", () => require("../__mocks__/fcl").default)
 
@@ -183,4 +183,55 @@ describe("useFlowQuery", () => {
 
     await waitFor(() => expect(hookResult.current.data).toEqual(updatedResult))
   })
+
+  describe("encodeQueryArgs", () => {
+    beforeEach(() => {
+      // Clear mocks
+      jest.clearAllMocks()
+    })
+
+    test("returns undefined when args is undefined", () => {
+      const result = encodeQueryArgs(undefined)
+      expect(result).toBeUndefined()
+    })
+
+    test("returns undefined when args is null", () => {
+      const result = encodeQueryArgs(null as any)
+      expect(result).toBeUndefined()
+    })
+
+    test("encodes single argument correctly", () => {
+      const argsFunction = (arg: typeof fcl.arg, t: typeof fcl.t) => [
+        arg("42", t.Int),
+      ]
+
+      const result = encodeQueryArgs(argsFunction)
+
+      expect(result).toEqual([{type: "Int", value: "42"}])
+    })
+
+    test("encodes multiple arguments correctly", () => {
+      const argsFunction = (arg: typeof fcl.arg, t: typeof fcl.t) => [
+        arg("42", t.Int),
+        arg("hello", t.String),
+        arg("0x1234567890abcdef", t.Address),
+      ]
+
+      const result = encodeQueryArgs(argsFunction)
+
+      expect(result).toEqual([
+        {type: "Int", value: "42"},
+        {type: "String", value: "hello"},
+        {type: "Address", value: "0x1234567890abcdef"},
+      ])
+    })
+
+    test("handles empty args array", () => {
+      const argsFunction = (arg: typeof fcl.arg, t: typeof fcl.t) => []
+
+      const result = encodeQueryArgs(argsFunction)
+
+      expect(result).toEqual([])
+    })
+  })
 })

packages/kit/src/hooks/useFlowQuery.ts

@@ -3,6 +3,14 @@ import {useQuery, UseQueryResult, UseQueryOptions} from "@tanstack/react-query"
 import {useCallback} from "react"
 import {useFlowQueryClient} from "../provider/FlowQueryClient"
 
+export function encodeQueryArgs(
+  args?: (arg: typeof fcl.arg, t: typeof fcl.t) => unknown[]
+): any[] | undefined {
+  // Encode the arguments to a JSON-CDC object so they can be deterministically
+  // serialized and used as the query key.
+  return args?.(fcl.arg, fcl.t)?.map((x: any) => x.xform.asArgument(x.value))
+}
+
 export interface UseFlowQueryArgs {
   cadence: string
   args?: (arg: typeof fcl.arg, t: typeof fcl.t) => unknown[]
@@ -32,12 +40,7 @@ export function useFlowQuery({
     return fcl.query({cadence, args})
   }, [cadence, args])
 
-  // Encode the arguments to a JSON-CDC object so they can be deterministically
-  // serialized and used as the query key.
-  const encodedArgs = args?.(fcl.arg, fcl.t)?.map((x: any) =>
-    x.xform.asArgument(x.value)
-  )
-
+  const encodedArgs = encodeQueryArgs(args)
   return useQuery<unknown, Error>(
     {
       queryKey: ["flowQuery", cadence, encodedArgs],