TSON

TSON 是一个可扩展的 JSON 解析器，涵盖了更多的数据类型，是 JSON 的严格超集。

TSON 最初作为 Milkio 的一部分，后续为了使前端及其他工程可用而被分离出来，作为一个独立的 npm 包发布。

TSON 的作用是什么

在数据传输过程中，序列化和反序列化是不可避免的步骤。JSON 是互联网上最常见的数据序列化协议，但它缺少了一些当今所需的新类型 (如 bigint、Date 等)。另一方面，Protocol 是一个看起来更好的选择，但是它太重了，而且不是专为 JavaScript 生态设计的。TSON 填补了这一空白，作为一个可扩展的 JSON 解析器，它提供了更多的数据类型，使得在传输数据时更加便捷和灵活。这使得我们可以在 JavaScript 环境中处理更为丰富的数据结构，而不仅仅局限于 JSON 定义的基本数据类型。

安装

Milkio 内置了 TSON，你发送的所有参数在接收并解析时，返回给前端的结果实际上都是通过 TSON 实现的。如果你正在使用 Milkio，无需安装，直接通过以下方式使用即可。

import { TSON } from "milkio";

对于前端开发者而言，你可以选择将 Milkio 的响应视为普通的 JSON，并按照常规方式处理它们。或者，你可以安装 TSON，并利用其功能，将一些有用的类型自动还原为原始对象，以便更方便地操作这些数据。这使得你可以更轻松地处理那些包含了更多复杂数据类型的响应，无需手动转换和处理。

# bun
bun add @southern-aurora/tson

# npm
npm install @southern-aurora/tson

使用

TSON 与 JSON 兼容，在大多数情况下，你可以简单地将代码中所有的 JSON 替换为 TSON。

序列化：

TSON.stringify({ hello: "world", date: new Date(0), url: new URL("https://example.com") });
// Output: '{"hello":"world","date":"t!Date:1970-01-01T00:00:00.000Z","url":"t!URL:https://example.com/"}'

反序列化：

TSON.parse(`{"hello":"world","date":"t!Date:1970-01-01T00:00:00.000Z","url":"t!URL:https://example.com/"}`);
// Output: { hello: "world", date: 1970-01-01T00:00:00.000Z, url: URL {...} }

原理

TSON 会将 JSON 不支持的类型转换为字符串表示，例如："t!Date:1970-01-01T00:00:00.000Z"。

该字符串由 TSON 前缀 t!、原对象的名称、和原对象的内容组成。原对象的内容会尽可能地被序列化为，可直接放置在对象构造函数中以便恢复的形式。你可以通过判断一个字符串是否以 t! 开头，来判断它是否是一个 TSON 前缀。

默认支持的类型

类型	JSON	TSON
string	✅	✅
number	✅	✅
boolean	✅	✅
null	✅	✅
Array	✅	✅
Object	✅	✅
bigint	❌	✅
Date	❌	✅
RegExp	❌	✅
URL	❌	✅
Uint8Array	❌	✅
ArrayBuffer	❌	✅

注意：虽然 TSON 支持 Uint8Array 和 ArrayBuffer 类型，便于在网络传输中传递二进制文件。但这并不总是一个好主意，因为你还需要考虑分块传输、网络波动、带宽成本等因素。也许你实际所需的是类似于 AWS S3或 Tencent Cloud COS的服务？

扩展更多类型

TSON 仅内置了常用的类型，你可以扩展更多类型。以常用的日期库 Day.js 为例。

import * as dayjs from "dayjs";

TSON.rules.stringify.push({
  match: (v) => v.$d instanceof Date,
  handler: (v: bigint) => `t!dayjs:${v.$d.toISOString()}`,
});

TSON.rules.parse.push({
  match: (v) => v.startsWith("t!dayjs:"),
  handler: (v: string) => dayjs(v.slice("t!dayjs:".length)),
});

我们通过判断一个对象是否存在 $d 属性，且该属性的值为 Date 类型来判断是否是 Day.js 日期对象。如果是，我们将其序列化为以 t!dayjs: 开头的字符串，以便在 JSON 中合法存储。注意，添加 TSON 规则的代码需要位于使用 TSON 的代码之前。

更多内置类型？

TSON 对于添加更多内置类型非常谨慎，我们只会将常见的可能用于网络传输的类型内置到 TSON 中。以下类型虽然常见，但我们永远不会内置支持。

undefined

JavaScript 会将不存在的值隐式转换为 undefined，因此在大多数情况下，你并不需要 TSON 支持 undefined 即可取到为 undefined 的值。而支持 undefined 将会增加传输的数据量。

Set & Map

大多数情况下，Set和Map 可以使用 Array & Object 来代替，并且它们可以轻松地与 Array & Object 相互转换。而且 Set & Map 语义是独立于 JSON 之外的，有些团队可能会倾向于使用 Set & Map 作为 Array & Object 的替代，来试图在某些场景下获得轻微的性能优势，但这么做除了会增加开发者的心智负担外，在 TSON 中序列化他们会拥有更低的性能，因为它们将被序列化两次。因此，TSON 不会内置支持 Set & Map。

Symbols

在网络传输中，我们无法保证他们是相等的，你是否在寻找 cuid2 或者其他类似的方案？

Function

序列化函数涉及到许多问题，例如上下文中的变量以及潜在的安全风险。因此，TSON 永远不会内置支持函数。如果你想要将某些函数共享给前端，请考虑是否将其抽离成 npm 包是更好的解决方案。