add branded type

package.json

@@ -23,6 +23,7 @@
     "pnpm": ">=9.1.0"
   },
   "devDependencies": {
+    "@type-challenges/utils": "0.1.1",
     "@types/node": "20.12.11",
     "eslint": "9.2.0",
     "typescript": "5.4.5",

types/Branded.test.ts

@@ -0,0 +1,57 @@
+import type { Equal, Expect, NotEqual } from '@type-challenges/utils'
+import { expect, test } from 'vitest'
+import { raise } from '../raise/index.js'
+import { Branded } from './Branded.ts'
+
+/** branded numbers */
+type Age = Branded<number, 'Age'>
+type Year = Branded<number, 'Year'>
+
+const validAge = (age: number): Age | undefined =>
+  age >= 0 && age <= 125 ? age as Age : undefined
+
+const birthYear = (age: Age, now: Date): Year =>
+  now.getFullYear() - age as Year // it's incorrect, but sufficient for demo purpose
+
+test('birthYear is compile-time safe', () => {
+  const fiveYears = validAge(5) ?? raise('invalid age')
+  expect(
+    birthYear(fiveYears, new Date(2024, 4, 11))
+  ).toBe(2019)
+})
+
+test('birthYear is compile-time safe', () => {
+  expect(
+    // @ts-expect-error argument must be Age
+    birthYear(5, new Date(2024, 4, 11))
+  ).toBe(2019)
+})
+
+const someAge = validAge(5) ?? raise('invalid age')
+const someBirthYear = birthYear(someAge, new Date(2024, 4, 11))
+
+// @ts-ignore unused
+type AgeTests = [
+  Expect<Equal<typeof someAge, Age>>,
+  Expect<NotEqual<typeof someAge, number>>,
+  Expect<Equal<Parameters<typeof validAge>, [number]>>,
+  Expect<Equal<Parameters<typeof birthYear>, [Age, Date]>>,
+  Expect<Equal<typeof someBirthYear, Year>>,
+  Expect<NotEqual<typeof someBirthYear, number>>,
+]
+
+/** branded string */
+type Email = Branded<string, 'Email'>
+
+const emailRegex = /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/
+const validEmail = (email: string): Email | undefined =>
+  emailRegex.test(email) ? email as Email : undefined
+
+const someEmail = validEmail('[email protected]') ?? raise('invalid email')
+
+// @ts-ignore unused
+type EmailTests = [
+  Expect<Equal<typeof someEmail, Email>>,
+  Expect<NotEqual<typeof someEmail, string>>,
+  Expect<Equal<Parameters<typeof validEmail>, [string]>>,
+]

types/Branded.ts

@@ -0,0 +1,3 @@
+declare const __brand: unique symbol
+type Brand<B> = { [__brand]: B }
+export type Branded<T, B> = T & Brand<B>

types/index.ts

@@ -1 +1,2 @@
+export * from './Branded.ts'
 export * from './DeepPartial.ts'