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. 

Este áudio é produzido no idioma original da história!

Muito longo; Para ler

Making security fun one episode at a time

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

Muito longo; Para ler

Maksim Zemskov

STORY’S CREDIBILITY

Code License

Guide

AI-assisted

About Author

Rótulos

Languages

ESTE ARTIGO FOI APRESENTADO EM...

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

Muito longo; Para ler

Maksim Zemskov

STORY’S CREDIBILITY

Code License

Guide

AI-assisted

About Author

Rótulos

Languages

ESTE ARTIGO FOI APRESENTADO EM...

HISTÓRIAS RELACIONADAS