ts-xor - npm Package Compare versions

Comparing version 1.0.8 to 1.1.0

dist/index.js

@@ -0,1 +1,2 @@
+export * from './types/Xor.type';
 //# sourceMappingURL=index.js.map

dist/types/Without.type.d.ts

 /**
  * Get the keys of T without any keys of U.
  */
-export declare type Without<T, U> = {
+export type Without<T, U> = {
     [P in Exclude<keyof T, keyof U>]?: never;
 };
 //# sourceMappingURL=Without.type.d.ts.map

dist/types/Without.type.js

@@ -0,1 +1,2 @@
+export {};
 //# sourceMappingURL=Without.type.js.map

dist/types/Xor.type.d.ts

@@ -0,1 +1,2 @@
+import { Prettify } from './Prettify.type';
 import { Without } from './Without.type';
@@ -12,3 +13,3 @@ /**
  */
-export declare type XOR<T, U> = (T | U) extends object ? (Without<T, U> & U) | (Without<U, T> & T) : T | U;
+export type XOR<T, U> = (T | U) extends object ? (Prettify<Without<T, U> & U>) | (Prettify<Without<U, T> & T>) : T | U;
 //# sourceMappingURL=Xor.type.d.ts.map

dist/types/Xor.type.js

@@ -0,1 +1,2 @@
+export {};
 //# sourceMappingURL=Xor.type.js.map

package.json

 {
   "name": "ts-xor",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Compose custom types containing mutually exclusive keys, using this generic Typescript helper type.",
+  "type": "module",
   "main": "dist/index.js",
@@ -21,3 +22,4 @@ "types": "dist/index.d.ts",
     "mutually exlusive keys",
-    "xor"
+    "xor",
+    "maninak"
   ],
@@ -31,5 +33,5 @@ "author": "Kostis Maninakis <[e-mail]> (https://maninak.github.io)",
   "devDependencies": {
-    "rimraf": "^2.6.3",
-    "typescript": "^3.4.5"
+    "rimraf": "^4.1.2",
+    "typescript": "^4.9.5"
   }
 }

README.md

@@ -6,34 +6,58 @@
 
