tRPC End-to-End Type Safe APIs · Lektion

Datentransformer für Serialisierung

Nutzen Sie die Datentransformer von tRPC, um benutzerdefinierte Datentypen wie Dates oder BigInts zu serialisieren und deserialisieren.

Datentransformer für Serialisierung ist eine kostenlose tRPC End-to-End Type Safe APIs-Lektion auf CoddyKit. Dies ist Lektion 3 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des tRPC End-to-End Type Safe APIs-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der tRPC End-to-End Type Safe APIs-Kurs umfasst insgesamt 4 Lektionen.

Teile dieser Lektion wurden noch nicht übersetzt und werden auf Englisch angezeigt.

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!

Häufig gestellte Fragen

Ist die Lektion „Datentransformer für Serialisierung“ kostenlos?

Ja — der vollständige Text von „Datentransformer für Serialisierung“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des tRPC End-to-End Type Safe APIs-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der tRPC End-to-End Type Safe APIs-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Datentransformer für Serialisierung“?

Nutzen Sie die Datentransformer von tRPC, um benutzerdefinierte Datentypen wie Dates oder BigInts zu serialisieren und deserialisieren. Du übst tRPC End-to-End Type Safe APIs mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um tRPC End-to-End Type Safe APIs zu starten?

Keine Vorkenntnisse erforderlich. tRPC End-to-End Type Safe APIs auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 3 von 4.

Wie lange dauert die Lektion „Datentransformer für Serialisierung“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser tRPC End-to-End Type Safe APIs-Lektion Code schreiben und ausführen?

Ja. Jede tRPC End-to-End Type Safe APIs-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

tRPC-Fehler elegant behandeln
Benutzerdefinierte Fehlertypen
Datentransformer für Serialisierung
Fehler formatieren und Validierungshinweise auf Feldebene

← Zurück zu tRPC End-to-End Type Safe APIs