Quase todas as   requerem serialização de dados. Essa necessidade surge em situações como: aplicações web  Transferência de dados pela rede (por exemplo, solicitações HTTP, WebSockets)  Incorporação de dados em HTML (para hidratação, por exemplo)  Armazenar dados em um armazenamento persistente (como LocalStorage)  Compartilhando dados entre processos (como web workers ou postMessage)  Em muitos casos, a perda ou corrupção de dados pode levar a consequências graves, tornando essencial fornecer um mecanismo de serialização conveniente e seguro que ajude a detectar o maior número possível de erros durante a fase de desenvolvimento. Para esses fins, é conveniente usar   como formato de transferência de dados e TypeScript para verificação de código estático durante o desenvolvimento. JSON  TypeScript serve como um superconjunto de JavaScript, que deve permitir o uso contínuo de funções como   e   , certo? Acontece que, apesar de todos os seus benefícios, o TypeScript não entende naturalmente o que é JSON e quais tipos de dados são seguros para serialização e desserialização em JSON. JSON.stringify JSON.parse  Vamos ilustrar isso com um exemplo.  O problema com JSON no TypeScript  Considere, por exemplo, uma função que salva alguns dados no LocalStorage. Como o LocalStorage não pode armazenar objetos, usamos a serialização JSON aqui:   interface PostComment { authorId: string; text: string; updatedAt: Date; } function saveComment(comment: PostComment) { const serializedComment = JSON.stringify(comment); localStorage.setItem('draft', serializedComment); }  Também precisaremos de uma função para recuperar os dados do LocalStorage.   function restoreComment(): PostComment | undefined { const text = localStorage.getItem('draft'); return text ? JSON.parse(text) : undefined; }  O que há de errado com esse código? O primeiro problema é que ao restaurar o comentário, obteremos um tipo   em vez de   para o campo   . string Date updatedAt  Isso acontece porque JSON possui apenas quatro tipos de dados primitivos (   ,   ,   ,   ), bem como arrays e objetos. Não é possível salvar um objeto   em JSON, assim como outros objetos que se encontram em JavaScript: funções, Mapa, Conjunto, etc. null string number boolean Date  Quando   encontra um valor que não pode ser representado no formato JSON, ocorre a conversão de tipo. No caso de um objeto   , obtemos uma string porque o objeto   implementa o método   , que retorna uma string em vez de um objeto   . JSON.stringify Date Date toJson() Date   const date = new Date('August 19, 1975 23:15:30 UTC'); const jsonDate = date.toJSON(); console.log(jsonDate); // Expected output: "1975-08-19T23:15:30.000Z" const isEqual = date.toJSON() === JSON.stringify(date); console.log(isEqual); // Expected output: true  O segundo problema é que a função   retorna o tipo   , em que o campo de data é do tipo   . Mas já sabemos que em vez de   , receberemos um tipo   . O TypeScript poderia nos ajudar a encontrar esse erro, mas por que não? saveComment PostComment Date Date string  Acontece que, na biblioteca padrão do TypeScript, a função   é digitada como   . Devido ao uso de   , a verificação de tipo está essencialmente desabilitada. Em nosso exemplo, o TypeScript simplesmente aceitou nossa palavra de que a função retornaria um   contendo um objeto   . JSON.parse (text: string) => any any PostComment Date  Esse comportamento do TypeScript é inconveniente e inseguro. Nosso aplicativo poderá travar se tentarmos tratar uma string como um objeto   . Por exemplo, pode quebrar se chamarmos   . Date comment.updatedAt.toLocaleDateString()  Na verdade, em nosso pequeno exemplo, poderíamos simplesmente substituir o objeto   por um carimbo de data/hora numérico, que funciona bem para serialização JSON. No entanto, em aplicações reais, os objetos de dados podem ser extensos, os tipos podem ser definidos em vários locais e identificar tal erro durante o desenvolvimento pode ser uma tarefa desafiadora. Date  E se pudéssemos melhorar a compreensão do TypeScript sobre JSON?  Lidando com serialização  Para começar, vamos descobrir como fazer o TypeScript entender quais tipos de dados podem ser serializados com segurança em JSON. Suponha que queiramos criar uma função   , onde o TypeScript verificará o formato dos dados de entrada para garantir que seja JSON serializável. safeJsonStringify   function safeJsonStringify(data: JSONValue) { return JSON.stringify(data); }  Nesta função, a parte mais importante é o tipo   , que representa todos os valores possíveis que podem ser representados no formato JSON. A implementação é bastante simples: JSONValue   type JSONPrimitive = string | number | boolean | null | undefined; type JSONValue = JSONPrimitive | JSONValue[] | { [key: string]: JSONValue; };  Primeiro, definimos o tipo   , que descreve todos os tipos de dados JSON primitivos. Também incluímos o tipo   com base no fato de que, quando serializadas, as chaves com valor   serão omitidas. Durante a desserialização, essas chaves simplesmente não aparecerão no objeto, o que na maioria dos casos é a mesma coisa. JSONPrimitive undefined undefined  A seguir, descrevemos o tipo   . Este tipo usa a capacidade do TypeScript para descrever tipos recursivos, que são tipos que se referem a si mesmos. Aqui,   pode ser   , uma matriz de   ou um objeto onde todos os valores são do tipo   . Como resultado, uma variável deste tipo   pode conter matrizes e objetos com aninhamento ilimitado. Os valores dentro deles também serão verificados quanto à compatibilidade com o formato JSON. JSONValue JSONValue JSONPrimitive JSONValue JSONValue JSONValue  Agora podemos testar nossa função   usando os seguintes exemplos: safeJsonStringify   // No errors safeJsonStringify({ updatedAt: Date.now() }); // Yields an error: // Argument of type '{ updatedAt: Date; }' is not assignable to parameter of type 'JSONValue'. // Types of property 'updatedAt' are incompatible. // Type 'Date' is not assignable to type 'JSONValue'. safeJsonStringify({ updatedAt: new Date(); });  Tudo parece funcionar corretamente. A função nos permite passar a data como um número, mas gera um erro se passarmos o objeto   . Date  Mas vamos considerar um exemplo mais realista, em que os dados passados para a função são armazenados em uma variável e possuem um tipo descrito.   interface PostComment { authorId: string; text: string; updatedAt: number; }; const comment: PostComment = {...}; // Yields an error: // Argument of type 'PostComment' is not assignable to parameter of type 'JSONValue'. // Type 'PostComment' is not assignable to type '{ [key: string]: JSONValue; }'. // Index signature for type 'string' is missing in type 'PostComment'. safeJsonStringify(comment);  Agora, as coisas estão ficando um pouco complicadas. O TypeScript não nos permite atribuir uma variável do tipo   a um parâmetro de função do tipo   , porque "A assinatura do índice para o tipo 'string' está faltando no tipo 'PostComment'". PostComment JSONValue  Então, o que é uma assinatura de índice e por que ela está faltando? Lembra como descrevemos objetos que podem ser serializados no formato JSON?   type JSONValue = { [key: string]: JSONValue; };  Neste caso,   é a assinatura do índice. Significa "este objeto pode ter quaisquer chaves na forma de strings, cujos valores possuem o tipo   ". Então, precisamos adicionar uma assinatura de índice ao tipo   , certo? [key: string] JSONValue PostComment   interface PostComment { authorId: string; text: string; updatedAt: number; // Don't do this: [key: string]: JSONValue; };  Fazer isso implicaria que o comentário poderia conter campos arbitrários, o que normalmente não é o resultado desejado ao definir tipos de dados em um aplicativo.  A verdadeira solução para o problema com a assinatura do índice vem de   , que permitem iterar recursivamente os campos, mesmo para tipos que não possuem uma assinatura de índice definida. Combinado com genéricos, esse recurso permite converter qualquer tipo de dados   em outro tipo   , que seja compatível com o formato JSON. Mapped Types T JSONCompatible<T>   type JSONCompatible<T> = unknown extends T ? never : { [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible<T[P]>; }; type NotAssignableToJson = | bigint | symbol | Function;  O tipo   é um tipo mapeado que inspeciona se um determinado tipo   pode ser serializado com segurança em JSON. Ele faz isso iterando cada propriedade no tipo   e fazendo o seguinte: JSONCompatible<T> T T  O   o tipo condicional verifica se o tipo da propriedade é compatível com o tipo   , garantindo que ela possa ser convertida para JSON com segurança. Quando for esse o caso, o tipo da propriedade permanece inalterado. T[P] extends JSONValue ? T[P] : ... JSONValue  O   o tipo condicional verifica se o tipo da propriedade não pode ser atribuído ao JSON. Nesse caso, o tipo da propriedade é convertido em   , filtrando efetivamente a propriedade do tipo final. T[P] extends NotAssignableToJson ? never : ... never  Se nenhuma dessas condições for atendida, o tipo é verificado recursivamente até que uma conclusão possa ser feita. Dessa forma funciona mesmo que o tipo não possua assinatura de índice.  A   check no início é usado para evitar que o tipo   seja convertido em um tipo de objeto vazio   , que é essencialmente equivalente ao tipo   . unknown extends T ? never :... unknown {} any  Outro aspecto interessante é o tipo   . Consiste em duas primitivas TypeScript (bigint e símbolo) e o tipo   , que descreve qualquer função possível. O tipo   é crucial para filtrar quaisquer valores que não sejam atribuíveis ao JSON. Isso ocorre porque qualquer objeto complexo em JavaScript é baseado no tipo Object e possui pelo menos uma função em sua cadeia de protótipo (por exemplo,   ). O tipo   itera sobre todas essas funções, portanto, verificar as funções é suficiente para filtrar qualquer coisa que não seja serializável para JSON. NotAssignableToJson Function Function toString() JSONCompatible  Agora, vamos usar este tipo na função de serialização:   function safeJsonStringify<T>(data: JSONCompatible<T>) { return JSON.stringify(data); }  Agora, a função usa um parâmetro genérico   e aceita o argumento   . Isso significa que é necessário um argumento   do tipo   , que deve ser um tipo compatível com JSON. Agora podemos usar a função com tipos de dados sem assinatura de índice. T JSONCompatible<T> data T  A função agora usa um parâmetro genérico   que se estende do tipo   . Isso significa que ele aceita um argumento   do tipo   , que deve ser um tipo compatível com JSON. Como resultado, podemos utilizar a função com tipos de dados que não possuem assinatura de índice. T JSONCompatible<T> data T   interface PostComment { authorId: string; text: string; updatedAt: number; } function saveComment(comment: PostComment) { const serializedComment = safeJsonStringify(comment); localStorage.setItem('draft', serializedComment); }  Essa abordagem pode ser usada sempre que a serialização JSON for necessária, como transferência de dados pela rede, incorporação de dados em HTML, armazenamento de dados em localStorage, transferência de dados entre trabalhadores, etc. Além disso, o auxiliar   pode ser usado quando um objeto estritamente digitado sem uma assinatura de índice precisa ser atribuída a uma variável do tipo   . toJsonValue JSONValue   function toJsonValue<T>(value: JSONCompatible<T>): JSONValue { return value; } const comment: PostComment = {...}; const data: JSONValue = { comment: toJsonValue(comment) };  Neste exemplo, usar   nos permite ignorar o erro relacionado à falta de assinatura de índice no tipo   . toJsonValue PostComment  Lidando com desserialização  Quando se trata de desserialização, o desafio é mais simples e mais complexo ao mesmo tempo porque envolve verificações de análise estática e verificações de tempo de execução para o formato dos dados recebidos.  Da perspectiva do sistema de tipos do TypeScript, o desafio é bastante simples. Vamos considerar o seguinte exemplo:   function safeJsonParse(text: string) { return JSON.parse(text) as unknown; } const data = JSON.parse(text); // ^? unknown  Neste caso, estamos substituindo o tipo de retorno   pelo tipo   . Por que escolher   ? Essencialmente, uma string JSON pode conter qualquer coisa, não apenas os dados que esperamos receber. Por exemplo, o formato dos dados pode mudar entre diferentes versões do aplicativo ou outra parte do aplicativo pode gravar dados na mesma chave LocalStorage. Portanto,   é a escolha mais segura e precisa. any unknown unknown unknown  Entretanto, trabalhar com o tipo   é menos conveniente do que simplesmente especificar o tipo de dados desejado. Além da conversão de tipo, existem várias maneiras de converter o tipo   no tipo de dados necessário. Um desses métodos é utilizar a biblioteca   para validar dados em tempo de execução e gerar erros detalhados se os dados forem inválidos. unknown unknown Superstruct   import { create, object, number, string } from 'superstruct'; const PostComment = object({ authorId: string(), text: string(), updatedAt: number(), }); // Note: we no longer need to manually specify the return type function restoreDraft() { const text = localStorage.getItem('draft'); return text ? create(JSON.parse(text), PostComment) : undefined; }  Aqui, a função   atua como um protetor de tipo,   o tipo à interface   desejada. Conseqüentemente, não precisamos mais especificar manualmente o tipo de retorno. create restringindo Comment  Implementar uma opção de desserialização segura é apenas metade da história. É igualmente crucial não se esquecer de usá-lo ao realizar a próxima tarefa do projeto. Isso se torna particularmente desafiador se uma equipe grande estiver trabalhando no projeto, pois pode ser difícil garantir que todos os acordos e melhores práticas sejam seguidos.    pode ajudar nesta tarefa. Esta ferramenta ajuda a identificar todos os casos de uso   . Especificamente, todos os usos de   podem ser encontrados e pode-se garantir que o formato dos dados recebidos seja verificado. Mais sobre como se livrar de   tipo em uma base de código pode ser lido no artigo   . Typescript-eslint any JSON.parse any Tornando o TypeScript verdadeiramente "fortemente digitado"  Conclusão  Aqui estão as funções e tipos de utilitários finais projetados para auxiliar na serialização e desserialização segura de JSON. Você pode testá-los no   preparado. TS Playground   type JSONPrimitive = string | number | boolean | null | undefined; type JSONValue = JSONPrimitive | JSONValue[] | { [key: string]: JSONValue; }; type NotAssignableToJson = | bigint | symbol | Function; type JSONCompatible<T> = unknown extends T ? never : { [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible<T[P]>; }; function toJsonValue<T>(value: JSONCompatible<T>): JSONValue { return value; } function safeJsonStringify<T>(data: JSONCompatible<T>) { return JSON.stringify(data); } function safeJsonParse(text: string): unknown { return JSON.parse(text); }  Eles podem ser usados em qualquer situação em que a serialização JSON seja necessária.  Tenho usado essa estratégia em meus projetos há vários anos e ela demonstrou sua eficácia ao detectar prontamente possíveis erros durante o desenvolvimento de aplicativos.  Espero que este artigo tenha fornecido a você alguns insights novos. Obrigado por ler!  Links Úteis   Tornando o TypeScript verdadeiramente "fortemente digitado"   Melhorando os tipos de biblioteca padrão do TypeScript   A biblioteca superestutu   Parque infantil

The code in this story is for educational purposes. The readers are solely responsible for whatever they build with it.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

This story contains AI-generated text. The author has used AI either for research, to generate outlines, or write the text itself. 

Dominando a serialização JSON com segurança de tipo em TypeScript

About Author

COMENTARIOS

Rótulos

ESTE ARTIGO FOI APRESENTADO EM

Related Stories

Vazamento do prompt do sistema Claude Sonnet 3.5: uma análise forense

Digital Nomads Ouçam: O que você precisa saber sobre o novo visto DTV da Tailândia

Modelo Bitcoin UTXO, alimentando um ecossistema único

Como melhorar seu fluxo de trabalho em 10 vezes: 17 aplicativos essenciais

Vazamento do prompt do sistema Claude Sonnet 3.5: uma análise forense

Digital Nomads Ouçam: O que você precisa saber sobre o novo visto DTV da Tailândia

Modelo Bitcoin UTXO, alimentando um ecossistema único

Como melhorar seu fluxo de trabalho em 10 vezes: 17 aplicativos essenciais

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps