Merge pull request #32 from Coder-Spirit/the-big-refactor

feat!: introduce brands & flavors

Author: castarco

README.md

@@ -14,19 +14,11 @@ It offers three kinds of nominal types:
   They are very useful when dealing with "rigid" code generators or other cases
   where we would be forced to write tons of mappings just to content the type
   checker.
-- **Tags:** As you might imagine, *tags* allow us to "attach" multiple nominal
-  types to a same variable. They are very useful to express things like:
-  - *roles & capabilities*: some times interfaces & classes are not enough, we
-    might need or want to encode many roles and/or capabilities at the same
-    time for a single entity, and to use the type checker to enforce
-    constraints based on that information.
-  - *logical/mathematical properties*: each attached *tag* can be interpreted
-    as, in some way, a property assertion (for example we could attach
-    properties like *positive*, *odd* or *prime* to a number, at the same time).
-
-On top of these three kinds of nominal type, `Nominal` also offers
-[taint tracking](https://en.wikipedia.org/wiki/Taint_checking) capabilities with
-zero runtime overhead.
+- **Properties:** They are very useful to express things like logical and
+  mathematical properties.
+
+While each type can only have either a *brand* or a *flavor*, we can easily
+combine *brands* or *flavors* with *properties*.
 
 ## Install instructions
 
@@ -50,265 +42,161 @@ import { ... } from 'https://deno.land/x/nominal@[VERSION]/nominal/deno/index.ts
 
 ## Brands
 
-Pending explanation.
-## Flavors
-
-Pending explanation.
-
-## Tags
-
-### Basic tags
-
-To define a new tagged type based on a previous type, we can do:
-
 ```typescript
-import { WithTag } from '@coderspirit/nominal'
+import { WithBrand } from '@coderspirit/nominal'
+
+type Email = WithBrand<string, 'Email'>
+type Username = WithBrand<string, 'Username'>
 
-type Prime = WithTag<number, 'Prime'>
+const email: Email = '[email protected]' as Email // Ok
+const user: Username = 'admin' as Username // Ok
+const text: string = email // OK
+const anotherText: string = user // Ok
 
-const myPrime: Prime = 23 as Prime
+const eMail: Email = '[email protected]' // Error, as we don't have a cast here
+const mail: Email = user // Error, as the brands don't match
 ```
 
 #### **Advice**
 - Although we perform a "static cast" here, this should be done only when:
   - the value is a literal (as in the example)
   - in validation, sanitization and/or anticorruption layers.
 - One way to protect against other developers "forging" the type is to use
-  symbols instead of strings as "type tags" when defining the new nominal type.
-
-### Combining tags
+  symbols instead of strings as property keys or property values when defining
+  the new nominal type.
 
-`WithTag` has been implemented in a way that allows us to easily compose many
-nominal types for a same value:
+## Flavors
 
 ```typescript
-import { WithTag, WithTags } from '@coderspirit/nominal'
+import { WithFlavor } from '@coderspirit/nominal'
 
-type Integer = WithTag<number, 'Integer'>
-type Even = WithTag<number, 'Even'>
-type Positive = WithTag<number, 'Positive'>
+type Email = WithFlavor<string, 'Email'>
+type Username = WithFlavor<string, 'Username'>
 
-// The first way is by adding "tags" to an already "tagged" type
-type EvenInteger = WithTag<Integer, 'Even'>
+const email: Email = '[email protected]' as Email // Ok
+const user: Username = 'admin' as Username // Ok
+const text: string = email // OK
+const anotherText: string = user // Ok
 
-// The second way is by adding many "tags" at the same time
-type EvenPositive = WithTags<number, ['Even', 'Positive']>
+const eMail: Email = '[email protected]' // Ok, flavors are more flexible than brands
+const mail: Email = user // Error, as the flavors don't match
 ```
 
-#### **Interesting properties**
-- `WithTag` and `WithTags` are additive, commutative and idempotent.
-- The previous point means that we don't have to worry about the order of
-  composition, we won't suffer typing inconsistencies because of that.
-
-#### **Unused type tags can be preserved across function boundaries**
-
-This feature can be very useful when we need to verify many properties for the
-same value and we don't want to lose this information along the way as the value
-is passed from one function to another.
-
-```typescript
-function throwIfNotEven<T extends number>(v: T): WithTag<T, 'Even'> {
-  if (v % 2 == 1) throw new Error('Not Even!')
-  return v as WithTag<T, 'Even'>
-}
-
-function throwIfNotPositive<T extends number>(v: T): WithTag<T, 'Positive'> {
-  if (v <= 0) throw new Error('Not positive!')
-  return v as WithTag<T, 'Positive'>
-}
-
-const v1 = 42
+#### **Advice**
+- Although we perform a "static cast" here, this should be done only when:
+  - the value is a literal (as in the example)
+  - in validation, sanitization and/or anticorruption layers.
+- One way to protect against other developers "forging" the type is to use
+  symbols instead of strings as property keys or property values when defining
+  the new nominal type.
 
-// typeof v2 === WithTag<number, 'Even'>
-const v2 = throwIfNotEven(v1)
 
-// typeof v3 === WithTags<number, ['Even', 'Positive']>
-const v3 = throwIfNotPositive(v2)
-```
+## Properties
 
-### Removing tags
+### Introduction
 
-If needed, we can easily remove *tags* from our types:
+To define a new type with a property, we can do:
 
 ```typescript
-import { WithTag, WithoutTag } from '@coderspirit/nominal'
-
-type Email = WithTag<string, 'Email'>
-
-// NotEmail === string
-type NotEmail = WithoutTag<string, 'Email'>
-
-// NotAnEmailAnymore === string
-type NotAnEmailAnymore = WithoutTag<Email, 'Email'>
+import { WithProperty } from '@coderspirit/nominal'
+type Even = WithProperty<number, 'Parity', 'Even'>
+const myEven: Even = 42 as Even
 ```
 
-The tags that we do not explicitly remove are preserved:
-```typescript
-type FibonacciPrime = WithTags<number, ['Prime', 'Fibonacci']>
-type Fibonacci = WithoutTag<FibonacciPrime, 'Prime'>
-```
+If we want to use the properties as simple tags, we can omit the property value,
+and it will implicitly default to `true`, although it's less flexible:
 
-WARNING: Notice that it's not a good idea to preserve all the previous tags for
-return types when the passed value is transformed. For example:
 ```typescript
-function square<T extends number>(v: T): WithoutTag<T, 'Prime'> {
-  return v * v as WithoutTag<T, 'Prime'>
-}
-
-const myNumber: FibonacciPrime = 13 as FibonacciPrime
-
-// Notice that the return type's tag is wrong, as 169 is not a Fibonacci number
-// typeof mySquaredNumber === WithTag<number, 'Fibonacci'>
-// mySquaredNumber === 13*13 === 169
-const mySquaredNumber = square(myNumber)
-
+import { WithProperty } from '@coderspirit/nominal'
+type Positive = WithProperty<number, 'Positive'>
+const myPositive: Positive = 1 as Positive
 ```
 
-We can also remove many tags at once, or all of them:
-```typescript
-// Editor === WithTag<User, 'Editor'>
-type Editor = WithoutTags<
-  WithTags<User, ['Editor', 'Moderator', 'Admin']>,
-  ['Moderator', 'Admin']
->
+#### **Advice**
+- Although we perform a "static cast" here, this should be done only when:
+  - the value is a literal (as in the example)
+  - in validation, sanitization and/or anticorruption layers.
+- One way to protect against other developers "forging" the type is to use
+  symbols instead of strings as property keys or property values when defining
+  the new nominal type.
 
-// NewNumber === number
-type NewNumber = WithoutTags<FibonacciPrime>
-```
+#### **Interesting properties**
+- `WithProperty` is additive, commutative and idempotent.
+- The previous point means that we don't have to worry about the order of
+  composition, we won't suffer typing inconsistencies because of that.
 
-### Negating tags
+### Crazy-level strictness
 
-If needed, we can easily **negate** *tags* from our types. This is similar to
-removing them, but it allows us to reject some values with certain tags.
+If we want, we can even define "property types", to ensure that we don't set
+invalid values:
 
 ```typescript
-import { WithTag, NegateTag } from '@coderspirit/nominal'
-
-type Email = WithTag<string, 'Email'>
-type NegatedEmail = NegateTag<string, 'Email'>
-type NegatedEmail2 = NegateTag<Email, 'Email'>
-
-const email: Email = '[email protected]' as Email
+import { PropertyTypeDefinition, WithStrictProperty } from '@coderspirit/nominal'
+type Parity = PropertyTypeDefinition<'Parity', 'Even' | 'Odd'>
 
-// The type checked accepts this
-const untypedEmail: string = email
+// == WithProperty<number, 'Parity', 'Even'>
+type Even = WithStrictProperty<number, Parity, 'Even'>
 
-// The type checker will error with any of the following two lines
-const notEmail1: NegatedEmail = email // ERROR!
-const notEmail2: NegatedEmail2 = email // ERROR!
-
-// NotEmail & NotAnEmailAnymore are still compatible with string
-const notEmail3: NegatedEmail = 'not an email'
-const notEmail4: string = notEmail3 // This is OK :)
-
-const notEmail5: NegatedEmail2 = 'not an email anymore'
-const notEmail6: string = notEmail5 // This is also OK :)
+// == never
+type Wrong = WithStrictProperty<number, Parity, 'Seven'>
 ```
 
-This can be a powerful building block to implement values tainting, although we
-already provide an out-of-box solution for that.
-
 ### Advanced use cases
 
-Now that we know how to [add](#basic-tags), [remove](#removing-tags), and
-[negate](#negating-tags) tags, let's see a fancy example:
-
-```typescript
-// By combining tags & tag negations we can define types that allow us to
-// express logical or mathematical properties in a consistent way.
-
-// Now we can use `Even` and `Odd` without fearing that they will be used at the
-// same time for the same variable.
-type Even<N extends number = number> = NegateTag<WithTag<N, 'Even'>, 'Odd'>
-type Odd<N extends number = number> = NegateTag<WithTag<N, 'Odd'>, 'Even'>
-type ChangeParity<N extends Even | Odd> = N extends Even ? Odd : Even
-
-type Positive<N extends number = number> = NegateTag<WithTag<N, 'Positive'>, 'Negative'>
-type Negative<N extends number = number> = NegateTag<WithTag<N, 'Negative'>, 'Positive'>
-
-// We preserve sign when the number is positive for obvious reasons, but we
-// cannot do the same for negative values (for example for the value -0.5).
-type PlusOneResult<N extends Even | Odd> = N extends Positive
-  ? Positive<ChangeParity<N>> // Notice that we do not write Positive & ChangeParity<N>
-  : ChangeParity<N>
-
-function <N extends Even | Odd>plusOne(v: N): PlusOneResult<N> {
-  return v + 1 as PlusOneResult<N>
-}
-
-const positiveEven: Positive<Even> = 42 as Positive<Even>
-const positiveOdd: Positive<Odd> = 3 as Positive<Odd>
-
-// typeof positiveEvenPlus1 == Positive<Odd>
-const positiveEvenPlus1 = plusOne(positiveEven)
-
-// typeof positiveOddPlus1 === Positive<Even>
-const positiveOddPlus1 = plusOne(positiveOdd)
-
+#### **Properties can be preserved across function boundaries**
 
-
-```
-
-## Tainting
-
-### Tainting values
-
-While using *brands*, *flavors* and *tags* is often enough, sometimes it can be
-handy to mark all the values coming from the "external world" as *tainted* (and
-therefore "dangerous"), independently of whether we took the time to assign them
-a specific nominal type or not.
-
-`Nominal` provides the types `Tainted<T>` and `Untainted<T>`, both of them
-operate recursively on `T`.
+This feature can be very useful when we need to verify many properties for the
+same value and we don't want to lose this information along the way as the value
+is passed from one function to another.
 
 ```typescript
-import { Tainted, Untainted } from '@coderspirit/nominal'
-
-interface LoginRequest {
-  username: string
-  password: string
+function throwIfNotEven<T extends number>(v: T): WithProperty<T, 'Parity', 'Even'> {
+  if (v % 2 == 1) throw new Error('Not Even!')
+  return v as WithProperty<T, 'Even'>
 }
 
-type TaintedLoginRequest = Tainted<LoginRequest>
-type UntaintedLoginRequest = Untainted<LoginRequest>
-
-function validateLoginRequest(req: TaintedLoginRequest): UntaintedLoginRequest {
-  // throw Error if `req` is invalid
-  return req as UntaintedLoginRequest
+function throwIfNotPositive<T extends number>(v: T): WithProperty<T, 'Sign', 'Positive'> {
+  if (v <= 0) throw new Error('Not positive!')
+  return v as WithProperty<T, 'Positive'>
 }
 
-// This function accepts LoginRequest and UntaintedLoginRequest,
-// but not TaintedLoginRequest
-function login(req: UntaintedLoginRequest): void {
-  // Do stuff
-}
+const v1 = 42
 
-// When req is tainted, we cannot pass req.password to this function, as all
-// req's fields are tainted as well.
-function doStuffWithPassword(password: Untainted<string>): void {
-  // Do stuff
-}
+// typeof v2 === WithProperty<number, 'Parity', 'Even'>
+const v2 = throwIfNotEven(v1)
+
+// typeof v3 extends WithProperty<number, 'Parity', 'Even'>
+// typeof v3 extends WithProperty<number, 'Sign', 'Positive'>
+const v3 = throwIfNotPositive(v2)
 ```
 
-While this specific use case is far from being exciting and quite simplistic,
-this idea can be applied to much more sensitive and convoluted scenarios.
+#### Chosing what properties to preserve across function boundaries
 
-### Generic tainting
+In the previous example, we could add many properties because we were just
+making assertions about the values. When we transform the passed values, we must
+be more careful about what we preserve.
 
-While it's difficult to imagine how a value might be tainted in multiple ways,
-it's not unheard of. This could be useful when managing sensitive information,
-if we need/want to statically enforce that some data won't cross certain
-boundaries.
+As a simple example of what we are telling here, we can see that adding `1` to a
+numeric variable would flip its parity, so in that case we wouldn't want to keep
+that property on the return value.
 
 ```typescript
-import { GenericTainted, GenericUntainted } from '@coderspirit/nominal'
-
-type BlueTaintedNumber = GenericTainted<number, 'Blue'>
-type RedTaintedNumber = GenericTainted<number, 'Red'>
-
-// Double-tainted type!
-type BlueRedTaintedNumber = GenericTainted<BlueTaintedNumber, 'Red'>
+type Even<N extends number = number> = WithProperty<N, 'Parity', 'Even'>
+type Odd<N extends number = number> = WithProperty<N, 'Parity', 'Odd'>
+
+// 1. 'Parity' is overwritten (when available)
+// 2. 'Sign' is kept only if it's positive
+// 3. We discard all other properties because they might stop being true
+type PlusOneResult<N> = KeepProperties<
+  N extends Even
+    ? KeepPropertyIfValueMatches<Odd<N>, 'Sign', 'Positive'>
+    : N extends Odd
+    ? KeepPropertyIfValueMatches<Even<N>, 'Sign', 'Positive'>
+    : KeepPropertyIfValueMatches<N, 'Sign', 'Positive'>,
+  'Sign' | 'Parity'
+>
 
-// We removed again the 'Blue' taint
-type OnlyBlueTaintedNumber = GenericUntainted<BlueRedTaintedNumber, 'Red'>
+function plusOne<N extends number>(v: N): PlusOneResult<N> {
+  return v + 1 as PlusOneResult<N>
+}
 ```