tRPC End-to-End Type Safe APIs · Lección

Transformadores de datos para serialización

Utilice los transformadores de datos de tRPC para serializar y deserializar tipos de datos personalizados, como Dates o BigInts.

Transformadores de datos para serialización es una lección gratuita de tRPC End-to-End Type Safe APIs en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de tRPC End-to-End Type Safe APIs, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de tRPC End-to-End Type Safe APIs incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

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!

Preguntas frecuentes

¿La lección «Transformadores de datos para serialización» es gratis?

Sí — el texto completo de «Transformadores de datos para serialización» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de tRPC End-to-End Type Safe APIs, actualiza a CoddyKit PRO. El curso de tRPC End-to-End Type Safe APIs incluye 4 lecciones en total.

¿Qué aprenderé en «Transformadores de datos para serialización»?

Utilice los transformadores de datos de tRPC para serializar y deserializar tipos de datos personalizados, como Dates o BigInts. Practicas tRPC End-to-End Type Safe APIs con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar tRPC End-to-End Type Safe APIs?

No se requiere experiencia previa. tRPC End-to-End Type Safe APIs en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.

¿Cuánto tiempo toma la lección «Transformadores de datos para serialización»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de tRPC End-to-End Type Safe APIs?

Sí. Cada lección de tRPC End-to-End Type Safe APIs incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Gestión adecuada de errores en tRPC
Tipos de error personalizados
Transformadores de datos para serialización
Formato de errores y mensajes de validación por campo

← Volver a tRPC End-to-End Type Safe APIs