superjson

날짜, bigints 등을 포함한 JSON의 슈퍼 세트로 JavaScript 표현식을 안전하게 직렬화하십시오.

주요 기능

• ? 신뢰할 수있는 직렬화 및 사막화
• ? 자동 완성으로 안전을 입력하십시오
• ? 무시할 수있는 런타임 풋 프린트
• ? 프레임 워크 Agnostic
• ? getServerSideProps 및 getInitialProps 에서 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 기능을 사용할 수 있습니다.

이에 대한 훌륭한 사용 사례 중 하나는 모든 클라이언트와 호환되는 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'],
  }
};
*/ 

다음에 사용하여 JS

getServerSideProps , getInitialProps 및 getStaticProps Next.js에서 제공하는 데이터 후크는 날짜와 같은 JavaScript 객체를 전송할 수 없습니다. 날짜를 문자열로 변환하지 않으면 오류가 발생합니다.

고맙게도 Superjson은 그 한계를 우회하는 완벽한 도구입니다!

다음 .js SWC 플러그인 (실험, v13 이상)

Next.js SWC 플러그인은 실험적이지만 상당한 속도를 약속합니다. Superjson SWC 플러그인을 사용하려면 설치하고 next.config.js 에 추가하십시오 .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 반환합니다.

사형화

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 호출하기 전에 실행되도록하십시오. 다음.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'
) ; 

기고자

이 멋진 사람들에게 감사합니다 (이모티콘 키) :

딜런 브룩스 ? 켈	사이먼 노트 ? 켈	브랜든 바이어 ?	제레미 리버먼 켈	Joris	Tomhooijenga ?	Ademílson F. Tonato 켈
Piotr Monwid-Orechnowicz ?	알렉스 요한슨 켈	사이먼 에델만 ? ?	샘 가슨 ?	마크 휴즈 ?	lxxyx	Máximo Mussini
피터 데크 커스 ?	Gabe O'Leary	베냐민	Ionut-Cristian Florescu ?	크리스 존슨	니콜라스 치앙 ?	DATNER
Ruessej ?	JH.Lee	나루민 초	Markus Greystone ?	다트 마임	MAX MALM	타일러 콜리어
Nick Quebbeman	톰 맥라이트 ?	피터 부다이 ?

이 프로젝트는 All-Contritors 사양을 따릅니다. 모든 종류의 공헌을 환영합니다!

참조하십시오

유사한 문제를 해결하는 것을 목표로하는 다른 라이브러리 :

• Eric Ferraiuolo의 직렬화 JavaScript
• Rich Harris의 평가 절하
• Daniele Ricci의 다음 Json