Download de superjson - Download de código fonte superjson

superjson

Outro código-fonte

v2.2.2

Baixar

Superjson

Serialize com segurança expressões de JavaScript a um superset de JSON, que inclui datas, bigints e muito mais.

Principais recursos

? Serialização confiável e desserialização
? Tipo de segurança com conclusão automática
? Pegada de tempo de execução desprezível
? Framework Agnóstico
? Fix perfeita para as limitações de serialização do Next.JS no getServerSideProps e getInitialProps

História de fundo

Na Blitz, lutamos com as limitações do JSON. Muitas vezes nos encontramos trabalhando com Date , Map , Set ou BigInt , mas JSON.stringify não suporta nenhum deles sem passar pelo aborrecimento de converter manualmente!

Superjson resolve esses problemas, fornecendo um embalagem fino sobre JSON.stringify e JSON.parse .

Patrocinadores

Superjson logotipo por numi:

Começando

Instale a biblioteca com o seu gerenciador de pacotes de escolha, por exemplo:

 yarn add superjson

Uso básico

A maneira mais fácil de usar o Superjson é com suas funções stringify e parse . Se você sabe usar JSON.stringify , já conhece Superjson!

Rigram facilmente qualquer expressão que você desejar:

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

E analisar seu json como assim:

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

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

Uso avançado

Para os casos em que você deseja acesso de nível mais baixo aos dados json e meta na saída, você pode usar as funções serialize e deserialize .

Um excelente caso de uso para isso é onde você tem uma API que deseja ser compatível com JSON para todos os clientes, mas ainda deseja transmitir os meta -dados para que os clientes possam usar o Superjson para desfilá -lo totalmente.

Por exemplo:

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

Usando com o próximo.js

Os ganchos de dados getServerSideProps , getInitialProps e getStaticProps fornecidos pelo Next.js não permitem que você transmita objetos JavaScript, como datas. Ele errará, a menos que você converta datas em strings, etc.

Felizmente, Superjson é uma ferramenta perfeita para ignorar essa limitação!

Next.JS SWC Plugin (Experimental, V13 ou acima)

Os plug -ins SWC do próximo.js são experimentais, mas prometem uma aceleração significativa. Para usar o plug -in Superjson SWC, instale -o e adicione -o ao seu next.config.js :

yarn add next-superjson-plugin

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

Next.js (transformada estável Babel)

Instale a biblioteca com o seu gerenciador de pacotes de escolha, por exemplo:

yarn add babel-plugin-superjson-next

Adicione o plug -in ao seu .babelrc. Se você não tiver um, crie -o.

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

Feito! Agora você pode usar com segurança todos os tipos de dados JS em seu getServerSideProps / etc.

API

serializar

Serializa qualquer valor JavaScript em um objeto compatível com JSON.

Exemplos

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

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

Retorna json e meta , ambos os valores compatíveis com JSON.

Desserialize

Desserializa a saída do Superjson de volta ao seu valor original.

Exemplos

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

deserialize ( { json , meta } ) ;

Retorna your original value .

stringify

Serializa e depois rigem seu valor JavaScript.

Exemplos

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

const jsonString = stringify ( object ) ;

Retorna string .

analisar

Passa e, em seguida, desaperializa a string json retornada por stringify .

Exemplos

 const jsonString = stringify ( object ) ;

parse ( jsonString ) ;

Retorna your original value .

Superjson suporta muitos tipos extras que JSON não. Você pode serializar tudo isso:

tipo	Apoiado pelo JSON padrão?	Apoiado por Superjson?
`string`	✅	✅
`number`	✅	✅
`boolean`	✅	✅
`null`	✅	✅
`Array`	✅	✅
`Object`	✅	✅
`undefined`		✅
`bigint`		✅
`Date`		✅
`RegExp`		✅
`Set`		✅
`Map`		✅
`Error`		✅
`URL`		✅

Receitas

Superjson Por padrão suporta apenas tipos de dados internos para manter o tamanho do pacote o mais baixo possível. Aqui estão algumas receitas que você pode usar para se estender a tipos de dados não padrão.

Coloque -os em algum arquivo de utilitário central e verifique se eles são executados antes de quaisquer outras ligações SuperJSON . Em um projeto Next.js, _app.ts seria um bom local para isso.

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

Colaboradores

Obrigado a essas pessoas maravilhosas (key emoji):

_{Dylan Brookes} ? ️	_{Simon Knott} ? ️	_{Brandon Bayer} ?	_{Jeremy Liberman} ️	_Joris	_Tomhooijenga ?	_{Ademílson F. Tonato} ️
_{PIOTR MONWID-ALECHNOWICZ} ?	_{Alex Johansson} ️	_{Simon Edelmann} ? ?	_{Sam Garson} ?	_{Mark Hughes} ?	_Lxxyx	_{Máximo Mussini}
_{Peter Dekkers} ?	_{Gabe O'Leary}	_Benjamin	_{Florescu Ionut-Cristã} ?	_{Chris Johnson}	_{Nicholas Chiang} ?	_Datner
_Ruessej ?	_JH.LEE	_Narumincho	_{Markus Greystone} ?	_Darthmaim	_{Max Malm}	_{Tyler Collier}
_{Nick Quebbeman}	_{Tom Macwright} ?	_{Peter Budai} ?