自從我們去年首次宣布TypeID 以來，我們看到了社區的廣泛採用和興趣，社區貢獻了23 種不同語言的客戶端，我們的Typescript 實現每週NPM 下載量達到90,000 次.

上週，我們發布了 Typescript 實作 TypeID-JS 的 1.0 版本。為了慶祝這個版本，我們想分享更多關於我們編寫 TypeID 的原因，以及我們如何使用它來確保 Jetify 的類型安全。

類型安全和唯一標識符

我們在建置 Jetify Cloud 時提出了 TypeID 的想法，Jetify Cloud 是我們在團隊中部署和管理基於 Devbox 或 Docker 的專案的解決方案。 Jetify Cloud 的架構有許多我們需要管理的不同實體：Orgs、Users、Deployments、Secrets 和 Projects，所有這些都需要唯一的識別碼來區分它們。

最初，我們首先遵循最佳實踐並為實體的每個實例分配一個 UUID。儘管如此，我們很快就遇到了一個問題：UUIDv7 缺乏型別安全！以下面程式碼為例：

export const getMember = async (
  memberId: UUID,
  orgId: UUID,
) => {
  const { member, organization } =
    await authClient.organizations.members.get({
      organization_id: orgId,
      member_id: memberId,
    });

  return { member, organization };
};

此函數使用兩個 UUID 來尋找成員和組織。但是，該函數無法確保memberID和orgID代表正確的實體！如果開發人員不小心使用了我們期望的 orgID 的 memberID，我們只會在運行時發現問題。

當我們尋找這個問題的解決方案時，我們遇到了 Stripe 的物件 ID，它使用前綴將類型資訊編碼為 ID。這似乎是一個很好的解決方案，但不幸的是，我們找不到一個明確定義的標準來跨多種語言一致地實現類型化 ID。

TypeID：K可排序、型別安全、全域唯一標識符

TypeID 是我們創造這樣一個一致標準的嘗試。 TypeID 是一個類型安全性、可 K 排序、全域唯一的標識符，其靈感來自 Stripe 的前綴類型。 TypeID 也為其他語言實現其用戶端和函式庫提供了一致的標準。

TypeID 將唯一識別碼編碼為包含三個部分的小寫字串：

1. 表示 ID 類型的前綴（63 個字符，小寫 ASCII 字母）
2. 底線 (_) 分隔符號
3. 使用修改後的 Base32 編碼將 128 位元 UUIDv7 編碼為 26 個字元的字串。

  user_2x4y6z8a0b1c2d3e4f5g6h7j8k
  └──┘ └────────────────────────┘
  type    uuid suffix (base32)

使用此格式，與 TypeID 相容的用戶端可以將類型資訊編碼和解碼到您的 ID 中，然後在建置或編譯時執行檢查以確保您使用正確的 ID。例如，如果我們想為使用者實體建立一個隨機 TypeID，我們可以這樣做：

使用 TypeID，我們還可以向函數添加類型檢查並在運行時捕獲錯誤。重寫上面的範例，我們現在可以確定開發人員將在正確的位置使用正確的 ID：

import { TypeID } from 'typeid-js';

export const getMember = async (
  memberId: TypeID,
  orgId: TypeID,
) => {
    ...
}

除了型別安全之外，這種格式還有一些屬性可以方便開發人員使用：

1. UUIDv7 相容： 您可以透過刪除前綴並解碼後綴輕鬆將 TypeID 轉換為 UUID。
2. K-sortable： 您可以使用 TypeID 作為資料庫中具有良好局部性的可排序主鍵。
3. URL 安全性： 我們在 URL 中使用 TypeID，以便輕鬆複製、貼上和分享。在 URL 中包含 TypeID 可以簡化頁面狀態的產生。
4. 輕鬆選擇：雙擊即可複製貼上（試試看！）

TypeID-JS v1.0 中的新功能

今天，我們宣布推出 TypeID-JS 函式庫的 1.0 版。此更新新增了多項新功能以提高可用性和類型安全性，包括：

1. 未裝箱、基於函數、可串流的 TypeID：這使得序列化 TypeID 成為可能，而無需將其轉換為字串，並允許您使用 TypeID 作為映射和集合中的鍵。
2. 更嚴格的類型和運行時檢查： 如果您嘗試解析空字串或帶有錯誤前綴的 typeid，TypeID 現在會拋出錯誤。
3. 與 TypeID 規範 v3 的兼容性： JS TypeID 現在可以在前綴中使用底線。例如： pro_subscription_2x4y6z8a0b1c2d3e4f5g6h7j8k 是帶有前綴 pro_subscription.
的有效 TypeID

如何在您的專案中使用 TypeID

您可以使用您選擇的 NodeJS 套件管理器將 TypeID 新增至您的 JS 專案。不使用JS？ TypeID 有 26 種不同的實現，從 Go 到 OCaml 到 SQL。如果您有興趣編寫自己的 TypeID 實現，您可以查看我們的正式規範。

希望增強您的開發團隊的實力？

我們的 Jetify 團隊建立了強大的開發人員工具。使用 Jetify Cloud 簡化您的部署和項目，或使用 Devbox 自動載入開發環境。您可以在 Twitter 上關注我們，或在我們的 Discord 伺服器上與我們的開發人員即時聊天。我們也歡迎在我們的 Github 儲存庫上提出問題和拉取請求。