`typia.protobuf.message` — emit a `.proto` schema from a TypeScript type

If you only encode and decode within TypeScript, you don’t need this — the encode and decode functions analyze your type internally and produce a wire-compatible binary form.

typia.protobuf.message<T>() is for the other case: when you need to share the schema with a service written in another language (Go, Python, …). It returns the .proto text that any Protocol Buffer compiler can consume.

signature


namespace protobuf {
  function message<T>(): string;  // returns .proto schema text
}

First example

hello-message.ts


import typia, { tags } from "typia";
 
interface User {
  id: string;
  age: number & tags.Type<"uint32">;
  hobbies: string[];
}
 
const proto: string = typia.protobuf.message<User>();
console.log(proto);
//
// syntax = "proto3";
// message User {
//   required string id = 1;
//   required uint32 age = 2;
//   repeated string hobbies = 3;
// }

TypeScript Source

examples/src/protobuf/message.ts


import typia, { tags } from "typia";
 
typia.protobuf.message<IMember>();
 
interface IMember {
  id:
    | (string & tags.Sequence<11>)
    | (number & tags.Type<"uint64"> & tags.Sequence<12>)
    | (Uint8Array & tags.Sequence<13>);
  name: (string & tags.Sequence<20>) | null;
  children: Array<IMember> & tags.Sequence<30>;
  keywords: Map<string, string> & tags.Sequence<40>;
  thumbnail:
    | (string & tags.Format<"uri"> & tags.ContentMediaType<"image/*">)
    | Uint8Array;
  email: string & tags.Format<"email">;
  hobbies: Array<IHobby>;
}
interface IHobby {
  id: string & tags.Format<"uuid">;
  name: string;
  valid: boolean;
}

Wire types

Protocol Buffer has narrower numeric types than TypeScript (int32, uint32, int64, uint64, float, double). Use type tags to pick the wire type explicitly:


type Score = number & tags.Type<"float">;
type Population = bigint & tags.Type<"uint64">;
type Mixed = (number & tags.Type<"int32">) | (bigint & tags.Type<"uint64">);

If you don’t tag a number, typia treats it as double. If you don’t tag a bigint, typia treats it as int64.

The TypeScript compiler will block invalid combinations — you can’t put tags.Type<"uint32"> on a bigint, for example.

TypeScript Source

examples/src/protobuf/message-type-tag.ts


import typia, { tags } from "typia";
 
interface TypeTagExample {
  // ATOMIC TYPES
  int32: number & tags.Type<"int32">;
  uint32: number & tags.Type<"uint32">;
  uint64: bigint & tags.Type<"uint64">;
  int64: number & tags.Type<"int64">;
  float: number & tags.Type<"float">;
  double: number | undefined;
  string: string | null;
 
  // UNION TYPES
  uint32_or_double: number & (tags.Type<"uint32"> | tags.Type<"double">);
  int32_or_uint64:
    | (number & tags.Type<"int32">)
    | (bigint & tags.Type<"uint64">);
  int32_or_float_or_uint64:
    | (number & (tags.Type<"int32"> | tags.Type<"float">))
    | (bigint & tags.Type<"uint64">);
 
  // ARRAY AND MAP
  uint64_array: Array<bigint & tags.Type<"uint64">>;
  int32_map?: Map<number & tags.Type<"int32">, string> | null;
}
 
//----
// PROTOBUF MESSAGE SCHEMA
//----
typia.protobuf.message<TypeTagExample>();
 
//----
// DECODE FUNCTION
//----
typia.protobuf.createDecode<TypeTagExample>();
 
//----
// ENCODE FUNCTION
//----
typia.protobuf.createEncode<TypeTagExample>();

Compiled JavaScript

examples/bin/protobuf/message-type-tag.js


