tRPC End-to-End Type Safe APIs · Урок

Преобразователи данных для сериализации

Используйте преобразователи данных tRPC для сериализации и десериализации пользовательских типов данных, например дат или BigInts.

«Преобразователи данных для сериализации» — бесплатный урок tRPC End-to-End Type Safe APIs на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения tRPC End-to-End Type Safe APIs, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс tRPC End-to-End Type Safe APIs содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

What are Data Transformers?

When building APIs, data often needs to be sent between different systems. This process is called serialization (converting data to a transportable format like JSON) and deserialization (converting it back).

tRPC's data transformers help handle complex data types that JSON doesn't natively support, ensuring they arrive on the client side just as they left the server.

JSON's Data Type Limits

JSON (JavaScript Object Notation) is great, but it has limitations. It natively supports strings, numbers, booleans, null, objects, and arrays.

Dates: JSON represents dates as strings, losing their Date object functionality.
BigInts: Large integer numbers (BigInt) are not a native JSON type.
Maps, Sets, RegExps: These also don't have direct JSON representations.

Without transformers, these types can break or change unexpectedly when sent via tRPC.

Default tRPC Serialization

By default, tRPC uses standard JSON JSON.stringify() and JSON.parse() for data transfer. This means any data types not supported by JSON will be converted to their closest JSON representation.

For example, a JavaScript Date object will become an ISO 8601 string, and a BigInt will throw an error if not handled.

Introducing SuperJSON

To overcome JSON's limitations, tRPC allows you to plug in a custom data transformer. The most popular choice is superjson.

superjson is a library that extends JSON's capabilities, allowing it to serialize and deserialize many common JavaScript types, including Date, BigInt, Map, Set, and more, while preserving their original type.

Server Setup with SuperJSON

Integrating superjson on the server is straightforward. You pass it to initTRPC when initializing your tRPC instance. This tells tRPC to use superjson for all serialization.

First, install it: npm install superjson

import { initTRPC } from '@trpc/server';
import superjson from 'superjson';

// Initialize tRPC with superjson transformer
export const t = initTRPC.context().transformer(superjson).create();

// Example of a tRPC router definition (conceptual):
// export const appRouter = t.router({
//   hello: t.procedure.query(() => {
//     return { message: 'Hello, tRPC!', now: new Date() };
//   }),
// });

Client Setup with SuperJSON

On the client side, you also need to tell your tRPC client to use superjson. This ensures that the data received from the server is correctly deserialized back into its original JavaScript types.

The setup varies slightly depending on your client (e.g., React Query, vanilla client).

import { createTRPCReact } from '@trpc/react-query';
import superjson from 'superjson';
// import type { AppRouter } from '../server/trpc'; // Adjust path

// Initialize tRPC client with superjson transformer
export const trpc = createTRPCReact<any>({
  transformer: superjson,
});

// Example client usage (conceptual):
// function MyComponent() {
//   const hello = trpc.hello.useQuery();
//   if (hello.data) {
//     console.log(hello.data.now instanceof Date); // true!
//   }
//   return <p>...</p>;
// }

Dates: Before & After

Let's see how superjson handles a Date object. Without it, a Date becomes a string. With superjson, it remains a Date object.

Run this example to see the serialization and deserialization process:

import superjson from 'superjson';

function main() {
  const originalDate = new Date();
  console.log("Original:", originalDate.toISOString());
  console.log("Is Date (original):", originalDate instanceof Date);

  // Simulate serialization (like tRPC server would do)
  const serialized = superjson.stringify({ date: originalDate });
  console.log("Serialized:", serialized);

  // Simulate deserialization (like tRPC client would do)
  const deserialized = superjson.parse(serialized) as { date: Date };
  console.log("Deserialized:", deserialized.date.toISOString());
  console.log("Is Date (deserialized):", deserialized.date instanceof Date);
}

main();

BigInts: From String to Type

BigInt values are used for integers larger than Number.MAX_SAFE_INTEGER. JSON doesn't support them. superjson correctly serializes them as strings and deserializes them back into BigInt types.

Try this example:

import superjson from 'superjson';

function main() {
  const originalBigInt = 9007199254740991n + 100n; // A BigInt
  console.log("Original:", originalBigInt);
  console.log("Type (original):", typeof originalBigInt);

  // Simulate serialization
  const serialized = superjson.stringify({ value: originalBigInt });
  console.log("Serialized:", serialized);

  // Simulate deserialization
  const deserialized = superjson.parse(serialized) as { value: bigint };
  console.log("Deserialized:", deserialized.value);
  console.log("Type (deserialized):", typeof deserialized.value);
  console.log("Is equal:", originalBigInt === deserialized.value);
}

main();

Beyond Dates & BigInts

superjson isn't just for Date and BigInt. It also supports many other JavaScript types:

Map and Set
RegExp
Error objects
URL objects
Even custom classes (with some configuration!)

This makes superjson a powerful tool for maintaining type fidelity across your tRPC application.

Transformer Check

Imagine you have a tRPC procedure that returns a JavaScript Date object and a BigInt. Which of the following statements are true about using superjson transformers in tRPC?

Recap: Data Transformers

In this lesson, we learned about tRPC's data transformers, specifically focusing on superjson.

JSON's limitations prevent native serialization of types like Date and BigInt.
superjson provides a robust solution to serialize and deserialize these complex types, preserving their original form.
It requires configuration on both the tRPC server and client.
superjson supports many other types beyond Dates and BigInts, enhancing type safety across your application.

This ensures your data remains consistent and type-safe from end-to-end!

Часто задаваемые вопросы

Урок «Преобразователи данных для сериализации» бесплатный?

Да — полный текст урока «Преобразователи данных для сериализации» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс tRPC End-to-End Type Safe APIs, подпишись на CoddyKit PRO. Курс tRPC End-to-End Type Safe APIs содержит 4 уроков всего.

Чему я научусь в уроке «Преобразователи данных для сериализации»?

Используйте преобразователи данных tRPC для сериализации и десериализации пользовательских типов данных, например дат или BigInts. Ты практикуешь tRPC End-to-End Type Safe APIs с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать tRPC End-to-End Type Safe APIs?

Предыдущий опыт не требуется. tRPC End-to-End Type Safe APIs на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Преобразователи данных для сериализации»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке tRPC End-to-End Type Safe APIs?

Да. Каждый урок tRPC End-to-End Type Safe APIs включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Корректная обработка ошибок tRPC
Пользовательские типы ошибок
Преобразователи данных для сериализации
Форматирование ошибок и обратная связь о проверке полей

← Назад к tRPC End-to-End Type Safe APIs