playground: ethers example implementation

.changeset/thirty-experts-listen.md

@@ -0,0 +1,5 @@
+---
+"abitype": patch
+---
+
+Adds a playground example of using `abitype` with ethers.

docs/guide/getting-started.md

@@ -60,3 +60,4 @@ After setting up your project with ABIType, you are ready to dive in further! He
 - Follow along with a [walkthrough](/guide/walkthrough) on building a type-safe `readContract` function.
 - Check out comparisons between features in [ABIType and TypeChain](/guide/comparisons#typechain) as well as [ABIType and ethers.js](/guide/comparisons#ethers-js).
 - Make reading and writing ABIs more human with [human-readable ABI support](/api/human).
+- Checkout our own [playground](https://github.com/wevm/abitype/tree/main/playgrounds/functions/src) full of examples on how to apply it on your projects. Including creating a wrapper for ethers contracts.

playgrounds/functions/package.json

@@ -7,5 +7,8 @@
   },
   "dependencies": {
     "abitype": "workspace:*"
+  },
+  "devDependencies": {
+    "ethers": "^6.5.1"
   }
 }

playgrounds/functions/src/ethers.test-d.ts

@@ -0,0 +1,104 @@
+import type { ExtractAbiEvent, ResolvedRegister } from 'abitype'
+import type { ContractTransaction } from 'ethers'
+import type { CallOverrides, Event, Overrides } from './utils.js'
+
+import { wagmiMintExampleAbi } from 'abitype/abis'
+import { assertType, describe, expectTypeOf } from 'vitest'
+import { getContract } from './ethers.js'
+
+describe('getContract', () => {
+  const contract = getContract({
+    address: '0xfoo',
+    abi: wagmiMintExampleAbi,
+  })
+
+  describe('regular function', () => {
+    expectTypeOf(contract.balanceOf).toBeCallableWith('0x…', { from: '0x…' })
+    expectTypeOf(contract.balanceOf)
+      .parameter(0)
+      .toEqualTypeOf<ResolvedRegister['AddressType']>()
+    expectTypeOf(contract.balanceOf)
+      .parameter(1)
+      .toEqualTypeOf<CallOverrides | undefined>()
+    expectTypeOf(contract.balanceOf).returns.resolves.toEqualTypeOf<bigint>()
+
+    expectTypeOf(contract.functions.balanceOf).toBeCallableWith('0x…', {
+      from: '0x…',
+    })
+    expectTypeOf(contract.functions.balanceOf)
+      .parameter(0)
+      .toEqualTypeOf<ResolvedRegister['AddressType']>()
+    expectTypeOf(contract.functions.balanceOf)
+      .parameter(1)
+      .toEqualTypeOf<CallOverrides | undefined>()
+    expectTypeOf(contract.functions.balanceOf).returns.resolves.toEqualTypeOf<
+      [bigint]
+    >()
+  })
+
+  describe('overloaded function', () => {
+    const functionNameA = 'safeTransferFrom(address,address,uint256)'
+    expectTypeOf(contract[functionNameA]).toBeCallableWith(
+      '0x…',
+      '0x…',
+      BigInt('123'),
+      { from: '0x…' },
+    )
+    expectTypeOf(contract[functionNameA])
+      .parameter(0)
+      .toEqualTypeOf<ResolvedRegister['AddressType']>()
+    expectTypeOf(contract[functionNameA])
+      .parameter(1)
+      .toEqualTypeOf<ResolvedRegister['AddressType']>()
+    expectTypeOf(contract[functionNameA])
+      .parameter(2)
+      .toEqualTypeOf<ResolvedRegister['BigIntType']>()
+    expectTypeOf(contract[functionNameA])
+      .parameter(3)
+      .toEqualTypeOf<
+        (Overrides & { from?: `0x${string}` | undefined }) | undefined
+      >()
+    expectTypeOf(
+      contract[functionNameA],
+    ).returns.resolves.toEqualTypeOf<ContractTransaction>()
+
+    const functionNameB = 'safeTransferFrom(address,address,uint256,bytes)'
+    expectTypeOf(contract[functionNameB]).toBeCallableWith(
+      '0x…',
+      '0x…',
+      BigInt('123'),
+      '0x…',
+      { from: '0x…' },
+    )
+    expectTypeOf(contract[functionNameB])
+      .parameter(0)
+      .toEqualTypeOf<ResolvedRegister['AddressType']>()
+    expectTypeOf(contract[functionNameB])
+      .parameter(1)
+      .toEqualTypeOf<ResolvedRegister['AddressType']>()
+    expectTypeOf(contract[functionNameB])
+      .parameter(2)
+      .toEqualTypeOf<ResolvedRegister['BigIntType']>()
+    expectTypeOf(contract[functionNameB])
+      .parameter(3)
+      .toEqualTypeOf<ResolvedRegister['BytesType']['inputs']>()
+    expectTypeOf(contract[functionNameB])
+      .parameter(4)
+      .toEqualTypeOf<
+        (Overrides & { from?: `0x${string}` | undefined }) | undefined
+      >()
+    expectTypeOf(
+      contract[functionNameB],
+    ).returns.resolves.toEqualTypeOf<ContractTransaction>()
+  })
+
+  // Events
+  contract.on('Transfer', (from, to, value, event) => {
+    assertType<ResolvedRegister['AddressType']>(from)
+    assertType<ResolvedRegister['AddressType']>(to)
+    assertType<ResolvedRegister['BigIntType']>(value)
+    assertType<
+      Event<ExtractAbiEvent<typeof wagmiMintExampleAbi, 'Transfer'>>
+    >(event)
+  })
+})