Plugin output scheme

[paul-sachs]

Less an issue and more of a discussion point. I've noticed the scheme for our generated file structure looks like:

import {
  deleteOrganizationByName,
  listOrganizations,
} from "@bufbuild/apigen/buf/alpha/registry/v1alpha1/organization-OrganizationService_connectquery";

I love that we can just import the specific methods we use, which can reduce bundle size, but I wonder about the scheme of {service}-{serviceName}_connectquery. Since this is effectively an api surface, maybe it makes sense to instead do:

import {
  deleteOrganizationByName,
  listOrganizations,
} from "@bufbuild/apigen/buf/alpha/registry/v1alpha1/organization_connectquery/organization_service";

This way we can stay consistent with our existing plugins which generate one file/folder for each protofile. And we can just nest the multiple services inside.

[timostamm]

We're looking at buf/alpha/registry/v1alpha1/organization.proto, right?

The current scheme is: {protoFileName}-{serviceName}_connectquery.

• protoFileName: path and name of the Protobuf source file, minus the .proto extension.
• serviceName: unqualified name of the service, escaped for safe identifiers and object properties.

With the plugin option target=ts, this generates the file:
buf/alpha/registry/v1alpha1/organization-OrganizationService_connectquery.ts.

The proposed scheme is: {protoFileName}_connectquery/{serviceNameSnakeCase}. It generates:
buf/alpha/registry/v1alpha1/organization_connectquery/organization_service.ts

This way we can stay consistent with our existing plugins which generate one file/folder for each protofile.

Typically, plugins generate one file per Protobuf input file. Generating multiple output files from one input file can be problematic because names cannot be predicted for bazel. We decided to prefer short import symbol names over support for bazel. The new scheme doesn't seem to change anything in this regard, but if it improves DX with more legible file paths, it can still be a worthwhile change.

IMO lower_snake_case is a better fit for file names. I wonder:

• How are we going to compute the lower_snake_case and avoid conflicting file names?
• Is this improvement worth the breaking change?
• How will this affect migration to v2? Ideally, common use cases would be migrated with connect-migrate.

[paul-sachs]

@timostamm All fair questions. I'm not convinced that the slightly simpler structure is worth a great deal of additional breaking changes. With the incoming v2, it also might be relatively moot anyways, since connect-query APIs will be compatible with generated code from connect so we might not even need anything special.

[timostamm]

Do you mean that the plugin becomes less important because it will be possible to use @bufbuild/protoc-gen-es generated descriptors? For example:

import { ElizaService } from "./gen/eliza_pb.ts";
useQuery(ElizaService.method.say);

And that it therefore may not be worth it to put much effort into it?

I think we should either remove the plugin or continue to improve it. But I'd be fine with waiting for user feedback regarding the new option to reference descriptors, and postpone the decision for after v2.