Desde que anunciamos o TypeID pela primeira vez no ano passado, vimos uma adoção e interesse significativos da comunidade, com 23 clientes de idiomas diferentes contribuídos pela comunidade e 90.000 downloads NPM semanais de nossa implementação Typescript .

Na semana passada, lançamos a versão 1.0 de nossa implementação Typescript, TypeID-JS. Para comemorar este lançamento, gostaríamos de compartilhar mais sobre por que escrevemos TypeID e como o usamos para garantir a segurança de tipo no Jetify.

Digite segurança e identificadores exclusivos

Desenvolvemos a ideia do TypeID enquanto construímos o Jetify Cloud, nossa solução para implantar e gerenciar projetos baseados em Devbox ou Docker em sua equipe. A arquitetura do Jetify Cloud tem muitas entidades diferentes que precisamos gerenciar: organizações, usuários, implantações, segredos e projetos, todos os quais exigem identificadores exclusivos para distingui-los.

Originalmente, começamos seguindo as práticas recomendadas e atribuindo um UUID a cada instância de uma entidade. Ainda assim, rapidamente encontramos um problema: falta segurança de tipo ao UUIDv7! Tome o código abaixo como exemplo:

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 };
};

Esta função usa dois UUIDs para procurar um membro e uma organização. No entanto, a função não pode garantir que memberID e orgID representem a entidade correta! Se um desenvolvedor usar acidentalmente um memberID onde esperávamos um orgID, só descobriríamos o problema em tempo de execução.

Enquanto procurávamos soluções para esse problema, encontramos o Object ID do Stripe, que codifica informações de tipo em IDs usando um prefixo. Parecia uma ótima solução, mas, infelizmente, não conseguimos encontrar um padrão bem definido para implementar consistentemente IDs digitados em vários idiomas.

TypeID: identificadores K-classificáveis, de tipo seguro e globalmente exclusivos

TypeID é nossa tentativa de criar um padrão tão consistente. TypeID é um identificador globalmente exclusivo, com segurança de tipo, classificável por K, inspirado nos tipos prefixados do Stripe. TypeID também fornece um padrão consistente para outras linguagens implementarem seus clientes e bibliotecas.

TypeIDs codificam identificadores exclusivos como uma string minúscula com três partes:

1. Um prefixo que representa o tipo do ID (63 caracteres, letras ASCII minúsculas)
2. Um separador de sublinhado (_)
3. Um UUIDv7 de 128 bits codificado como uma string de 26 caracteres usando uma codificação base32 modificada.

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

Com esse formato, um cliente compatível com TypeID pode codificar e decodificar informações de tipo em seus IDs e, em seguida, executar verificações em tempo de construção ou compilação para garantir que você está usando o ID correto. Por exemplo, se quiséssemos criar um TypeID aleatório para uma entidade de usuário, poderíamos fazer algo assim:

Com TypeID, também podemos adicionar verificações de tipo às nossas funções e detectar erros em tempo de execução. Reescrevendo o exemplo acima, agora podemos ter certeza de que os desenvolvedores usarão os IDs adequados no lugar certo:

import { TypeID } from 'typeid-js';

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

Além da segurança de tipo, esse formato tem algumas propriedades que o tornam fácil de usar pelos desenvolvedores:

1. Compatível com UUIDv7: Você pode facilmente converter um TypeID em um UUID removendo o prefixo e decodificando o sufixo.
2. K-classificável: Você pode usar um TypeID como uma chave primária classificável em seu banco de dados com boa localidade.
3. URL seguro: Usamos TypeIDs em nossos URLs para facilitar a cópia, colagem e compartilhamento. Incluir TypeIDs no URL simplifica a geração do estado da página.
4. Facilmente selecionável: Você pode copiar e colar clicando duas vezes (Experimente!)

Novos recursos no TypeID-JS v1.0

Hoje, estamos anunciando a versão 1.0 de nossa biblioteca TypeID-JS. Esta atualização adiciona vários novos recursos para melhorar a usabilidade e a segurança de digitação, incluindo:

1. TypeIDs sem caixa, baseados em função e transmitíveis: Isso torna possível serializar TypeIDs sem convertê-los em strings e permite usar TypeIDs como chaves em mapas e conjuntos.
2. Verificação mais rigorosa de tipo e tempo de execução: TypeID agora gera um erro se você tentar analisar uma string vazia ou um typeid com o prefixo errado.
3. Compatibilidade com especificação TypeID v3: TypeIDs JS agora podem usar sublinhados no prefixo. Por exemplo: pro_subscription_2x4y6z8a0b1c2d3e4f5g6h7j8k é um TypeID válido com prefixo pro_subscription.

Como usar TypeID com seu projeto

Você pode adicionar TypeID ao seu projeto JS usando o gerenciador de pacotes NodeJS de sua preferência. Não está usando JS? TypeID tem 26 implementações diferentes, variando de Go para OCaml a SQL. Se você estiver interessado em escrever sua própria implementação de TypeID, você pode verificar nossa especificação formal.

Procurando fortalecer sua equipe de desenvolvimento?

Nossa equipe no Jetify cria ferramentas poderosas para desenvolvedores. Simplifique suas implantações e projetos com Jetify Cloud ou automatize a integração de ambientes de desenvolvimento com Devbox. Você pode nos seguir no Twitter ou conversar com nossos desenvolvedores ao vivo em nosso servidor Discord. Também aceitamos problemas e solicitações pull em nosso repositório Github.