superjson

Sicherlich serialisieren Sie JavaScript -Ausdrücke mit einem Superet von JSON, der Daten, Bigints und mehr umfasst.

Schlüsselmerkmale

• ? Zuverlässige Serialisierung und Deserialisierung
• ? Geben Sie die Sicherheit mit Autokonfliege ein
• ? Vernachlässigbarer Laufzeit -Fußabdruck
• ? Rahmen agnostisch
• ? Perfekte Lösung für die Serialisierungsbeschränkungen von Next.JS bei getServerSideProps und getInitialProps

Hintergrundgeschichte

Bei Blitz haben wir mit den Grenzen von JSON zu kämpfen. Wir arbeiten oft mit Date , Map , Set oder BigInt , aber JSON.stringify unterstützt keine von ihnen, ohne den Ärger zu durchlaufen, manuell zu konvertieren!

Superjson löst diese Probleme, indem er einen dünnen Wrapper über JSON.stringify und JSON.parse bereitstellt.

Sponsoren

Superjson -Logo von Numi:

Erste Schritte

Installieren Sie die Bibliothek mit Ihrem Paketmanager Ihrer Wahl, z. B.:

 yarn add superjson

Grundnutzung

Der einfachste Weg, um Superjson zu verwenden, ist die stringify und parse . Wenn Sie wissen, wie Sie JSON.stringify verwenden, kennen Sie Superjson bereits!

Leicht für jeden Ausdruck, den Sie möchten, stritifizieren:

 import superjson from 'superjson' ;

const jsonString = superjson . stringify ( { date : new Date ( 0 ) } ) ;

// jsonString === '{"json":{"date":"1970-01-01T00:00:00.000Z"},"meta":{"values":{date:"Date"}}}'

Und analysieren Sie Ihren JSON so:

 const object = superjson . parse <
{ date : Date }
> ( jsonString ) ;

// object === { date: new Date(0) } 

Erweiterte Verwendung

In Fällen, in denen Sie in der Ausgabe einen niedrigeren Zugriff auf die json und meta -Daten haben möchten, können Sie die serialize und deserialize -Funktionen verwenden.

Ein großartiger Anwendungsfall dafür ist, dass Sie eine API haben, die Sie für alle Kunden kompatibel sein möchten. Sie möchten jedoch auch die Meta -Daten übertragen, damit Clients Superjson verwenden können, um sie vollständig zu deserialisieren.

Zum Beispiel:

 const object = {
  normal : 'string' ,
  timestamp : new Date ( ) ,
  test : / superjson / ,
} ;

const { json , meta } = superjson . serialize ( object ) ;

/*
json = {
  normal: 'string',
  timestamp: "2020-06-20T04:56:50.293Z",
  test: "/superjson/",
};

// note that `normal` is not included here; `meta` only has special cases
meta = {
  values: {
    timestamp: ['Date'],
    test: ['regexp'],
  }
};
*/ 

Verwenden Sie mit Next.js

Die getServerSideProps , getInitialProps und getStaticProps -Datenhaken von Next.js ermöglichen es Ihnen nicht, JavaScript -Objekte wie Daten zu übertragen. Es wird fehlerhaft sein, es sei denn, Sie konvertieren Daten in Zeichenfolgen usw.

Zum Glück ist Superjson ein perfektes Werkzeug, um diese Einschränkung zu umgehen!

Next.js SWC Plugin (experimentell, v13 oder höher)

NEXT.JS SWC -Plugins sind experimentell, versprechen jedoch eine erhebliche Beschleunigung. Um das Superjson SWC -Plugin zu verwenden, installieren Sie es und fügen Sie es zu Ihrem next.config.js :

yarn add next-superjson-plugin

 // next.config.js
module . exports = {
  experimental : {
    swcPlugins : [
      [
        'next-superjson-plugin' ,
        {
          excluded : [ ] ,
        } ,
      ] ,
    ] ,
  } ,
} ;

Next.js (stabile Babel -Transformation)

Installieren Sie die Bibliothek mit Ihrem Paketmanager Ihrer Wahl, z. B.:

yarn add babel-plugin-superjson-next

