[DRAFT] Web3API Client Type Extensions for plugins, API wrappers

[krisbitney]

It is possible to allow plugin and API developers to extend the Web3API Client interface. In doing so, developers can provide abbreviated syntax, facilitate type checking, and facilitate IDE features like type suggestions and code auto-completion (e.g. intellisense).

From the end-user perspective, this:

const tokenData = await client.query<{
  fetchTokenData: Token;
}>({
  uri: ensUri,
  query: `
    query {
      fetchTokenData(
        chainId: $chainId
        address: $address
      )
    }
  `,
  variables: {
    chainId: chainId,
    address: address,
  },
});

Would become something like this:

const tokenData = client.uniswap.fetchTokenData(chainId, address);

This is syntactic sugar. Behind the scenes, client.query() would still be called.

Plugin developers can package their plugin to use the shortened syntax by default. API developers may need to write language-specific wrappers. This feature may be specific to languages like JavaScript/TypeScript, Kotlin, and others that offer this sort of type extension without the need for class extension/inheritance. Plugin and API developers could also use this approach to bundle custom redirects or other configuration.

This idea comes from Hardhat, which allows Hardhat plugin developers to extend their HardhatRuntimeEnvironment type. The TypeScript syntax to extend the type for the hardhat plugin I've been (slowly) working on looks something like this abridged code snippet:

declare module "hardhat/types/runtime" {
  export interface HardhatRuntimeEnvironment {
    web3api: {
      providers: {
        ipfs: string;
      };
      myFunction(arg1: string, arg2: number) => Promise<{ result: string; }>
    };
  }
}

Once that is done, features like type suggestions work immediately in my IDE.

Harhdat provides a hook that Hardhat plugin developers can use to assign values to the new properties. The hook runs when the HardhatRuntimeEnvironment object is instantiated:

extendEnvironment((hre) => {
  hre.web3api = {
    providers: {
      ipfs: "myProvider",
    },
    myFunction: async (arg1: string, arg2: number) => { return "result"; };
  };
});

Now I just import my hardhat plugin in my hardhat config file, and I can then call myFunction in other files like so:

import * as hre from "hardhat";
const result = hre.myFunction("arg1", 2);

Hardhat links:
Simple example on GitHub used for Plugin Developer boilerplate (analogous to our web3api templates)
Building Hardhat plugins
Extending the Hardhat Runtime Environment

[dOrgJelli]

This sounds amazing! I could definitely see "Web3API Extensions" fitting nicely alongside WASM Web3APIs and Web3API plugins.

The process of defining a Web3API Extension may look something like this:

1. Define a "constructor" function that takes all initialization values.
2. Define any required redirects, plugins, or env variables that should be added to the Web3ApiClient.
3. Create as many query functions as you need.

The user experience could look something like:

import { Web3ApiClient } from "@web3api/client-js"
import { uniswapExtension } from "uniswap-web3api-ext"

const client = new Web3ApiClient({
  extensions: [
    uniswapExtension("some config value")
  ]
});

const { data, errors } = await client.uniswap.swap({
  from: "ETH",
  to: "DAI",
  amount: 500
}).execute();

// additionally, I think it'd be important to support the `useWeb3ApiQuery` hook
// as well maybe something like this:
const { data, errors, execute, loading } = useWeb3ApiQuery(
  client.uniswap.swap({
    from: "ETH",
    to: "DAI",
    amount: 500
  }).config()
);

To ensure the above is typesafe and intellisense picks up on everything may be difficult.

[krisbitney]

The extensions should be automatically generated by a codegen template. It would presumably depend on PR #494.

[dOrgJelli]

Migrating the discussion of this issue to #729