С тех пор, как мы впервые анонсировали TypeID в прошлом году, мы стали свидетелями значительного принятия и интереса со стороны сообщества: сообщество предоставило 23 различных языковых клиента и 90 000 еженедельных загрузок NPM нашей реализации Typescript. .

На прошлой неделе мы выпустили версию 1.0 нашей реализации Typescript, TypeID-JS. Чтобы отметить этот выпуск, мы хотели рассказать больше о том, почему мы написали TypeID и как мы используем его для обеспечения безопасности типов в Jetify.

Типовая безопасность и уникальные идентификаторы

Мы разработали идею TypeID при создании Jetify Cloud, нашего решения для развертывания и управления проектами на основе Devbox или Docker в вашей команде. Архитектура Jetify Cloud включает в себя множество различных объектов, которыми нам нужно управлять: организации, пользователи, развертывания, секреты и проекты, для различения которых требуются уникальные идентификаторы.

Изначально мы начали с того, что следовали лучшим практикам и присваивали 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 представляют правильный объект! Если разработчик случайно использует идентификатор участника вместо ожидаемого идентификатора организации, мы обнаружим проблему только во время выполнения.

Пока мы искали решение этой проблемы, мы столкнулись с идентификатором объекта Stripe, который кодирует информацию о типе в идентификаторы с помощью префикса. Это казалось отличным решением, но, к сожалению, мы не смогли найти четко определенного стандарта для последовательной реализации типизированных идентификаторов на нескольких языках.

TypeID: глобальные уникальные идентификаторы с возможностью K-сортировки, типобезопасности.

TypeID — это наша попытка создать такой последовательный стандарт. TypeID — это безопасный по типу, K-сортируемый, глобальный уникальный идентификатор, созданный на основе префиксных типов Stripe. TypeID также предоставляет согласованный стандарт для других языков для реализации своих клиентов и библиотек.

TypeID кодируют уникальные идентификаторы в виде строки нижнего регистра, состоящей из трех частей:

1. Префикс, обозначающий тип идентификатора (63 символа, строчные буквы ASCII)
2. Разделитель подчеркивание (_)
3. 128-битный UUIDv7, закодированный как 26-символьная строка с использованием модифицированной кодировки Base32.

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

С помощью этого формата клиент, совместимый с TypeID, может кодировать и декодировать информацию о типе в ваши идентификаторы, а затем запускать проверки во время сборки или компиляции, чтобы убедиться, что вы используете правильный идентификатор. Например, если бы мы хотели создать случайный TypeID для пользовательской сущности, мы могли бы сделать что-то вроде этого:

С помощью TypeID мы также можем добавлять проверки типов в наши функции и выявлять ошибки во время выполнения. Переписав приведенный выше пример, мы теперь можем быть уверены, что разработчики будут использовать правильные идентификаторы в нужном месте:

import { TypeID } from 'typeid-js';

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

Помимо безопасности типов, этот формат имеет несколько свойств, которые делают его удобным для использования разработчиками:

1. Совместимость с UUIDv7: Вы можете легко преобразовать TypeID в UUID, удалив префикс и декодировав суффикс.
2. K-sortable: Вы можете использовать TypeID в качестве сортируемого первичного ключа в вашей базе данных с хорошей локальностью.
3. Безопасность URL-адресов: Мы используем TypeID в наших URL-адресах, чтобы их можно было легко копировать, вставлять и делиться. Включение TypeID в URL-адрес упрощает создание состояния страницы.
4. Легко выбрать: Вы можете скопировать и вставить его, дважды щелкнув (Попробуйте!)

Новые возможности в TypeID-JS v1.0

Сегодня мы анонсируем версию 1.0 нашей библиотеки TypeID-JS. В этом обновлении добавлено несколько новых функций для повышения удобства использования и безопасности типов, в том числе:

1. Неупакованные, основанные на функциях, потоковые идентификаторы типов: это позволяет сериализовать идентификаторы типа без приведения их к строкам и позволяет использовать идентификаторы типа в качестве ключей в картах и ​​наборах.
2. Более строгая проверка типов и времени выполнения: TypeID теперь выдает ошибку, если вы пытаетесь проанализировать пустую строку или идентификатор типа с неверным префиксом.
3. Совместимость со спецификацией TypeID v3: JS TypeID теперь может использовать символы подчеркивания в префиксе. Например: pro_subscription_2x4y6z8a0b1c2d3e4f5g6h7j8k — это действительный TypeID с префиксом pro_subscription.

Как использовать TypeID в вашем проекте

Вы можете добавить TypeID в свой JS-проект, используя выбранный вами менеджер пакетов NodeJS. Не используете JS? TypeID имеет 26 различных реализаций, от Go до OCaml и SQL. Если вы заинтересованы в написании собственной реализации TypeID, вы можете ознакомиться с нашей официальной спецификацией.

Хотите усилить свою команду разработчиков?

Наша команда Jetify создает мощные инструменты для разработчиков. Упростите свои развертывания и проекты с помощью Jetify Cloud или автоматизируйте внедрение сред разработки с помощью Devbox. Вы можете следить за нами в Твиттере или общаться с нашими разработчиками в прямом эфире на нашем сервере Discord. Мы также приветствуем проблемы и запросы на включение в нашем репозитории Github.