import { Tabs, Tab } from 'nextra-theme-docs'
import Alert from '@mui/material/Alert';
import AlertTitle from '@mui/material/AlertTitle';
<Tabs items={[
typia,
TypeGuardError.ts,
IValidation.ts,
Resolved.ts,
]}>
export namespace protobuf {
export function decode<T>(buffer: Uint8Array): Resolved<T>;
export function isDecode<T>(buffer: Uint8Array): Resolved<T> | null;
export function assertDecode<T>(buffer: Uint8Array): Resolved<T>;
export function validateDecode<T>(
buffer: Uint8Array,
): IValidation<Resolved<T>>;
}type Equal<X, Y> = X extends Y ? (Y extends X ? true : false) : false;
type ResolvedMain = T extends [never]
? never // (special trick for jsonable | null) type
: ValueOf extends boolean | number | bigint | string
? ValueOf
: T extends Function
? never
: T extends object
? ResolvedObject
: ValueOf;
type ResolvedObject = T extends Array
? IsTuple extends true
? ResolvedTuple
: ResolvedMain[]
: T extends Set
? Set<ResolvedMain>
: T extends Map<infer K, infer V>
? Map<ResolvedMain, ResolvedMain>
: T extends WeakSet | WeakMap<any, any>
? never
: T extends
| Date
| Uint8Array
| Uint8ClampedArray
| Uint16Array
| Uint32Array
| BigUint64Array
| Int8Array
| Int16Array
| Int32Array
| BigInt64Array
| Float32Array
| Float64Array
| ArrayBuffer
| SharedArrayBuffer
| DataView
| Blob
| File
? T
: {
[P in keyof T]: ResolvedMain<T[P]>;
};
type ResolvedTuple<T extends readonly any[]> = T extends []
? []
: T extends [infer F]
? [ResolvedMain]
: T extends [infer F, ...infer Rest extends readonly any[]]
? [ResolvedMain, ...ResolvedTuple]
: T extends [(infer F)?]
? [ResolvedMain?]
: T extends [(infer F)?, ...infer Rest extends readonly any[]]
? [ResolvedMain?, ...ResolvedTuple]
: [];
type IsTuple<T extends readonly any[] | { length: number }> = [T] extends [
never,
]
? false
: T extends readonly any[]
? number extends T["length"]
? false
: true
: false;
type ValueOf = IsValueOf<Instance, Boolean> extends true
? boolean
: IsValueOf<Instance, Number> extends true
? number
: IsValueOf<Instance, String> extends true
? string
: Instance;
type IsValueOf<Instance, Object extends IValueOf> = Instance extends Object
? Object extends IValueOf
? Instance extends Primitive
? false
: true // not Primitive, but Object
: false // cannot be
: false;
interface IValueOf {
valueOf(): T;
}
</Tab>
</Tabs>
Protocol Buffer Decoder.
You can easily convert a Protocol Buffer's binary data to a JavaScript object, without any extra Protocol Buffer [Message Schema](./message) definition. `typia.protobuf.decode<T>()` function analyzes your type `T`, and generates a Protocol Buffer Message Schema internally.And then, it converts the binary data to a JavaScript object.
By the way, as Protocol Buffer handles binary data directly, there's no way when `input` binary data was not encoded from the `T` typed value. In that case, unexpected behavior or internal error would be occured. Therefore, I recommend you to encode binary data of Protocol Buffer from type safe encode functions like below, Use `typia.protobuf.encode<T>()` function only when you can trust it.
- [`typia.protobuf.isEncode<T>()`](./encode)
- [`typia.protobuf.assertEncode<T>()`](./encode)
- [`typia.protobuf.validateEncode<T>()`](./encode)
For reference, `typia` provides type safe decorators like below, but they are just for additional type validation like `number & Minimum<7>` or `string & Format<"uuid">` cases, that are represented by [Special Tags](../validators/tags). Thus, I repeat that, you've to ensure type safety when using decoder function.
- `typia.protobuf.isDecode<T>()`: [`typia.is<T>()`](../validators/is) + `typia.protobuf.decode<T>()`
- `typia.protobuf.assertDecode<T>()`: [`typia.assert<T>()`](../validators/assert) + `typia.protobuf.decode<T>()`
- `typia.protobuf.validateDecode<T>()`: [`typia.validate<T>()`](../validators/validate) + `typia.protobuf.decode<T>()`
<br/>
<Alert severity="success">
<AlertTitle>
**AOT compliation**
</AlertTitle>
`typia.protobuf.decode<T>()` and other similar functions are still much faster than any other competitive libraries, even though they include type checking process. This is the power of AOT compilation, writing optimal dedicated code by analyzing TypeScript type, in the compilation level.
</Alert>
<Tabs items={['TypeScript Source Code', 'Compiled JavaScript File']}>
<Tab>
```typescript copy filename="protobuf.decode.ts" showLineNumbers
import typia, { tags } from "typia";
interface ICustomer {
id: number & tags.Type<"int32">;
email: string & tags.Format<"email">;
name: string;
pet: null | ICat | IDog;
memo: null | Map<string, string>;
logins: Array<ICustomerLogin>;
}
interface ICat {
type: "cat";
name: string;
ribbon: boolean;
}
interface IDog {
type: "dog";
name: string;
hunt: boolean;
}
interface ICustomerLogin {
success: boolean;
href: string & tags.Format<"url">;
referrer: string & tags.Format<"url">;
ip: string & (tags.Format<"ipv4"> | tags.Format<"ipv6">);
time: string & tags.Format<"date-time">;
}
const data: ICustomer = typia.random<ICustomer>();
const encoded: Uint8Array = typia.protobuf.encode(data);
typia.protobuf.decode<ICustomer>(encoded);
<Tabs items={[
typia,
TypeGuardError.ts,
IValidation.ts,
Resolved.ts,
]}>
export namespace protobuf {
export function createDecode<T>(): (buffer: Uint8Array) => Resolved<T>;
export function createIsDecode<T>: (buffer: Uint8Array) => Resolved<T> | null;
export function createAssertDecode<T>(): (buffer: Uint8Array) => Resolved<T>;
export function createValidateDecode<T>(): (
buffer: Uint8Array
) => IValidation<Resolved<T>>;
}interface ICustomer {
id: number & tags.Type<"int32">;
email: string & tags.Format<"email">;
name: string;
pet: null | ICat | IDog;
memo: null | Map<string, string>;
logins: Array;
}
interface ICat {
type: "cat";
name: string;
ribbon: boolean;
}
interface IDog {
type: "dog";
name: string;
hunt: boolean;
}
interface ICustomerLogin {
success: boolean;
href: string & tags.Format<"url">;
referrer: string & tags.Format<"url">;
ip: string & (tags.Format<"ipv4"> | tags.Format<"ipv6">);
time: string & tags.Format<"date-time">;
}
const data: ICustomer = typia.random();
const encoded: Uint8Array = typia.protobuf.encode(data);
typia.protobuf.decode(encoded);
</Tab>
</Tabs>
Reusable `typia.protobuf.decode<T>()` function generators.
If you repeat to call `typia.protobuf.decode<T>()` function on the same type, size of JavaScript files would be larger because of duplicated AOT compilation. To prevent it, you can generate reusable function through `typia.protobuf.createDecode<T>()` function.
Just look at the code below, then you may understand how to use it.
<Tabs items={['TypeScript Source Code', 'Compiled JavaScript File']}>
<Tab>
```typescript copy filename="protobuf.createDecode.ts" showLineNumbers
import typia, { tags } from "typia";
export const encode = typia.protobuf.createDecode<ICustomer>();
interface ICustomer {
id: number & tags.Type<"int32">;
email: string & tags.Format<"email">;
name: string;
pet: null | ICat | IDog;
memo: null | Map<string, string>;
logins: Array<ICustomerLogin>;
}
interface ICat {
type: "cat";
name: string;
ribbon: boolean;
}
interface IDog {
type: "dog";
name: string;
hunt: boolean;
}
interface ICustomerLogin {
success: boolean;
href: string & tags.Format<"url">;
referrer: string & tags.Format<"url">;
ip: string & (tags.Format<"ipv4"> | tags.Format<"ipv6">);
time: string & tags.Format<"date-time">;
}
Protocol Buffer supports special numeric types like int32 or uint64 that are not supported in TypeScript. Also, types of Protocol Buffer cannot fully meet TypeScript type specs either, as expression power of TypeScript types are much stronger than Protocol Buffer.
To know how to define special numeric types like uint64, and to understand which TypeScript types are not supported in Protocol Buffer specs, it would better to read below documents. I recommend you to read them before using typia.protobuf.decode<T>() related functions.