/* @ttsc-rewritten */
const {
  _ProtobufReader: __typia_transform__ProtobufReader,
} = require("typia/lib/internal/_ProtobufReader");
const {
  _ProtobufSizer: __typia_transform__ProtobufSizer,
} = require("typia/lib/internal/_ProtobufSizer");
const {
  _ProtobufWriter: __typia_transform__ProtobufWriter,
} = require("typia/lib/internal/_ProtobufWriter");
const {
  _throwTypeGuardError: __typia_transform__throwTypeGuardError,
} = require("typia/lib/internal/_throwTypeGuardError");
//----
// PROTOBUF MESSAGE SCHEMA
//----
[
  'syntax = "proto3";',
  "",
  "message TypeTagExample {",
  "  required int32 int32 = 1;",
  "  required uint32 uint32 = 2;",
  "  required uint64 uint64 = 3;",
  "  required int64 int64 = 4;",
  "  required float float = 5;",
  "  optional double double = 6;",
  "  optional string string = 7;",
  "  oneof uint32_or_double {",
  "    uint32 v8 = 8;",
  "    double v9 = 9;",
  "  }",
  "  oneof int32_or_uint64 {",
  "    int32 v10 = 10;",
  "    uint64 v11 = 11;",
  "  }",
  "  oneof int32_or_float_or_uint64 {",
  "    int32 v12 = 12;",
  "    uint64 v13 = 13;",
  "    float v14 = 14;",
  "  }",
  "  repeated uint64 uint64_array = 15;",
  "  map<int32, string> int32_map = 16;",
  "}",
].join("\n");
//----
// DECODE FUNCTION
//----
(() => {
  const _pdo0 = (reader, length = -1) => {
    length = length < 0 ? reader.size() : reader.index() + length;
    const output = {
      int32: undefined,
      uint32: undefined,
      uint64: undefined,
      int64: undefined,
      float: undefined,
      double: undefined,
      string: null,
      uint32_or_double: undefined,
      int32_or_uint64: undefined,
      int32_or_float_or_uint64: undefined,
      uint64_array: [],
      int32_map: null,
    };
    while (reader.index() < length) {
      const tag = reader.uint32();
      switch (tag >>> 3) {
        case 1:
          // int32;
          output.int32 = reader.int32();
          break;
        case 2:
          // uint32;
          output.uint32 = reader.uint32();
          break;
        case 3:
          // uint64;
          output.uint64 = reader.uint64();
          break;
        case 4:
          // int64;
          output.int64 = Number(reader.int64());
          break;
        case 5:
          // float;
          output.float = reader.float();
          break;
        case 6:
          // double;
          output.double = reader.double();
          break;
        case 7:
          // string;
          output.string = reader.string();
          break;
        case 8:
          // uint32;
          output.uint32_or_double = reader.uint32();
          break;
        case 9:
          // double;
          output.uint32_or_double = reader.double();
          break;
        case 10:
          // int32;
          output.int32_or_uint64 = reader.int32();
          break;
        case 11:
          // uint64;
          output.int32_or_uint64 = reader.uint64();
          break;
        case 12:
          // int32;
          output.int32_or_float_or_uint64 = reader.int32();
          break;
        case 13:
          // uint64;
          output.int32_or_float_or_uint64 = reader.uint64();
          break;
        case 14:
          // float;
          output.int32_or_float_or_uint64 = reader.float();
          break;
        case 15:
          // Array<(bigint & Type<"uint64">)>;
          if (2 === (tag & 7)) {
            const piece = reader.uint32() + reader.index();
            while (reader.index() < piece)
              output.uint64_array.push(reader.uint64());
          } else output.uint64_array.push(reader.uint64());
          break;
        case 16:
          // Map<(number & Type<"int32">), string>;
          (() => {
            const piece = reader.uint32() + reader.index();
            const entry = {
              key: undefined,
              value: "",
            };
            while (reader.index() < piece) {
              const kind = reader.uint32();
              switch (kind >>> 3) {
                case 1:
                  // int32;
                  entry.key = reader.int32();
                  break;
                case 2:
                  // string;
                  entry.value = reader.string();
                  break;
                default:
                  reader.skipType(kind & 7);
                  break;
              }
            }
            output.int32_map ??= new Map();
            output.int32_map.set(entry.key, entry.value);
          })();
          break;
        default:
          reader.skipType(tag & 7);
          break;
      }
    }
    return output;
  };
  return (input) => {
    const reader = new __typia_transform__ProtobufReader(input);
    return _pdo0(reader);
  };
})();
//----
// ENCODE FUNCTION
//----
(() => {
  const encoder = (writer, input) => {
    const _peo0 = (input) => {
      // property "int32": (number & Type<"int32">);
      writer.uint32(8);
      writer.int32(input.int32);
      // property "uint32": (number & Type<"uint32">);
      writer.uint32(16);
      writer.uint32(input.uint32);
      // property "uint64": (bigint & Type<"uint64">);
      writer.uint32(24);
      writer.uint64(input.uint64);
      // property "int64": (number & Type<"int64">);
      writer.uint32(32);
      writer.int64(input.int64);
      // property "float": (number & Type<"float">);
      writer.uint32(45);
      writer.float(input.float);
      // property "double": (number | undefined);
      if (undefined !== input.double) {
        writer.uint32(49);
        writer.double(input.double);
      }
      // property "string": (null | string);
      if (null !== input.string) {
        writer.uint32(58);
        writer.string(input.string);
      }
      // property "uint32_or_double": (number & (Type<"double"> | Type<"uint32">));
      if (
        "number" === typeof input.uint32_or_double &&
        Math.floor(input.uint32_or_double) === input.uint32_or_double &&
        0 <= input.uint32_or_double &&
        input.uint32_or_double <= 4294967295
      ) {
        writer.uint32(64);
        writer.uint32(input.uint32_or_double);
      } else if ("number" === typeof input.uint32_or_double && true) {
        writer.uint32(73);
        writer.double(input.uint32_or_double);
      } else
        __typia_transform__throwTypeGuardError({
          method: "createEncode",
          expected: '(number & (Type<"double"> | Type<"uint32">))',
          value: input.uint32_or_double,
        });
      // property "int32_or_uint64": ((bigint & Type<"uint64">) | (number & Type<"int32">));
      if ("number" === typeof input.int32_or_uint64) {
        writer.uint32(80);
        writer.int32(input.int32_or_uint64);
      } else if ("bigint" === typeof input.int32_or_uint64) {
        writer.uint32(88);
        writer.uint64(input.int32_or_uint64);
      } else
        __typia_transform__throwTypeGuardError({
          method: "createEncode",
          expected: '((bigint & Type<"uint64">) | (number & Type<"int32">))',
          value: input.int32_or_uint64,
        });
      // property "int32_or_float_or_uint64": ((bigint & Type<"uint64">) | (number & (Type<"float"> | Type<"int32">)));
      if (
        "number" === typeof input.int32_or_float_or_uint64 &&
        Math.floor(input.int32_or_float_or_uint64) ===
          input.int32_or_float_or_uint64 &&
        -2147483648 <= input.int32_or_float_or_uint64 &&
        input.int32_or_float_or_uint64 <= 2147483647
      ) {
        writer.uint32(96);
        writer.int32(input.int32_or_float_or_uint64);
      } else if ("bigint" === typeof input.int32_or_float_or_uint64) {
        writer.uint32(104);
        writer.uint64(input.int32_or_float_or_uint64);
      } else if (
        "number" === typeof input.int32_or_float_or_uint64 &&
        -1.175494351e38 <= input.int32_or_float_or_uint64 &&
        input.int32_or_float_or_uint64 <= 3.4028235e38
      ) {
        writer.uint32(117);
        writer.float(input.int32_or_float_or_uint64);
      } else
        __typia_transform__throwTypeGuardError({
          method: "createEncode",
          expected:
            '((bigint & Type<"uint64">) | (number & (Type<"float"> | Type<"int32">)))',
          value: input.int32_or_float_or_uint64,
        });
      // property "uint64_array": Array<bigint & Type<"uint64">>;
      if (0 !== input.uint64_array.length) {
        writer.uint32(122);
        writer.fork();
        for (const elem of input.uint64_array) {
          writer.uint64(elem);
        }
        writer.ldelim();
      }
      // property "int32_map": (Map<(number & Type<"int32">), string> | null | undefined);
      if (undefined !== input.int32_map && null !== input.int32_map) {
        for (const [key, value] of input.int32_map) {
          writer.uint32(130);
          writer.fork();
          writer.uint32(8);
          writer.int32(key);
          writer.uint32(18);
          writer.string(value);
          writer.ldelim();
        }
      }
    };
    _peo0(input);
    return writer;
  };
  return (input) => {
    const sizer = encoder(new __typia_transform__ProtobufSizer(), input);
    const writer = encoder(new __typia_transform__ProtobufWriter(sizer), input);
    return writer.buffer();
  };
})();

Comment tags

Same wire types are also expressible as @type comments:


interface User {
  /** @type uint32 */
  age: number;
}

Caution

Same caveats as validators/tags: comment tags are not type-checked (a typo silently falls back to double), they only work on object properties, and they can’t express union numeric types. Prefer type tags unless you’re maintaining a JSDoc-style codebase.

TypeScript Source

examples/src/protobuf/message-comment-tag.ts


import typia from "typia";
 
export interface CommentTagExample {
  /** @type int32 */
  int32: number;
 
  /** @type uint32 */
  uint32?: number | null;
 
  /** @type uint64 */
  uint64?: number;
 
  /** @type int64 */
  int64: number;
 
  /** @type float */
  float: number | null;
 
  double: number;
 
  string: string;
}
 
//----
// PROTOBUF MESSAGE SCHEMA
//----
typia.protobuf.message<CommentTagExample>();
 
//----
// DECODE FUNCTION
//----
typia.protobuf.createDecode<CommentTagExample>();
 
//----
// ENCODE FUNCTION
//----
typia.protobuf.createEncode<CommentTagExample>();

Compiled JavaScript

examples/bin/protobuf/message-comment-tag.js


/* @ttsc-rewritten */
const {
  _ProtobufReader: __typia_transform__ProtobufReader,
} = require("typia/lib/internal/_ProtobufReader");
const {
  _ProtobufSizer: __typia_transform__ProtobufSizer,
} = require("typia/lib/internal/_ProtobufSizer");
const {
  _ProtobufWriter: __typia_transform__ProtobufWriter,
} = require("typia/lib/internal/_ProtobufWriter");
//----
// PROTOBUF MESSAGE SCHEMA
//----
[
  'syntax = "proto3";',
  "",
  "message CommentTagExample {",
  "  required int32 int32 = 1;",
  "  optional uint32 uint32 = 2;",
  "  optional uint64 uint64 = 3;",
  "  required int64 int64 = 4;",
  "  optional float float = 5;",
  "  required double double = 6;",
  "  required string string = 7;",
  "}",
].join("\n");
//----
// DECODE FUNCTION
//----
(() => {
  const _pdo0 = (reader, length = -1) => {
    length = length < 0 ? reader.size() : reader.index() + length;
    const output = {
      int32: undefined,
      uint32: null,
      uint64: undefined,
      int64: undefined,
      float: null,
      double: undefined,
      string: "",
    };
    while (reader.index() < length) {
      const tag = reader.uint32();
      switch (tag >>> 3) {
        case 1:
          // int32;
          output.int32 = reader.int32();
          break;
        case 2:
          // uint32;
          output.uint32 = reader.uint32();
          break;
        case 3:
          // uint64;
          output.uint64 = Number(reader.uint64());
          break;
        case 4:
          // int64;
          output.int64 = Number(reader.int64());
          break;
        case 5:
          // float;
          output.float = reader.float();
          break;
        case 6:
          // double;
          output.double = reader.double();
          break;
        case 7:
          // string;
          output.string = reader.string();
          break;
        default:
          reader.skipType(tag & 7);
          break;
      }
    }
    return output;
  };
  return (input) => {
    const reader = new __typia_transform__ProtobufReader(input);
    return _pdo0(reader);
  };
})();
//----
// ENCODE FUNCTION
//----
(() => {
  const encoder = (writer, input) => {
    const _peo0 = (input) => {
      // property "int32": (number & Type<"int32">);
      writer.uint32(8);
      writer.int32(input.int32);
      // property "uint32": ((number & Type<"uint32">) | null | undefined);
      if (undefined !== input.uint32 && null !== input.uint32) {
        writer.uint32(16);
        writer.uint32(input.uint32);
      }
      // property "uint64": ((number & Type<"uint64">) | undefined);
      if (undefined !== input.uint64) {
        writer.uint32(24);
        writer.uint64(input.uint64);
      }
      // property "int64": (number & Type<"int64">);
      writer.uint32(32);
      writer.int64(input.int64);
      // property "float": ((number & Type<"float">) | null);
      if (null !== input.float) {
        writer.uint32(45);
        writer.float(input.float);
      }
      // property "double": number;
      writer.uint32(49);
      writer.double(input.double);
      // property "string": string;
      writer.uint32(58);
      writer.string(input.string);
    };
    _peo0(input);
    return writer;
  };
  return (input) => {
    const sizer = encoder(new __typia_transform__ProtobufSizer(), input);
    const writer = encoder(new __typia_transform__ProtobufWriter(sizer), input);
    return writer.buffer();
  };
})();

Restrictions

Protocol Buffer’s type system is much narrower than TypeScript’s. The following are not representable:

Top-level type must be a single static object

number, Array<T>, Cat | Dog, Record<string, T> — none of these are valid top-level shapes. Wrap them in an object.

TypeScript Source


import typia from "typia";
 
interface Cat { type: "cat";  name: string; ribbon: boolean }
interface Dog { type: "dog";  name: string; hunt: boolean }
 
typia.protobuf.message<bigint>();
typia.protobuf.createDecode<Record<string, number>>();
typia.protobuf.createDecode<Map<number & typia.tags.Type<"float">, Dog>>();
typia.protobuf.createEncode<boolean[]>();
typia.protobuf.createEncode<Cat | Dog>();

Container nesting is limited

Array<T>, Map<K, V>, and Record<string, T> are containers. The rules:

No two-dimensional containers. number[][] is not allowed. Neither is Map<string, number[]>.
No unions inside container values. Map<string, Cat | Dog> is not allowed.
Map keys must be atomic and non-union. Map<Cat, string> and Map<string | number, Dog> are not allowed.

TypeScript Source


import typia from "typia";
 
interface IPointer<T> { value: T }
interface Cat { type: "cat"; name: string; ribbon: boolean }
interface Dog { type: "dog"; name: string; hunt: boolean }
 
typia.protobuf.message<IPointer<number[][]>>();
typia.protobuf.createEncode<IPointer<Record<string, string[]>>>();
typia.protobuf.createDecode<IPointer<Map<string, Cat | Dog>>>();
typia.protobuf.message<IPointer<Map<Cat, string>>>();
typia.protobuf.message<IPointer<Map<number | string, Dog>>>();

Types with no Protocol Buffer counterpart

These are rejected outright:

any / unknown (you don’t know how to encode an unknown value)
function types
Set<T>, WeakSet<T>, WeakMap<K, V> — use Array<T> / Map<K, V> instead
Date, Boolean, BigInt, Number, String — use the primitive (string, boolean, …) instead
Typed arrays except Uint8Array — use Uint8Array for binary data

TypeScript Source


import typia from "typia";
 
interface Something {
  any: any;
  unknown: unknown;
  closure: () => void;
  dict: Set<string> | WeakSet<Something> | WeakMap<Something, string>;
  date: Date;
  classic: String;
  buffer: ArrayBuffer;
}
 
typia.protobuf.message<Something>();

Where to go next

Encoding a value → protobuf.encode
Decoding bytes → protobuf.decode
Numeric constraints in tags → Special Tags

`typia.protobuf.message` — emit a `.proto` schema from a TypeScript type

First example

TypeScript Source

Compiled JavaScript

Wire types

TypeScript Source

Compiled JavaScript

Comment tags

TypeScript Source

Compiled JavaScript

Restrictions

Top-level type must be a single static object

TypeScript Source

Console Output

Container nesting is limited

TypeScript Source

Console Output

Types with no Protocol Buffer counterpart

TypeScript Source

Console Output

Where to go next

typia.protobuf.message — emit a .proto schema from a TypeScript type

First example

TypeScript Source

Compiled JavaScript

Wire types

TypeScript Source

Compiled JavaScript

Comment tags

TypeScript Source

Compiled JavaScript

Restrictions

Top-level type must be a single static object

TypeScript Source

Console Output

Container nesting is limited

TypeScript Source

Console Output

Types with no Protocol Buffer counterpart

TypeScript Source

Console Output

Where to go next

`typia.protobuf.message` — emit a `.proto` schema from a TypeScript type