`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;
}

Numeric scalar types

Protocol Buffer has narrower numeric types than TypeScript (int32, uint32, int64, uint64, float, double). Use type tags to pick the protobuf scalar 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.

tags.Type<"int8"> and tags.Type<"int16"> validate the smaller signed integer ranges, then emit the protobuf int32 scalar type. tags.Type<"uint8"> and tags.Type<"uint16"> validate the smaller unsigned integer ranges, then emit uint32. Protocol Buffer has no distinct 8-bit or 16-bit numeric scalar types.

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


import typia from "typia";
import * as _e from "typia/lib/internal/_ProtobufReader";
import * as _g from "typia/lib/internal/_ProtobufSizer";
import * as _h from "typia/lib/internal/_ProtobufWriter";
import * as _d from "typia/lib/internal/_isTypeFloat";
import * as _a from "typia/lib/internal/_isTypeInt32";
import * as _c from "typia/lib/internal/_isTypeInt64";
import * as _b from "typia/lib/internal/_isTypeUint32";
import * as _f from "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 _e._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
        _f._throwTypeGuardError({
          method: "typia.protobuf.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
        _f._throwTypeGuardError({
          method: "typia.protobuf.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
        _f._throwTypeGuardError({
          method: "typia.protobuf.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 _g._ProtobufSizer(), input);
    const writer = encoder(new _h._ProtobufWriter(sizer), input);
    return writer.buffer();
  };
})();

Comment tags

The same scalar choices are also expressible as @type comments:


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

Caution

Same caveats as validators/tags: comment tags are not type-checked (a typo is ignored, so protobuf falls back to the default double scalar for an untagged number), 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


import typia from "typia";
import * as _a from "typia/lib/internal/_ProtobufReader";
import * as _b from "typia/lib/internal/_ProtobufSizer";
import * as _c from "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 _a._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 _b._ProtobufSizer(), input);
    const writer = encoder(new _c._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

Numeric scalar 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

Numeric scalar 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