Fügen Sie das Plugin zu Ihrem .babelRC hinzu. Wenn Sie keine haben, erstellen Sie ihn.

 {
  "presets" : [ "next/babel" ] ,
  "plugins" : [
    ...
    "superjson-next" // ?
  ]
}

Erledigt! Jetzt können Sie alle JS -Datentypen in Ihren getServerSideProps / usw. sicher verwenden.

API

serialisieren

Serialisiert jeden JavaScript-Wert in ein JSON-kompatibler Objekt.

Beispiele

 const object = {
  normal : 'string' ,
  timestamp : new Date ( ) ,
  test : / superjson / ,
} ;

const { json , meta } = serialize ( object ) ;

Gibt json und meta zurück, beide JSON-kompatible Werte.

Deserialisieren

Deserialisiert die Ausgabe von Superjson in Ihren ursprünglichen Wert zurück.

Beispiele

 const { json , meta } = serialize ( object ) ;

deserialize ( { json , meta } ) ;

Gibt your original value zurück.

Stringify

Serialisiert und anschließend Ihren JavaScript -Wert.

Beispiele

 const object = {
  normal : 'string' ,
  timestamp : new Date ( ) ,
  test : / superjson / ,
} ;

const jsonString = stringify ( object ) ;

Gibt string zurück.

analysieren

Parsen und dann die von stringify zurückgegebene JSON -Zeichenfolge.

Beispiele

 const jsonString = stringify ( object ) ;

parse ( jsonString ) ;

Gibt your original value zurück.

---

Superjson unterstützt viele zusätzliche Typen, die JSON nicht tut. Sie können all dies serialisieren:

Typ	Unterstützt von Standard JSON?	Unterstützt von Superjson?
string	✅	✅
number	✅	✅
boolean	✅	✅
null	✅	✅
Array	✅	✅
Object	✅	✅
undefined		✅
bigint		✅
Date		✅
RegExp		✅
Set		✅
Map		✅
Error		✅
URL		✅

Rezepte

Superjson unterstützt standardmäßig nur integrierte Datentypen, um die Bündelgröße so gering wie möglich zu halten. Hier sind einige Rezepte, mit denen Sie sich auf Nicht-Default-Datentypen ausdehnen können.

Platzieren Sie sie in eine zentrale Dienstprogrammdatei und stellen Sie sicher, dass sie vor anderen SuperJSON -Anrufen ausgeführt werden. In einem Next.js -Projekt wäre _app.ts ein guter Ort dafür.

Decimal.js / Prisma.Decimal

 import { Decimal } from 'decimal.js' ;

SuperJSON . registerCustom < Decimal , string > (
  {
    isApplicable : ( v ) : v is Decimal => Decimal . isDecimal ( v ) ,
    serialize : v => v . toJSON ( ) ,
    deserialize : v => new Decimal ( v ) ,
  } ,
  'decimal.js'
) ; 

Mitwirkende

Vielen Dank an diese wunderbaren Menschen (Emoji -Schlüssel):

Dylan Brookes ? Euen	Simon Knott ? Euen	Brandon Bayer ?	Jeremy Liberman Euen	Joris	Tomhooijenga ?	ADEMílson F. Tonato Euen
Piotr monwid-olechnowicz ?	Alex Johansson Euen	Simon Edelmann ? ?	Sam Garson ?	Mark Hughes ?	Lxxyx	Máximo Musssini
Peter Dekkers ?	Gabe O'Leary	Benjamin	Ionut-Cristian Florescu ?	Chris Johnson	Nicholas Chiang ?	Datner
Ruessej ?	JH.LEE	Narumincho	Markus Greystone ?	Darthmaim	Max Malm	Tyler Collier
Nick Quebbeman	Tom MacWright ?	Peter Budai ?

Dieses Projekt folgt der All-Contributors-Spezifikation. Beiträge jeglicher Art willkommen!

Siehe auch

Andere Bibliotheken, die ein ähnliches Problem lösen möchten:

• Serialisieren Sie JavaScript von Eric Ferraiuolo
• Abwertung durch Rich Harris
• Nächstes Json von Daniele Ricci