Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@connectrpc/protoc-gen-connect-query

Package Overview
Dependencies
Maintainers
7
Versions
28
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@connectrpc/protoc-gen-connect-query

Code generator for connect-query

  • 1.0.0-rc.2
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
12K
increased by56.31%
Maintainers
7
Weekly downloads
 
Created
Source

@connectrpc/protoc-gen-connect-query

The code generator for Connect-Query, a expansion pack for TanStack Query (react-query), that enables effortless communication with servers that speak the Connect Protocol.

Learn more about Connect-Query at github.com/connectrpc/connect-query-es.

Installation

protoc-gen-connect-query is a code generator plugin for Protocol Buffer compilers like buf and protoc. It generates clients from your Protocol Buffer schema, and works in tandem with @bufbuild/protoc-gen-es, the code generator plugin for all Protocol Buffer base types. The code those two plugins generate requires the runtime libraries @connectrpc/connect-query, and @bufbuild/protobuf.

To install the plugins and their runtime libraries, run:

npm install --save-dev @connectrpc/protoc-gen-connect-query @bufbuild/protoc-gen-es
npm install @connectrpc/connect-query @bufbuild/protobuf

We use peer dependencies to ensure that code generator and runtime library are compatible with each other. Note that yarn and pnpm only emit a warning in this case.

Generating Code

example.proto

For these examples, consider the following example proto file example.proto:

syntax = "proto3";

package example.v1;

message Nothing {}

message Todo {
  string id = 1;
  string name = 2;
  bool completed = 3;
}

message Todos {
  repeated Todo todos = 1;
}

service TodoService {
  rpc GetTodos(Nothing) returns (Todos);
  rpc AddTodo(Todo) returns (Nothing);
}

This file creates an RPC service with the following:

  • GetTodos takes no inputs and returns an array of Todos.
  • AddTodo adds a new Todo and returns nothing.

buf.gen.yaml

Add a new configuration file buf.gen.yaml

version: v1
plugins:
  # This will invoke protoc-gen-es and write output to src/gen
  - name: es
    out: src/gen
    opt: target=ts
    # This will invoke protoc-gen-connect-query
  - name: connect-query
    out: src/gen
    opt: target=ts

With the buf CLI

To use the buf CLI to generate code for all protobuf files within your project, simply run:

npx @bufbuild/buf generate

Note that buf can generate from various inputs, not just local protobuf files. For example, npm run generate buf.build/connectrpc/eliza generates code for the module connectrpc/eliza on the Buf Schema Registry.

With protoc

PATH=$PATH:$(pwd)/node_modules/.bin \
  protoc -I . \
  --es_out src/gen \
  --es_opt target=ts \
  --connect-query_out src/gen \
  --connect-query_opt target=ts \
  example.proto

Note that we are adding node_modules/.bin to the $PATH, so that the protocol buffer compiler can find them. This happens automatically with npm scripts.

Note: Since yarn v2 and above does not use a node_modules directory, you need to change the variable a bit:

PATH=$(dirname $(yarn bin protoc-gen-es)):$(dirname $(yarn bin protoc-gen-connect-es)):$PATH

With Node

Add a line to the scripts section of your package.json to run buf generate.

"scripts": {
    ...
    "buf:generate": "npx @bufbuild/buf generate example.proto"
},

Finally, tell Buf to generate code by running your command:

npm run buf:generate

Now you should see your generated code:

.
└── gen/
    ├── example_pb.ts
    └── example-TodoService_connectquery.ts

Generated Output

Connect-Query will create one output file for every service in every protofile. Say you have the following file structure:

.
└── proto/
    ├── pizza.proto
    └── curry.proto

Where pizza.proto contains DetroitStyleService and ChicagoStyleService, and where curry.proto contains VindalooService. Your generated output will look like this:

.
└── gen/
    ├── pizza_pb.ts
    ├── pizza-DetroitStyleService_connectquery.ts
    ├── pizza-ChicagoStyleService_connectquery.ts
    ├── curry_pb.ts
    └── curry-VindalooService_connectquery.ts

The reason each service gets a separate file is to facilitate intellisense and language server protocol imports. Notice that one file per input proto is generated by protoc-gen-es (pizza_pb.ts and curry_pb.ts), and that one file per service is created by protoc-gen-connect-query (making up the remainder). The Protobuf-ES generated files (*_pb.ts) are important because those files are referenced from the *_connectquery.ts files.

Plugin options

target

This option controls whether the plugin generates JavaScript, TypeScript, or TypeScript declaration files.

Say, for example, you used example.proto:

TargetGenerated output
target=jsexample-TodoService_connectquery.js
target=tsexample-TodoService_connectquery.ts
target=dtsexample-TodoService_connectquery.d.ts

Multiple values can be given by separating them with +, for example target=js+dts.

By default, we generate JavaScript and TypeScript declaration files, which produces the smallest code size and is the most compatible with various bundler configurations. If you prefer to generate TypeScript, use target=ts.

import_extension=.js

By default, protoc-gen-connect-query (and all other plugins based on @bufbuild/protoplugin) uses a .js file extensions in import paths, even in TypeScript files.

This is unintuitive, but necessary for ECMAScript modules in Node.js.

Unfortunately, not all bundlers and tools have caught up yet, and Deno requires .ts. With this plugin option, you can replace .js extensions in import paths with the given value. For example, set

  • import_extension=none to remove the .js extension
  • import_extension=.ts to replace the .js extension with .ts

keep_empty_files=true

This option exists for other plugins but is not applicable to protoc-gen-connect-query because, unlike most other plugins, it does not generate a maximum of one output file for every input proto file. Instead, it generates one output file per service. If you provide a valid proto file that contains no services, protoc-gen-connect-query will have no output.

Example Generated Code

See eliza.proto for example inputs, and look here to see the outputs those files generate.

FAQs

Package last updated on 07 Dec 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc