feat: type predicates + serialize and parsing functions

chore: deps

.prettierignore

@@ -1,2 +1,3 @@
 # package.json is formatted by package managers, so we ignore it here
 package.json
+CHANGELOG.md

README.md

@@ -129,6 +129,43 @@ Returns a new KeySet with the intersection of both Sets `(A ∩ B)`, representin
 const diffKeySet = keySet.intersect(other);
 ```
 
+## Serialization
+
+The Serialized representation of the KeySet (`KeySetSerialized`) is a plain object with `type` and optionally `elements`.
+
+- `{ type: "ALL" }`
+- `{ type: "NONE" }`
+- `{ type: "SOME", elements: [1, 2, 3] }`
+- `{ type: "ALL_EXCEPT_SOME", elements: [1, 2, 3] }`
+
+There are 2 ways of getting the serialized representation of the keySet
+
+- `keySet.serialized()`
+- `serializeKeySet(keySet)`
+
+## Parsing
+
+We can create a KeySet from the serialized representation
+
+- `parseKeySet(serialized)`
+
+we can also pass the actual KeySet to the `parseKeySet`, which will return the given KeySet without touching it.
+
+## Type Predicates
+
+There are type predicates exposed, one for each KeySet type and the other for each KeySetSerialized.
+
+- `isKeySet(x): x is KeySet`
+- `isKeySetAll(x): x is KeySetAll`
+- `isKeySetAllExceptSome(x): x is KeySetAllExceptSome`
+- `isKeySetNone(x): x is KeySetNone`
+- `isKeySetSome(x): x is KeySetSome`
+- `isKeySetSerialized(x): x is KeySetSerialized`
+- `isKeySetAllSerialized(x): x is KeySetAllSerialized`
+- `isKeySetAllExceptSomeSerialized(x): x is KeySetAllExceptSomeSerialized`
+- `isKeySetNoneSerialized(x): x is KeySetNoneSerialized`
+- `isKeySetSomeSerialized(x): x is KeySetSomeSerialized`
+
 ## Util functions
 
 The lib also exports the 2 util functions used in the code
@@ -137,3 +174,27 @@ The lib also exports the 2 util functions used in the code
   - **adapted from <https://medium.com/@jakubsynowiec/unique-array-values-in-javascript-7c932682766c> (credit to Jakub Synowiec)**
 - `arraysEqual(a, b)`: returns true if the 2 arrays have the same keys
   - **adapted from <https://stackoverflow.com/questions/3115982/how-to-check-if-two-arrays-are-equal-with-javascript> (credit to [enyo](https://stackoverflow.com/users/170851/enyo))**
+
+## Util array types
+
+The lib also exports 2 util array types `EmptyArray<T>` and `NonEmptyArray<T>`, with their corresponding type predicates `isEmptyArray()`, and `isNonEmptyArray()`.
+
+```ts
+const lists: Array<NonEmptyArray<any>> = [
+  [1], // ok
+  [] // error
+];
+
+const lists2: Array<EmptyArray<any>> = [
+  [], // ok
+  [1] // error
+];
+
+const a: string[] = [];
+isEmptyArray(a); // => true (also sets that a is EmptyArray<string>)
+isNonEmptyArray(a); // => false
+
+const b: string[] = ["something"];
+isEmptyArray(b); // => false
+isNonEmptyArray(b); // => true (also sets that a is NonEmptyArray<string>)
+```

package.json

@@ -58,7 +58,7 @@
   "dependencies": {},
   "devDependencies": {
     "@bitjson/npm-scripts-info": "^1.0.0",
-    "@types/jest": "^25.1.1",
+    "@types/jest": "^25.1.3",
     "cz-conventional-changelog": "^3.0.2",
     "gh-pages": "^2.0.1",
     "jest": "^25.1.0",
@@ -68,15 +68,15 @@
     "standard-version": "^7.0.0",
     "strip-json-comments": "^3.0.1",
     "trash-cli": "^3.0.0",
-    "ts-jest": "^25.0.0",
+    "ts-jest": "^25.2.1",
     "ts-loader": "^6.0.4",
     "ts-node": "^8.3.0",
     "tslint": "^5.18.0",
     "tslint-config-prettier": "^1.18.0",
     "tslint-immutable": "^6.0.1",
     "typedoc": "^0.16.7",
     "typedoc-themes-color": "^0.0.10",
-    "typescript": "^3.5.3"
+    "typescript": "^3.8.2"
   },
   "config": {
     "commitizen": {

src/lib/__tests__/key-set.spec.ts

@@ -77,3 +77,11 @@ test("allExceptSomeForced([1, 2, 3])", () => {
   expect((keySet as KeySetAllExceptSome<number>).keys).toEqual([1, 2, 3]);
   expect(keySet.type).toEqual(KeySetTypes.allExceptSome);
 });
+
+test("new KeySetSome([]) throws error", () => {
+  expect(() => new KeySetSome([])).toThrowError(InvalidEmptySetError);
+});
+
+test("new KeySetAllExceptSome([]) throws error", () => {
+  expect(() => new KeySetAllExceptSome([])).toThrowError(InvalidEmptySetError);
+});