@poppinss/utils 6.9.4 → 7.0.0-next.1

package/README.md

@@ -4,19 +4,25 @@
 
 [![gh-workflow-image]][gh-workflow-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
 
-## Why this package exists?
+## Why does this package exist?
 
-Many of my open source projects (including AdonisJS) use many single-purpose utility packages from npm. Over the years, I have faced the following challenges when using these packages.
+My open-source projects (including AdonisJS) use many single-purpose utility packages from npm. Over the years, I have faced the following challenges when using these packages.
 
-- It takes a lot of time to find a perfect package for the use case. The package should be well maintained, have good test coverage, and not accumulate debt by supporting some old versions of Node.js.
+- Finding the perfect package for the use case takes a lot of time. The package should be well maintained, have good test coverage, and not accumulate debt by supporting some old versions of Node.js.
 - Some packages are great, but they end up pulling a lot of unnecessary dependencies like [(requiring TypeScript as a prod dependency)](https://github.com/blakeembrey/change-case/issues/281)
-- Sometimes I end up using different packages for the same utility (because, I cannot remember what I used last time in that other package). So I want to spend time once choosing the one I need and then bundle it inside `@poppinss/utils`.
+- Sometimes, I use different packages for the same utility (because I cannot remember what I used last time in that other package). So I want to spend time once choosing the one I need and then bundle it inside `@poppinss/utils`.
 - Some authors introduce breaking changes too often (not a criticism). Therefore, I prefer wrapping their packages with my external API only to absorb breaking changes in one place.
-- Rest are some handwritten utilities to fit my needs
+- The rest are some handwritten utilities that fit my needs.
 
-> **Note**: If you are creating an AdonisJS package, I highly recommend using this package since it is already part of the user's project dependencies.
+## Re-exported packages
 
-> **Warning**: This package is not for general use (outside the AdonisJS ecosystem). I will not add new helpers or remove any to cater to a broader audience.
+The following packages are re-exported as it is and you must consult their documentation for usage instructions.
+
+| Package                                                                  | Subpath export              |
+| ------------------------------------------------------------------------ | --------------------------- |
+| [@poppinss/exception](https://www.npmjs.com/package/@poppinss/exception) | `@poppinss/utils/exception` |
+| [@poppinss/string](https://www.npmjs.com/package/@poppinss/string)       | `@poppinss/utils/string`    |
+| [@poppinss/types](https://www.npmjs.com/package/@poppinss/types)         | `@poppinss/utils/types`     |
 
 ## Other packages to use
 
@@ -24,18 +30,17 @@ A note to self and others to consider the following packages.
 
 | Package                                                            | Description                                                                    |
 | ------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| [he](https://www.npmjs.com/package/he)                             | For escaping HTML entities and encoding unicode symbols. Has zero dependencies |
+| [he](https://www.npmjs.com/package/he)                             | For escaping HTML entities and encoding Unicode symbols. Has zero dependencies |
 | [@sindresorhus/is](https://www.npmjs.com/package/@sindresorhus/is) | For advanced type checking. Has zero dependencies                              |
+| [moize](https://www.npmjs.com/package/moize)                       | For memoizing functions with complex parameters                                |
 
 ## Package size
 
-Even though I do not care much about the package size (most of work is consumed on server side), I am mindful around the utilities and ensure not end up using really big packages for smaller use-cases.
+Even though I do not care much about package size (most of my work is consumed on the server side), I am mindful of the utilities and ensure that I do not end up using really big packages for smaller use cases.
 
 Here's the last checked install size of this package.
 
-<a href="https://pkg-size.dev/@poppinss/utils@next">
-  <img src="https://pkg-size.dev/badge/install/319382" title="Install size for @poppinss/utils">
-</a>
+<a href="https://pkg-size.dev/@poppinss/utils@next"><img src="https://pkg-size.dev/badge/install/370120" title="Install size for @poppinss/utils"></a>
 
 ## Installation
 
@@ -48,607 +53,167 @@ npm i @poppinss/utils
 yarn add @poppinss/utils
 ```
 
-## Exported modules
-
-Following are the exported modules. Only the generic helpers are shipped from the main path. The rest of the helpers are grouped inside sub-modules.
-
-```ts
-// string sub-module
-import string from '@poppinss/utils/string'
-
-// string builder
-import string from '@poppinss/utils/string_builder'
-
-// json sub-module
-import json from '@poppinss/utils/json'
-
-// lodash sub-module
-import lodash from '@poppinss/utils/lodash'
-
-// assert sub-module
-import assert from '@poppinss/utils/assert'
-
-// main module
-import { base64, fsReadAll } from '@poppinss/utils'
-
-// types sub-module
-import { ReadAllFilesOptions } from '@poppinss/utils/types'
-```
-
-### String helpers
-
-A collection of helpers to perform operations on/related to a string value.
-
-```ts
-import string from '@poppinss/utils/string'
-```
-
-#### excerpt
-
-Generate an excerpt from a string value. If the input value contains HTML tags, we will remove them from the excerpt.
-
-```ts
-const html = `<p>AdonisJS is a Node.js framework, and hence it requires Node.js to be installed on your computer. To be precise, we need at least the latest release of <code>Node.js v14</code>.</p>`
-
-console.log(string.excerpt(html, 70))
-// AdonisJS is a Node.js framework, and hence it requires Node.js to be i...
-```
-
-| Argument                | Type    | Description                                                                                                                      |
-| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `sentence`              | string  | The value for which to generate excerpt                                                                                          |
-| `charactersLimit`       | string  | The number of characters to keep                                                                                                 |
-| `options.completeWords` | boolean | When set to `true`, the truncation will happen only after complete words. This option might go over the defined characters limit |
-| `options.suffix`        | string  | The value to append after the truncated string. Defaults to three dots `...`                                                     |
-
-#### truncate
-
-Truncate a string value to a certain length. The method is the same as the `excerpt` method but does not remove any HTML tags. It is a great fit when you are truncating a non-HTML string.
-
-```ts
-const text = `AdonisJS is a Node.js framework, and hence it requires Node.js to be installed on your computer. To be precise, we need at least the latest release of Node.js 14.`
-
-console.log(string.truncate(text, 70))
-// AdonisJS is a Node.js framework, and hence it requires Node.js to be i...
-```
-
-| Argument                | Type    | Description                                                                                                                      |
-| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `sentence`              | string  | The value to truncate                                                                                                            |
-| `charactersLimit`       | string  | The number of characters to keep                                                                                                 |
-| `options.completeWords` | boolean | When set to `true`, the truncation will happen only after complete words. This option might go over the defined characters limit |
-| `options.suffix`        | string  | The value to append after the truncated string. Defaults to three dots `...`                                                     |
-
-#### slug
-
-Generate slug for a string value. The method is exported directly from the [slugify](https://www.npmjs.com/package/slugify) package.
-
-Please check the package documentation for [available options](https://www.npmjs.com/package/slugify#options).
-
-```ts
-console.log(string.slug('hello ♥ world'))
-// hello-love-world
-```
-
-You can add custom replacements for Unicode values as follows.
-
-```ts
-string.slug.extend({ '☢': 'radioactive' })
-
-console.log(string.slug('unicode ♥ is ☢'))
-// unicode-love-is-radioactive
-```
-
-#### interpolate
-
-Interpolate variables inside a string. The variables must be inside double curly braces.
-
-```ts
-string.interpolate('hello {{ user.username }}', { user: { username: 'virk' } })
-
-// hello virk
-```
-
-You can also replace array values by mentioning the array index.
-
-```ts
-string.interpolate('hello {{ users.0 }}', { users: ['virk'] })
-
-// hello virk
-```
-
-You can escape the curly braces by prefixing them with `\\`.
-
-```ts
-string.interpolate('hello \\{{ users.0 }}', {})
-
-// hello {{ users.0 }}
-```
-
-#### plural
+## JSON helpers
 
-Convert a word to its plural form. The method is exported directly from the [pluralize](https://www.npmjs.com/package/pluralize) package.
+Safely parse and stringify JSON values. These helpers are thin wrappers over [secure-json-parse](https://github.com/fastify/secure-json-parse) and [safe-stable-stringify](https://github.com/BridgeAR/safe-stable-stringify) packages.
 
-```ts
-string.plural('test')
-// tests
-```
-
-#### singular
-
-Convert a word to its singular form. The method is exported directly from the [pluralize](https://www.npmjs.com/package/pluralize) package.
-
-```ts
-string.singular('tests')
-// test
-```
-
-#### pluralize
+### safeParse
 
-This method combines the `singular` and `plural` methods and uses one or the other based on the count. For example:
+The native implementation of `JSON.parse` opens up the possibility for [prototype poisoning](https://medium.com/intrinsic-blog/javascript-prototype-poisoning-vulnerabilities-in-the-wild-7bc15347c96). The `safeParse` method protects you from that by removing the `__proto__` and the `constructor.prototype` properties from the JSON string at the time of parsing it.
 
 ```ts
-string.pluralize('box', 1) // box
-string.pluralize('box', 2) // boxes
-string.pluralize('box', 0) // boxes
-
-string.pluralize('boxes', 1) // box
-string.pluralize('boxes', 2) // boxes
-string.pluralize('boxes', 0) // boxes
-```
-
-The `addPluralRule`, `addSingularRule`, `addIrregularRule`, and `addUncountableRule` methods exposed by the pluralize package can be called as follows.
+import { safeParse } from '@poppinss/utils/json'
 
-```ts
-string.pluralize.addUncountableRule('paper')
-string.pluralize.addSingularRule(/singles$/i, 'singular')
+safeParse('{ "a": 5, "b": 6, "__proto__": { "x": 7 } }')
+// { a: 5, b: 6 }
 ```
 
-#### isPlural
+### safeStringify
 
-Find if a word is already in plural form. The method is exported directly from the [pluralize](https://www.npmjs.com/package/pluralize) package.
+The native implementation of `JSON.stringify` cannot handle circular references or language-specific data types like `BigInt`. The `safeStringify` method removes circular references and converts BigInts to strings.
+The `safeStringify` method accepts the same set of parameters as the `JSON.stringify` method.
 
 ```ts
-string.isPlural('tests') // true
-```
-
-#### isSingular
-
-Find if a word is already in a singular form. The method is exported directly from the [pluralize](https://www.npmjs.com/package/pluralize) package.
-
-```ts
-string.isSingular('test') // true
-```
-
-#### camelCase
-
-Convert a string value to camelcase.
-
-```ts
-string.camelCase('user_name') // userName
-```
-
-Following are some of the conversion examples.
-
-| Input            | Output        |
-| ---------------- | ------------- |
-| 'test'           | 'test'        |
-| 'test string'    | 'testString'  |
-| 'Test String'    | 'testString'  |
-| 'TestV2'         | 'testV2'      |
-| '_foo_bar_'      | 'fooBar'      |
-| 'version 1.2.10' | 'version1210' |
-| 'version 1.21.0' | 'version1210' |
-
-#### capitalCase
-
-Convert a string value to a capital case.
-
-```ts
-string.capitalCase('helloWorld') // Hello World
-```
-
-Following are some of the conversion examples.
-
-| Input            | Output           |
-| ---------------- | ---------------- |
-| 'test'           | 'Test'           |
-| 'test string'    | 'Test String'    |
-| 'Test String'    | 'Test String'    |
-| 'TestV2'         | 'Test V 2'       |
-| 'version 1.2.10' | 'Version 1.2.10' |
-| 'version 1.21.0' | 'Version 1.21.0' |
-
-#### dashCase
-
-Convert a string value to a dash case.
-
-```ts
-string.dashCase('helloWorld') // hello-world
-```
-
-Optionally, you can capitalize the first letter of each word.
-
-```ts
-string.dashCase('helloWorld', { capitalize: true }) // Hello-World
-```
-
-Following are some of the conversion examples.
-
-| Input            | Output         |
-| ---------------- | -------------- |
-| 'test'           | 'test'         |
-| 'test string'    | 'test-string'  |
-| 'Test String'    | 'test-string'  |
-| 'Test V2'        | 'test-v2'      |
-| 'TestV2'         | 'test-v-2'     |
-| 'version 1.2.10' | 'version-1210' |
-| 'version 1.21.0' | 'version-1210' |
-
-#### dotCase
-
-Convert a string value to a dot case.
-
-```ts
-string.dotCase('helloWorld') // hello.World
-```
-
-Optionally, you can also convert the first letter of all the words to lowercase.
-
-```ts
-string.dotCase('helloWorld', { lowerCase: true }) // hello.world
-```
-
-Following are some of the conversion examples.
-
-| Input            | Output         |
-| ---------------- | -------------- |
-| 'test'           | 'test'         |
-| 'test string'    | 'test.string'  |
-| 'Test String'    | 'Test.String'  |
-| 'dot.case'       | 'dot.case'     |
-| 'path/case'      | 'path.case'    |
-| 'TestV2'         | 'Test.V.2'     |
-| 'version 1.2.10' | 'version.1210' |
-| 'version 1.21.0' | 'version.1210' |
-
-#### noCase
-
-Remove all sorts of casing from a string value.
-
-```ts
-string.noCase('helloWorld') // hello world
-```
-
-Following are some of the conversion examples.
-
-| Input                  | Output                 |
-| ---------------------- | ---------------------- |
-| 'test'                 | 'test'                 |
-| 'TEST'                 | 'test'                 |
-| 'testString'           | 'test string'          |
-| 'testString123'        | 'test string123'       |
-| 'testString_1_2_3'     | 'test string 1 2 3'    |
-| 'ID123String'          | 'id123 string'         |
-| 'foo bar123'           | 'foo bar123'           |
-| 'a1bStar'              | 'a1b star'             |
-| 'CONSTANT_CASE '       | 'constant case'        |
-| 'CONST123_FOO'         | 'const123 foo'         |
-| 'FOO_bar'              | 'foo bar'              |
-| 'XMLHttpRequest'       | 'xml http request'     |
-| 'IQueryAArgs'          | 'i query a args'       |
-| 'dot.case'             | 'dot case'             |
-| 'path/case'            | 'path case'            |
-| 'snake_case'           | 'snake case'           |
-| 'snake_case123'        | 'snake case123'        |
-| 'snake_case_123'       | 'snake case 123'       |
-| '"quotes"'             | 'quotes'               |
-| 'version 0.45.0'       | 'version 0 45 0'       |
-| 'version 0..78..9'     | 'version 0 78 9'       |
-| 'version 4_99/4'       | 'version 4 99 4'       |
-| ' test '               | 'test'                 |
-| 'something_2014_other' | 'something 2014 other' |
-| 'amazon s3 data'       | 'amazon s3 data'       |
-| 'foo_13_bar'           | 'foo 13 bar'           |
-
-#### pascalCase
-
-Convert a string value to pascal case. Great for generating JavaScript class names.
-
-```ts
-string.pascalCase('user team') // UserTeam
-```
-
-Following are some of the conversion examples.
-
-| Input            | Output        |
-| ---------------- | ------------- |
-| 'test'           | 'Test'        |
-| 'test string'    | 'TestString'  |
-| 'Test String'    | 'TestString'  |
-| 'TestV2'         | 'TestV2'      |
-| 'version 1.2.10' | 'Version1210' |
-| 'version 1.21.0' | 'Version1210' |
-
-#### sentenceCase
-
-Convert a value to a sentence.
-
-```ts
-string.sentenceCase('getting-started-with-adonisjs')
-// Getting started with adonisjs
-```
-
-Following are some of the conversion examples.
-
-| Input            | Output           |
-| ---------------- | ---------------- |
-| 'test'           | 'Test'           |
-| 'test string'    | 'Test string'    |
-| 'Test String'    | 'Test string'    |
-| 'TestV2'         | 'Test v2'        |
-| 'version 1.2.10' | 'Version 1 2 10' |
-| 'version 1.21.0' | 'Version 1 21 0' |
-
-#### snakeCase
-
-Convert value to snake case.
-
-```ts
-string.snakeCase('user team') // user_team
-```
-
-Following are some of the conversion examples.
-
-| Input            | Output         |
-| ---------------- | -------------- |
-| '\_id'           | 'id'           |
-| 'test'           | 'test'         |
-| 'test string'    | 'test_string'  |
-| 'Test String'    | 'test_string'  |
-| 'Test V2'        | 'test_v2'      |
-| 'TestV2'         | 'test_v_2'     |
-| 'version 1.2.10' | 'version_1210' |
-| 'version 1.21.0' | 'version_1210' |
-
-#### titleCase
-
-Convert a string value to title case.
-
-```ts
-string.titleCase('small word ends on')
-// Small Word Ends On
-```
-
-Following are some of the conversion examples.
-
-| Input                              | Output                             |
-| ---------------------------------- | ---------------------------------- |
-| 'one. two.'                        | 'One. Two.'                        |
-| 'a small word starts'              | 'A Small Word Starts'              |
-| 'small word ends on'               | 'Small Word Ends On'               |
-| 'we keep NASA capitalized'         | 'We Keep NASA Capitalized'         |
-| 'pass camelCase through'           | 'Pass camelCase Through'           |
-| 'follow step-by-step instructions' | 'Follow Step-by-Step Instructions' |
-| 'this vs. that'                    | 'This vs. That'                    |
-| 'this vs that'                     | 'This vs That'                     |
-| 'newcastle upon tyne'              | 'Newcastle upon Tyne'              |
-| 'newcastle \*upon\* tyne'          | 'Newcastle \*upon\* Tyne'          |
-
-#### random
-
-Generate a cryptographically secure random string of a given length. The output value is URL safe base64 encoded string.
-
-```ts
-string.random(32)
-// 8mejfWWbXbry8Rh7u8MW3o-6dxd80Thk
-```
-
-#### toSentence
-
-Convert an array of words to a comma-separated sentence.
-
-```ts
-string.toSentence(['routes', 'controllers', 'middleware'])
-// routes, controllers, and middleware
-```
-
-You can replace the `and` with an `or` by specifying the `options.lastSeparator` property.
-
-```ts
-string.toSentence(['routes', 'controllers', 'middleware'], {
-  lastSeparator: ', or ',
-})
-```
-
-In the following example, the two words are combined using the `and` separator, not the comma (usually advocated in English). However, you can use a custom separator for a pair of words.
-
-```ts
-string.toSentence(['routes', 'controllers'])
-// routes and controllers
-
-string.toSentence(['routes', 'controllers'], {
-  pairSeparator: ', and ',
-})
-// routes, and controllers
-```
-
-#### condenseWhitespace
+import { safeStringify } from '@poppinss/utils/json'
 
-Remove multiple whitespaces from a string to a single whitespace.
+const value = {
+  b: 2,
+  c: BigInt(10),
+}
 
-```ts
-string.condenseWhitespace('hello  world')
-// hello world
+// Circular reference
+value.a = value
 
-string.condenseWhitespace('  hello  world  ')
-// hello world
+safeStringify(value)
+// '{"b":2,"c":"10"}'
 ```
 
-#### ordinal
+## Lodash helpers
 
-Get the ordinal letter for a given number.
+Lodash is quite a big library, and we do not use all its helper methods. Therefore, we create a custom build using the lodash CLI and bundle only the needed ones.
 
-```ts
-string.ordinal(1) // 1st
-string.ordinal(2) // '2nd'
-string.ordinal(3) // '3rd'
-string.ordinal(4) // '4th'
-
-string.ordinal(23) // '23rd'
-string.ordinal(24) // '24th'
-```
+> **Why not use something else**: All other helpers I have used are not as accurate or well implemented as lodash.
 
-#### seconds.(parse/format)
+- pick
+- omit
+- has
+- get
+- set
+- unset
+- mergeWith
+- merge
+- size
+- clone
+- cloneDeep
+- toPath
 
-Parse a string-based time expression to seconds.
+You can use the methods as follows.
 
 ```ts
-string.seconds.parse('10h') // 36000
-string.seconds.parse('1 day') // 86400
-```
-
-Passing a numeric value to the `parse` method is returned as it is, assuming the value is already in seconds.
+import lodash from '@poppinss/utils/lodash'
 
-```ts
-string.seconds.parse(180) // 180
+lodash.pick(collection, keys)
 ```
 
-You can format seconds to a pretty string using the `format` method.
+## FS helpers
 
-```ts
-string.seconds.format(36000) // 10h
-string.seconds.format(36000, true) // 10 hours
-```
+### fsReadAll
 
-#### milliseconds.(parse/format)
+Get a recursive list of all files from a given directory. This method is similar to the Node.js `readdir` method, with the following differences.
 
-Parse a string-based time expression to milliseconds.
+- Dot files and directories are ignored.
+- Only files are returned (not directories).
+- You can define how the output paths should be returned. The supported types are `relative`, `absolute`, `unixRelative`, `unixAbsolute`, and `url`.
 
 ```ts
-string.milliseconds.parse('1 h') // 3.6e6
-string.milliseconds.parse('1 day') // 8.64e7
-```
+import { fsReadAll } from '@poppinss/utils/fs'
 
-Passing a numeric value to the `parse` method is returned as it is, assuming the value is already in milliseconds.
+const basePath = new URL('./config', import.meta.url)
+const files = await fsReadAll(basePath, { pathType: 'url' })
 
-```ts
-string.milliseconds.parse(180) // 180
+console.log(files)
 ```
 
-Using the `format` method, you can format milliseconds to a pretty string.
+#### OPTIONS
 
-```ts
-string.seconds.format(3.6e6) // 1h
-string.seconds.format(3.6e6, true) // 1 hour
-```
+<dl>
+  <dt>ignoreMissingRoot</dt>
+  <dd>By default, an exception is raised when the root directory is missing. Setting <code>ignoreMissingRoot</code> to true will not result in an error, and an empty array will be returned.</dd>
 
-#### bytes.(parse/format)
+  <dt>filter</dt>
+  <dd>Define a filter to ignore certain paths. The method is called on the final list of files.</dd>
 
-Parse a string-based unit expression to bytes.
+  <dt>sort</dt>
+  <dd>Define a custom method to sort file paths. By default, the files are sorted using natural sort.</dd>
 
-```ts
-string.bytes.parse('1KB') // 1024
-string.bytes.parse('1MB') // 1048576
-```
+  <dt>pathType</dt>
+  <dd>Define how to return the collected paths. By default, OS-specific relative paths are returned. If you want to import the collected files, you must set the <code>pathType = 'url'</code></dd>
+</dl>
 
-Passing a numeric value to the `parse` method is returned as it is, assuming the value is already in bytes.
+### fsImportAll
 
-```ts
-string.bytes.parse(1024) // 1024
-```
+The `fsImportAll` method recursively imports all the JavaScript, TypeScript, and JSON files from a given directory and returns their exported values as an object of key-value pairs.
 
-Using the `format` method, you can format bytes to a pretty string. The method is exported directly from the [bytes](https://www.npmjs.com/package/bytes) package. Please reference the package README for available options.
+- If there are nested directories, then the output will also contain nested objects.
+- Value is the exported values from the module. Only the default value is used if a module exports both the `default` and `named` values.
 
 ```ts
-string.bytes.format(1048576) // 1MB
-string.bytes.format(1024 * 1024 * 1000) // 1000MB
-string.bytes.format(1024 * 1024 * 1000, { thousandsSeparator: ',' }) // 1,000MB
-```
-
-### String builder
+import { fsImportAll } from '@poppinss/utils/fs'
 
-The string builder offers a fluent API for applying a set of transforms on a string value. You can create an instance of the string builder as follows.
+const configDir = new URL('./config', import.meta.url)
+const collection = await fsImportAll(configDir)
 
-```ts
-import StringBuilder from '@poppinss/utils/string_builder'
-const builder = new StringBuilder('hello world')
-
-const value = builder.snakeCase().suffix('_controller').toString()
-assert(value === 'hello_world_controller')
+console.log(collection)
 ```
 
-### JSON helpers
-
-Following are the helpers we use to `stringify` and `parse` JSON.
-
-#### safeParse
-
-The native implementation of `JSON.parse` opens up the possibility for [prototype poisoning](https://medium.com/intrinsic-blog/javascript-prototype-poisoning-vulnerabilities-in-the-wild-7bc15347c96). The `safeParse` method removes the `__proto__` and the `constructor.prototype` properties from the JSON string at the time of parsing it.
-
-The method is a wrapper over [secure-json-parse](https://github.com/fastify/secure-json-parse) package.
-
-#### safeStringify
-
-The native implementation of `JSON.stringify` cannot handle circular references or language-specific data types like `BigInt`.
-
-Therefore, we use the [safe-stable-stringify](https://github.com/BridgeAR/safe-stable-stringify) package under the hood to overcome the limitations of native implementation.
-
-```ts
-import { safeStringify } from '@poppinss/utils/json'
-
-const value = {
-  b: 2,
-  c: BigInt(10),
+```sh
+// title: Directory structure
+├── js
+│   └── config.cjs
+├── json
+│   └── main.json
+└── ts
+    ├── app.ts
+    └── server.ts
+```
+
+```ts
+// title: Output
+{
+  ts: {
+    app: {},
+    server: {},
+  },
+  js: {
+    config: {},
+  },
+  json: {
+    main: {},
+  },
 }
-
-// Circular reference
-value.a = value
-
-safeStringify(value)
-// '{"b":2,"c":10}'
 ```
 
-- The circular references are removed from the final JSON string.
-- The BigInt values are converted to a string.
-
-The `safeStringify` API is the same as the `JSON.stringify` method.
+#### OPTIONS
 
-- You can pass a replacer function as the second parameter.
-- And number of spaces as the third parameter.
+<dl>
+  <dt>ignoreMissingRoot</dt>
+  <dd>By default, an exception is raised when the root directory is missing. Setting <code>ignoreMissingRoot</code> to true will not result in an error, and an empty object will be returned.</dd>
 
-### Lodash helpers
-
-Lodash is quite a big library, and we do not use all its helper methods. Therefore we create a custom build using the lodash CLI and bundle only the once we need.
-
-> **Why not use something else**: All other helpers I have used are not as accurate or well implemented as lodash.
+  <dt>filter</dt>
+  <dd>Define a filter to ignore certain paths. By default only files ending with <code>.js</code>, <code>.ts</code>, <code>.json</code>, <code>.cjs</code>, and <code>.mjs</code> are imported.</dd>
 
-- pick
-- omit
-- has
-- get
-- set
-- unset
-- mergeWith
-- merge
-- size
-- clone
-- cloneDeep
-- toPath
-
-You can use the methods as follows.
-
-```ts
-import lodash from '@poppinss/utils/lodash'
+  <dt>sort</dt>
+  <dd>Define a custom method to sort file paths. By default, the files are sorted using natural sort.</dd>
 
-lodash.pick(collection, keys)
-```
+  <dt>transformKeys</dt>
+  <dd>Define a callback method to transform the keys for the final object. The method receives an array of nested keys and must return an array back.</dd>
+</dl>
 
-### Assertion helpers
+## Assertion helpers
 
-The following assertion methods offers type-safe approach for writing conditionals and throwing error when the variable has unexpected values.
+The following assertion methods offer a type-safe approach for writing conditionals and throwing errors when the variable has unexpected values.
 
-#### assertExists(message?: string)
+### assertExists
 
 Throws [AssertionError](https://nodejs.org/api/assert.html#new-assertassertionerroroptions) when the value is `false`, `null`, or `undefined`.
 
@@ -658,10 +223,10 @@ import { assertExists } from '@poppinss/utils/assert'
 const value = false as string | false
 assertExists(value)
 
-// value is string
+// value is a string
 ```
 
-#### assertNotNull(value: unknown, message?: string)
+### assertNotNull
 
 Throws [AssertionError](https://nodejs.org/api/assert.html#new-assertassertionerroroptions) when the value is `null`.
 
@@ -671,10 +236,10 @@ import { assertNotNull } from '@poppinss/utils/assert'
 const value = null as string | null
 assertNotNull(value)
 
-// value is string
+// value is a string
 ```
 
-#### assertIsDefined(value: unknown, message?: string)
+### assertIsDefined
 
 Throws [AssertionError](https://nodejs.org/api/assert.html#new-assertassertionerroroptions) when the value is `undefined`.
 
@@ -684,10 +249,10 @@ import { assertIsDefined } from '@poppinss/utils/assert'
 const value = undefined as string | undefined
 assertIsDefined(value)
 
-// value is string
+// value is a string
 ```
 
-#### assertUnreachable(value: unknown)
+### assertUnreachable
 
 Throws [AssertionError](https://nodejs.org/api/assert.html#new-assertassertionerroroptions) when the method is invoked. In other words, this method always throws an exception.
 
@@ -696,67 +261,63 @@ import { assertUnreachable } from '@poppinss/utils/assert'
 assertUnreachable()
 ```
 
-### All other helpers
-
-The following helpers are exported from the package main module.
-
-```ts
-import { base64, compose } from '@poppinss/utils'
-```
+## Base64 encoding
 
-#### base64
+### encode
 
-Utility methods to base64 encode and decode values.
+Base64 encodes a string or a Buffer value.
 
 ```ts
-import { base64 } from '@poppinss/utils'
+import base64 from '@poppinss/utils/base64'
 
 base64.encode('hello world')
 // aGVsbG8gd29ybGQ=
 ```
 
-Similar to the `encode` method, you can use the `urlEncode` to generate a base64 string safe to pass in a URL.
+### urlEncode
 
-The `urlEncode` method performs the following replacements.
+The `urlEncode` method returns a base64 string safe for use inside a URL. The following characters are replaced.
 
-- Replace `+` with `-`.
-- Replace `/` with `_`.
-- And remove the `=` sign from the end of the string.
+- The `+` character is replaced with `-`.
+- The `/` character is replaced with `_`.
+- Trailing `=` sign is removed.
 
 ```ts
 base64.urlEncode('hello world')
 // aGVsbG8gd29ybGQ
 ```
 
-You can use the `decode` and the `urlDecode` methods to decode a previously encoded base64 string.
+### decode
+
+Decode a previously encoded base64 string. By default, a `null` value is returned when the string cannot be decoded. However, you can turn on the strict mode to throw an exception instead.
 
 ```ts
 base64.decode(base64.encode('hello world'))
-// hello world
 
-base64.urlDecode(base64.urlEncode('hello world'))
-// hello world
+base64.decode('foo') // null
+base64.decode('foo', true) // throws error
 ```
 
-The `decode` and the `urlDecode` methods return `null` when the input value is an invalid base64 string. You can turn on the `strict` mode to raise an exception instead.
+### urlDecode
+
+Decode a previously URL-encoded base64 string. By default, a `null` value is returned when the string cannot be decoded. However, you can turn on the strict mode to throw an exception instead.
 
 ```ts
-base64.decode('hello world') // null
-base64.decode('hello world', 'utf-8', true) // raises exception
+base64.urlDecode(base64.urlEncode('hello world'))
+
+base64.urlDecode('foo') // null
+base64.urlDecode('foo', true) // throws error
 ```
 
-#### compose
+## compose
 
-The `compose` helper allows you to use TypeScript class mixins with a cleaner API. Following is an example of mixins usage without the compose helper.
+The `compose` helper allows you to use TypeScript class mixins with a cleaner API. Following is an example of mixin usage without the compose helper.
 
 ```ts
 class User extends UserWithAttributes(UserWithAge(UserWithPassword(UserWithEmail(BaseModel)))) {}
 ```
 
-Following is an example with the `compose` helper.
-
-- There is no nesting.
-- The order of mixins is from left to right. Whereas earlier, it was inside out.
+The following is an example of the `compose` helper. As you can notice, the `compose` removes nesting and applies mixins from left to right.
 
 ```ts
 import { compose } from '@poppinss/utils'
@@ -770,13 +331,14 @@ class User extends compose(
 ) {}
 ```
 
-#### defineStaticProperty
+## defineStaticProperty
 
-The `defineStaticProperty` method allows you to define static properties on a class with different reference strategies.
+### PROBLEM STATEMENT
 
-If you use class inheritance alongside static properties, then either, you will share properties by reference, or you will define them directly on the parent class.
+If you use class inheritance alongside static properties, you will either share properties by reference or define them directly on the parent class.
 
-In the following example, we are not inherting `columns` from the `AppModel`. Instead, we define a new set of columns on the `UserModel`.
+**Redefining a property**\
+In the following example, we re-define the `static columns` member on the `UserModel` class.
 
 ```ts
 class AppModel {
@@ -788,7 +350,8 @@ class UserModel extends AppModel {
 }
 ```
 
-In the following example, we are inherting `columns` from the `AppModel`. However, the mutations (array.push) from the `UserModel` will reflect on the `AppModel` as well.
+**Sharing by reference**\
+In the following example, we are share the `static columns` between the `AppModel` and the `UserModel` classes. However, mutating the property via the `UserModel` will also impact the `AppModel` (not something we want).
 
 ```ts
 class AppModel {
@@ -799,7 +362,9 @@ class UserModel extends AppModel {}
 UserModel.columns.push('username')
 ```
 
-The ideal behavior is to deep clone the `columns` array and then push new values to it.
+### SOLUTION
+
+To solve the mutation side-effect, you must deep-clone the `columns` array from the parent class and re-define them on `UserModel` class.
 
 ```ts
 import lodash from '@poppinss/utils/lodash'
@@ -808,64 +373,45 @@ class AppModel {
   static columns = ['id']
 }
 
-const inheritedColumns = lodash.cloneDeep(AppModel.columns)
 class UserModel extends AppModel {
-  static columns = inheritedColumns.push('username')
+  static columns = lodash.cloneDeep(AppModel.columns)
 }
+
+UserModel.columns.push('username')
 ```
 
-The `defineStaticProperty` method abstracts the logic to clone and also performs some interal checks to see if the value is already defined as an `ownProperty` or not.
+The `defineStaticProperty` method abstracts the logic of cloning the values. Member values are only cloned when the same member is not defined as an `ownProperty`.
 
 ```ts
-class UserModel extends AppModel {}
+import { defineStaticProperty } from '@poppinss/utils'
 
+class AppModel {
+  static columns = ['id']
+}
+
+class UserModel extends AppModel {}
 defineStaticProperty(UserModel, 'columns', {
   strategy: 'inherit',
   initialValue: [],
 })
 ```
 
-- The `inherit` strategy clones the value from the parent class.
-- The `define` strategy always re-defines the property, discarding any values on the parent class.
-- The `strategy` value can be function to perform a custom clone operations.
-
-#### Exception
-
-A custom exception class with support for defining the error status, error code, and help description. This class aims to standardize exceptions within your projects.
-
-```ts
-import { Exception } from '@poppinss/utils/exception'
-
-class ResourceNotFound extends Exception {
-  static code = 'E_RESOURCE_NOT_FOUND'
-  static status = 404
-  static message = 'Unable to find resource'
-}
-
-throw new ResourceNotFound()
-```
-
-#### Anonymous error classes
-
-You can also create an anonymous exception class using the `createError` method. The return value is a class
-constructor that accepts an array of values to use for interpolation.
+#### AVAILABLE STRATEGIES
 
-The interpolation of error message is performed using the `util.format` message.
+<dl>
+  <dt>inherit</dt>
+  <dd>The <code>inherit</code> strategy clones the value from the parent class.</dd>
 
-```ts
-import { createError } from '@poppinss/utils/exception'
-const E_RESOURCE_NOT_FOUND = createError(
-  'Unable to find resource with id %d',
-  'E_RESOURCE_NOT_FOUND'
-)
+  <dt>define</dt>
+  <dd>The <code>define</code> strategy always re-defines the property, discarding any values on the parent class.</dd>
 
-const id = 1
-throw new E_RESOURCE_NOT_FOUND([id])
-```
+  <dt>callback</dt>
+  <dd>The <code>strategy</code> value can be a function to perform custom clone operations.</dd>
+</dl>
 
-#### flatten
+## flatten
 
-Create a flat object from a nested object/array. The nested keys are combined with a dot-notation (`.`). The method is exported from the [flattie](https://www.npmjs.com/package/flattie) package.
+Create a flat object from a nested object/array. The nested keys are combined with a dot notation (`.`). The method is exported from the [flattie](https://www.npmjs.com/package/flattie) package.
 
 ```ts
 import { flatten } from '@poppinss/utils'
@@ -907,65 +453,9 @@ flatten({
 // }
 ```
 
-#### fsReadAll
-
-Get a list of all the files from a directory. The method recursively fetches files from the main and the sub-folders. The dotfiles are ignored implicitly.
-
-```ts
-import { fsReadAll } from '@poppinss/utils'
-
-const files = await fsReadAll(new URL('./config', import.meta.url), { pathType: 'url' })
-await Promise.all(files.map((file) => import(file)))
-```
-
-You can also pass the options along with the directory path as the second argument.
-
-```ts
-type Options = {
-  ignoreMissingRoot?: boolean
-  filter?: (filePath: string, index: number) => boolean
-  sort?: (current: string, next: string) => number
-  pathType?: 'relative' | 'unixRelative' | 'absolute' | 'unixAbsolute' | 'url'
-}
-
-const options: Partial<Options> = {}
-await fsReadAll(location, options)
-```
-
-| Argument            | Type    | Description                                                                                                                                                                   |
-| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ignoreMissingRoot` | boolean | By default, an exception is raised when the root directory is missing. Setting `ignoreMissingRoot` to true will not result in an error and an empty array is returned back.   |
-| `filter`            | method  | Define a filter to ignore certain paths. The method is called on the final list of files.                                                                                     |
-| `sort`              | method  | Define a custom method to sort file paths. By default, the files are sorted using natural sort.                                                                               |
-| `pathType`          | enum    | Define how to return the collected paths. By default, OS-specific relative paths are returned. If you want to import the collected files, you must set the `pathType = 'url'` |
-
-#### fsImportAll
+## isScriptFile
 
-The `fsImportAll` method imports all the files recursively from a given directory and set the exported value from each module on an object.
-
-```ts
-import { fsImportAll } from '@poppinss/utils'
-
-const collection = await fsImportAll(new URL('./config', import.meta.url))
-console.log(collection)
-```
-
-- Collection is an object with a tree of key-value pair.
-- The key is the nested object created from the file path.
-- Value is the exported values from the module. If a module exports both the `default` and `named` values, then only the default values are used.
-
-The second param is the options to customize the import behavior.
-
-| Argument            | Type    | Description                                                                                                                                                                  |
-| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ignoreMissingRoot` | boolean | By default, an exception is raised when the root directory is missing. Setting `ignoreMissingRoot` to true will not result in an error and an empty object is returned back. |
-| `filter`            | method  | Define a filter to ignore certain paths. By default only files ending with `.js`, `.ts`, `.json`, `.cjs`, and `.mjs` are imported.                                           |
-| `sort`              | method  | Define a custom method to sort file paths. By default, the files are sorted using natural sort.                                                                              |
-| `transformKeys`     | method  | Define a callback method to transform the keys for the final object. The method receives an array of nested keys and must return an array back.                              |
-
-#### isScriptFile
-
-A filter to know if the file path ends with `.js`, `.json`, `.cjs`, `.mjs` or `.ts`. In the case of `.ts` files, the `.d.ts` returns false.
+A filter to know if the file path ends with `.js`, `.json`, `.cjs`, `.mjs`, or `.ts`. In the case of `.ts` files, the `.d.ts` returns false.
 
 ```ts
 import { isScriptFile } from '@poppinss/utils'
@@ -979,41 +469,18 @@ isScriptFile('foo/bar.ts') // true
 isScriptFile('foo/bar.d.ts') // false
 ```
 
-The goal of this method is to use it as a filter with the `fsReadAll` method.
-
-```ts
-import { fsReadAll, isScriptFile } from '@poppinss/utils'
+## importDefault
 
-const dir = new URL('./config', import.meta.url)
-const options = { pathType: 'url', filter: isScriptFile }
-
-const files = await fsReadAll(dir, options)
-
-await Promise.all(
-  files.map((file) => {
-    if (file.endsWith('.json')) {
-      return import(file, { with: { type: 'json' } })
-    }
-
-    return import(file)
-  })
-)
-```
-
-#### importDefault
-
-A helper function that assert a lazy import function output to have a `default export`, otherwise raises an exception.
-
-We use dynamic default exports a lot in AdonisJS apps, so extracting the check to a helper function.
+Returns the default exported value from a dynamic import function. An exception is thrown when the module does not have a `default` export.
 
 ```ts
 import { importDefault } from '@poppinss/utils'
 const defaultVal = await importDefault(() => import('./some_module.js'))
 ```
 
-#### naturalSort
+## naturalSort
 
-A sorting function to use natural sort for ordering an array.
+Sort values of an Array using natural sort.
 
 ```ts
 import { naturalSort } from '@poppinss/utils'
@@ -1025,7 +492,7 @@ const values = ['1_foo_bar', '12_foo_bar'].sort(naturalSort)
 // Default sorting: ['1_foo_bar', '12_foo_bar']
 ```
 
-#### safeEqual
+## safeEqual
 
 Check if two buffer or string values are the same. This method does not leak any timing information and prevents [timing attack](https://javascript.plainenglish.io/what-are-timing-attacks-and-how-to-prevent-them-using-nodejs-158cc7e2d70c).
 
@@ -1035,7 +502,7 @@ Under the hood, this method uses Node.js [crypto.timeSafeEqual](https://nodejs.o
 import { safeEqual } from '@poppinss/utils'
 
 /**
- * The trusted value, it might be saved inside the db
+ * The trusted value. Might be saved inside the db
  */
 const trustedValue = 'hello world'
 
@@ -1045,24 +512,15 @@ const trustedValue = 'hello world'
 const userInput = 'hello'
 
 if (safeEqual(trustedValue, userInput)) {
-  // both are same
+  //Both are the same
 } else {
-  // value mis-match
+  // value mismatch
 }
 ```
 
-#### slash
+## MessageBuilder
 
-Convert OS-specific file paths to Unix file paths. Credits [https://github.com/sindresorhus/slash](https://github.com/sindresorhus/slash)
-
-```ts
-import { slash } from '@poppinss/utils/slash'
-slash('foo\\bar') // foo/bar
-```
-
-#### MessageBuilder
-
-Message builder is a convenience layer to stringify JavaScript values with an expiry date and a purpose. For example:
+The `MessageBuilder` is used to stringify values with an encoded expiry date and purpose.
 
 ```ts
 import { MessageBuilder } from '@poppinss/utils'
@@ -1087,12 +545,12 @@ const encoded = builder.build(
  */
 ```
 
-Once you have the JSON string with the expiry and the purpose, you can encrypt it (to prevent tampering) and share it with the client.
+Once you have the JSON string with the expiration and purpose, you can encrypt it or sign it (to prevent tampering) and share it with the client.
 
-During the email verification, you can decrypt the key and then ask the `MessageBuilder` to verify the payload.
+Later, when the encrypted value is presented to perform an action, you must decrypt or unsign it and verify it using the `MessageBuilder`.
 
 ```ts
-const decoded = builder.verify(value, 'email_verification')
+const decoded = builder.verify(decryptedValue, 'email_verification')
 if (!decoded) {
   return 'Invalid token'
 }
@@ -1100,62 +558,11 @@ if (!decoded) {
 console.log(decoded.token)
 ```
 
-Now let's imagine someone presents the same token to reset their account password. In the following example, the validation will fail since the purpose of the original token is not the same as the purpose set during the `verify` method call.
-
-```ts
-const decoded = builder.verify(value, 'reset_password')
-```
-
-#### ObjectBuilder
-
-The `ObjectBuilder` is a convenience class to create an object with dynamic properties. Consider the following example, where we wrap our code inside conditionals before adding the property `b` to the `startingObject`.
-
-```ts
-const startingObject = {
-  a: 1
-  // Add "b", if it exists
-  ...(b ? { b } : {})
-}
-
-// OR
-if (b) {
-  startingObject.b = b
-}
-```
-
-Instead of writing conditionals, you can consider using the Object builder fluent API.
-
-```ts
-const builder = new ObjectBuilder({ a: 1 })
-
-const plainObject = builder.add('b', b).toObject()
-```
-
-By default, only the `undefined` values are ignored. However, you can also ignore `null` values.
-
-```ts
-const ignoreNullValues = true
-const builder = new ObjectBuilder({ a: 1 }, ignoreNullValues)
-```
-
-Following are the available methods on the `ObjectBuilder` class.
-
-```ts
-builder.remove(key)
-builder.has(key)
-builder.get(key)
-builder.add(key)
-
-builder.toObject() // get plain object
-```
-
-#### Secret
+## Secret
 
-Creates a secret value that prevents itself from getting logged inside `console.log` statements, during JSON serialization, and string concatenation.
+Wrap a value inside a Secret object to prevent it from leaking inside log statements or serialized payloads.
 
-To understand why you need a special `Secret` object, you need to understand the root of the problem. Let's start with an example.
-
-Given that you have a `Token` class that generates an opaque token for a user and persists its hash inside the database. The plain token (aka raw value) is shared with the user and it should only be visible once (for security reasons). Here is a dummy implementation of the same.
+For example, you issue an opaque token to a user and persist its hash inside the database. The plain token (aka raw value) is shared with the user and should only be visible once (for security reasons).
 
 ```ts
 class Token {
@@ -1171,7 +578,7 @@ const token = new Token().generate()
 return response.send(token)
 ```
 
-At the same time, you want to drop a log statement inside your application that you can later use to debug the flow of the application, and this is how you log the token.
+At the same time, you want to drop a log statement inside your application that you can later use to debug its flow.
 
 ```ts
 const token = new Token().generate()
@@ -1182,11 +589,9 @@ logger.log('token generated %O', token)
 return response.send(token)
 ```
 
-BOOM! You have weakened the security of your app. Now, anyone monitoring the logs can grab raw token values from the log and use them to perform the actions on behalf of the user.
-
-Now, to prevent this from happening, you **should work with a branded data type**. Our [old friend PHP has it](https://www.php.net/manual/en/class.sensitiveparametervalue.php), so we need it as well.
+As you can notice above, logging the token also logs its raw value. Now, anyone monitoring the logs can grab raw token values from the log and use them to perform the actions on behalf of the user.
 
-This is what exactly the `Secret` utility class does for you. Create values that prevent themselves from leaking inside logs or during JSON serialization.
+To prevent this from happening, you can wrap the secret values like an opaque token inside the `Secret` utility class. Logging an instance of the `Secret` class will redact the underlying value.
 
 ```ts
 import { Secret } from '@poppinss/utils'
@@ -1210,8 +615,8 @@ logger.log('token generated %O', token)
 return response.send(token)
 ```
 
-**Need the original value back?**
-You can call the `release` method to get the secret value back. Again, the idea is not to prevent your code from accessing the raw value. It's to stop the logging and serialization layer from reading it.
+**Need the original value back?**\
+You can call the `release` method to regain the original value. The idea is not to prevent your code from accessing the raw value. It's to stop the logging and serialization layer from reading it.
 
 ```ts
 const secret = new Secret('opaque_raw_token')
@@ -1220,35 +625,6 @@ const rawValue = secret.release()
 rawValue === opaque_raw_token // true
 ```
 
-> Shoutout to [https://transcend.io/blog/keep-sensitive-values-out-of-your-logs-with-types](transcend.io's article) to helping me design the API. In fact, I have ripped their implementation for my personal use.
-
-#### dirname/filename
-
-ES modules does not have magic variables `__filename` and `__dirname`. You can use these helpers to get the current directory and filenames as follows.
-
-```ts
-import { getDirname, getFilename } from '@poppinss/utils'
-
-const dirname = getDirname(import.meta.url)
-const filename = getFilename(import.meta.url)
-```
-
-#### joinToURL
-
-Similar to the Node.js `path.join`, but instead expects the first parameter to be a URL instance or a string with the `file:///` protocol.
-
-The return value is an absolute file system path without the `file:///` protocol.
-
-```ts
-import { joinToURL } from '@poppinss/utils'
-
-// With URL as a string
-const APP_PATH = joinToURL(import.meta.url, 'app')
-
-// With URL instance
-const APP_PATH = joinToURL(new URL('./', import.meta.url), 'app')
-```
-
 [gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/poppinss/utils/checks.yml?style=for-the-badge
 [gh-workflow-url]: https://github.com/poppinss/utils/actions/workflows/checks.yml 'Github action'
 [typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript