feat(experiment): named tuples

.changeset/fresh-jokes-guess.md

@@ -0,0 +1,5 @@
+---
+"abitype": minor
+---
+
+Added experimental named tuple support to `AbiParametersToPrimitiveTypes`

.github/workflows/verify.yml

@@ -50,7 +50,7 @@ jobs:
     timeout-minutes: 5
     strategy:
       matrix:
-        version: ['5.0.4', '5.1.6', '5.2.2', '5.3.3', '5.4.5', '5.5.2', '5.6', 'latest']
+        version: ['5.0.4', '5.2.2', '5.3.3', '5.4.5', '5.5.4', '5.6.3', '5.7.3', '5.8.3', '5.9.3', 'latest']
 
     steps:
       - name: Clone repository

docs/pages/config.md

@@ -153,6 +153,21 @@ declare module 'abitype' {
 }
 ```
 
+### `experimental_namedTuples`
+
+Enables named tuple generation in [`AbiParametersToPrimitiveTypes`](/api/utilities#abiparameterstoprimitivetypes) for common ABI parameter names.
+
+- Type `boolean`
+- Default `false`
+
+```ts twoslash
+declare module 'abitype' {
+  export interface Register {
+    experimental_namedTuples: false
+  }
+}
+```
+
 ### `strictAbiType`
 
 When set, validates `AbiParameter`'s `type` against `AbiType`.

packages/abitype/src/abi.ts

@@ -245,3 +245,156 @@ export type TypedData = Pretty<
     [_ in TypedDataType]?: never
   }
 >
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+// update lookup with `pnpm node scripts/genAbiParameterNameLookup.ts`
+// biome-ignore format: no formatting
+export interface AbiParameterTupleNameLookup<type> extends Record<string, [type]> {
+  _data: [_data: type]
+  a: [a: type]
+  account: [account: type]
+  accounts: [accounts: type]
+  address: [address: type]
+  addresses: [addresses: type]
+  admin: [admin: type]
+  allowFailure: [allowFailure: type]
+  allowed: [allowed: type]
+  amount: [amount: type]
+  approved: [approved: type]
+  approver: [approver: type]
+  ask: [ask: type]
+  asset: [asset: type]
+  assets: [assets: type]
+  authority: [authority: type]
+  available: [available: type]
+  b: [b: type]
+  balance: [balance: type]
+  bid: [bid: type]
+  buffer: [buffer: type]
+  c: [c: type]
+  call: [call: type]
+  callData: [callData: type]
+  caller: [caller: type]
+  calls: [calls: type]
+  clone: [clone: type]
+  coinType: [coinType: type]
+  count: [count: type]
+  currency: [currency: type]
+  d: [d: type]
+  data: [data: type]
+  deadline: [deadline: type]
+  decimals: [decimals: type]
+  dest: [dest: type]
+  divisor: [divisor: type]
+  dns: [dns: type]
+  dst: [dst: type]
+  e: [e: type]
+  endTime: [endTime: type]
+  ens: [ens: type]
+  errorData: [errorData: type]
+  f: [f: type]
+  failures: [failures: type]
+  from: [from: type]
+  funder: [funder: type]
+  g: [g: type]
+  gateway: [gateway: type]
+  gateways: [gateways: type]
+  guy: [guy: type]
+  h: [h: type]
+  hash: [hash: type]
+  hashes: [hashes: type]
+  i: [i: type]
+  id: [id: type]
+  ids: [ids: type]
+  idsLength: [idsLength: type]
+  implementation: [implementation: type]
+  index: [index: type]
+  interfaceId: [interfaceId: type]
+  j: [j: type]
+  k: [k: type]
+  key: [key: type]
+  l: [l: type]
+  label: [label: type]
+  length: [length: type]
+  limit: [limit: type]
+  m: [m: type]
+  market: [market: type]
+  memo: [memo: type]
+  message: [message: type]
+  n: [n: type]
+  name: [name: type]
+  needed: [needed: type]
+  new: [new: type]
+  next: [next: type]
+  nextOwner: [nextOwner: type]
+  node: [node: type]
+  nonce: [nonce: type]
+  nonceKey: [nonceKey: type]
+  numerator: [numerator: type]
+  o: [o: type]
+  offerer: [offerer: type]
+  old: [old: type]
+  operator: [operator: type]
+  order: [order: type]
+  orders: [orders: type]
+  owner: [owner: type]
+  p: [p: type]
+  policyId: [policyId: type]
+  policyType: [policyType: type]
+  previous: [previous: type]
+  previousOwner: [previousOwner: type]
+  price: [price: type]
+  primary: [primary: type]
+  proposer: [proposer: type]
+  q: [q: type]
+  queries: [queries: type]
+  quoteToken: [quoteToken: type]
+  r: [r: type]
+  receiver: [receiver: type]
+  recipient: [recipient: type]
+  refund: [refund: type]
+  required: [required: type]
+  resolvedName: [resolvedName: type]
+  resolver: [resolver: type]
+  responses: [responses: type]
+  restricted: [restricted: type]
+  returnData: [returnData: type]
+  reverseName: [reverseName: type]
+  reverseResolver: [reverseResolver: type]
+  s: [s: type]
+  secs: [secs: type]
+  selector: [selector: type]
+  sender: [sender: type]
+  shares: [shares: type]
+  signature: [signature: type]
+  signer: [signer: type]
+  source: [source: type]
+  src: [src: type]
+  startTime: [startTime: type]
+  status: [status: type]
+  success: [success: type]
+  symbol: [symbol: type]
+  t: [t: type]
+  target: [target: type]
+  timestamp: [timestamp: type]
+  to: [to: type]
+  token: [token: type]
+  tokenId: [tokenId: type]
+  ttl: [ttl: type]
+  u: [u: type]
+  updater: [updater: type]
+  user: [user: type]
+  v: [v: type]
+  value: [value: type]
+  values: [values: type]
+  valuesLength: [valuesLength: type]
+  version: [version: type]
+  w: [w: type]
+  wad: [wad: type]
+  weth: [weth: type]
+  x: [x: type]
+  y: [y: type]
+  z: [z: type]
+  zone: [zone: type]
+}

packages/abitype/src/register.ts

@@ -88,6 +88,17 @@ export type ResolvedRegister = {
       ? type
       : DefaultRegister['fixedArrayMaxLength']
 
+  /**
+   * Enables named tuple generation in {@link AbiParametersToPrimitiveTypes} for common ABI parameter names.
+   *
+   * @default false
+   */
+  experimental_namedTuples: Register extends {
+    experimental_namedTuples: infer type extends boolean
+  }
+    ? type
+    : DefaultRegister['experimental_namedTuples']
+
   /**
    * When set, validates {@link AbiParameter}'s `type` against {@link AbiType}
    *
@@ -142,6 +153,9 @@ export type DefaultRegister = {
   /** TypeScript type to use for `int<M>` and `uint<M>` values, where `M <= 48` */
   intType: number
 
+  /** Enables named tuple generation in {@link AbiParametersToPrimitiveTypes} for common ABI parameter names */
+  experimental_namedTuples: false
+
   /** When set, validates {@link AbiParameter}'s `type` against {@link AbiType} */
   strictAbiType: false
 

packages/abitype/src/utils.bench-d.ts

@@ -1,9 +1,10 @@
 import { attest } from '@arktype/attest'
 import { describe, test } from 'vitest'
-
+import type { erc20Abi } from './abis/json.js'
 import type {
   AbiParameterToPrimitiveType,
   AbiParametersToPrimitiveTypes,
+  ExtractAbiFunction,
   TypedDataToPrimitiveTypes,
 } from './utils.js'
 
@@ -225,7 +226,7 @@ test('deeply nested parameters', () => {
   attest.instantiations([11348, 'instantiations'])
   attest<
     [
-      {
+      s: {
         a: number
         b: readonly number[]
         c: readonly {
@@ -266,3 +267,53 @@ test('self-referencing', () => {
     }
   }>(res)
 })
+
+type transferFrom = ExtractAbiFunction<
+  typeof erc20Abi,
+  'transferFrom'
+>['inputs']
+test('basic without named tuple', () => {
+  const res = {} as AbiParametersToPrimitiveTypes<transferFrom, 'inputs', false>
+  attest.instantiations([906, 'instantiations'])
+  attest<
+    readonly [sender: `0x${string}`, recipient: `0x${string}`, amount: bigint]
+  >(res)
+})
+test('basic with named tuple', () => {
+  const res = {} as AbiParametersToPrimitiveTypes<transferFrom, 'inputs', true>
+  attest.instantiations([1131, 'instantiations'])
+  attest<
+    readonly [sender: `0x${string}`, recipient: `0x${string}`, amount: bigint]
+  >(res)
+})
+
+type parameters = readonly [
+  { name: 'account'; type: 'uint8' },
+  { name: 'address'; type: 'uint8' },
+  { name: 'admin'; type: 'uint8' },
+  { name: 'allowed'; type: 'uint8' },
+  { name: 'amount'; type: 'uint8' },
+  { name: 'authority'; type: 'uint8' },
+  { name: 'available'; type: 'uint8' },
+  { name: 'count'; type: 'uint8' },
+  { name: 'currency'; type: 'uint8' },
+  { name: 'deadline'; type: 'uint8' },
+  { name: 'from'; type: 'uint8' },
+  { name: 'funder'; type: 'uint8' },
+  { name: 'hash'; type: 'address' },
+  { name: 'id'; type: 'uint8' },
+  { name: 'memo'; type: 'uint8' },
+  { name: 'nonce'; type: 'uint8' },
+  { name: 'nonceKey'; type: 'uint8' },
+  { name: 'owner'; type: 'uint8' },
+  { name: 'policyId'; type: 'uint8' },
+  { name: 'policyType'; type: 'uint8' },
+]
+test('without named tuples', () => {
+  ;({}) as AbiParametersToPrimitiveTypes<parameters, 'inputs', false>
+  attest.instantiations([1276, 'instantiations'])
+})
+test('with named tuples', () => {
+  ;({}) as AbiParametersToPrimitiveTypes<parameters, 'inputs', true>
+  attest.instantiations([1998, 'instantiations'])
+})