diff --git a/README.md b/README.md index f5a2b3f..322cc87 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ A collection of common utility functions used across all our ## Contents - [Installation](#installation) - [Usage](#usage) - - [List of Pure Functions](#list-of-pure-functions) + - [Available functions](#available-functions) - [Development](#development) ## Installation @@ -35,8 +35,8 @@ 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. +products. The functions are structured in a manner reminiscent of Ramda, +enabling seamless interoperability among them. 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`. @@ -46,77 +46,109 @@ 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 +## Available functions + + + - - - + + + + +
-Name +Array operations + + + +Object operations + + + +String operations + + + +General utility functions
-- [findById](./docs/pure/arrays.md#findbyid) -- [findIndexById](./docs/pure/arrays.md#findindexbyid) -- [removeById](./docs/pure/arrays.md#removebyid) -- [replaceById](./docs/pure/arrays.md#replacebyid) -- [modifyById](./docs/pure/arrays.md#modifybyid) -- [existsById](./docs/pure/arrays.md#existsbyid) -- [findBy](./docs/pure/arrays.md#findby) -- [findIndexBy](./docs/pure/arrays.md#findindexby) -- [removeBy](./docs/pure/arrays.md#removeby) -- [replaceBy](./docs/pure/arrays.md#replaceby) -- [modifyBy](./docs/pure/arrays.md#modifyby) -- [existsBy](./docs/pure/arrays.md#existsby) -- [findLastBy](./docs/pure/arrays.md#findlastby) -- [findLastIndexBy](./docs/pure/arrays.md#findlastindexby) -- [filterBy](./docs/pure/arrays.md#filterby) -- [countBy](./docs/pure/arrays.md#countby) -- [renameKeys](./docs/pure/arrays.md#renamekeys) -- [copyKeys](./docs/pure/arrays.md#copykeys) -- [copyKeysDeep](./docs/pure/arrays.md#copykeysdeep) -- [transformObjectDeep](./docs/pure/objects.md#transformobjectdeep) -- [preprocessForSerialization](./docs/pure/objects.md#preprocessforserialization) -- [keysToCamelCase](./docs/pure/objects.md#keystocamelcase) -- [keysToSnakeCase](./docs/pure/objects.md#keystosnakecase) -- [deepFreezeObject](./docs/pure/objects.md#deepfreezeobject) -- [matches](./docs/pure/objects.md#matches) -- [filterNonNull](./docs/pure/objects.md#filternonnull) -- [slugify](./docs/pure/strings.md#slugify) -- [humanize](./docs/pure/strings.md#humanize) -- [snakeToCamelCase](./docs/pure/strings.md#snaketocamelcase) -- [camelToSnakeCase](./docs/pure/strings.md#cameltosnakecase) -- [capitalize](./docs/pure/strings.md#capitalize) -- [hyphenate](./docs/pure/strings.md#hyphenate) -- [truncate](./docs/pure/strings.md#truncate) -- [noop](./docs/pure/general.md#noop) -- [toLabelAndValue](./docs/pure/general.md#tolabelandvalue) -- [getRandomInt](./docs/pure/general.md#getrandomint) -- [randomPick](./docs/pure/general.md#randompick) -- [dynamicArray](./docs/pure/general.md#dynamicarray) -- [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) +- [findById](docs/pure/arrays/findById.md) +- [findIndexById](docs/pure/arrays/findIndexById.md) +- [removeById](docs/pure/arrays/removeById.md) +- [replaceById](docs/pure/arrays/replaceById.md) +- [modifyById](docs/pure/arrays/modifyById.md) +- [existsById](docs/pure/arrays/existsById.md) + +--- + +- [findBy](docs/pure/arrays/findBy.md) +- [findIndexBy](docs/pure/arrays/findIndexBy.md) +- [removeBy](docs/pure/arrays/removeBy.md) +- [replaceBy](docs/pure/arrays/replaceBy.md) +- [modifyBy](docs/pure/arrays/modifyBy.md) +- [existsBy](docs/pure/arrays/existsBy.md) +- [findLastBy](docs/pure/arrays/findLastBy.md) +- [findLastIndexBy](docs/pure/arrays/findLastIndexBy.md) +- [filterBy](docs/pure/arrays/filterBy.md) +- [countBy](docs/pure/arrays/countBy.md) + +--- + +- [renameKeys](docs/pure/arrays/renameKeys.md) +- [copyKeys](docs/pure/arrays/copyKeys.md) +- [copyKeysDeep](docs/pure/arrays/copyKeysDeep.md)
+ +- [matchesImpl](docs/pure/objects/matchesImpl.md) +- [transformObjectDeep](docs/pure/objects/transformObjectDeep.md) +- [keysToCamelCase](docs/pure/objects/keysToCamelCase.md) +- [keysToSnakeCase](docs/pure/objects/keysToSnakeCase.md) +- [serializeKeysToSnakeCase](docs/pure/objects/serializeKeysToSnakeCase.md) +- [preprocessForSerialization](docs/pure/objects/preprocessForSerialization.md) +- [deepFreezeObject](docs/pure/objects/deepFreezeObject.md) +- [matches](docs/pure/objects/matches.md) +- [filterNonNull](docs/pure/objects/filterNonNull.md) -
+ +- [slugify](docs/pure/strings/slugify.md) +- [humanize](docs/pure/strings/humanize.md) +- [snakeToCamelCase](docs/pure/strings/snakeToCamelCase.md) +- [camelToSnakeCase](docs/pure/strings/camelToSnakeCase.md) +- [capitalize](docs/pure/strings/capitalize.md) +- [hyphenate](docs/pure/strings/hyphenate.md) +- [truncate](docs/pure/strings/truncate.md) + + + +- [nullSafe](docs/pure/general/nullSafe.md) +- [noop](docs/pure/general/noop.md) +- [toLabelAndValue](docs/pure/general/toLabelAndValue.md) +- [getRandomInt](docs/pure/general/getRandomInt.md) +- [randomPick](docs/pure/general/randomPick.md) +- [dynamicArray](docs/pure/general/dynamicArray.md) +- [isNotEmpty](docs/pure/general/isNotEmpty.md) +- [isNot (notEquals)](docs/pure/general/isNot.md) +- [isNotPresent](docs/pure/general/isNotPresent.md) +- [isPresent](docs/pure/general/isPresent.md) +- [isNotEqualDeep (alias notEqualsDeep)](docs/pure/general/isNotEqualDeep.md) +- [modifyWithImmer](docs/pure/general/modifyWithImmer.md) +
## Development - [Development instructions](./docs/general/development-instructions.md) +- [API documentation logistics](./docs/general/api-documentation-logistics.md) - [Building and releasing](./docs/general/building-and-releasing.md) diff --git a/docs/general/api-documentation-logistics.md b/docs/general/api-documentation-logistics.md new file mode 100644 index 0000000..b3f5790 --- /dev/null +++ b/docs/general/api-documentation-logistics.md @@ -0,0 +1,55 @@ +# API documentation logistics + +We offer a meticulously organized API documentation to support developers in +enhancing their comprehension of the functionalities available within the +`@bigbinary/neeto-cist` package. This documentation serves the dual +purpose of generating [JSDocs](https://jsdoc.app/), underscoring the importance +of upholding a uniform format. + +To ensure a consistent structure for the documentation, it's necessary to follow +the guidelines outlined below when adding a new utility or editing an existing +one within the package: + +1. When adding a new utility, create a file with the same name as that of + function in the respective directory inside the `pure` directory based on its use case. +2. Follow the format below to compose the function documentation: + +``` +## ([source code]()) + + + +### Arguments: + + + +### Return value: + + + +### Usage + + +``` + +3. Link to the source code should be attached using a + [permalink](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files) + from GitHub instead of generic links. Whenever the function is edited in the + future, make sure to update the permalink to reference the latest version of + the function. +4. `Arguments` and `Return value` sections may be omitted depending on the + function signature. +5. In the `Usage` section, include comprehensive examples that demonstrate how + the function should be utilized in various scenarios. If a function requires + additional context, consider explaining the problem it solves using + real-world scenarios. +6. Maintain a clear and concise language. Avoid unnecessary embellishments and + keep your descriptions succinct. +7. Ensure that sentences are well-formed with proper punctuation. +8. It's worth noting that when the document is converted to JSDoc, all headers + and bullet points will be excluded, leaving only the descriptive portion of + the function documentation. +9. It's crucial to present examples in the `Usage` section within a code block. + The content within the code block will be parsed, and its contents will be + added within the [example](https://jsdoc.app/tags-example.html) tags in + JSDoc. diff --git a/docs/general/building-and-releasing.md b/docs/general/building-and-releasing.md index 06f5f3d..0eb3164 100644 --- a/docs/general/building-and-releasing.md +++ b/docs/general/building-and-releasing.md @@ -1,18 +1,18 @@ -# Building and releasing. +# Building and releasing -The `@bigbinary/neeto-cist` package gets published to NPM when we merge a PR -with `patch`, `minor` or `major` label to the `main` branch. The `patch` label -is used for bug fixes, `minor` label is used for new features and `major` label -is used for breaking changes. You can checkout the `Create and publish releases` -workflow in GitHub Actions to get a live update. +The `@bigbinary/neeto-cist` package gets published to NPM when we +merge a PR with `patch`, `minor` or `major` label to the `main` branch. The +`patch` label is used for bug fixes, `minor` label is used for new features and +`major` label is used for breaking changes. You can checkout the +`Create and publish releases` workflow in GitHub Actions to get a live update. In case if you missed to add the label, you can manually publish the package. For that first you need to create a PR to update the version number in the `package.json` file and merge it to the `main` branch. After merging the PR, you need to create a -[new github release](https://github.com/bigbinary/neeto-cist/releases/new) from -main branch. Whenever a new release is created with a new version number, the -github actions will automatically publish the built package to npm. You can +[new github release](https://github.com/bigbinary/neeto-cist/releases/new) +from main branch. Whenever a new release is created with a new version number, +the github actions will automatically publish the built package to npm. You can checkout the `Publish to npm` workflow in GitHub Actions to get a live update. Please note that before publishing the package, you need to verify the diff --git a/docs/general/development-instructions.md b/docs/general/development-instructions.md index aa63538..dcd6f5f 100644 --- a/docs/general/development-instructions.md +++ b/docs/general/development-instructions.md @@ -6,10 +6,11 @@ 3. Have a host application ready. 4. Run `yarn build --watch` to automatically transpile code as you save the file. You can omit the `--watch` flag if you want to run the build only once. -5. In a different terminal, run `yalc publish` to publish the neeto-cist to the - local yalc store. -6. Run `yalc add @bigbinary/neeto-cist` to install the neeto-cist to the host - application. -7. After making necessary changes to `neeto-cist`, run `yalc push` to push the - changes to the host application (assuming that you are in watch mode and the - changes are bundled automatically). +5. In a different terminal, run `yalc publish` to publish the + neeto-cist to the local yalc store. +6. Run `yalc add @bigbinary/neeto-cist` to install the + neeto-cist to the host application. +7. After making necessary changes to `neeto-cist`, run `yalc push` + to push the changes to the host application (assuming that you are in watch + mode and the changes are bundled automatically). +8. Video explanation on how to use yalc: https://youtu.be/F4zZFnrNTq8 diff --git a/docs/pure/README.md b/docs/pure/README.md deleted file mode 100644 index 1e0212c..0000000 --- a/docs/pure/README.md +++ /dev/null @@ -1,122 +0,0 @@ -# General utility functions - -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 }`. - -## Usage - -You can import all functions from `@bigbinary/neeto-cist`. - -```js -import { slugify } from "@bigbinary/neeto-cist"; -``` - -## Available functions - - - - - - - - - - - - - - - - - - -
- -[Array operations](./arrays.md) - - - -[Object operations](./objects.md) - - - -[String operations](./strings.md) - - - -[General utility functions](./general.md) - -
- -- [findById](./arrays.md#findbyid) -- [findIndexById](./arrays.md#findindexbyid) -- [removeById](./arrays.md#removebyid) -- [replaceById](./arrays.md#replacebyid) -- [modifyById](./arrays.md#modifybyid) -- [existsById](./arrays.md#existsbyid) - ---- - -- [findBy](./arrays.md#findby) -- [findIndexBy](./arrays.md#findindexby) -- [removeBy](./arrays.md#removeby) -- [replaceBy](./arrays.md#replaceby) -- [modifyBy](./arrays.md#modifyby) -- [existsBy](./arrays.md#existsby) -- [findLastBy](./arrays.md#findlastby) -- [findLastIndexBy](./arrays.md#findlastindexby) -- [filterBy](./arrays.md#filterby) -- [countBy](./arrays.md#countby) - ---- - -- [renameKeys](./arrays.md#renamekeys) -- [copyKeys](./arrays.md#copykeys) -- [copyKeysDeep](./arrays.md#copykeysdeep) - - - -- [matchesImpl](./objects.md#matchesimpl) -- [transformObjectDeep](./objects.md#transformobjectdeep) -- [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) - - - -- [slugify](./strings.md#slugify) -- [humanize](./strings.md#humanize) -- [snakeToCamelCase](./strings.md#snaketocamelcase) -- [camelToSnakeCase](./strings.md#cameltosnakecase) -- [capitalize](./strings.md#capitalize) -- [hyphenate](./strings.md#hyphenate) -- [truncate](./strings.md#truncate) - - - -- [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) -
diff --git a/docs/pure/arrays/copyKeys.md b/docs/pure/arrays/copyKeys.md new file mode 100644 index 0000000..1af929f --- /dev/null +++ b/docs/pure/arrays/copyKeys.md @@ -0,0 +1,45 @@ +## copyKeys ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L79-L88)) + +- Curried: true +- Failsafe status: alternative available + +The `copyKeys` function is similar to the [renameKeys](./renameKeys.md) function +but retains both the source and destination keys in the resulting array. For +deep copying of nested objects refer to [copyKeysDeep](./copyKeysDeep.md) +function. + +### Arguments: + +- `keyMap`: An object where the keys are the original keys of the array of + objects and values are the new keys that will be added in the object. + ```js + { + sourceKey1: "destinationKey1", + sourceKey2: "destinationKey2", + } + ``` +- `objectArray`: The array of objects on which the copy function works. + +### Usage: + +```js +const data = [ + { id: 1, name: "Tomato", quantity: 10 }, + { id: 2, name: "Potato", quantity: 20 }, +]; + +// copy name to label and id to value +copyKeys({ name: "label", id: "value" }, data); + +/* +output: [ + { label: "Tomato", value: 1, id: 1, name: "Tomato", quantity: 10 }, + { label: "Potato", value: 2, id: 2, name: "Potato", quantity: 20 }, +]; +*/ +``` + +### See also + +- [copyKeysDeep](./copyKeysDeep.md) +- [renameKeys](./renameKeys.md) diff --git a/docs/pure/arrays/copyKeysDeep.md b/docs/pure/arrays/copyKeysDeep.md new file mode 100644 index 0000000..d4345bd --- /dev/null +++ b/docs/pure/arrays/copyKeysDeep.md @@ -0,0 +1,96 @@ +## copyKeysDeep ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L102-L121)) + +- Curried: true +- Failsafe status: alternative available + +The `copyKeysDeep` function is an advanced version of the +[copyKeys](./copyKeys.md) function. It supports deep copying with nested objects +and offers flexibility in specifying key mappings for the copy operation. + +### Arguments: + +- `keyMap`: The key mapping object which supports object nesting. The value can + be of three types: + + - string: the value of the source key in the object of same nesting will be + copied. + ```js + { + destinationKey: "sourceKey", + { + destinationKey: "sourceKeyInNestedObject", + }, + } + ``` + - array: to pass an absolute path of the source keys to the object that needs + to be copied. + ```js + { + destinationKey: ["path", "to", "sourceKeyInNestedObject"]; + } + ``` + - function: the function will be called with the value corresponding to the + destination key in the source object and the result will be copied. It will + also get the root object as the second argument. + ```js + { destinationKey: (value, root) => value + root.id, } + ``` + +- `objectArray`: The array of objects on which the copyKeysDeep object works. + +### Usage: + +```js +const data = [ + { + id: 1, + name: "Tomato", + quantity: 10, + user: { id: 1, name: "John", bonusQty: 3 }, + address: { street: "First street", pin: 101283 }, + }, + { + id: 2, + name: "Potato", + quantity: 20, + user: { id: 2, name: "Jane", bonusQty: 2 }, + address: { street: "Second street", pin: 998472 }, + }, +]; + +// Create a new array to hold the transformed objects +copyKeysDeep( + { + label: "name", + quantity: (qty, root) => qty + root.user.bonusQty, + user: { pin: ["address", "pin"] }, + }, + data +); + +/* +output: [ + { + label: "Tomato", // label copied + id: 1, + name: "Tomato", + quantity: 13, // quantity updated + user: { pin: 101283, id: 1, name: "John", bonusQty: 3 }, // pin copied + address: { street: "First street", pin: 101283 }, + }, + { + label: "Potato", + id: 2, + name: "Potato", + quantity: 22, + user: { id: 2, name: "Jane", bonusQty: 2 }, + address: { pin: 998472, street: "Second street" }, + }, +]; +*/ +``` + +### See also + +- [copyKeys](./copyKeys.md) +- [renameKeys](./renameKeys.md) diff --git a/docs/pure/arrays/countBy.md b/docs/pure/arrays/countBy.md new file mode 100644 index 0000000..ba04556 --- /dev/null +++ b/docs/pure/arrays/countBy.md @@ -0,0 +1,28 @@ +## countBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L75-L77)) + +- Curried: true +- Failsafe status: alternative available + +The `countBy` function counts the number of items in an array that match the +provided pattern. + +### Arguments: + +- `pattern`: The pattern using which objects will be matched. +- `entityArray`: The array of objects from which the objects with the given + pattern will be counted. + +### Usage: + +```js +const array = [ + { name: "Oliver", age: 20 }, + { name: "Sam", age: 40 }, + { name: "George", age: 41 }, + { name: "Smith", age: 20 }, +]; + +countBy({ age: 20 }, array); // returns 2 +countBy({ age: gt(__, 40) }, array); // returns 1 +countBy({ age: 50 }, array); // returns 0 +``` diff --git a/docs/pure/arrays/existsBy.md b/docs/pure/arrays/existsBy.md new file mode 100644 index 0000000..c41fbe8 --- /dev/null +++ b/docs/pure/arrays/existsBy.md @@ -0,0 +1,29 @@ +## existsBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L51-L53)) + +- Curried: true +- Failsafe status: alternative available + +The `existsBy` function searches for an item in the array that matches the +provided pattern and returns true if found, or false otherwise. + +### Arguments: + +- `pattern`: The pattern using which an object will be matched. +- `entityArray`: The array of objects in which the object with the given pattern + will be searched. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam", address: { street: "First street", pin: 101283 } }, + { id: 2, name: "Oliver", address: { street: "Second street", pin: 998472 } }, +]; + +existsBy({ name: "Sam" }, array); // true +existsBy({ name: "Harry" }, array); // false +``` + +### See also + +- [existsById](./existsById.md) diff --git a/docs/pure/arrays/existsById.md b/docs/pure/arrays/existsById.md new file mode 100644 index 0000000..7ed6557 --- /dev/null +++ b/docs/pure/arrays/existsById.md @@ -0,0 +1,28 @@ +## existsById ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L47-L49)) + +- Curried: true +- Failsafe status: alternative available + +The `existsById` function searches for an item in the provided array using the +given id. + +### Arguments: + +- `id`: The id of the object to be searched. +- `entityArray`: The array of objects in which the given id will be searched. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam" }, + { id: 2, name: "Oliver" }, +]; + +existsById(2, array); // true Oliver's id is 2 +existsById(5, array); // false no one has an id of 5 +``` + +### See also + +- [existsBy](./existsBy.md) diff --git a/docs/pure/arrays/filterBy.md b/docs/pure/arrays/filterBy.md new file mode 100644 index 0000000..150c50b --- /dev/null +++ b/docs/pure/arrays/filterBy.md @@ -0,0 +1,27 @@ +## filterBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L71-L73)) + +- Curried: true +- Failsafe status: alternative available + +The `filterBy` function filters an array of items based on pattern matching. + +### Arguments: + +- `pattern`: The pattern using which objects will be matched. +- `entityArray`: The array of objects from which the objects with the given + pattern will be returned. + +### Usage: + +```js +const array = [ + { name: "Oliver", age: 20 }, + { name: "Sam", age: 40 }, + { name: "George", age: 41 }, + { name: "Smith", age: 20 }, +]; + +filterBy({ age: 20 }, array); // [{ name: "Oliver", age: 20 }, { name: "Smith", age: 20 }] +filterBy({ age: gt(__, 40) }, array); // [{ name: "George", age: 41 }] +filterBy({ age: 50 }, array); // [] +``` diff --git a/docs/pure/arrays/findBy.md b/docs/pure/arrays/findBy.md new file mode 100644 index 0000000..cd98616 --- /dev/null +++ b/docs/pure/arrays/findBy.md @@ -0,0 +1,30 @@ +## findBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L31-L33)) + +- Curried: true +- Failsafe status: alternative available + +The `findBy` function locates the first item in the array that matches the +provided pattern. + +### Arguments: + +- `pattern`: The pattern using which an object will be matched. +- `entityArray`: The array of objects in which the object with the given pattern + will be found. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam", address: { street: "First street", pin: 123456 } }, + { id: 2, name: "Oliver", address: { street: "Second street", pin: 654321 } }, +]; + +findBy({ name: "Sam" }, array); // returns object corresponding to Sam +findBy({ id: 2, address: { pin: 654321 } }, array); // returns object corresponding to Oliver +findBy({ id: 3 }, array); // returns undefined +``` + +### See also + +- [findById](./findById.md) diff --git a/docs/pure/arrays/findById.md b/docs/pure/arrays/findById.md new file mode 100644 index 0000000..df4dc13 --- /dev/null +++ b/docs/pure/arrays/findById.md @@ -0,0 +1,29 @@ +## findById ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L19-L21)) + +- Curried: true +- Failsafe status: alternative available + +The `findById` function is used to locate an object within an array based on the +provided Id. + +### Arguments: + +- `id`: The id of object to be searched. +- `entityArray`: The array of objects in which the given id will be searched. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam" }, + { id: 2, name: "Oliver" }, +]; +const idOfItemToBeFind = 2; + +findById(idOfItemToBeFind, array); +// { id: 2, name: "Oliver" } +``` + +### See also + +- [findBy](./findBy.md) diff --git a/docs/pure/arrays/findIndexBy.md b/docs/pure/arrays/findIndexBy.md new file mode 100644 index 0000000..1ed6320 --- /dev/null +++ b/docs/pure/arrays/findIndexBy.md @@ -0,0 +1,30 @@ +## findIndexBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L63-L65)) + +- Curried: true +- Failsafe status: alternative available + +The `findIndexBy` function finds the index of the item in the array that matches +the provided pattern. + +### Arguments: + +- `pattern`: The pattern using which an object will be matched. +- `entityArray`: The array of objects in which the object with the given pattern + will be searched. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam", address: { street: "First street", pin: 123456 } }, + { id: 2, name: "Oliver", address: { street: "Second street", pin: 654321 } }, +]; + +findIndexBy({ name: "Sam" }, array); // returns 0 +findIndexBy({ id: 2, address: { pin: 654321 } }, array); // returns 1 +findIndexBy({ id: 3 }, array); // returns -1 +``` + +### See also + +- [findIndexById](./findIndexById.md) diff --git a/docs/pure/arrays/findIndexById.md b/docs/pure/arrays/findIndexById.md new file mode 100644 index 0000000..2bf77d4 --- /dev/null +++ b/docs/pure/arrays/findIndexById.md @@ -0,0 +1,29 @@ +## findIndexById ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L59-L61)) + +- Curried: true +- Failsafe status: alternative available + +The `findIndexById` function is used to find the index of an item within an +array of items based on the `id` property of the entities within it. + +### Arguments: + +- `id`: The id of object to be searched. +- `entityArray`: The array of objects in which the given id will be searched. + +### Usage: + +```js +const array = [ + { id: "1001", name: "Sam" }, + { id: "2001", name: "Oliver" }, +]; + +findIndexById("2001", array); // returns 1 +findIndexById("1001", array); // returns 0 +findIndexById("3001", array); // returns -1 +``` + +### See also + +- [findIndexBy](./findIndexBy.md) diff --git a/docs/pure/arrays/findLastBy.md b/docs/pure/arrays/findLastBy.md new file mode 100644 index 0000000..66c229b --- /dev/null +++ b/docs/pure/arrays/findLastBy.md @@ -0,0 +1,31 @@ +## findLastBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L55-L57)) + +- Curried: true +- Failsafe status: alternative available + +The `findLastBy` function finds the last item in the array that matches the +provided pattern. + +### Arguments: + +- `pattern`: The pattern using which an object will be matched. +- `entityArray`: The array of objects in which the object with the given pattern + will be searched. + +### Usage: + +```js +const array = [ + { name: "Oliver", age: 20 }, + { name: "Sam", age: 40 }, + { name: "George", age: 41 }, + { name: "Smith", age: 20 }, +]; + +findLastBy({ age: 20 }, array); // { name: "Smith", age: 20 } +findLastBy({ name: includes("e") }, array); // { name: "George", age: 41 } +``` + +### See also + +- [findLastIndexBy](./findLastIndexBy.md) diff --git a/docs/pure/arrays/findLastIndexBy.md b/docs/pure/arrays/findLastIndexBy.md new file mode 100644 index 0000000..70739b8 --- /dev/null +++ b/docs/pure/arrays/findLastIndexBy.md @@ -0,0 +1,31 @@ +## findLastIndexBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L67-L69)) + +- Curried: true +- Failsafe status: alternative available + +The `findLastIndexBy` function finds the last index of an item in the array that +matches the provided pattern. + +### Arguments: + +- `pattern`: The pattern using which an object will be matched. +- `entityArray`: The array of objects in which the object with the given pattern + will be searched. + +### Usage: + +```js +const array = [ + { name: "Oliver", age: 20 }, + { name: "Sam", age: 40 }, + { name: "George", age: 41 }, + { name: "Smith", age: 20 }, +]; + +findLastIndexBy({ age: 20 }, array); // returns 3 +findLastIndexBy({ name: includes("e") }, array); // returns 2 +``` + +### See also + +- [findLastBy](./findLastBy.md) diff --git a/docs/pure/arrays/modifyBy.md b/docs/pure/arrays/modifyBy.md new file mode 100644 index 0000000..f6e1cda --- /dev/null +++ b/docs/pure/arrays/modifyBy.md @@ -0,0 +1,34 @@ +## modifyBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L43-L45)) + +- Curried: true +- Failsafe status: alternative available + +The `modifyBy` function modifies all items in the array that match the provided +pattern using the given modifier function. + +### Arguments: + +- `pattern`: The pattern using which the objects will be matched. +- `modifier`: A modifier function to modify required properties of the matched + objects. +- `entityArray`: The array of objects in which the objects with given pattern + will be modified using the modifier function. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam", address: { street: "First street", pin: 101283 } }, + { id: 2, name: "Oliver", address: { street: "Second street", pin: 998472 } }, +]; +const modifier = item => assoc("name", item.name.toUpperCase(), item); + +modifyBy({ name: "Oliver" }, modifier, array); +/* +[{id: 1, name: "Sam"}, {id: 2, name: "OLIVER"}] + */ +``` + +### See also + +- [modifyById](./modifyById.md) diff --git a/docs/pure/arrays/modifyById.md b/docs/pure/arrays/modifyById.md new file mode 100644 index 0000000..21e4825 --- /dev/null +++ b/docs/pure/arrays/modifyById.md @@ -0,0 +1,35 @@ +## modifyById ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L27-L29)) + +- Curried: true +- Failsafe status: alternative available + +The `modifyById` function applies a modifier function to the item with the +specified id in an array and returns a new array with the modified item in the +same index. + +### Arguments: + +- `id`: The id of the object to be modified. +- `modifier`: A modifier function to modify required properties of the object. +- `entityArray`: The array of objects in which the object with given id will be + modified using the modifier function. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam" }, + { id: 2, name: "Oliver" }, +]; +const idOfItemToBeModified = 2; +const modifier = item => assoc("name", item.name.toUpperCase(), item); + +modifyById(idOfItemToBeModified, modifier, array); +/* +[{ id: 1, name: "Sam" }, { id: 2, name: "OLIVER" }] +*/ +``` + +### See also + +- [modifyBy](./modifyBy.md) diff --git a/docs/pure/arrays/removeBy.md b/docs/pure/arrays/removeBy.md new file mode 100644 index 0000000..9aa0170 --- /dev/null +++ b/docs/pure/arrays/removeBy.md @@ -0,0 +1,30 @@ +## removeBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L35-L37)) + +- Curried: true +- Failsafe status: alternative available + +The `removeBy` function removes all items in the array that match the provided +pattern. + +### Arguments: + +- `pattern`: The pattern using which the objects will be matched. +- `entityArray`: The array of objects in which the objects with the given + pattern will be removed. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam", address: { street: "First street", pin: 101283 } }, + { id: 2, name: "Oliver", address: { street: "Second street", pin: 998472 } }, +]; + +removeBy({ name: "Sam" }, array); // removes Sam +removeBy({ id: 2, address: { pin: 654321 } }, array); // removes Oliver +removeBy({ id: 3 }, array); // does nothing +``` + +### See also + +- [removeById](./removeById.md) diff --git a/docs/pure/arrays/removeById.md b/docs/pure/arrays/removeById.md new file mode 100644 index 0000000..92e6a35 --- /dev/null +++ b/docs/pure/arrays/removeById.md @@ -0,0 +1,30 @@ +## removeById ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L15-L17)) + +- Curried: true +- Failsafe status: alternative available + +The `removeById` function generates a new array with the item possessing the +specified id removed. + +### Arguments: + +- `id`: The id of object to be removed. +- `entityArray`: The array of objects from which the object with given id will + be removed. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam" }, + { id: 2, name: "Oliver" }, +]; +const idOfItemToBeRemoved = 2; + +removeById(idOfItemToBeRemoved, array); +// [{ id: 1, name: "Sam" }] +``` + +### See also + +- [removeBy](./removeBy.md) diff --git a/docs/pure/arrays/renameKeys.md b/docs/pure/arrays/renameKeys.md new file mode 100644 index 0000000..d907999 --- /dev/null +++ b/docs/pure/arrays/renameKeys.md @@ -0,0 +1,44 @@ +## renameKeys ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L90-L100)) + +- Curried: true +- Failsafe status: alternative available + +The `renameKeys` function renames specified keys in each object of an array +while keeping their values the same. It creates a new instance and does not +mutate the original array. + +### Arguments: + +- `keyMap`: An object where the keys are the original keys of the array of + objects and values are the keys to which it should be renamed. + ```js + { + sourceKey1: "destinationKey1", + sourceKey2: "destinationKey2", + } + ``` +- `entityArray`: The array of objects on which the rename function works. + +### Usage: + +```js +const data = [ + { id: 1, name: "Tomato", quantity: 10 }, + { id: 2, name: "Potato", quantity: 20 }, +]; + +// rename name to label and id to value +renameKeys({ name: "label", id: "value" }, data); + +/* +output: [ + { label: "Tomato", value: 1, quantity: 10 }, + { label: "Potato", value: 2, quantity: 20 }, +]; +*/ +``` + +### See also + +- [copyKeys](./copyKeys.md) +- [copyKeysDeep](./copyKeysDeep.md) diff --git a/docs/pure/arrays/replaceBy.md b/docs/pure/arrays/replaceBy.md new file mode 100644 index 0000000..2bb2ee6 --- /dev/null +++ b/docs/pure/arrays/replaceBy.md @@ -0,0 +1,33 @@ +## replaceBy ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L39-L41)) + +- Curried: true +- Failsafe status: alternative available + +The `replaceBy` function replaces all items in the array that match the provided +pattern with the given item. + +### Arguments: + +- `pattern`: The pattern using which the objects will be matched. +- `newItem`: The object with which the matched objects need to be replaced. +- `entityArray`: The array of objects in which the objects with the given + pattern will be replaced. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam", address: { street: "First street", pin: 101283 } }, + { id: 2, name: "Oliver", address: { street: "Second street", pin: 998472 } }, +]; +const newItem = { id: 2, name: "John" }; + +replaceBy({ name: "Oliver" }, newItem, array); +/* +[{id: 1, name: "Sam"}, {id: 2, name: "John"}] + */ +``` + +### See also + +- [replaceById](./replaceById.md) diff --git a/docs/pure/arrays/replaceById.md b/docs/pure/arrays/replaceById.md new file mode 100644 index 0000000..56d3582 --- /dev/null +++ b/docs/pure/arrays/replaceById.md @@ -0,0 +1,34 @@ +## replaceById ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/arrays.js#L23-L25)) + +- Curried: true +- Failsafe status: alternative available + +The `replaceById` function returns a new array with the item having the +specified id replaced by the provided object. + +### Arguments: + +- `id`: The id of the object to be replaced. +- `newItem`: The new object to replace. +- `entityArray`: The array of objects in which the object with given id will be + replaced with the given object. + +### Usage: + +```js +const array = [ + { id: 1, name: "Sam" }, + { id: 2, name: "Oliver" }, +]; +const idOfItemToBeReplaced = 2; +const newItem = { id: 3, name: "John" }; + +replaceById(idOfItemToBeReplaced, newItem, array); +/* +[{ id: 1, name: "Sam" }, { id: 3, name: "John" }] +*/ +``` + +### See also + +- [replaceBy](./replaceBy.md) diff --git a/docs/pure/general/dynamicArray.md b/docs/pure/general/dynamicArray.md new file mode 100644 index 0000000..5c349e3 --- /dev/null +++ b/docs/pure/general/dynamicArray.md @@ -0,0 +1,25 @@ +## dynamicArray ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L49-L50)) + +- Curried: false +- Failsafe status: not failsafe + +The `dynamicArray` function constructs an array of a specified length using a +provided function to generate each element. The function takes the index as a +parameter and is expected to return the element corresponding to that index. + +This function does not include a failsafe mechanism, so it is important to +ensure that the provided function and length are valid to prevent errors. + +### Arguments: + +- `count`: The length of the array to be generated. +- `elementGenerator`: The function that returns the element to be generated for + that index. This function will get index as a parameter. + +### Usage: + +```js +dynamicArray(3, index => `option ${index + 1}`); + +// output: ["option 1", "option 2", "option 3"] +``` diff --git a/docs/pure/general/getRandomInt.md b/docs/pure/general/getRandomInt.md new file mode 100644 index 0000000..bc9ff9f --- /dev/null +++ b/docs/pure/general/getRandomInt.md @@ -0,0 +1,21 @@ +## getRandomInt ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L31-L41)) + +- Curried: false +- Failsafe status: not failsafe + +The `getRandomInt` function generates a random integer within a specified range. +If only one argument is provided, it is considered as the upper bound, and the +lower bound is assumed to be 0. + +### Arguments: + +- `a`: The lower bound of the range. Defaults to 0. +- `b`: The upper bound of the range. Defaults to 9007199254740991. + +### Usage: + +```js +getRandomInt(); // returns a random integer between 0 and 9007199254740991 (MAX_SAFE_INTEGER) +getRandomInt(10); // returns a random integer between 0 and 10 +getRandomInt(1, 5); // returns a random integer between 1 and 5 +``` diff --git a/docs/pure/general/isNot.md b/docs/pure/general/isNot.md new file mode 100644 index 0000000..d2dbd95 --- /dev/null +++ b/docs/pure/general/isNot.md @@ -0,0 +1,31 @@ +## isNot ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L54-L55)) + +- Alias: notEquals +- Curried: false +- Failsafe status: failsafe by default + +The `isNot` function returns `true` if the given values (or references) are not +equal and `false` otherwise. It provides the opposite behavior of the +`Object.is()` method. + +### Arguments: + +- The two values to be checked for equality. + +### Usage: + +The primary difference between `isNot()` and `!==` is that `isNot()` is a +curried function, which means you can partially apply it to create a new +function that's pre-configured to compare one value against another value +repeatedly. + +```js +const value1 = 10; +const isNotValue1 = isNot(value1); +const value2 = 20; +isNotValue1(value2); // true + +// Filter out fruits that are not Apple +const fruits = ["Apple", "Orange", "Lemon"]; +fruits.filter(notEquals("Apple")); // ["Orange", "Lemon"]; +``` diff --git a/docs/pure/general/isNotEmpty.md b/docs/pure/general/isNotEmpty.md new file mode 100644 index 0000000..1cfb57b --- /dev/null +++ b/docs/pure/general/isNotEmpty.md @@ -0,0 +1,21 @@ +## isNotEmpty ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L52)) + +- Curried: false +- Failsafe status: failsafe by default + +The `isNotEmpty` returns `true` if the given value is not empty (includes +strings, arrays, objects) and `false` otherwise. It provides the opposite +behavior of checking if a value is empty, similar to the isEmpty function in +Ramda. + +### Arguments: + +- The value to be checked. Accepts strings, arrays or objects + +### Usage: + +```js +isNotEmpty(""); // returns false +isNotEmpty(["a"]); // returns true +isNotEmpty({ name: "Oliver" }); //return true +``` diff --git a/docs/pure/general/isNotEqualDeep.md b/docs/pure/general/isNotEqualDeep.md new file mode 100644 index 0000000..841f99f --- /dev/null +++ b/docs/pure/general/isNotEqualDeep.md @@ -0,0 +1,31 @@ +## isNotEqualDeep ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L60-L61)) + +- Alias: notEqualsDeep +- Curried: false +- Failsafe status: failsafe by default + +The `isNotEqualDeep` function returns `true` if the given values are not equal, +considering deep equality. It checks for deep inequality between objects or +arrays. + +### Arguments: + +- The two values to be checked for equality. It can also include deeply nested + objects. + +### Usage: + +```js +const object1 = { + a: 1, + b: { c: 3 }, +}; + +const object2 = { + a: 1, + b: { c: 2 }, +}; + +isNotEqualsDeep(object1, object2); //returns true +notEqualsDeep(object1, object2); //returns true +``` diff --git a/docs/pure/general/isNotPresent.md b/docs/pure/general/isNotPresent.md new file mode 100644 index 0000000..d33cce9 --- /dev/null +++ b/docs/pure/general/isNotPresent.md @@ -0,0 +1,22 @@ +## isNotPresent ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L57)) + +- Curried: true +- Failsafe status: failsafe by default + +The `isNotPresent` function is a utility that checks if a value is not present. +It combines checks for null and empty values. It is worth noting that we also +have an [isPresent](./isPresent.md) `isPresent` utility function that returns the complement of +`isNotPresent`. + +## Arguments + +- The value to be checked for presence. + +## Usage + +```jsx +isNotPresent([]); // returns true +isNotPresent(null); // returns true +isNotPresent(""); // returns true +isNotPresent("Oliver"); // returns false +``` diff --git a/docs/pure/general/isPresent.md b/docs/pure/general/isPresent.md new file mode 100644 index 0000000..8618480 --- /dev/null +++ b/docs/pure/general/isPresent.md @@ -0,0 +1,22 @@ +## isPresent ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L58)) + +- Curried: true +- Failsafe status: failsafe by default + +The `isPresent` function is a utility that checks if a value is present. +It combines checks for null and empty values. It is worth noting that we also +have an [isNotPresent](./isNotPresent.md) utility function that returns the complement of +`isPresent`. + +## Arguments + +- The value to be checked for presence. + +## Usage + +```jsx +isPresent([]); // returns false +isPresent(null); // returns false +isPresent(""); // returns false +isPresent("Oliver"); // returns true +``` diff --git a/docs/pure/general/modifyWithImmer.md b/docs/pure/general/modifyWithImmer.md new file mode 100644 index 0000000..913f9b2 --- /dev/null +++ b/docs/pure/general/modifyWithImmer.md @@ -0,0 +1,49 @@ +## modifyWithImmer ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L63-L65)) + +- Curried: true +- Failsafe status: not failsafe + +The `modifyWithImmer` function is designed for immutable modification of values +and is an abstraction over Immer's `produce` method. Immer is a library that +simplifies working with complex data structures and state updates in a more +immutable manner. + +This function does not include a failsafe mechanism, so it is important to use +it with care, especially when working with complex data structures. + +You can read more about Immer [here](https://immerjs.github.io/immer). + +### Arguments: + +- `modifier`: This is a function that receives a draft state as its parameter. + The draft state is a mutable version of the original state. Inside the + modifier function, we can directly make changes to the draft state as if it + were mutable. Once the modifier function finishes, the changes made to the + draft state are used to create a new immutable result. +- `state`: The value that needs to be modified. + +Returns the new modified value. + +### Usage: + +```js +const data = { name: "Oliver" }; +modifyWithImmer(draft => { + draft.name = "Oliver smith"; +})(data); +// outputs: { name: "Oliver smith" } +``` + +We can utilize currying with state updator functions: + +```js +const { setUsers } = useZustandStore.pick(); + +setUsers( + modifyWithImmer(draft => { + draft[0].addresses.push("Oliver smith"); + }) +); + +// updates users to: [{ name: "Oliver smith" }, { name: "Eve" }] +``` diff --git a/docs/pure/general/noop.md b/docs/pure/general/noop.md new file mode 100644 index 0000000..aca6d0b --- /dev/null +++ b/docs/pure/general/noop.md @@ -0,0 +1,8 @@ +## noop ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L26)) + +- Curried: false +- Failsafe status: failsafe by default + +The `noop` function is a "no-operation" function that does nothing when called and +returns `undefined`. It is often used as a placeholder or a default function +when a function is expected but no action is required. diff --git a/docs/pure/general/nullSafe.md b/docs/pure/general/nullSafe.md new file mode 100644 index 0000000..33fe6af --- /dev/null +++ b/docs/pure/general/nullSafe.md @@ -0,0 +1,18 @@ +## nullSafe ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L18-L24)) + +- Curried: false +- Failsafe status: failsafe by default + +The `nullSafe` function takes a function as an argument and returns a curried version of the function. It ensures that the last argument passed to the curried function is not null or undefined before invoking the original function `func`. + +### Arguments + +- `func`: A function that needs to be curried. + +### Usage + +```js +const add = (a, b) => a + b; +nullSafe(add)(1)(2); +// Output: 3 +``` diff --git a/docs/pure/general/randomPick.md b/docs/pure/general/randomPick.md new file mode 100644 index 0000000..2d97386 --- /dev/null +++ b/docs/pure/general/randomPick.md @@ -0,0 +1,20 @@ +## randomPick ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L43-L47)) + +- Curried: false +- Failsafe status: not failsafe + +The `randomPick` function accepts a variable number of arguments and returns a +random element from the list of arguments. It randomly selects one of the +provided values and returns it. + +### Arguments: + +- Any number of arguments. + +### Usage: + +```js +randomPick("arg1", "arg2", "arg3", "arg4", "arg5"); + +// output: a random element from the list "arg1", "arg2", "arg3", "arg4" and "arg5" +``` diff --git a/docs/pure/general/toLabelAndValue.md b/docs/pure/general/toLabelAndValue.md new file mode 100644 index 0000000..f22d3db --- /dev/null +++ b/docs/pure/general/toLabelAndValue.md @@ -0,0 +1,20 @@ +## toLabelAndValue ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/general.js#L28)) + +- Curried: false +- Failsafe status: failsafe by default + +The `toLabelAndValue` function takes a string as an argument and returns an +object with keys "label" and "value." It is often used to transform a string +into an object with specific key-value pairs. + +### Arguments: + +- `string`: A string that needs to be converted to an object. + +### Usage: + +```js +toLabelAndValue("test"); + +// output: {label: "test", value: "test"} +``` diff --git a/docs/pure/objects/deepFreezeObject.md b/docs/pure/objects/deepFreezeObject.md new file mode 100644 index 0000000..ca8a6bb --- /dev/null +++ b/docs/pure/objects/deepFreezeObject.md @@ -0,0 +1,50 @@ +## deepFreezeObject ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L68-L75)) + +- Curried: false +- Failsafe status: failsafe by default + +The `deepFreezeObject` function is used to make an object immutable by +recursively freezing each property that is of type object. Freezing an object +prevents any changes to its properties, making it effectively immutable. + +### Arguments: + +- `object`: The object to be deep freezed. + +### Usage: + +```js +const user = { + address: { city: "Miami", phoneNumber: "389791382" }, + firstName: "Oliver", +}; +deepFreezeObject(user); + +user.address.phoneNumber = "123456789"; // fails silently in non-strict mode +user.lastName = "Smith"; // fails silently in non-strict mode + +console.log(user); + +/* +{ + address: { city: "Miami", phoneNumber: "389791382" }, + firstName: "Oliver", +}; +*/ +``` + +The assignment operation will throw the error only when we execute it in strict +mode, in non-strict mode it will fail silently. + + +```js +"use strict"; user.address.phoneNumber = "123456789"; +/* +Cannot assign to read only property 'phoneNumber' of object '# +*/ + +"use strict"; user.lastName = "Smith"; +/* +Cannot add property lastName, object is not extensible +*/ +``` diff --git a/docs/pure/objects/filterNonNull.md b/docs/pure/objects/filterNonNull.md new file mode 100644 index 0000000..904cfc4 --- /dev/null +++ b/docs/pure/objects/filterNonNull.md @@ -0,0 +1,30 @@ +## filterNonNull ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L81-L89)) + +- Curried: false +- Failsafe status: alternative available + +The `filterNonNull` function accepts an object and returns a new object with +only the properties that are not `null` or `undefined`. It filters out +properties with these values, creating a new object with only the non-null and +non-undefined properties. + +### Arguments: + +- `object`: An object which can contain `null` or `undefined` values. + +### Usage: + +```js +filterNonNull({ + firstName: "Oliver", + lastName: null, + phoneNumbers: { home: undefined, office: "1234567890" }, +}); + +/* +{ + firstName: "Oliver", + phoneNumbers: { office: "1234567890" }, +} +*/ +``` diff --git a/docs/pure/objects/keysToCamelCase.md b/docs/pure/objects/keysToCamelCase.md new file mode 100644 index 0000000..04e9e25 --- /dev/null +++ b/docs/pure/objects/keysToCamelCase.md @@ -0,0 +1,28 @@ +## keysToCamelCase ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L48-L49)) + +- Curried: false +- Failsafe status: failsafe by default + +The `keysToCamelCase` function recursively converts the snake-cased object keys +to camel case. + +### Arguments: + +- `object`: An object with `snake_case` keys. + +### Usage: + +```js +keysToCamelCase({ + first_name: "Oliver", + last_name: "Smith", + address: { city: "Miami", phone_number: "389791382" }, +}); +/* +{ + address: {city: 'Miami', phoneNumber: '389791382'}, + firstName: "Oliver", + lastName: "Smith", +} +*/ +``` diff --git a/docs/pure/objects/keysToSnakeCase.md b/docs/pure/objects/keysToSnakeCase.md new file mode 100644 index 0000000..8b813e9 --- /dev/null +++ b/docs/pure/objects/keysToSnakeCase.md @@ -0,0 +1,28 @@ +## keysToSnakeCase ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L51-L52)) + +- Curried: false +- Failsafe status: failsafe by default + +The `keysToSnakeCase` function recursively converts the camel-cased object keys +to snake case. + +### Arguments: + +- `object`: An object with `camelCase` keys. + +### Usage: + +```js +keysToSnakeCase({ + address: { city: "Miami", phoneNumber: "389791382" }, + firstName: "Oliver", + lastName: "Smith", +}); +/* +{ + first_name: "Oliver", + last_name: "Smith", + address: { city: "Miami", phone_number: "389791382" }, +} +*/ +``` diff --git a/docs/pure/objects/matches.md b/docs/pure/objects/matches.md new file mode 100644 index 0000000..87ea2ba --- /dev/null +++ b/docs/pure/objects/matches.md @@ -0,0 +1,45 @@ +## matches ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L77-L79)) + +- Curried: true +- Failsafe status: failsafe by default + +The `matches` function checks whether the given object matches the given +pattern. It compares the primitive value (int, boolean, string, etc.) in the +object with the corresponding values in the pattern (deeply) and checks if all +conditions (functions) are satisfied for a match. + +### 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" }], +}; + +matches({ firstName: "Oliver" }, user); // true +matches({ address: { city: "Miami" } }, user); // true +matches({ cars: [{ brand: "Ford" }] }, user); // true +matches({ firstName: "Sam" }, user); // false +matches({ address: { country: "US" } }, user); // false +matches({ cars: [{ brand: "Honda" }] }, user); // false +// array index as object key +matches({ cars: { 1: { brand: "Honda" } } }, user); // true +// conditional functions +matches({ cars: arr => arr.length === 2 }, user); // true +// point-free functions with ramda +matches({ firstName: startsWith("O") }, user); // true +``` diff --git a/docs/pure/objects/matchesImpl.md b/docs/pure/objects/matchesImpl.md new file mode 100644 index 0000000..c83bbd1 --- /dev/null +++ b/docs/pure/objects/matchesImpl.md @@ -0,0 +1,39 @@ +## matchesImpl ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L6-L18)) + +- Curried: false +- Failsafe status: failsafe by default + +Non curried version of [matches](./matches.md). See matches for curried version. + +The `matchesImpl` function 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. + +### 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 +``` diff --git a/docs/pure/objects/preprocessForSerialization.md b/docs/pure/objects/preprocessForSerialization.md new file mode 100644 index 0000000..114161e --- /dev/null +++ b/docs/pure/objects/preprocessForSerialization.md @@ -0,0 +1,23 @@ +## preprocessForSerialization ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L61-L66)) + +- Curried: false +- Failsafe status: failsafe by default + +The `preprocessForSerialization` function creates a ready-to-be-serialized +version of the given object by recursively traversing all the object properties +and replacing them with their JSON serializable versions. This is particularly +helpful when serializing objects that include non-serializable data types, such +as `Date` objects, `dayjs` objects or custom classes. + +### Arguments: + +- `object`: The object to be JSON serialized. + +### Usage: + +```js +preprocessForSerialization(dayjs("1980-01-01")); // returns "1980-01-01T00:00:00.000Z" +preprocessForSerialization({ + toJSON: () => ({ firstName: "Oliver", lastName: "Smith" }), +}); // returns { firstName: "Oliver", lastName: "Smith" } +``` diff --git a/docs/pure/objects/serializeKeysToSnakeCase.md b/docs/pure/objects/serializeKeysToSnakeCase.md new file mode 100644 index 0000000..c2d5e8a --- /dev/null +++ b/docs/pure/objects/serializeKeysToSnakeCase.md @@ -0,0 +1,58 @@ +## serializeKeysToSnakeCase ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L54-L59)) + +- Curried: false +- Failsafe status: failsafe by default + +The `serializeKeysToSnakeCase` function recursively converts the camel-cased +object keys to snake case. It gracefully handles special objects like `Date` and +`dayjs` instances. Additionally, while converting, this function checks if the +value being processed is an object and if it has a `toJSON` function. If the +`toJSON` function is present, it calls the function and uses the return value +for further processing. + +### Arguments: + +- `object`: An object with `camelCase` keys to be converted and serialized. + +### Usage: + +Example 1: + +```js +serializeKeysToSnakeCase({ + name: { toJSON: () => ({ firstName: "Oliver", lastName: "Smith" }) }, + phoneNumber: "389791382", +}); + +/* +{ + name: { first_name: "Oliver", last_name: "Smith" }, + phone_number: "389791382", +} +*/ +``` + +Example 2: (Real world example) + +```js +serializeKeysToSnakeCase({ + address: { city: "Miami", phoneNumber: "389791382" }, + firstName: "Oliver", + lastName: "Smith", + dob: new Date("1980-01-01"), +}); + +/* +{ + first_name: "Oliver", + last_name: "Smith", + address: { city: "Miami", phone_number: "389791382" }, + dob: "1980-01-01T00:00:00.000Z", +} +*/ +``` + +In the above example, the value of `dob` is an date object and has `toJSON` +method present in it. The `toJSON` method returns the date in ISO format which +will be used for further processing instead of recursively converting the +original date object. diff --git a/docs/pure/objects/transformObjectDeep.md b/docs/pure/objects/transformObjectDeep.md new file mode 100644 index 0000000..8c818d8 --- /dev/null +++ b/docs/pure/objects/transformObjectDeep.md @@ -0,0 +1,51 @@ +## transformObjectDeep ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/objects.js#L20-L46)) + +- Curried: false +- Failsafe status: failsafe by default + +The `transformObjectDeep` function passes each key and value of the given object +(recursively) to the provided transformer function. It reconstructs an object of +the same hierarchy with the key-value pairs that the transformer function +returns. + +### Arguments: + +- `object`: The object or array to be modified. +- `keyValueTransforme`: The transformer function that receives the key and value + as parameters. It should return a key-value pair. +- `objectPreProcessor`: An object transformer which will be executed on every + value (including the supplied object itself) before any processing is done to + it. (optional) + +Usage: + +```js +transformObjectDeep( + { + name: "Oliver", + email: "oliver@example.com", + address: { street: "First street", pin: 123456 }, + }, + (key, value) => [key.toUpperCase(), value] +); +/* +output: { + NAME: "Oliver", + EMAIL: "oliver@example.com", + ADDRESS: { STREET: "First street", PIN: 123456 }, +} +*/ + +transformObjectDeep( + [ + [1, 2, 3], + [4, 5, 6], + [7, 8, 9], + ], + (key, value) => [key, value], + item => (Array.isArray(item) ? item.slice(1) : item) +); +/* +output: [[5, 6], [8, 9]] +*/ +``` diff --git a/docs/pure/strings/camelToSnakeCase.md b/docs/pure/strings/camelToSnakeCase.md new file mode 100644 index 0000000..96f3952 --- /dev/null +++ b/docs/pure/strings/camelToSnakeCase.md @@ -0,0 +1,16 @@ +## camelToSnakeCase ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/strings.js#L32-L33)) + +- Curried: false +- Failsafe status: alternative available + +The `camelToSnakeCase` function converts a camelCase string to snake_case. + +### Arguments: + +- `string`: The string to be converted. + +### Usage: + +```js +camelToSnakeCase("firstName"); // "first_name" +``` diff --git a/docs/pure/strings/capitalize.md b/docs/pure/strings/capitalize.md new file mode 100644 index 0000000..d3bdf65 --- /dev/null +++ b/docs/pure/strings/capitalize.md @@ -0,0 +1,18 @@ +## capitalize ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/strings.js#L35-L36)) + +- Curried: false +- Failsafe status: alternative available + +The `capitalize` function converts the first character of a string to uppercase. + +### Arguments: + +- `string`: The string to be converted. + +### Usage: + +```js +capitalize("oliver"); // "Oliver" +capitalize("OLIVER"); // "OLIVER" +capitalize("oLIVER"); // "OLIVER" +``` diff --git a/docs/pure/strings/humanize.md b/docs/pure/strings/humanize.md new file mode 100644 index 0000000..6f1c199 --- /dev/null +++ b/docs/pure/strings/humanize.md @@ -0,0 +1,20 @@ +## humanize ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/strings.js#L16-L27)) + +- Curried: false +- Failsafe status: alternative available + +The `humanize` function converts common developer-friendly string formats such +as camelCase, snake_case, dash-case, etc., into human-readable strings. + +### Arguments: + +- `string`: The string to be converted. + +### Usage: + +```js +humanize("helloWorld"); // "Hello world" +humanize("hello-world"); // "Hello world" +humanize("__hello_world"); // "Hello world" +humanize("HelloUSA"); // "Hello usa" +``` diff --git a/docs/pure/strings/hyphenate.md b/docs/pure/strings/hyphenate.md new file mode 100644 index 0000000..de9b6dd --- /dev/null +++ b/docs/pure/strings/hyphenate.md @@ -0,0 +1,20 @@ +## hyphenate ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/strings.js#L38-L50)) + +- Curried: false +- Failsafe status: alternative available + +The `hyphenate` function converts strings that contain underscores, spaces, and +camelCase strings into hyphenated strings + +### Arguments: + +- `string`: The string to be hyphenated. +- `fallbackString`: value to be returned if string is empty. + +### Usage: + +```js +hyphenate("Hello World"); // "hello-world" +hyphenate("hello_world"); // "hello-world" +hyphenate("helloWorld"); // "hello-world" +``` diff --git a/docs/pure/strings/slugify.md b/docs/pure/strings/slugify.md new file mode 100644 index 0000000..2967088 --- /dev/null +++ b/docs/pure/strings/slugify.md @@ -0,0 +1,24 @@ +## slugify ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/strings.js#L5-L14)) + +- Curried: false +- Failsafe status: alternative available + +The `slugify` function converts a given string into a slug. A slug is a +URL-friendly representation of a string, typically used for creating +human-readable and SEO-friendly URLs. This function transforms a string by +removing spaces, special characters, and converting it to lowercase to create a +valid slug. + +### Arguments: + +- `string`: The string to be converted. + +### Usage: + +```js +slugify("My quiz"); // "my-quiz" +slugify("my-quiz"); // "my-quiz" +slugify("-----my----quiz"); // "my-quiz" +slugify("Me & my quiz"); // "me-and-my-quiz" +slugify("my!@#$%^*(quiz"); // "myquiz" +``` diff --git a/docs/pure/strings/snakeToCamelCase.md b/docs/pure/strings/snakeToCamelCase.md new file mode 100644 index 0000000..c544310 --- /dev/null +++ b/docs/pure/strings/snakeToCamelCase.md @@ -0,0 +1,16 @@ +## snakeToCamelCase ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/strings.js#L29-L30)) + +- Curried: false +- Failsafe status: alternative available + +The `snakeToCamelCase` function converts a snake_case string to camelCase. + +### Arguments: + +- `string`: The string to be converted. + +### Usage: + +```js +snakeToCamelCase("first_name"); // "firstName" +``` diff --git a/docs/pure/strings/truncate.md b/docs/pure/strings/truncate.md new file mode 100644 index 0000000..9fd88d8 --- /dev/null +++ b/docs/pure/strings/truncate.md @@ -0,0 +1,19 @@ +## truncate ([source code](https://github.com/bigbinary/neeto-cist/blob/9b5f349ecf0c1c7d258fa92ef2088c29f85274e6/src/strings.js#L52-L53)) + +- Curried: false +- Failsafe status: alternative available + +The `truncate` function truncates a string by adding "..." if it exceeds a +specified maximum length. + +### Arguments: + +- `string`: The string to be truncated. +- `length`: The maximum allowed length of the string. + +### Usage: + +```js +truncate("Hello World", 5); // "Hello..." +truncate("Hello World", 15); // "Hello World" +```