API ideas

api_ideas.txt

Proposing this structure for getters and senders.

export interface Pong {
  response: string;
}

export class Ping<TBigNumber> {
  public static PingParams = t.type({});
  public statuf PongParams = t.type({ respopnse: t.string });

  @Getter()
  public static async pingGetter<TBigNumber>(db: DB<TBigNumber>, params: t.TypeOf<typeof Ping.PingParams>): Promise<Pong> {
    return {
      response: "pong",
    };
  }
  
  @Sender()
  public static async pingSender<TBigNumber>(provider: AugurProvider, params: t.TypeOf<typeof Ping.PingParams>): Promise<Pong> {
    return Ping.PongParams.decode(provider.send(params.encode());
  }
}

The provider is responsible for the following operations:

{ subscribe, unsubscribe, send, connect, disconnect }
 
Event handlers can have a similar format
 
export PING_EVENT = "ping";

export class Ping<TBigNumber> {
  public static PongParams = t.type({ response: t.string });

  @HandleEvent()
  public static async ping<TBigNumber>(params: any): Promise<Pong> {
    return Ping.PongParams.decode(params);
  }
}

A couple questions/thougths.

1. What does a getter/sender decorator do in this context?
2. Should we think of a term to use other than "provider"?

1. The Getter adds the method and the method's name (as the json-rpc method) to a map in API. It also ads the params type to the map so that the params can be type checked at runtime. When a json-rpc request comes in it looks up the getter in the map by the request name and routes it to that getter while converting the params to the right type.
2. The @sender decorator would work like

const foo: returnType = API.send(PING_REQUEST, params_type);

API would look up the sender in a map in API and route it. When it gets routed the correct provider gets passed to the sender.

1. Happy to use as different term other than provider. Connector?

Would be nice to make sending not need to know the actual API call name...def possible but have to think about it.

This format looks fine to me. Personally, I like Connector or Connection better than Provider. I can't really think of any other better names at the moment.

What does the caller look like? What are the imports needed? Is each getter encapsulated with request, response and getter?

something like

const connector = new AugurConnector(...)

const ping = new Ping();
const param = new ping.pingParam()
const response: ping.PongParams = ping.Sender(connector, param);

I think the invocation will be more like

const response = API.send(Ping.PING_REQ, new Ping.PingParams({...});