Effect CommunityEC
Effect Community•5mo ago
sprite

Adding annotation examples for a branded type in Effect Typescript library

What's the best way of adding annotation examples for a branded type?

In the screenshot you will see the 2 TS errors:
- Block-scoped variable 'UserId' used before its declaration.ts(2448)
- Type 'string' is not assignable to type 'Brand<"UserId">'.ts(2322)

A couple of ideas/options I have are:

Option 1: Assign the branded UUID schema to a variable first and then add the annotations:
const BrandedUserId = Schema.UUID.pipe(Schema.brand("UserId"))
export const UserId = BrandedUserId.annotations({
  identifier: "UserId",
  description: "Unique identifier for a user",
  examples: [
    BrandedUserId.make("a81bc81b-dead-4e5d-abff-90865d1e13b1"),
    BrandedUserId.make("123e4567-e89b-12d3-a456-426614174000"),
  ],
})

Option 2: Create the branded type using Brand ...and then use Schema.fromBrand 
type UserId = string & Brand.Brand<"UserId">
const BrandedUserId = Brand.refined<UserId>(...)
export const UserId = Schema.UUID.pipe(Schema.fromBrand(BrandedUserId)).annotations({
  identifier: "UserId",
  description: "Unique identifier for a user",
  examples: [
    BrandedUserId("a81bc81b-dead-4e5d-abff-90865d1e13b1"),
    BrandedUserId("123e4567-e89b-12d3-a456-426614174000"),
  ],
})

...but I prefer inferring the branded type from the schema in option 1.

Are there any other approaches that I'm missing?
Screenshot_2025-08-09_at_18.39.14.png
Was this page helpful?