feat: useEnsName

packages/vue/src/composables/useEnsName.test.ts

@@ -0,0 +1,52 @@
+import { renderComposable, waitFor } from '@wagmi/test/vue'
+import { expect, test } from 'vitest'
+
+import { deepUnref } from '../utils/cloneDeep.js'
+import { useEnsName } from './useEnsName.js'
+
+test('default', async () => {
+  const [result] = renderComposable(() =>
+    useEnsName({
+      address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+    }),
+  )
+
+  await waitFor(result.isSuccess)
+
+  expect(deepUnref(result)).toMatchInlineSnapshot(`
+    {
+      "data": "wevm.eth",
+      "dataUpdatedAt": 1675209600000,
+      "error": null,
+      "errorUpdateCount": 0,
+      "errorUpdatedAt": 0,
+      "failureCount": 0,
+      "failureReason": null,
+      "fetchStatus": "idle",
+      "isError": false,
+      "isFetched": true,
+      "isFetchedAfterMount": true,
+      "isFetching": false,
+      "isInitialLoading": false,
+      "isLoading": false,
+      "isLoadingError": false,
+      "isPaused": false,
+      "isPending": false,
+      "isPlaceholderData": false,
+      "isRefetchError": false,
+      "isRefetching": false,
+      "isStale": true,
+      "isSuccess": true,
+      "queryKey": [
+        "ensName",
+        {
+          "address": "0xd2135CfB216b74109775236E36d4b433F1DF507B",
+          "chainId": 1,
+        },
+      ],
+      "refetch": [Function],
+      "status": "success",
+      "suspense": [Function],
+    }
+  `)
+})

packages/vue/src/composables/useEnsName.ts

@@ -0,0 +1,65 @@
+import type { Config, GetEnsNameErrorType, ResolvedRegister } from '@wagmi/core'
+import { type Evaluate } from '@wagmi/core/internal'
+import {
+  type GetEnsNameData,
+  type GetEnsNameOptions,
+  type GetEnsNameQueryFnData,
+  type GetEnsNameQueryKey,
+  getEnsNameQueryOptions,
+} from '@wagmi/core/query'
+
+import { computed } from 'vue'
+import type { ConfigParameter, QueryParameter } from '../types/properties.js'
+import type { DeepMaybeRef } from '../types/ref.js'
+import { deepUnref } from '../utils/cloneDeep.js'
+import { type UseQueryReturnType, useQuery } from '../utils/query.js'
+import { useChainId } from './useChainId.js'
+import { useConfig } from './useConfig.js'
+
+export type UseEnsNameParameters<
+  config extends Config = Config,
+  selectData = GetEnsNameData,
+> = Evaluate<
+  DeepMaybeRef<
+    GetEnsNameOptions<config> &
+      ConfigParameter<config> &
+      QueryParameter<
+        GetEnsNameQueryFnData,
+        GetEnsNameErrorType,
+        selectData,
+        GetEnsNameQueryKey<config>
+      >
+  >
+>
+
+export type UseEnsNameReturnType<selectData = GetEnsNameData> =
+  UseQueryReturnType<selectData, GetEnsNameErrorType>
+
+/** https://wagmi.sh/vue/api/composables/useEnsName */
+export function useEnsName<
+  config extends Config = ResolvedRegister['config'],
+  selectData = GetEnsNameData,
+>(
+  parameters_: UseEnsNameParameters<config, selectData> = {},
+): UseEnsNameReturnType<selectData> {
+  const parameters = computed(() => deepUnref(parameters_))
+
+  const config = useConfig(parameters)
+  const configChainId = useChainId({ config })
+
+  const queryOptions = computed(() => {
+    const {
+      address,
+      chainId = configChainId.value,
+      query = {},
+    } = parameters.value
+    const options = getEnsNameQueryOptions(config, {
+      ...parameters.value,
+      chainId,
+    })
+    const enabled = Boolean(address && (query.enabled ?? true))
+    return { ...query, ...options, enabled }
+  })
+
+  return useQuery(queryOptions as any) as UseEnsNameReturnType<selectData>
+}

