From a0875ba0e51a2bc1e08ebd98d8288ccaa1f65a87 Mon Sep 17 00:00:00 2001
From: Shreyansh Gupta <40631571+shreyansh-g24@users.noreply.github.com>
Date: Wed, 27 Dec 2023 22:06:22 +0530
Subject: [PATCH] Structures readme. Adds documentation for missing general
functions. Adds documentation for missing object functions.
---
README.md | 63 +++++++++++++++---------------
docs/pure/README.md | 8 +++-
docs/pure/general.md | 91 ++++++++++++++++++++++++++++++++++++++++++++
docs/pure/objects.md | 44 +++++++++++++++++++++
4 files changed, 174 insertions(+), 32 deletions(-)
diff --git a/README.md b/README.md
index fd87a35..f5a2b3f 100644
--- a/README.md
+++ b/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
@@ -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)
@@ -87,35 +116,7 @@ Name
-## 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)
diff --git a/docs/pure/README.md b/docs/pure/README.md
index 44e0aa5..1e0212c 100644
--- a/docs/pure/README.md
+++ b/docs/pure/README.md
@@ -80,10 +80,12 @@ import { slugify } from "@bigbinary/neeto-cist";
+- [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,6 +104,7 @@ import { slugify } from "@bigbinary/neeto-cist";
|
+- [nullSafe](./general.md#nullsafe)
- [noop](./general.md#noop)
- [toLabelAndValue](./general.md#tolabelandvalue)
- [getRandomInt](./general.md#getrandomint)
@@ -109,7 +112,10 @@ import { slugify } from "@bigbinary/neeto-cist";
- [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)
|
diff --git a/docs/pure/general.md b/docs/pure/general.md
index db26b1b..daffae0 100644
--- a/docs/pure/general.md
+++ b/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.
+
+
+{click for more}
+
+### Arguments:
+ - `func`: A function that needs to be curried.
+
+### Usage:
+```js
+const add = (a, b) => a + b;
+nullSafe(add)(1)(2);
+// Output: 3
+```
+
+
+
## noop
Curried: false
@@ -152,6 +174,46 @@ isNot("Oliver", "Oliver"); // returns false
+## isNotPresent
+
+Curried: false
+Failsafe status: failsafe by default
+
+Returns `true` if value is not present. Returns false otherwise.
+
+
+(click for more)
+
+### Arguments:
+ - One value to be checked
+
+### Usage:
+```js
+isNotPresent(null);
+// Output: true
+```
+
+
+## isPresent
+
+Curried: false
+Failsafe status: failsafe by default
+
+Returns `true` if value is present. Returns false otherwise.
+
+
+(click for more)
+
+### Arguments:
+ - One value to be checked
+
+### Usage:
+```js
+isPresent(null);
+// Output: false
+```
+
+
## isNotEqualDeep (alias notEqualsDeep)
Curried: false
@@ -181,3 +243,32 @@ isNotEqualsDeep(object1, object2); //returns true
```
+
+## 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.
+
+
+(click for more)
+
+### 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"] }
+```
+
diff --git a/docs/pure/objects.md b/docs/pure/objects.md
index 9f7f79b..e4b4508 100644
--- a/docs/pure/objects.md
+++ b/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.
+
+
+(click for more)
+
+### 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
+```
+
+
+
## transformObjectDeep
Curried: false