docs: up

package.json

@@ -15,7 +15,8 @@
     "deps": "pnpx taze -r",
     "dev": "pnpm preconstruct && pnpm playground",
     "docs:dev": "pnpm --filter site dev",
-    "docs:gen": "pnpm api-extractor run -c scripts/docgen/api-extractor.json && tsx scripts/docgen/build.ts",
+    "docs:extract": "pnpm api-extractor run -c scripts/docgen/api-extractor.json && tsx scripts/docgen/build.ts",
+    "docs:gen": "pnpm clean && pnpm build:esm && pnpm docs:extract",
     "docs:build": "pnpm docs:gen && pnpm --filter site build",
     "knip": "knip --production",
     "format": "biome format --write",

scripts/docgen/utils/renderApiFunction.ts

@@ -97,9 +97,9 @@ ${content}
       : `
 ## Return Type
 
-\`${returnType.type}\`
-
 ${comment?.returns}
+
+\`${returnType.type}\`
 `
 
   const errorTypeId = `${item.canonicalReference.split(':')[0]}.ErrorType:type`

src/Abi.ts

@@ -32,3 +32,6 @@ export { Abi_getSelector as getSelector } from './internal/abi/getSelector.js'
 export { Abi_getSignature as getSignature } from './internal/abi/getSignature.js'
 
 export { Abi_getSignatureHash as getSignatureHash } from './internal/abi/getSignatureHash.js'
+
+// TODO: Bring into Ox
+export { parseAbiParameters as parseParameters } from 'abitype'

src/internal/abi/decodeParameters.ts

