superjson

Безопасно сериализуйте экспрессию JavaScript на суперсет JSON, который включает в себя даты, бигинты и многое другое.

Ключевые функции

• ? Надежная сериализация и десериализация
• ? Безопасность типа с автозаполнением
• ? Незначительное время выполнения
• ? Структура агностик
• ? Идеальное исправление для ограничений сериализации Next.js в getServerSideProps и getInitialProps

Предыстория

В Blitz мы боролись с ограничениями JSON. Мы часто работаем с Date , Map , Set или BigInt , но JSON.stringify не поддерживает ни один из них, не проходя через хлопоты вручную вручную!

Superjson решает эти проблемы, предоставляя тонкую обертку над JSON.stringify и JSON.parse .

Спонсоры

Логотип Superjson от Numi:

Начиная

Установите библиотеку с выбранным менеджером пакетов, например:

 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 .

Одним из отличных вариантов использования это то, где у вас есть API, который вы хотите быть совместимыми с JSON для всех клиентов, но вы также хотите передать метаданные, чтобы клиенты могли использовать 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 Data Clocs, предоставленные Next.js, не позволяют вам передавать объекты JavaScript, такие как даты. Это будет ошибка, если вы не преобразуете даты в строки и т. Д.

К счастью, Superjson - идеальный инструмент для обойти это ограничение!

Next.js SWC плагин (экспериментальный, V13 или выше)

Следующие плагины 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" // ?
  ]
}

Сделанный! Теперь вы можете безопасно использовать все DataTypes JS в ваших getServerSideProps / и т. Д.

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 .

строка

Сериализуется, а затем строит ваше значение JavaScript.

Примеры

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

const jsonString = stringify ( object ) ;

Возвращает string .

разбор

Подготовки, а затем десериализуют строку JSON, возвращаемая stringify .

Примеры

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

Участники

Спасибо этим замечательным людям (ключ эмодзи):

Дилан Брукс ? ️	Саймон Нотт ? ️	Брэндон Байер ?	Джереми Либерман ️	Йорис	Tomhooijenga ?	Адемилсон Ф. Тонато ️
ПИОТР МОНВИД-Олечнович ?	Алекс Йоханссон ️	Саймон Эдельманн ? ?	Сэм Гарсон ?	Марк Хьюз ?	Lxxyx	Массини Массини
Питер Деккерс ?	Гейб О'Лири	Бенджамин	Ионут-Кристиан Флорско ?	Крис Джонсон	Николас Чианг ?	Datner
Ruessej ?	JH.lee	Наруминчо	Маркус Грейстон ?	Дартмайм	Макс Мальм	Тайлер Коллиер
Ник Квеббман	Том Макрайт ?	Питер Будай ?

Этот проект следует за спецификацией всех контролей. Взносы любого вида приветствуются!

Смотрите также

Другие библиотеки, которые стремятся решить аналогичную проблему:

• Сериализовать javascript от Эрика Феррайуоло
• деваль с Рич Харрисом
• Next-Json от Даниэле Риччи