protoc-gen-ts

    0.8.1 • Public • Published

    Protoc Gen Typescript

    test npm npm

    Aim of this protoc plugin is to make usage of protocol buffers easy in Javascript/Typescript by taking modern approaches. This plugin generates plain Typescript files that can be used AMD, UMD, CommonJS module systems.

    Example

    syntax = "proto3";
    
    message Author {
        string name = 1;
        string role = 2;
    }
    
    message Change {
        Kind kind = 1;
        string patch = 2;
        repeated string tags = 3; 
        oneof name_or_id {
            string name = 4;
            string id = 5;
        }
        Author author = 6;
    }
    
    enum Kind {
        UPDATED = 0;
        DELETED = 1;
    }
    // Constructed message
    const change = new Change({
        kind: Kind.UPDATED,
        patch: "@@ -7,11 +7,15 @@",
        tags: ["no prefix", "as is"],
        name: "patch for typescript 4.5",
        author: new Author({
            name: "mary poppins",
            role: "maintainer"
        })
    });
    
    // Sent over the wire
    const bytes: Uint8Array = change.serialize();
    
    const receivedChange: Change = Change.deserialize(bytes);
    
    console.log(receivedChange.kind == Kind.UPDATED) // true
    console.log(receivedChange.patch) // "@@ -7,11 +7,15 @@"
    console.log(receivedChange.tags) // ["no prefix", "as is"]
    console.log(receivedChange.name) // "patch for typescript 4.5"
    // see which one of the fields were filled
    console.log(receivedChange.name_or_id) // "name"
    console.log(receivedChange.author.name) // "mary poppins"

    Support for Message.fromObject and Message.toObject

    When mapping raw json data to message classes, dealing with nested structures can be rather annoying. To overcome this problem, every generated message class has a static method called fromObject and toObject which can handle the mapping bidirectionally for you, even with the deeply structured messages. since it is aware of the field graph, it does not rely on any runtime type information thus we get the chance to keep it fast.

    One can write code as;

    const change = Change.fromObject({
        kind: Kind.UPDATED,
        patch: "@@ -7,11 +7,15 @@",
        tags: ["no prefix", "as is"],
        name: "patch for typescript 4.5",
        author: {
            name: "mary poppins",
            role: "maintainer"
        }
    });
    
    console.log(change.author instanceof Author) // true

    Usage with @grpc/grpc-js or grpc

    There is a seperate documentation for the usage of protoc-gen-ts along with either @grpc/grpc-js or grpc. By default this generated gRPC interfaces will use @grpc/grpc-js.

    Checkout rpcs.

    Key Differences

    This protoc plugin does generate;

    • Fields as getter setters.
    • No such prefixes as "getField" or "getFieldList". If you have repeated field named users, then the generated message class will have a getter named users not getUsersList
    • Enums as enums.
    • Messages within a namespace if the proto has a package directive.

    Usage

    Without Bazel

    npm install -g protoc-gen-ts
    
    protoc -I=sourcedir --ts_out=dist myproto.proto

    With Bazel

    # Add protoc-gen-ts to dependencies section of your package.json file.
    # Then use it like you would use the other bazel compatible npm packages.
    
    load("@npm//protoc-gen-ts//:index.bzl", "ts_proto_library")
    
    ts_proto_library(
        name = "protos",
        deps = [
            ":some_proto_library_target"
        ]
    )
    
    # Checkout the examples/bazel directory for an example.

    Supported Options

    • With --ts_opt=unary_rpc_promise=true, the service definition will contain a promise based rpc with a calling pattern of const result = await client.METHOD(message). Note: all othe metadata and options parameters are still available to you.

    • With --ts_opt=grpc_package=xxxx, you can specify a different package to import rather than @grpc/grpc-js.

    Roadmap

    • Support for repeated non-integer fields
    • Generate appropriate service code that is usable with node grpc package.
    • Support for creating protocol buffer messages directly from their constructors with an object.
    • Support for import directive.
    • Support for Promise in rpcs.
    • Make services strongly typed.
    • Support oneof fields
    • Support map<TYPE, TYPE> types as ES Map.
    • Support grpc-web without any manual intervention.
    • Interopability with well knowns.

    Alternatives

    Plugin google-protobuf Typescript Declarations gRPC Node gRPC Web ES6 Support Notes
    thesayyn/protoc-gen-ts Yes Yes Yes Yes Partial Yes The generated messages are compatible with ever-green browsers.
    However, you might need to use third-party packages to use rpcs.
    improbable-eng/ts-protoc-gen Yes No Yes No Yes Partial Drawback: You can't bundle generated files with rollup since
    they are not >= ES6 compatible.
    stephenh/ts-proto No Yes Yes No No Yes There is no support for rpcs.
    See: https://github.com/stephenh/ts-proto/issues/2

    Development

    Generates appropriate Protocol Buffer sources from Proto files directly through TypeScript Compiler API.

    # to run test invoke
    yarn test
    # additionally if you want to see error details
    yarn test --test_output=errors
    

    Contributors

    GitHub Contributors Image

    Support

    If you find this plugin useful please consider giving us a star to get into open collective.

    You can also support me directly by buying us some coffees.

    Keywords

    none

    Install

    npm i protoc-gen-ts

    DownloadsWeekly Downloads

    13,659

    Version

    0.8.1

    License

    MIT

    Unpacked Size

    297 kB

    Total Files

    13

    Last publish

    Collaborators

    • thesayyn