@@ -30,27 +30,32 @@ import {
  * Decodes ABI-encoded data into its respective primitive values based on ABI Parameters.
  *
  * @example
- * ```ts
+ * ```ts twoslash
  * import { Abi } from 'ox'
  *
- * const values = Abi.decodeParameters(
+ * Abi.decodeParameters(
  *   ['string', 'uint', 'bool'],
- *   '0x000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001a4000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000057761676d69000000000000000000000000000000000000000000000000000000'
+ *   '0x000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001a4000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000057761676d69000000000000000000000000000000000000000000000000000000',
  * )
  * // ['wagmi', 420n, true]
  * ```
  *
- * You can also pass in Human Readable parameters with the `Abi.parseParameters` utility.
+ * You can also pass in Human Readable parameters with the {@link Abi#parseParameters} utility.
  *
  * @example
- * ```ts
+ * ```ts twoslash
  * import { Abi } from 'ox'
  *
- * const values = Abi.decodeParameters(
+ * Abi.decodeParameters(
  *   Abi.parseParameters('string x, uint y, bool z'),
- *   '0x000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001a4000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000057761676d69000000000000000000000000000000000000000000000000000000'
+ *   '0x000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001a4000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000057761676d69000000000000000000000000000000000000000000000000000000',
  * )
+ * // ['wagmi', 420n, true]
  * ```
+ *
+ * @param parameters - The set of ABI parameters to decode, in the shape of the `inputs` or `outputs` attribute of an ABI Item. These parameters must include valid [ABI types](https://docs.soliditylang.org/en/latest/types.html).
+ * @param data - ABI encoded data.
+ * @returns Array of decoded values.
  */
 export function Abi_decodeParameters<
   const parameters extends readonly IsomorphicAbiParameter[],

src/internal/abi/encodePacked.ts

@@ -27,37 +27,23 @@ import {
   InvalidAbiTypeError,
 } from './errors.js'
 
-/** @internal */
-export type PackedAbiType =
-  | SolidityAddress
-  | SolidityBool
-  | SolidityBytes
-  | SolidityInt
-  | SolidityString
-  | SolidityArrayWithoutTuple
-
-/** @internal */
-export type EncodePackedValues<
-  packedAbiTypes extends readonly PackedAbiType[] | readonly unknown[],
-> = {
-  [K in keyof packedAbiTypes]: packedAbiTypes[K] extends AbiType
-    ? AbiParameterToPrimitiveType<{ type: packedAbiTypes[K] }>
-    : unknown
-}
-
 /**
  * Encodes an array of primitive values to a [packed ABI encoding](https://docs.soliditylang.org/en/latest/abi-spec.html#non-standard-packed-mode).
  *
  * @example
- * ```ts
- * import { Abi } from 'viem'
+ * ```ts twoslash
+ * import { Abi } from 'ox'
  *
  * const encoded = Abi.encodePacked(
  *   ['address', 'string'],
  *   ['0xd8da6bf26964af9d7eed9e03e53415d37aa96045', 'hello world'],
  * )
  * // '0xd8da6bf26964af9d7eed9e03e53415d37aa9604568656c6c6f20776f726c64'
  * ```
+ *
+ * @param types - Set of ABI types to pack encode.
+ * @param values - The set of primitive values that correspond to the ABI types defined in `types`.
+ * @returns The encoded packed data.
  */
 export function Abi_encodePacked<
   const packedAbiTypes extends readonly PackedAbiType[] | readonly unknown[],
@@ -88,6 +74,24 @@ export declare namespace Abi_encodePacked {
 Abi_encodePacked.parseError = (error: unknown) =>
   error as Abi_encodePacked.ErrorType
 
+/** @internal */
+export type PackedAbiType =
+  | SolidityAddress
+  | SolidityBool
+  | SolidityBytes
+  | SolidityInt
+  | SolidityString
+  | SolidityArrayWithoutTuple
+
+/** @internal */
+export type EncodePackedValues<
+  packedAbiTypes extends readonly PackedAbiType[] | readonly unknown[],
+> = {
+  [key in keyof packedAbiTypes]: packedAbiTypes[key] extends AbiType
+    ? AbiParameterToPrimitiveType<{ type: packedAbiTypes[key] }>
+    : unknown
+}
+
 //////////////////////////////////////////////////////////////////////////////
 // Internal
 //////////////////////////////////////////////////////////////////////////////

src/internal/abi/encodeParameters.ts

@@ -26,47 +26,50 @@ import {
   InvalidAbiTypeError,
 } from './errors.js'
 
-// TODO: These types should be in abitype?
-/** @internal */
-export type IsomorphicAbiParameter = AbiParameter | AbiType | (string & {})
-
-/** @internal */
-export type IsomorphicAbiParametersToPrimitiveTypes<
-  types extends readonly IsomorphicAbiParameter[],
-> = Compute<{
-  [key in keyof types]: types[key] extends AbiParameter
-    ? AbiParameterToPrimitiveType<types[key]>
-    : types[key] extends AbiType
-      ? AbiParameterToPrimitiveType<{ type: types[key] }>
-      : types[key] extends string | readonly string[] | readonly unknown[]
-        ? AbiParameterToPrimitiveType<ParseAbiParameter<types[key]>>
-        : never
-}>
-
 /**
  * Encodes primitive values into ABI encoded data as per the [Application Binary Interface (ABI) Specification](https://docs.soliditylang.org/en/latest/abi-spec).
  *
  * @example
- * ```ts
+ * ```ts twoslash
  * import { Abi } from 'ox'
  *
  * const data = Abi.encodeParameters(
  *   ['string', 'uint', 'bool'],
- *   ['wagmi', 420n, true]
+ *   ['wagmi', 420n, true],
  * )
  * ```
  *
- * You can also pass in Human Readable parameters with the `Abi.parseParameters` utility.
+ * @example
+ * Specify structured ABI Parameters as schema:
+ *
+ * ```ts twoslash
+ * import { Abi } from 'ox'
+ *
+ * const data = Abi.encodeParameters(
+ *   [
+ *     { type: 'string', name: 'name' },
+ *     { type: 'uint', name: 'age' },
+ *     { type: 'bool', name: 'isOwner' },
+ *   ],
+ *   ['wagmi', 420n, true],
+ * )
+ * ```
  *
  * @example
- * ```ts
+ * You can also pass in Human Readable parameters with the {@link Abi#parseParameters} utility.
+ *
+ * ```ts twoslash
  * import { Abi } from 'ox'
  *
  * const data = Abi.encodeParameters(
  *   Abi.parseParameters('string x, uint y, bool z'),
- *   ['wagmi', 420n, true]
+ *   ['wagmi', 420n, true],
  * )
  * ```
+ *
+ * @param parameters - The set of ABI parameters to encode, in the shape of the `inputs` or `outputs` attribute of an ABI Item. These parameters must include valid [ABI types](https://docs.soliditylang.org/en/latest/types.html).
+ * @param values - The set of primitive values that correspond to the ABI types defined in `parameters`.
+ * @returns ABI encoded data.
  */
 export function Abi_encodeParameters<
   const parameters extends
@@ -77,7 +80,7 @@ export function Abi_encodeParameters<
   values: parameters extends readonly IsomorphicAbiParameter[]
     ? IsomorphicAbiParametersToPrimitiveTypes<parameters>
     : never,
-): Abi_encodeParameters.ReturnType {
+): Hex {
   if (parameters.length !== values.length)
     throw new AbiEncodingLengthMismatchError({
       expectedLength: parameters.length as number,
@@ -94,8 +97,6 @@ export function Abi_encodeParameters<
 }
 
 export declare namespace Abi_encodeParameters {
-  type ReturnType = Hex
-
   type ErrorType =
     | AbiEncodingLengthMismatchError
     | encode.ErrorType
@@ -107,6 +108,23 @@ Abi_encodeParameters.parseError = (error: unknown) =>
   /* v8 ignore next */
   error as Abi_encodeParameters.ErrorType
 
+// TODO: These types should be in abitype?
+/** @internal */
+export type IsomorphicAbiParameter = AbiParameter | AbiType | (string & {})
+
+/** @internal */
+export type IsomorphicAbiParametersToPrimitiveTypes<
+  types extends readonly IsomorphicAbiParameter[],
+> = Compute<{
+  [key in keyof types]: types[key] extends AbiParameter
+    ? AbiParameterToPrimitiveType<types[key]>
+    : types[key] extends AbiType
+      ? AbiParameterToPrimitiveType<{ type: types[key] }>
+      : types[key] extends string | readonly string[] | readonly unknown[]
+        ? AbiParameterToPrimitiveType<ParseAbiParameter<types[key]>>
+        : never
+}>
+
 /////////////////////////////////////////////////////////////////////////////////
 // Utilities
 /////////////////////////////////////////////////////////////////////////////////

src/internal/abi/extractItem.ts

@@ -24,8 +24,7 @@ import type {
  * ```ts
  * import { Abi } from 'ox'
  *
- * const abiItem = Abi.extractItem(abi, { name: 'y' })
- *
+ * Abi.extractItem(abi, { name: 'y' })
  * // {
  * //   name: 'y',
  * //   type: 'event',
@@ -34,6 +33,10 @@ import type {
  * //   stateMutability: 'view'
  * // }
  * ```
+ *
+ * @param abi - The contract's ABI.
+ * @param options - The extraction options.
+ * @returns The ABI item.
  */
 export function Abi_extractItem<
   const abi extends Abi | readonly unknown[],

src/internal/abi/getSelector.ts

@@ -3,20 +3,23 @@ import type { AbiFunction } from 'abitype'
 import type { GlobalErrorType } from '../errors/error.js'
 import { Hex_slice } from '../hex/slice.js'
 import { Abi_getSignatureHash } from './getSignatureHash.js'
+import type { Hex } from '../hex/types.js'
 
 /**
  * Computes the selector for an ABI Item.
  *
  * @example
  * ```ts twoslash
  * import { Abi } from 'ox'
+ *
  * const selector = Abi.getSelector('function ownerOf(uint256 tokenId)')
  * // '0x6352211e'
  * ```
  *
  * @example
  * ```ts twoslash
  * import { Abi } from 'ox'
+ *
  * const selector = Abi.getSelector({
  *   inputs: [{ type: 'uint256' }],
  *   name: 'ownerOf',
@@ -26,13 +29,15 @@ import { Abi_getSignatureHash } from './getSignatureHash.js'
  * })
  * // '0x6352211e'
  * ```
+ *
+ * @param abiItem - The ABI item to compute the selector for. Can be a signature or an ABI item for an error, event, function, etc.
+ * @returns The first 4 bytes of the {@link Hash#keccak256} hash of the function signature.
  */
-export const Abi_getSelector = (abiItem: string | AbiFunction) =>
-  Hex_slice(Abi_getSignatureHash(abiItem), 0, 4)
+export function Abi_getSelector(abiItem: string | AbiFunction): Hex {
+  return Hex_slice(Abi_getSignatureHash(abiItem), 0, 4)
+}
 
 export declare namespace Abi_getSelector {
-  type Parameters = Abi_getSignatureHash.Parameters
-
   type ErrorType =
     | Abi_getSignatureHash.ErrorType
     | Hex_slice.ErrorType

src/internal/abi/getSignature.ts

@@ -8,13 +8,15 @@ import type { GlobalErrorType } from '../errors/error.js'
  * @example
  * ```ts twoslash
  * import { Abi } from 'ox'
+ *
  * const signature = Abi.getSignature('function ownerOf(uint256 tokenId)')
  * // 'ownerOf(uint256)'
  * ```
  *
  * @example
  * ```ts twoslash
  * import { Abi } from 'ox'
+ *
  * const signature = Abi.getSignature({
  *   name: 'ownerOf',
  *   type: 'function',
@@ -24,8 +26,11 @@ import type { GlobalErrorType } from '../errors/error.js'
  * })
  * // 'ownerOf(uint256)'
  * ```
+ *
+ * @param abiItem - The ABI Item to compute the signature for.
+ * @returns The stringified signature of the ABI Item.
  */
-export const Abi_getSignature = (abiItem: Abi_getSignature.Parameters) => {
+export function Abi_getSignature(abiItem: string | Abi[number]): string {
   const signature = (() => {
     if (typeof abiItem === 'string') return abiItem
     return formatAbiItem(abiItem)
@@ -34,8 +39,6 @@ export const Abi_getSignature = (abiItem: Abi_getSignature.Parameters) => {
 }
 
 export declare namespace Abi_getSignature {
-  type Parameters = string | Abi[number]
-
   type ErrorType = normalizeSignature.ErrorType | GlobalErrorType
 }