Identifiers

This page discusses the concepts of identifiers in relational models within Better-Core.

Identifier Algorithm

After evaluating UUID v4, UUID v7, Snowflake IDs, and sequential identifiers, and others, we selected ULID as the standard for our database software.

We chose ULID because it delivers sortable, timestamp-aware IDs that cluster sequential writes on disk for better insert performance, requires zero coordination unlike Snowflake IDs, embeds queryable creation time without extra columns,and presents a cleaner, more URL-safe format than UUID v7 - all while being battle-tested in production systems like Discord and Auth0 since 2015.

Branded Identifiers Types

Better-Core provides branded identifier types to help create a type-safe identifier for your models.

import type { Id } from "better-core";

export type User = {
    id: Id<"user">; 
	name: string;
	email: string;
	emailVerified: boolean;
	createdAt: Date;
	updatedAt: Date;
};

export type Session = {
    id: Id<"session">; 
    userId: Id<"user">; 
    createdAt: Date;
    updatedAt: Date;
    expiresAt: Date;
    token: string;
    ipAddress: string;
    userAgent: string;
};

Branded identifiers are useful as they provide a type-safe way to identify models, which means that the compiler will show type errors when you try to use an identifier of the wrong type.

// Function that expects a user id
function findUser(userId: Id<"user">) {}

// Works!
findUser(user.id); 

// Error!
findUser(session.id);
Argument of type 'Id<"session">' is not assignable to parameter of type 'Id<"user">'.
  Type 'Id<"session">' is not assignable to type '{ __brand: "user"; }'.
    Types of property '__brand' are incompatible.
      Type '"session"' is not assignable to type '"user"'.

// Function that expects a user or session id
function findUserOrSession(id: Id<"user" | "session">) {}

// Works!
findUserOrSession(user.id);

// Works!
findUserOrSession(session.id);

// Error!
findUserOrSession('some-random-id');
Argument of type 'string' is not assignable to parameter of type 'Id<"user" | "session">'.
  Type 'string' is not assignable to type '{ __brand: "user" | "session"; }'.