superjson

安全地将JavaScript序列化与JSON的超集，其中包括日期，bigints等。

关键功能

• ？可靠的序列化和挑选化
• ？与自动完成键入安全性
• ？可以忽略的运行时足迹
• ？框架不可知论
• ？ Next.js在getServerSideProps和getInitialProps中的序列化限制的完美修复

背景故事

在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功能。

一个很棒的用例是，您拥有希望与所有客户端兼容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一起使用

Next.js提供的getServerSideProps ， getInitialProps和getStaticProps数据挂钩不允许您像日期这样传输JavaScript对象。除非您将日期转换为字符串等，否则它将出错。

值得庆幸的是，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（稳定的Babel Transform）

使用您选择的软件包管理器安装库，例如：

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没有的许多额外类型。您可以序列化所有这些：

类型	由标准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'
) ; 

贡献者

谢谢这些好人（表情符号钥匙）：

迪伦·布鲁克斯 ？配x	西蒙·诺特（Simon Knott） ？配x	布兰登·拜耳 ？	杰里米·利比曼（Jeremy Liberman） 配x	乔里斯	tomhooijenga ？	AdemílsonF。Tonato 配x
piotr monwid-olechnowicz ？	亚历克斯·约翰逊 配x	西蒙·埃德曼（Simon Edelmann） ？ ？	山姆·加森 ？	马克·休斯 ？	lxxyx	máximo墨西尼
彼得·德克斯 ？	Gabe O'Leary	本杰明	离子 - 佛罗里达州的弗洛雷斯库 ？	克里斯·约翰逊	尼古拉斯·清 ？	Datner
Ruessej ？	JH.Lee	Narumincho	马库斯·格雷斯通 ？	达斯米姆	马克斯·马尔姆（Max Malm）	泰勒·科利尔（Tyler Collier）
尼克·奎斯曼（Nick Quebbeman）	汤姆·麦克赖特 ？	彼得·布泰 ？

该项目遵循全企业规范。欢迎任何形式的贡献！

参见

旨在解决类似问题的其他库：

• Eric Ferraiuolo序列化JavaScript
• Rich Harris的贬值
• Daniele Ricci的Next-json