Téléchargement superjson - Téléchargement du code source superjson

superjson

Autre code source

v2.2.2

Télécharger

superjson

Sérialisez en toute sécurité les expressions JavaScript à un superset de JSON, qui comprend des dates, des grandsints, etc.

Caractéristiques clés

? Sérialisation et désérialisation fiables
? Type de sécurité avec l'observance automatique
? Empreinte d'exécution négligeable
? Cadre agnostique
? Correction parfaite pour les limitations de sérialisation de Next.js dans getServerSideProps et getInitialProps

Trame de fond

Chez Blitz, nous avons lutté avec les limites de JSON. Nous nous retrouvons souvent en travaillant avec Date , Map , Set ou BigInt , mais JSON.stringify ne supporte aucun d'entre eux sans passer par les tracas de convertir manuellement!

Superjson résout ces problèmes en fournissant un emballage mince sur JSON.stringify et JSON.parse .

Commencer

Installez la bibliothèque avec votre gestionnaire de packages de choix, par exemple:

 yarn add superjson

Utilisation de base

La façon la plus simple d'utiliser Superjson est avec ses fonctions stringify et parse . Si vous savez comment utiliser JSON.stringify , vous connaissez déjà Superjson!

Stringifiez facilement toute expression que vous souhaitez:

 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"}}}'

Et analyser votre json comme ça:

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

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

Utilisation avancée

Pour les cas où vous souhaitez un accès de niveau inférieur au json et meta dans la sortie, vous pouvez utiliser les fonctions serialize et deserialize .

Un excellent cas d'utilisation pour cela est l'endroit où vous avez une API que vous souhaitez être compatible JSON pour tous les clients, mais vous souhaitez également transmettre les méta-données afin que les clients puissent utiliser Superjson pour le désérialiser pleinement.

Par exemple:

 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'],
  }
};
*/

Utilisation avec Next.js

Les crochets de données getServerSideProps , getInitialProps et getStaticProps fournis par Next.js ne vous permettent pas de transmettre des objets JavaScript comme les dates. Il errera à moins que vous ne convertiez les dates en chaînes, etc.

Heureusement, Superjson est un outil parfait pour contourner cette limitation!

Plugin suivant.js SWC (expérimental, v13 ou supérieur)

Next.js Les plugins SWC sont expérimentaux, mais promettent une accélération importante. Pour utiliser le plugin Superjson SWC, installez-le et ajoutez-le à votre next.config.js :

yarn add next-superjson-plugin

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

Next.js (Transform Babel stable)

Installez la bibliothèque avec votre gestionnaire de packages de choix, par exemple:

yarn add babel-plugin-superjson-next

Ajoutez le plugin à votre .babelrc. Si vous n'en avez pas, créez-le.

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

Fait! Vous pouvez maintenant utiliser tous les données JS dans votre getServerSideProps / etc.

API

sérialiser

Sérialise toute valeur JavaScript dans un objet compatible JSON.

Exemples

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

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

Renvoie json et meta , les deux valeurs compatibles JSON.

désérialiser

Désérialise la sortie de Superjson dans votre valeur d'origine.

Exemples

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

deserialize ( { json , meta } ) ;

Renvoie your original value .

chasser

Sérialise puis stringifie votre valeur javascript.

Exemples

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

const jsonString = stringify ( object ) ;

Renvoie string .

analyse

Parses puis désérialise la chaîne JSON renvoyée par stringify .

Exemples

 const jsonString = stringify ( object ) ;

parse ( jsonString ) ;

Renvoie your original value .

Superjson prend en charge de nombreux types supplémentaires que JSON ne fait pas. Vous pouvez sérialiser tous ces éléments:

taper	Soutenu par JSON standard?	Soutenu par Superjson?
`string`	✅	✅
`number`	✅	✅
`boolean`	✅	✅
`null`	✅	✅
`Array`	✅	✅
`Object`	✅	✅
`undefined`		✅
`bigint`		✅
`Date`		✅
`RegExp`		✅
`Set`		✅
`Map`		✅
`Error`		✅
`URL`		✅

Recettes

Superjson par défaut ne prend en charge que les types de données intégrés pour maintenir la taille du bundle aussi bas que possible. Voici quelques recettes que vous pouvez utiliser pour étendre aux types de données non défaut.

Placez-les dans un fichier utilitaire central et assurez-vous qu'ils sont exécutés avant tout autre appel SuperJSON . Dans un projet suivant.js, _app.ts serait un bon endroit pour cela.

`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'
) ;

Contributeurs

Merci à ces gens merveilleux (clé emoji):

_{Dylan Brookes} ? ️	_{Simon Knott} ? ️	_{Brandon Bayer} ?	_{Jeremy Liberman} ️	_Joris	_tomhooijenga ?	_{Ademílson F. Tonato} ️
_{Piotr monwid-olechnowicz} ?	_{Alex Johansson} ️	_{Simon Edelmann} ? ?	_{Sam Garson} ?	_{Mark Hughes} ?	_Lxxyx	_{Máximo Mussini}
_{Peter Dekkers} ?	_{Gabe O'Leary}	_Benjoin	_{Ionut-critian Florescu} ?	_{Chris Johnson}	_{Nicholas Chiang} ?	_Datner
_ruessej ?	_Jh.lee	_narumincho	_{Markus Greystone} ?	_darthmaim	_{Max Malm}	_{Tyler Collier}
_{Nick Québbeman}	_{Tom MacWright} ?	_{Peter Budai} ?