packages/vue/src/exports/index.test.ts

@@ -25,6 +25,7 @@ test('exports', () => {
       "useDisconnect",
       "useEnsAddress",
       "useEnsAvatar",
+      "useEnsName",
       "useEstimateGas",
       "useReadContract",
       "useReconnect",

packages/vue/src/exports/index.ts

@@ -110,6 +110,12 @@ export {
   useEnsAvatar,
 } from '../composables/useEnsAvatar.js'
 
+export {
+  type UseEnsNameParameters,
+  type UseEnsNameReturnType,
+  useEnsName,
+} from '../composables/useEnsName.js'
+
 export {
   type UseEstimateGasParameters,
   type UseEstimateGasReturnType,

site/vue/api/composables/useEnsName.md

@@ -0,0 +1,206 @@
+---
+title: useEnsName
+description: Composable for fetching primary ENS name for address.
+---
+
+<script setup>
+const packageName = '@wagmi/vue'
+const actionName = 'getEnsName'
+const typeName = 'GetEnsName'
+const TData = 'string | null'
+const TError = 'GetEnsNameErrorType'
+</script>
+
+# useEnsName
+
+Composable for fetching primary ENS name for address.
+
+## Import
+
+```ts
+import { useEnsName } from '@wagmi/vue'
+```
+
+## Usage
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+## Parameters
+
+```ts
+import { type UseEnsNameParameters } from '@wagmi/vue'
+```
+
+### address
+
+`Address | undefined`
+
+Name to get the resolver for. [`enabled`](#enabled) set to `false` if `address` is `undefined`.
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B', // [!code focus]
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+---
+
+### blockNumber
+
+`bigint | undefined`
+
+Block number to get ENS name at.
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+  blockNumber: 17829139n, // [!code focus]
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+### blockTag
+
+`'latest' | 'earliest' | 'pending' | 'safe' | 'finalized' | undefined`
+
+Block tag to get ENS name at.
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+  blockTag: 'latest', // [!code focus]
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+---
+
+### chainId
+
+`config['chains'][number]['id'] | undefined`
+
+ID of chain to use when fetching data.
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+import { mainnet } from 'wagmi/chains' // [!code focus]
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+  chainId: mainnet.id, // [!code focus]
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+### config
+
+`Config | undefined`
+
+[`Config`](/vue/api/createConfig#config) to use instead of retrieving from the [`WagmiPlugin`](/vue/api/WagmiPlugin).
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+import { normalize } from 'viem/ens'
+import { config } from './config' // [!code focus]
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+  config, // [!code focus]
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+### scopeKey
+
+`string | undefined`
+
+Scopes the cache to a given context. Composables that have identical context will share the same cache.
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+  scopeKey: 'foo', // [!code focus]
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+### universalResolverAddress
+
+`Address | undefined`
+
+- Address of ENS Universal Resolver Contract.
+- Defaults to current chain's Universal Resolver Contract address.
+
+::: code-group
+```vue [index.vue]
+<script setup lang="ts">
+import { useEnsName } from '@wagmi/vue'
+
+const result = useEnsName({
+  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
+  universalResolverAddress: '0x74E20Bd2A1fE0cdbe45b9A1d89cb7e0a45b36376', // [!code focus]
+})
+</script>
+```
+<<< @/snippets/vue/config.ts[config.ts]
+:::
+
+<!--@include: @shared/query-options.md-->
+
+## Return Type
+
+```ts
+import { type UseEnsNameReturnType } from '@wagmi/vue'
+```
+
+<!--@include: @shared/query-result.md-->
+
+<!--@include: @shared/query-imports.md-->
+
+## Action
+
+- [`getEnsName`](/core/api/actions/getEnsName)