Updates the format of documentation to match neeto-commons-frontend style.

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:
+
+```
+## <function-name> ([source code](<perma-link>))
+
+<description>
+
+### Arguments:
+
+<Arguments as points>
+
+### Return value:
+
+<Return values as points>
+
+### Usage
+
+<Usage goes here>
+```
+
+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.

docs/general/building-and-releasing.md

@@ -1,18 +1,18 @@
 # 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

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

docs/pure/README.md

@@ -1,11 +1,11 @@
 # 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.
+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`.
+Pure functions were designed to be fail fast. If you call `findById(10, null)`, it
+will throw an 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:
@@ -27,22 +27,22 @@ import { slugify } from "@bigbinary/neeto-cist";
 <tr>
 <th>
 
-[Array operations](./arrays.md)
+Array operations
 
 </th>
 <th>
 
-[Object operations](./objects.md)
+Object operations
 
 </th>
 <th>
 
-[String operations](./strings.md)
+String operations
 
 </th>
 <th>
 
-[General utility functions](./general.md)
+General utility functions
 
 </th>
 </tr>
@@ -51,71 +51,71 @@ import { slugify } from "@bigbinary/neeto-cist";
 <tr>
 <td style="vertical-align: top;">
 
-- [findById](./arrays.md#findbyid)
-- [findIndexById](./arrays.md#findindexbyid)
-- [removeById](./arrays.md#removebyid)
-- [replaceById](./arrays.md#replacebyid)
-- [modifyById](./arrays.md#modifybyid)
-- [existsById](./arrays.md#existsbyid)
+- [findById](./arrays/findById.md)
+- [findIndexById](./arrays/findIndexById.md)
+- [removeById](./arrays/removeById.md)
+- [replaceById](./arrays/replaceById.md)
+- [modifyById](./arrays/modifyById.md)
+- [existsById](./arrays/existsById.md)
 
 ---
 
-- [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)
+- [findBy](./arrays/findBy.md)
+- [findIndexBy](./arrays/findIndexBy.md)
+- [removeBy](./arrays/removeBy.md)
+- [replaceBy](./arrays/replaceBy.md)
+- [modifyBy](./arrays/modifyBy.md)
+- [existsBy](./arrays/existsBy.md)
+- [findLastBy](./arrays/findLastBy.md)
+- [findLastIndexBy](./arrays/findLastIndexBy.md)
+- [filterBy](./arrays/filterBy.md)
+- [countBy](./arrays/countBy.md)
 
 ---
 
-- [renameKeys](./arrays.md#renamekeys)
-- [copyKeys](./arrays.md#copykeys)
-- [copyKeysDeep](./arrays.md#copykeysdeep)
+- [renameKeys](./arrays/renameKeys.md)
+- [copyKeys](./arrays/copyKeys.md)
+- [copyKeysDeep](./arrays/copyKeysDeep.md)
 
 </td>
 <td  style="vertical-align: top;">
 
-- [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)
+- [matchesImpl](./objects/matchesImpl.md)
+- [transformObjectDeep](./objects/transformObjectDeep.md)
+- [keysToCamelCase](./objects/keysToCamelCase.md)
+- [keysToSnakeCase](./objects/keysToSnakeCase.md)
+- [serializeKeysToSnakeCase](./objects/serializeKeysToSnakeCase.md)
+- [preprocessForSerialization](./objects/preprocessForSerialization.md)
+- [deepFreezeObject](./objects/deepFreezeObject.md)
+- [matches](./objects/matches.md)
+- [filterNonNull](./objects/filterNonNull.md)
 
 </td>
 <td  style="vertical-align: top;">
 
-- [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)
+- [slugify](./strings/slugify.md)
+- [humanize](./strings/humanize.md)
+- [snakeToCamelCase](./strings/snakeToCamelCase.md)
+- [camelToSnakeCase](./strings/camelToSnakeCase.md)
+- [capitalize](./strings/capitalize.md)
+- [hyphenate](./strings/hyphenate.md)
+- [truncate](./strings/truncate.md)
 
 </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)
+- [nullSafe](./general/nullSafe.md)
+- [noop](./general/noop.md)
+- [toLabelAndValue](./general/toLabelAndValue.md)
+- [getRandomInt](./general/getRandomInt.md)
+- [randomPick](./general/randomPick.md)
+- [dynamicArray](./general/dynamicArray.md)
+- [isNotEmpty](./general/isNotEmpty.md)
+- [isNot (notEquals)](./general/isNot.md)
+- [isNotPresent](./general/isNotPresent.md)
+- [isPresent](./general/isPresent.md)
+- [isNotEqualDeep (alias notEqualsDeep)](./general/isNotEqualDeep.md)
+- [modifyWithImmer](./general/modifyWithImmer.md)
 </td>
 <tr>
 </tbody>

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)