Освоение типобезопасной сериализации JSON в TypeScript

Почти каждое требует сериализации данных. Такая необходимость возникает в таких ситуациях, как: веб-приложение Передача данных по сети (например, HTTP-запросы, WebSockets) Встраивание данных в HTML (например, для гидратации) Хранение данных в постоянном хранилище (например, LocalStorage) Обмен данными между процессами (например, веб-работниками или postMessage) Во многих случаях потеря или повреждение данных может привести к серьезным последствиям, поэтому крайне важно обеспечить удобный и безопасный механизм сериализации, который помогает обнаружить как можно больше ошибок на этапе разработки. Для этих целей удобно использовать в качестве формата передачи данных и TypeScript для статической проверки кода во время разработки. JSON TypeScript представляет собой расширенную версию JavaScript, которая должна обеспечить беспрепятственное использование таких функций, как и , верно? Оказывается, несмотря на все свои преимущества, TypeScript, естественно, не понимает, что такое JSON и какие типы данных безопасны для сериализации и десериализации в JSON. JSON.stringify JSON.parse Проиллюстрируем это примером. Проблема с JSON в TypeScript Рассмотрим, например, функцию, которая сохраняет некоторые данные в LocalStorage. Поскольку LocalStorage не может хранить объекты, здесь мы используем сериализацию JSON: interface PostComment { authorId: string; text: string; updatedAt: Date; } function saveComment(comment: PostComment) { const serializedComment = JSON.stringify(comment); localStorage.setItem('draft', serializedComment); } Нам также понадобится функция для получения данных из LocalStorage. function restoreComment(): PostComment | undefined { const text = localStorage.getItem('draft'); return text ? JSON.parse(text) : undefined; } Что не так с этим кодом? Первая проблема заключается в том, что при восстановлении комментария мы получим для поля тип вместо . updatedAt string Date Это происходит потому, что JSON имеет только четыре примитивных типа данных ( , , , ), а также массивы и объекты. Невозможно сохранить объект в JSON, а также другие объекты, которые встречаются в JavaScript: функции, Map, Set и т. д. null string number boolean Date Когда встречает значение, которое невозможно представить в формате JSON, происходит приведение типов. В случае объекта мы получаем строку, поскольку объект реализует метод , который возвращает строку вместо объекта . 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 Вторая проблема заключается в том, что функция возвращает тип , в котором поле даты имеет тип . Но мы уже знаем, что вместо мы получим тип. TypeScript мог бы помочь нам найти эту ошибку, но почему бы и нет? saveComment PostComment Date Date string Оказывается, в стандартной библиотеке TypeScript функция записывается как . Из-за использования проверка типов по существу отключена. В нашем примере TypeScript просто поверил нам на слово, что функция вернет , содержащий объект . JSON.parse (text: string) => any any PostComment Date Такое поведение TypeScript неудобно и небезопасно. Наше приложение может аварийно завершить работу, если мы попытаемся обращаться со строкой как с объектом . Например, он может сломаться, если мы вызовем . Date comment.updatedAt.toLocaleDateString() Действительно, в нашем небольшом примере мы могли бы просто заменить объект числовой меткой времени, что хорошо подходит для сериализации JSON. Однако в реальных приложениях объекты данных могут быть обширными, типы могут определяться в нескольких местах, и выявление такой ошибки во время разработки может оказаться сложной задачей. Date Что, если бы мы могли улучшить понимание JSON в TypeScript? Работа с сериализацией Для начала давайте разберемся, как заставить TypeScript понять, какие типы данных можно безопасно сериализовать в JSON. Предположим, мы хотим создать функцию , где TypeScript проверит формат входных данных, чтобы убедиться, что они сериализуемы в формате JSON. safeJsonStringify function safeJsonStringify(data: JSONValue) { return JSON.stringify(data); } В этой функции наиболее важной частью является тип , который представляет все возможные значения, которые могут быть представлены в формате JSON. Реализация довольно проста: JSONValue type JSONPrimitive = string | number | boolean | null | undefined; type JSONValue = JSONPrimitive | JSONValue[] | { [key: string]: JSONValue; }; Сначала мы определяем тип , который описывает все примитивные типы данных JSON. Мы также включаем тип, поскольку при сериализации ключи с значением будут опущены. При десериализации эти ключи просто не появятся в объекте, что в большинстве случаев одно и то же. JSONPrimitive undefined undefined Далее мы опишем тип . Этот тип использует способность TypeScript описывать рекурсивные типы, которые ссылаются сами на себя. Здесь может быть , массивом или объектом, все значения которого имеют тип . В результате переменная типа может содержать массивы и объекты с неограниченной вложенностью. Значения внутри них также будут проверены на совместимость с форматом JSON. JSONValue JSONValue JSONPrimitive JSONValue JSONValue JSONValue Теперь мы можем протестировать нашу функцию , используя следующие примеры: 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(); }); Кажется, все работает правильно. Функция позволяет нам передавать дату в виде числа, но выдает ошибку, если мы передаем объект . Date Но давайте рассмотрим более реалистичный пример, в котором данные, передаваемые в функцию, хранятся в переменной и имеют описанный тип. 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); Теперь все становится немного сложнее. TypeScript не позволит нам присвоить переменную типа параметру функции типа , поскольку «В типе PostComment отсутствует сигнатура индекса для типа 'string'». PostComment JSONValue Итак, что такое индексная подпись и почему она отсутствует? Помните, как мы описывали объекты, которые можно сериализовать в формат JSON? type JSONValue = { [key: string]: JSONValue; }; В данном случае — это подпись индекса. Это означает, что «данный объект может иметь любые ключи в виде строк, значения которых имеют тип ». Получается, нам нужно добавить индексную подпись к типу , верно? [key: string] JSONValue PostComment interface PostComment { authorId: string; text: string; updatedAt: number; // Don't do this: [key: string]: JSONValue; }; Это будет означать, что комментарий может содержать любые произвольные поля, что обычно не является желаемым результатом при определении типов данных в приложении. Реальное решение проблемы с сигнатурой индекса можно найти в , которые позволяют рекурсивно перебирать поля даже для типов, для которых не определена сигнатура индекса. В сочетании с дженериками эта функция позволяет преобразовывать любой тип данных в другой тип , совместимый с форматом JSON. Mapped Types T JSONCompatible type JSONCompatible = unknown extends T ? never : { [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible ; }; type NotAssignableToJson = | bigint | symbol | Function; Тип — это сопоставленный тип, который проверяет, можно ли безопасно сериализовать данный тип в JSON. Это делается путем перебора каждого свойства типа и выполнения следующих действий: JSONCompatible T T условный тип проверяет, совместим ли тип свойства с типом , гарантируя, что его можно безопасно преобразовать в JSON. В этом случае тип свойства остается неизменным. T[P] extends JSONValue ? T[P] : ... JSONValue условный тип проверяет, нельзя ли назначить тип свойства JSON. В этом случае тип свойства преобразуется в , что эффективно отфильтровывает свойство из окончательного типа. T[P] extends NotAssignableToJson ? never : ... never Если ни одно из этих условий не выполняется, тип проверяется рекурсивно до тех пор, пока не будет сделан вывод. Таким образом, это работает, даже если тип не имеет индексной подписи. проверка в начале используется для предотвращения преобразования типа в пустой тип объекта , который по сути эквивалентен типу. unknown extends T ? never :... unknown {} any Еще один интересный аспект — тип . Он состоит из двух примитивов TypeScript (bigint и символ) и типа , который описывает любую возможную функцию. Тип имеет решающее значение для фильтрации любых значений, которые нельзя присвоить JSON. Это связано с тем, что любой сложный объект в JavaScript основан на типе Object и имеет хотя бы одну функцию в цепочке прототипов (например, ). Тип выполняет итерацию по всем этим функциям, поэтому проверки функций достаточно, чтобы отфильтровать все, что не сериализуется в JSON. NotAssignableToJson Function Function toString() JSONCompatible Теперь давайте используем этот тип в функции сериализации: function safeJsonStringify (data: JSONCompatible ) { return JSON.stringify(data); } Теперь функция использует общий параметр и принимает аргумент . Это означает, что он принимает аргумента типа , который должен быть типом, совместимым с JSON. Теперь мы можем использовать функцию с типами данных без индексной подписи. T JSONCompatible data T Функция теперь использует универсальный параметр , который наследуется от типа . Это означает, что он принимает аргумента типа , который должен быть JSON-совместимым типом. В результате мы можем использовать эту функцию с типами данных, у которых нет сигнатуры индекса. T JSONCompatible data T interface PostComment { authorId: string; text: string; updatedAt: number; } function saveComment(comment: PostComment) { const serializedComment = safeJsonStringify(comment); localStorage.setItem('draft', serializedComment); } Этот подход можно использовать всякий раз, когда необходима сериализация JSON, например, при передаче данных по сети, встраивании данных в HTML, хранении данных в localStorage, передаче данных между рабочими процессами и т. д. Кроме того, хелпер можно использовать, когда строго типизированный объект без подпись индекса необходимо присвоить переменной типа . toJsonValue JSONValue function toJsonValue (value: JSONCompatible ): JSONValue { return value; } const comment: PostComment = {...}; const data: JSONValue = { comment: toJsonValue(comment) }; В этом примере использование позволяет нам обойти ошибку, связанную с отсутствием подписи индекса в типе . toJsonValue PostComment Работа с десериализацией Когда дело доходит до десериализации, задача одновременно проще и сложнее, поскольку она включает в себя как статический анализ, так и проверку формата полученных данных во время выполнения. С точки зрения системы типов TypeScript задача довольно проста. Давайте рассмотрим следующий пример: function safeJsonParse(text: string) { return JSON.parse(text) as unknown; } const data = JSON.parse(text); // ^? unknown В этом случае мы заменяем возвращаемый тип типом. Почему выбирают ? По сути, строка JSON может содержать что угодно, а не только данные, которые мы ожидаем получить. Например, формат данных может меняться в разных версиях приложения или другая часть приложения может записывать данные в один и тот же ключ LocalStorage. Поэтому — самый безопасный и точный выбор. any unknown unknown unknown Однако работать с типом менее удобно, чем просто указывать нужный тип данных. Помимо приведения типов, существует несколько способов преобразования типа в требуемый тип данных. Одним из таких методов является использование библиотеки для проверки данных во время выполнения и выдачи подробных ошибок, если данные недействительны. 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; } Здесь функция действует как защита типа, тип до желаемого интерфейса . Следовательно, нам больше не нужно вручную указывать тип возвращаемого значения. create сужая Comment Реализация опции безопасной десериализации — это только половина дела. Не менее важно не забывать использовать его при решении следующей задачи проекта. Это становится особенно сложно, если над проектом работает большая команда, поскольку обеспечить соблюдение всех соглашений и передового опыта может быть сложно. может помочь в этой задаче. Этот инструмент помогает выявить все случаи использования. В частности, можно найти все случаи использования и гарантировать, что формат полученных данных проверен. Подробнее об избавлении от типа в кодовой базе можно прочитать в статье . Typescript-eslint any JSON.parse any Making TypeScript Truly «Strongly Typeded» Заключение Вот окончательные служебные функции и типы, предназначенные для безопасной сериализации и десериализации JSON. Вы можете протестировать их на подготовленной . площадке TS Playground type JSONPrimitive = string | number | boolean | null | undefined; type JSONValue = JSONPrimitive | JSONValue[] | { [key: string]: JSONValue; }; type NotAssignableToJson = | bigint | symbol | Function; type JSONCompatible = unknown extends T ? never : { [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible ; }; function toJsonValue (value: JSONCompatible ): JSONValue { return value; } function safeJsonStringify (data: JSONCompatible ) { return JSON.stringify(data); } function safeJsonParse(text: string): unknown { return JSON.parse(text); } Их можно использовать в любой ситуации, когда необходима сериализация JSON. Я использую эту стратегию в своих проектах уже несколько лет, и она продемонстрировала свою эффективность, оперативно выявляя потенциальные ошибки при разработке приложений. Я надеюсь, что эта статья предоставила вам новые идеи. Спасибо за чтение! Полезные ссылки Делаем TypeScript по-настоящему «строго типизированным» Улучшение типов стандартной библиотеки TypeScript Суперструктурная библиотека ТС игровая площадка