-[![npm version](https://badge.fury.io/js/ts-xor.svg)](https://badge.fury.io/js/ts-xor)
-[![Build Status](https://travis-ci.org/maninak/ts-xor.svg?branch=master)](https://travis-ci.org/maninak/ts-xor)
-[![Greenkeeper badge](https://badges.greenkeeper.io/maninak/ts-xor.svg)](https://greenkeeper.io/)
-![Last commit](https://badgen.net/github/last-commit/maninak/ts-xor)
+[![npm version](https://badgen.net/npm/v/ts-xor?color=green)](https://www.npmjs.com/package/ts-xor)
+[![Licence](https://badgen.net/badge/license/MIT/green)](LICENCE.md)
 
-[![Licence](https://badgen.net/badge/license/MIT/blue)](LICENCE.md)
+[![Downloads per week](https://badgen.net/npm/dt/ts-xor?color=blue)](https://npm-stat.com/charts.html?package=ts-xor&from=2019-02-22)
 [![Downloads per week](https://badgen.net/npm/dw/ts-xor?color=blue)](https://npm-stat.com/charts.html?package=ts-xor&from=2019-02-22)
-[![NPM dependent packages](https://badgen.net/npm/dependents/ts-xor?color=blue)](https://www.npmjs.com/browse/depended/ts-xor)
+[![Repos depending on ts-xor](https://badgen.net/github/dependents-repo/maninak/ts-xor?color=blue)](https://github.com/maninak/ts-xor/network/dependents)
 [![Github stars](https://badgen.net/github/stars/maninak/ts-xor)](https://github.com/maninak/ts-xor/stargazers)
 
 [![Minified and gzipped size](https://badgen.net/bundlephobia/minzip/ts-xor?color=orange)](https://bundlephobia.com/result?p=ts-xor)
-![Dependencies](https://badgen.net/david/dep/maninak/ts-xor?color=orange)
+[![0 Dependencies](https://badgen.net/bundlephobia/dependency-count/ts-xor?color=orange)](https://github.com/maninak/ts-xor/blob/87aa237a1b246efa4e8028d89dc7168ba4c4fd84/package.json#L30)
 
 ## Description
 
-Typescript's union operator (`|`) allows combining two types `A` and `B`, into a superset type C which _can_ contain all the members of both `A` and `B`.
+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 support this feature out of the box yet](https://github.com/Microsoft/TypeScript/issues/6579).
+Typescript does not have this feature built-in.
 
-This package introduces the new 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 logical XOR 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 |
-| :-: | :-: | :-: |
-| 0 | 0 | 0 |
-| 0 | 1 | 1 |
-| 1 | 0 | 1 |
-| 1 | 1 | 0 |
+| A | B | Result | Note
+| :-: | :-: | :-: | :-: |
+| 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<A, B>
+```
+
+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
@@ -51,5 +75,5 @@
 
-In any typescript file you can just have:
+```typescript
+// example1.ts
 
-```typescript
 import { XOR } from 'ts-xor'
@@ -65,8 +89,8 @@
 
-let A_XOR_B: XOR<A, B>
+let test: XOR<A, B>
 
-A_XOR_B = { a: '' }         // OK
-A_XOR_B = { b: '' }         // OK
-A_XOR_B = { a: '', b: '' }  // fails
-A_XOR_B = {}                // fails
+test = { a: '' }         // OK
+test = { b: '' }         // OK
+test = { a: '', b: '' }  // rejected
+test = {}                // rejected
 ```
@@ -76,10 +100,12 @@
 
-Say that we have the following specification for the response of a weather forecast service:
+Let's assume that we have the following spec for a weather forecast API's response:
 
 1. A weather forecast object _always_ contains the `id` _and_ `station` members
 2. A weather forecast object _always_ contains either a member `rain` _or_ a member `snow`, but _never_ both at the same time.
-3. The rain or snow members are objects containing additional forecast accuracy data
-4. The rain or snow member _always_ contain either a member `1h` or a member `3h` with a number value, but _never_ both keys at the same time.
+3. The rain, snow members are objects containing additional forecast accuracy data
+4. The rain, snow members _always_ contain either a member `1h` or a member `3h` with a number value, but _never_ both keys at the same time.
 
 ```typescript
+// example2.ts
+
 import { XOR } from 'ts-xor'
@@ -104,19 +130,50 @@
 
-const ourTestCase: WeatherForecast = {
-  id: 123456,
-  station: 'Acropolis Weather Reporter',
+const test: WeatherForecast = {
+  id: 1,
+  station: 'Acropolis',
   // rain: { '1h': 1 },           // OK
-  // rain: { '2h': 1 },           // fails
+  // rain: { '2h': 1 },           // rejected
   // rain: { '3h': 1 },           // OK
-  // rain: {},                    // fails
-  // rain: { '1h': 1 , '3h': 3 }, // fails
-  // lel: { '3h': 1 },            // fails
+  // rain: {},                    // rejected
+  // rain: { '1h': 1 , '3h': 3 }, // rejected
+  // lel: { '3h': 1 },            // rejected
+  // rain: { '3h': 1, lel: 1 },   // rejected
   // snow: { '3h': 1 },           // OK
-  // when BOTH `rain` AND `snow` are declared, compilation fails
+                                  // rejected when BOTH `rain` AND `snow` keys are defined at the same time
 }
 ```
 
+### XORing more than two types
+
+If you want to create a type as the product of the logical XOR operation between multiple types (more than two), then nest the generic params.
+
+```typescript
+// example1.ts
+
+import { XOR } from 'ts-xor'
+
+interface A {
+  a: string
+}
+
+interface B {
+  b: string
+}
+
+interface C {
+  c: string
+}
+
+let test: XOR<A, XOR<B, C>>
+
+test = { a: '' }         // OK
+test = { b: '' }         // OK
+test = { c: '' }         // OK
+test = { a: '', c: '' }  // rejected
+test = {}                // rejected
+```
+
 ## Tests and Coverage
 
-The library `ts-xor` is fully covered with acceptance and mutation tests against the typescript compiler itself. The tests can be found inside the [`test`](https://github.com/maninak/ts-xor/tree/master/test) folder.
+The library `ts-xor` is fully covered with smoke, acceptance and mutation tests against the typescript compiler itself. The tests can be found inside the [`test`](https://github.com/maninak/ts-xor/tree/master/test) folder.
 
@@ -126,3 +183,3 @@ To run all tests locally, execute the following command inside your git-cloned `ts-xor` folder:
 ```sh
-npm test
+npm run test
 ```
@@ -129,0 +186,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

17657

increased by98.15%

Number of package files

21

increased by40%

Lines of code

31

increased by63.16%

Number of lines in readme file

198

increased by40.43%

Is type module

Yes

No dependency changes