superjson

JavaScriptの式をJSONのスーパーセットに安全にシリアル化します。これには、日付、Bigintなどを含む。

重要な機能

• ？信頼性の高いシリアル化と脱派化
• ？オートコンプリートで安全をタイプします
• ？無視できるランタイムフットプリント
• ？フレームワーク不可知論者
• ？ getServerSidePropsとgetInitialPropsのnext.jsのシリアル化の制限に最適な修正

バックストーリー

Blitzでは、JSONの限界に苦しんでいます。私たちはしばしばDate 、 Map 、 Set 、またはBigIntで作業していますが、 JSON.stringify手動で変換する手間をかけずにそれらのいずれもサポートしていません！

Superjsonは、 JSON.stringifyとJSON.parseに薄いラッパーを提供することにより、これらの問題を解決します。

スポンサー

NumiによるSuperjsonロゴ：

はじめる

選択したパッケージマネージャーと一緒にライブラリをインストールします。

 yarn add superjson

基本的な使用法

Superjsonを使用する最も簡単な方法は、 stringifyとparse機能を使用することです。 JSON.stringify使用方法を知っている場合は、すでにSuperjsonを知っています！

希望する表現を簡単に文字化する：

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

そして、あなたのjsonをそうするように次のように解析します：

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

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

高度な使用

出力内のjsonデータとmetaデータへのより低いレベルのアクセスを必要とする場合、 serializeおよびdeserialize機能を使用できます。

これの素晴らしいユースケースの1つは、すべてのクライアントにJSONに互換性のあるAPIを使用していることですが、クライアントがSuperJSONを使用して完全に脱色できるようにメタデータを送信したい場合もあります。

例えば：

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

next.jsで使用します

getServerSideProps 、 getInitialProps 、およびgetStaticPropsデータフックは、next.jsによって提供されます。日付を文字列などに変換しない限りエラーが発生します。

ありがたいことに、Superjsonはその制限をバイパスするのに最適なツールです！

next.js SWCプラグイン（実験、V13以上）

Next.js SWCプラグインは実験的ですが、重要なスピードアップを約束します。 SuperJson SWCプラグインを使用するには、インストールしてnext.config.jsに追加します：

yarn add next-superjson-plugin

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

next.js（安定したバベル変換）

選択したパッケージマネージャーと一緒にライブラリをインストールします。

yarn add babel-plugin-superjson-next

.babelrcにプラグインを追加します。持っていない場合は、作成してください。

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

終わり！これで、 getServerSideProps /などですべてのJSデータ型を安全に使用できます。

API

シリアライズ

JavaScript値をJSON互換オブジェクトにシリアル化します。

例

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

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

jsonとmetaを返します。どちらもJSON互換値です。

脱介入

Superjsonの出力を元の値に戻します。

例

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

deserialize ( { json , meta } ) ;

your original valueを返します。

stringify

JavaScript値をシリアル化してから弦楽器に貼り付けます。

例

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

const jsonString = stringify ( object ) ;

stringを返します。

解析

stringifyによって返されたJSON文字列を解析してから脱必要にします。

例

 const jsonString = stringify ( object ) ;

parse ( jsonString ) ;

your original valueを返します。

---

Superjsonは、JSONがそうではない多くの余分なタイプをサポートしています。これらすべてをシリアル化できます：

タイプ	Standard JSONによってサポートされていますか？	Superjsonによってサポートされていますか？
string	✅	✅
number	✅	✅
boolean	✅	✅
null	✅	✅
Array	✅	✅
Object	✅	✅
undefined		✅
bigint		✅
Date		✅
RegExp		✅
Set		✅
Map		✅
Error		✅
URL		✅

レシピ

SuperJsonはデフォルトでは、組み込みのデータ型のみをサポートして、バンドルサイズをできるだけ低く保つことができます。以下は、非デフォルトデータ型まで拡張するために使用できるレシピをいくつか紹介します。

いくつかの中央ユーティリティファイルにそれらを配置し、他のSuperJSONコールの前に実行されることを確認してください。 next.jsプロジェクトでは、 _app.tsそのための良い場所になります。

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

貢献者

これらの素晴らしい人々に感謝します（絵文字キー）：

ディラン・ブルックス ？ショ和	サイモン・ノット ？ショ和	ブランドンバイエル ？	ジェレミーリベルマン ショ和	ジョリス	Tomhooijenga ？	アデミルソンF.トナト ショ和
Piotr Monwid-Olechnowicz ？	アレックスヨハンソン ショ和	サイモン・エデルマン ？ ？	サム・ガーソン ？	マーク・ヒューズ ？	lxxyx	MáximoMussini
ピーター・デッカーズ ？	Gabe O'Leary	ベンジャミン	イオン・クリスタン・フロレスク ？	クリス・ジョンソン	ニコラス・チェン ？	ダットナー
ruessej ？	jh.lee	ナルミチョ	マルクスグレイストーン ？	ダルメイム	マックスマルム	タイラー・コリアー
ニック・ケッベマン	トム・マクライト ？	ピーター・ブダイ ？

このプロジェクトは、全委員会の仕様に従います。あらゆる種類の貢献を歓迎します！

参照してください

同様の問題を解決することを目的とした他のライブラリ：

• Eric FerraiuoloによるJavaScriptのシリアル化
• リッチ・ハリスによる価値ある
• ダニエレ・リッチによる次のjson