Structures readme. Adds documentation for missing general functions. Adds documentation for missing object functions. (#30)

Author: shreyansh-g24

README.md

@@ -6,12 +6,18 @@ A collection of common utility functions used across all our
 [neeto](https://neeto.com) products. Try out the utility functions live at
 [neetoCommons REPL](https://neeto-cist.neeto.com/).
 
-## Installation Instructions
+## Contents
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [List of Pure Functions](#list-of-pure-functions)
+  - [Development](#development)
+
+## Installation
 
 Install from npm:
 
 ```bash
-yarn add @bigbinary/neeto-cist
+yarn add @bigbinary/neeto-cist@latest
 ```
 
 Install the peer dependencies:
@@ -20,6 +26,26 @@ Install the peer dependencies:
 yarn add ramda
 ```
 
+## Usage
+
+You can import all functions from `@bigbinary/neeto-cist`.
+
+```js
+import { slugify } from "@bigbinary/neeto-cist";
+```
+
+Exports several general utility functions that are used throughout neeto
+products. The functions are designed in a similar fashion as ramda so that they
+can easily interoperate with each other.
+
+Pure functions were designed to be fail fast. If you call `findById(10, null)`,
+it will throw error saying that it can't iterate through `null`.
+
+But for most such pure functions, there is a failsafe alternative available. The
+failsafe alternative function will be prefixed with `_`. Example:
+`_findById(10, null)` returns `null`, `_findById(10, undefined)` returns
+`undefined` and `_findById(10, [{ id: 10 }])` returns `{ id: 10 }`.
+
 ## List of Pure Functions
 
 <table>
@@ -79,6 +105,9 @@ Name
 - [isNotEmpty](./docs/pure/general.md#isnotempty)
 - [isNot (alias notEquals)](./docs/pure/general.md#isnot_alias_notequals)
 - [isNotEqualDeep (alias notEqualsDeep)](./docs/pure/general.md#isnotequaldeep_alias_notequalsdeep)
+- [isNotPresent](./docs/pure/general.md#isnotpresent)
+- [isPresent](./docs/pure/general.md#ispresent)
+- [modifyWithImmer](./docs/pure/general.md#modifywithimmer)
 
 </td>
 </tr>
@@ -87,35 +116,7 @@ Name
 </tbody>
 </table>
 
-## Installation Instructions
-
-Install from npm:
-
-```bash
-yarn add "@bigbinary/neeto-cist@latest"
-```
-
-## Usage
-
-You can import all functions from `@bigbinary/neeto-cist`.
-
-```js
-import { slugify } from "@bigbinary/neeto-cist";
-```
-
-Exports several general utility functions that are used throughout neeto
-products. The functions are designed in a similar fashion as ramda so that they
-can easily interoperate with each other.
-
-Pure functions were designed to be fail fast. If you call `findById(10, null)`,
-it will throw error saying that it can't iterate through `null`.
-
-But for most such pure functions, there is a failsafe alternative available. The
-failsafe alternative function will be prefixed with `_`. Example:
-`_findById(10, null)` returns `null`, `_findById(10, undefined)` returns
-`undefined` and `_findById(10, [{ id: 10 }])` returns `{ id: 10 }`.
-
-## Other references
+## Development
 
 - [Development instructions](./docs/general/development-instructions.md)
 - [Building and releasing](./docs/general/building-and-releasing.md)

docs/pure/README.md

@@ -80,10 +80,12 @@ import { slugify } from "@bigbinary/neeto-cist";
 </td>
 <td  style="vertical-align: top;">
 
+- [matchesImpl](./objects.md#matchesimpl)
 - [transformObjectDeep](./objects.md#transformobjectdeep)
-- [preprocessForSerialization](./objects.md#preprocessforserialization)
 - [keysToCamelCase](./objects.md#keystocamelcase)
 - [keysToSnakeCase](./objects.md#keystosnakecase)
+- [serializeKeysToSnakeCase](./objects.md#serializekeystosnakecase)
+- [preprocessForSerialization](./objects.md#preprocessforserialization)
 - [deepFreezeObject](./objects.md#deepfreezeobject)
 - [matches](./objects.md#matches)
 - [filterNonNull](./objects.md#filternonnull)
@@ -102,14 +104,18 @@ import { slugify } from "@bigbinary/neeto-cist";
 </td>
 <td  style="vertical-align: top;">
 
+- [nullSafe](./general.md#nullsafe)
 - [noop](./general.md#noop)
 - [toLabelAndValue](./general.md#tolabelandvalue)
 - [getRandomInt](./general.md#getrandomint)
 - [randomPick](./general.md#randompick)
 - [dynamicArray](./general.md#dynamicarray)
 - [isNotEmpty](./general.md#isnotempty)
 - [isNot (alias notEquals)](./general.md#isnot_alias_notequals)
+- [isNotPresent](./general.md#isnotpresent)
+- [isPresent](./general.md#ispresent)
 - [isNotEqualDeep (alias notEqualsDeep)](./general.md#isnotequaldeep_alias_notequalsdeep)
+- [modifyWithImmer](./general.md#modifywithimmer)
 </td>
 <tr>
 </tbody>

docs/pure/general.md

@@ -1,5 +1,27 @@
 # General Functions
 
+## nullSafe
+
+Curried: false
+Failsafe status: failsafe by default
+
+This function takes a function as an argument and returns a curried version of the function.
+
+<details>
+<summary>{click for more}</summary>
+
+### Arguments:
+  - `func`: A function that needs to be curried.
+
+### Usage:
+```js
+const add = (a, b) => a + b;
+nullSafe(add)(1)(2);
+// Output: 3
+```
+
+</details>
+
 ## noop
 
 Curried: false
@@ -152,6 +174,46 @@ isNot("Oliver", "Oliver"); // returns false
 
 </details>
 
+## isNotPresent
+
+Curried: false
+Failsafe status: failsafe by default
+
+Returns `true` if value is not present. Returns false otherwise.
+
+<details>
+<summary>(click for more)</summary>
+
+### Arguments:
+  - One value to be checked
+
+### Usage:
+```js
+isNotPresent(null);
+// Output: true
+```
+</details>
+
+## isPresent
+
+Curried: false
+Failsafe status: failsafe by default
+
+Returns `true` if value is present. Returns false otherwise.
+
+<details>
+<summary>(click for more)</summary>
+
+### Arguments:
+  - One value to be checked
+
+### Usage:
+```js
+isPresent(null);
+// Output: false
+```
+</details>
+
 ## isNotEqualDeep (alias notEqualsDeep)
 
 Curried: false
@@ -181,3 +243,32 @@ isNotEqualsDeep(object1, object2); //returns true
 ```
 
 </details>
+
+## modifyWithImmer
+
+Curried: true
+Failsafe status: Not failsafe
+
+Receives a state and a modifier function. Returns modified state. Original state object is left untouched.
+
+Modifier function receives draft state as the argument. We can use mutating methods like `push`, `pop`, `splice`, `delete` without any issues on that parameter.
+
+<details>
+<summary>(click for more)</summary>
+
+### Arguments:
+  - `modifier`: The modifier function.
+  - `data`: The state object.
+
+### Usage:
+```js
+const modifier = (state) => state.names.push("Tom");
+const data = { names: ["Oliver", "Sam", "Jon"] };
+const updatedState = modifyWithImmer(modifier, data);
+
+console.log(data);
+// { names: ["Oliver", "Sam", "Jon"] }
+console.log(updatedState);
+// { names: ["Oliver", "Sam", "Jon", "Tom"] }
+```
+</details>

docs/pure/objects.md

@@ -1,5 +1,49 @@
 # Object operations
 
+## matchesImpl
+
+Curried: false
+Failsafe status: failsafe by default
+
+Non curried version of [matches](#matches). See matches for curried version.
+
+Checks whether the given object matches the given pattern. Each primitive value (int, boolean, string, etc.) in the pattern should be same as the corresponding value in the object (deeply) and all conditions (functions) should be satisfied for a match.
+
+<details>
+<summary>(click for more)</summary>
+
+### Arguments:
+- `pattern`: The pattern object to be matched against the data.
+  It's values can be either a value or a function.
+  - value: Returns true if all the keys in pattern exist in data and the primitive values of those keys are identical to the data. Object values are compared recursively for inner primitives.
+  - function: equality test is performed with corresponding object property. If equality fails, the function will be evaluated with the value of the corresponding property of the data. If function returns true, it will be considered as a match.
+- `data`: The data object.
+
+### Usage:
+
+```js
+const user = {
+  firstName: "Oliver",
+  address: { city: "Miami", phoneNumber: "389791382" },
+  cars: [{ brand: "Ford" }, { brand: "Honda" }],
+};
+
+matchesImpl({ firstName: "Oliver" }, user); // true
+matchesImpl({ address: { city: "Miami" } }, user); // true
+matchesImpl({ cars: [{ brand: "Ford" }] }, user); // true
+matchesImpl({ firstName: "Sam" }, user); // false
+matchesImpl({ address: { country: "US" } }, user); // false
+matchesImpl({ cars: [{ brand: "Honda" }] }, user); // false
+// array index as object key
+matchesImpl({ cars: { 1: { brand: "Honda" } } }, user); // true
+// conditional functions
+matchesImpl({ cars: arr => arr.length === 2 }, user); // true
+// point-free functions with ramda
+matchesImpl({ firstName: startsWith("O") }, user); // true
+```
+
+</details>
+
 ## transformObjectDeep
 
 Curried: false