Scalability #1: Semantic types are awesome

When I worked at Brainstud I was introduced to a type strategy which I'll refer to as "semantic typing". Essentially you create types that represent the semantics of that value, not just its primitive shape. This comes in handy when working in a team or on a large codebase.

:::note Type aliases like type ID = string are purely semantic and interchangeable at compile time. If you need to prevent mixing values like UserId and PostId, you can use branded types. This will be covered in a later article. :::

It's up to you how far you take this. The idea is to make it clear what the value actually is, since an id can be a string or integer, and a timestamp can be a number or a string.

Instead of having generic types like so:

1type Post = {2	id: string | number3	content: string4	createdAt: number | string5	updatedAt: number | string6}

You define explicit semantics:

1export type ID = string2export type Timestamp = string

Then create a base.types.ts to avoid redefining shapes over and over:

1import { ID, Timestamp } from './semantics'2 3export type Timestamps = {4	createdAt: Timestamp5	updatedAt: Timestamp6}7 8export type Entity = {9	id: ID10} & Timestamps

This ensures consistency. We're almost certain that every persisted object will (or should) have an id, createdAt, and updatedAt. In the drizzle article I cover optionally deletedAt usage.

This might seem like overengineering, but it greatly reduces onboarding time and discrepancies. It prevents the "Wait, is usage time in milliseconds (number) or an ISO string?" questions months down the line. And not only that, it sets guidelines to follow instead of free-for-all.

A Full Domain Example

This is the frontend part of the implementation. For the backend I use a similar strategy which you can read in Part two: Scalable Drizzle ORM setup.

I'll be showcasing the code I have running in production for Skriuw. The source for semantics and base types lives in the shared package.

In my domain logic for creating notes, utilizing the base types yields this:

1export type Note = Entity & {2	name: string3	content: string4	icon?: string5	coverImage?: string6	tags?: string[]7	parentFolderId?: ID8	pinned?: boolean9	pinnedAt?: Timestamp10	favorite?: boolean11	isPublic?: boolean12	publicId?: string | null13	userId?: ID14	type: 'note'15}

TypeScript ensures the Note type automatically inherits id, createdAt, and updatedAt via the intersection.

Building on this, domain models become self documenting:

1import { Entity } from './base'2import { ID, Timestamp } from './semantics'3 4export type User = Entity & {5	username: string6	email: string7	avatarUrl?: string8	bio?: string9	role: 'admin' | 'author' | 'reader'10}11 12export type Post = Entity & {13	authorId: ID14	title: string15	slug: string16	content: string17	published: boolean18	publishedAt?: Timestamp19	tags: string[]20}21 22export type Comment = Entity & {23	postId: ID24	authorId: ID25	content: string26	parentId?: ID27}

Why is this better?

1. Refactoring is trivial at the type level: If you decide to switch your IDs from string UUIDs to number auto increments, you change it in one place (types/semantics.ts), and it propagates everywhere.
2. Intent is clear: When you see content: string versus a more specific semantic type, you know how it should be treated.
3. Cross referencing: authorId: ID tells you exactly what kind of value is expected there, matching the id field of the User entity.

The Generic Data Access Layer

The real power of semantic typing shines when combined with a generic data access layer. Instead of writing a specific function to create a Note, and another to create a Tag, you write a single generic create function.

By using a generic constraint like T extends Entity, you tell TypeScript: "I don't care what specific object this is, whether it's a Note, a User, or a settings config, as long as it adheres to my base entity semantics."

1export async function create<T extends Entity>(2	storageKey: string,3	data: T4): Promise<T> {5	// implementation6}

This ensures that your data layer is predictable and consistent. It is impossible to accidentally pass an object that does not have an ID or timestamps to your database layer, the compiler will not allow it.

By defining your semantics upfront, what an ID is, what a timestamp is, and what an Entity must look like, you stop writing defensive code to check if properties exist, and start writing domain logic that just works.