From f66461f7683b258662a68e4783757d0fa8075c67 Mon Sep 17 00:00:00 2001 From: Kostis Maninakis Date: Fri, 10 Feb 2023 12:36:14 +0100 Subject: [PATCH] docs(readme): further contrast with images `|` operator vs `XOR` --- README.md | 41 ++++++++++++++++++++++++++++++++++------- assets/A_OR_B.png | Bin 0 -> 2655 bytes assets/A_XOR_B.png | Bin 0 -> 3476 bytes 3 files changed, 34 insertions(+), 7 deletions(-) create mode 100644 assets/A_OR_B.png create mode 100644 assets/A_XOR_B.png diff --git a/README.md b/README.md index e1078cb..b55ef22 100644 --- a/README.md +++ b/README.md @@ -18,20 +18,47 @@ Compose custom types containing mutually exclusive keys, using this generic Type Typescript's union operator (`|`) allows combining two object types `A` and `B`, into a superset type C which _can_ contain all the members of both `A` and `B`. -But sometimes the requirements dictate that we combine two types with mutually exclusive members. So take the members `A.a` and `B.b`. Given `type C = A | B` then we want to impose the restriction that we can set _either_ `C.a` _or_ `C.b` _but never both_ AND _at least one of the two_! +But sometimes the requirements dictate that we combine two types with mutually exclusive members. So take the members `A.a` and `B.b`. Given `type C = A | B` then we want to impose the restriction that we can set _either_ `C.a` _or_ `C.b` _but never both_ AND _always at least one of the two_! Typescript does not have this feature built-in. -This package introduces the new custom type `XOR`. You can use XOR to compose your own custom types with mutually exclusive members. +The package `ts-xor` introduces the new custom type `XOR`. You can use XOR to compose your own custom types with mutually exclusive members. -XOR effectively implements the well-known XOR logical operator from boolean algebra as defined by the following truth table: +The XOR type effectively implements the well-known XOR logical operator from boolean algebra as defined by the following truth table: | A | B | Result | Note | :-: | :-: | :-: | :-: | -| 0 | 0 | 0 | achievable with union operator (`\|`) and `ts-xor` -| 0 | 1 | 1 | achievable with union operator (`\|`) and `ts-xor` -| 1 | 0 | 1 | achievable with union operator (`\|`) and `ts-xor` -| 1 | 1 | 0 | achievable only with `ts-xor` +| 0 | 0 | 0 | achievable with union operator (`\|`) and `XOR` +| 0 | 1 | 1 | achievable with union operator (`\|`) and `XOR` +| 1 | 0 | 1 | achievable with union operator (`\|`) and `XOR` +| 1 | 1 | 0 | achievable only with `XOR` + +### Union operator vs the XOR type in practice + +If we use the union operator + +```ts +type A_OR_B = A | B +``` + +then the derived type is shown in VS Code like so: + +![Resulting type when using the union operator](assets/A_OR_B.png) + +Whereas if we use the XOR mapped type + +```ts +type A_XOR_B = XOR +``` + +then the derived type is shown quite differently in VS Code: + +![Resulting type when using the XOR mapped type](assets/A_XOR_B.png) + +Notice that when using XOR each "variant" of the resulting type contains all keys of one source type plus all keys of the other, with those of the second type defined as _optional_ and at the same time typed as _undefined_. + +This trick will not only forbid defining keys of both source types at the same time (since the type of each key is explicitly `undefined`), but also _allow_ us to not need to define all keys all of the time since each set of keys is optional on each variant. + ## Installation In your typescript powered, npm project, run: diff --git a/assets/A_OR_B.png b/assets/A_OR_B.png new file mode 100644 index 0000000000000000000000000000000000000000..b05eb480a385c4cfb846128c2e13ae0e9d9cd36a GIT binary patch literal 2655 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 N002ovPDHLkV1lbB39tYF literal 0 HcmV?d00001 diff --git a/assets/A_XOR_B.png b/assets/A_XOR_B.png new file mode 100644 index 0000000000000000000000000000000000000000..bb0ad5b3da7c455e1646f741da32073f1bbaee84 GIT binary patch literal 3476 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