docs: Explain branded types

linz · Feb 1, 2024 · 243ceeb · 243ceeb
1 parent 25f890c
commit 243ceeb
Showing 1 changed file with 8 additions and 0 deletions.
diff --git a/src/utils/types.ts b/src/utils/types.ts
@@ -1,3 +1,11 @@
+/**
+ * Branded types can't be replaced with their underlying types. This means that we can't, for example, pass a `string`
+ * when a function expects a `PathString`. This clarifies the semantics of containers (variables, parameters) while
+ * allowing us to use the values of those containers as plain strings.
+ *
+ * See <https://egghead.io/blog/using-branded-types-in-typescript> for details.
+ */
+
 declare const __brand: unique symbol;
 type Brand<B> = { [__brand]: B };