Proposal: alternative interface that's more aligned with current idioms

[dpup]

Background

Currently the generated functions are exposed as static methods on a class. For example:

export class AccountService {
  static CreateAccount(
    this: void,
    req: CreateAccountRequest,
    initReq?: fm.InitReq,
  ): Promise<CreateAccountResponse> {
    return fm.fetchRequest<CreateAccountResponse>(`/api/accounts`, {
      ...initReq,
      method: 'POST',
      body: JSON.stringify(req, fm.replacer),
    });
  }
}

I don't know the original intent of this pattern, but you lose any benefits of having a Service instance that tracks state and you get typescript that's not very idiomatic.

import { AccountService } from './accounts.pb';

const resp = AccountService.CreateAccount(newAccount, {
  pathPrefix: API_HOST,
  credentials: 'include',
  headers: {
    'X-CSRF-Protection': 1
  }
})

Proposal

Introduce a flag use_static_classes which defaults to true for now. When use_static_classes is false, you simply get an exported function that maps to the method name:

export const createAccount = (
  req: CreateAccountRequest,
  initReq?: InitReq,
): Promise<CreateAccountResponse> => {
  {
    return fm.fetchRequest<CreateAccountResponse>(`/api/accounts`, {
      ...initReq,
      method: 'POST',
      body: JSON.stringify(req, fm.replacer),
    });
  }
};

And then:

import { createAccount } from './accounts.pb';

const resp = createAccount(newAccount, {
  pathPrefix: API_HOST,
  credentials: 'include',
  headers: {
    'X-CSRF-Protection': 1
  }
})

Problem : conflicting function names

The main downside I see in this approach is that there could be ambiguous function names in the case where a single proto file contains multiple services with the same method. This seems unlikely in my experience, but a possible fix could be to generate multiple TS files.

For example: consider accounts.proto contains AccountService and AdminService, both with createAccount methods.

We could generate:

• accounts.pb.ts → all the message definitions.
• accountservice.gw.pb.ts → functions for calling AccountService gateway endpoints
• adminservice.gw.pb.ts → functions for calling AdminService gateway endpoints

Additional Variant

As well as exposing simple functions, we could also introduce a more classical Client. The client instance could be used to store request configuration:

export class AccountServiceClient {
  constructor(initReq: InitReq) {
    this.initReq = initReq;
  } 

  createAccount(
    this: void,
    req: CreateAccountRequest
  ): Promise<CreateAccountResponse> {
    return createAccount(req, this.initReq);
  }
}

[dpup]

@seanami would be curious to hear your opinions on this.

[seanami]

Nice! I like this as a way to make the code more idiomatic and also be able to have a more typical stateful client object that can preserve configuration across multiple requests.

I do use the service level class objects right now in some of my client configuration, but only to get the name of the service as a string for generating react-query cache names, and that can easily be replaced with something else.

I do highly suggest putting all of the request functions in per-service files. That will solve the potential dupe issue, and also allow those who want similar semantics as the existing implementation to do: import { * as AccountService } from ‘file’

[dpup]

Any thoughts on naming of the files? Given accounts.proto should it be accounts-accountservice.gw.ts or just accountservice.gw.ts.

[seanami]

Can service names be duplicated between separate proto files that are part of the same environment/project? E.g. Could I also have an additions.proto file in the same project which also defines an AccountService? (And if so, do the definitions get merged or what?)

If no duplicates are allowed, or the duplicates get merged into one definition, then I think just accountservice.gw.ts makes sense. Otherwise, I'd go with accounts-accountservice.gw.ts.