Typia Guide Documents

`message()` function

undefined


export namespace protobuf {
  export function message<T>(): string;
}

typia.protobuf.message() function returns a Protocol Buffer message (structure) as a string value.

With this message() function, you can share *.proto files with other languages. If you want to customize byte order or define specific type (that is not supported in the TypeScript) like uint32, use comment tags by following comment tags section.

TypeScript Source Code

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

Type Tags

By using type tags, you can use special numeric types that are not supported in the TypeScript.

Just import Type (or typia.tags.Type) type, and combine it with number or bigint type through intersection symbol number & typia.tagsType<"float"> case. If you want to declare an union numeric type, combine | and bracket (()) symbols properly like below.

When you take a mistake that choosing different target type, TypeScript compiler would block it with compilation error message. Therefore, have a confidence when using the Type tag. For such type safety reason, I recommend to use Type tag instead of using comment tags as much as possible.

number & (Type<"uint32"> | Type<"double">)
- number type can be both uint32 and double
(number & Type<"int32">) | (bigint & Type<"uint64">)
- number is int32
- bigint is uint64
(number & (Type<"int32">)| Type<"float">) | (bigint & Type<"uint64">)
- number can be both int32 and float
- bigint is uint64

TypeScript Source Code

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 File

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


import typia from "typia";
import * as __typia_transform__ProtobufReader from "typia/lib/internal/_ProtobufReader.js";
import * as __typia_transform__ProtobufSizer from "typia/lib/internal/_ProtobufSizer.js";
import * as __typia_transform__ProtobufWriter from "typia/lib/internal/_ProtobufWriter.js";
import * as __typia_transform__isTypeFloat from "typia/lib/internal/_isTypeFloat.js";
import * as __typia_transform__isTypeInt32 from "typia/lib/internal/_isTypeInt32.js";
import * as __typia_transform__isTypeInt64 from "typia/lib/internal/_isTypeInt64.js";
import * as __typia_transform__isTypeUint32 from "typia/lib/internal/_isTypeUint32.js";
import * as __typia_transform__throwTypeGuardError from "typia/lib/internal/_throwTypeGuardError.js";
 
//----
// 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._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<"uint32"> | Type<"double">));
      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._throwTypeGuardError({
          method: "typia.protobuf.createEncode",
          expected: '(number & (Type<"uint32"> | Type<"double">))',
          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._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<"int32"> | Type<"float">)));
      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._throwTypeGuardError({
          method: "typia.protobuf.createEncode",
          expected:
            '((bigint & Type<"uint64">) | (number & (Type<"int32"> | Type<"float">)))',
          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._ProtobufSizer(),
      input,
    );
    const writer = encoder(
      new __typia_transform__ProtobufWriter._ProtobufWriter(sizer),
      input,
    );
    return writer.buffer();
  };
})();

Comment Tags

By using @type {target} comment tag, you also can use special numeric types.

However, this way is not recommended, because it can’t perform union numeric types, and cannot be used in Array and Map types. When you declare @type int32 statement, target number type be fixed as int32 type, and never can have another numeric type by declaring union statements.

Also, those comment tags are not type safe. If you take a mistake when writing a comment tag, it will not be detected by the compiler, and will cause an error at runtime. For example, if you write a miss-spelled keyword like @type unit32, the target number type would be double type, and you can identify it just by running the program (or visiting playground website).

Why supports comment tags?

Despite these disadvantages, the reason for maintaining comment tags is as follows.

First, it is to support the legacy JSDoc style that had been used in the JS camp for a long time. If you had developed a legacy project and JSDoc being used, you can use it as is.

Second, to support Prisma. If a comment is created in the Prisma Schema through the /// statement as shown below and a type is created, it is converted to a TS comment as it is. And since there is no way that union types, numeric Arrays or Maps are used in Prisma (database) schema, these comment tags are surprisingly compatible with Prisma.

TypeScript Source Code

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 File

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


import typia from "typia";
import * as __typia_transform__ProtobufReader from "typia/lib/internal/_ProtobufReader.js";
import * as __typia_transform__ProtobufSizer from "typia/lib/internal/_ProtobufSizer.js";
import * as __typia_transform__ProtobufWriter from "typia/lib/internal/_ProtobufWriter.js";
 
//----
// 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._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._ProtobufSizer(),
      input,
    );
    const writer = encoder(
      new __typia_transform__ProtobufWriter._ProtobufWriter(sizer),
      input,
    );
    return writer.buffer();
  };
})();

Restrictions

You know what? Expression power of Protocol Buffer is extremely narrower than type system of TypeScript. For example, Protocol Buffer can’t express complicate union type containing array. Also, Protocol Buffer can’t express multi dimensional array type, either.

In such reason, when converting TypeScript type to Protocol buffer message schema, lots of restrictions are exist. Let’s study which types of TypeScript are not supported in Protocol Buffer. For reference, if you try to call typia.protobuf.message<T>() function with unsupported type, typia will generate compile errors like below example cases.

At first, top level type must be a sole and static object.

If you try to use number or Array<T> type as a top level type, typia will generate compile error like below. Dynamic object types like Record<string, T>, or Map<string, T> types are not allowed either. For reference, the sole object means that, union of object types is not allowed, either.

TypeScript Source Code


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>();

At next, in Protocol Buffer, those types are categorized as container types.

Array<T>
Map<Key, T>
Record<string, T> (dynamic object)

Also, those container types does not allow over two-dimensional stacking. Therefore, it is not possible to declaring two dimensional array like number[][], or Array type in Map like Map<string, number[]>. Besides, value type of those container also do not support union type either.

Additionally, about Map<Key, T> type, key type must be an atomic type. It means that, only boolean, number, bigint and string types are allowed. Also, key type cannot be union type, either.

TypeScript Source Code


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>>>();

At last, those types are all not allowed.

any
functional type
Set<T>, WeakSet<T> and WeakMap<T>
Date, Boolean, BigInt, Number, String
Binary classes except Uint8Array
- Uint8ClampedArray, Uint16Array, Uint32Array, BigUint64Array
- Int8Array, Int16Array, Int32Array, BigInt64Array
- ArrayBuffer, SharedArrayBuffer and DataView

TypeScript Source Code


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>();

`message()` function

undefined

TypeScript Source Code

Compiled JavaScript File

Type Tags

TypeScript Source Code

Compiled JavaScript File

Comment Tags

TypeScript Source Code

Compiled JavaScript File

Restrictions

TypeScript Source Code

Console Output

TypeScript Source Code

Console Output

TypeScript Source Code

Console Output

message() function

undefined

TypeScript Source Code

Compiled JavaScript File

Type Tags

TypeScript Source Code

Compiled JavaScript File

Comment Tags

TypeScript Source Code

Compiled JavaScript File

Restrictions

TypeScript Source Code

Console Output

TypeScript Source Code

Console Output

TypeScript Source Code

Console Output

`message()` function