@poppinss/utils 4.0.4 → 6.0.0-0

package/README.md

@@ -1,1264 +1,1052 @@
-<div align="center"><img src="https://res.cloudinary.com/adonisjs/image/upload/q_100/v1557762307/poppinss_iftxlt.jpg" width="600px"></div>
+# @poppinss/utils
 
-# Utils
+> A toolkit of utilities used across all the AdonisJS, Edge, and Japa packages
 
-> Collection of reusable scripts used by AdonisJS core team
 
 [![gh-workflow-image]][gh-workflow-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url] [![synk-image]][synk-url]
 
-This module exports a collection of re-usable utilties to avoid re-writing the same code in every other package. We also include a handful of Lodash utilities, which are used across the AdonisJS packages eco-system.
-
-<details>
-  <summary>
-    <strong>Version 3.0 breaking changes</strong>
-  </summary>
-  
-  The version 3.0 re-format the exports to expose an "helpers" subpath to be used within the AdonisJS apps as well.
-  
-  The idea is to separate helpers that we need to share with AdonisJS core inside its own module, accessible as `‌@poppinss/utils/build/helpers`.
- 
- 
- ### Inside helpers subpath
-  
-  Following modules are now moved to a subpath.
-  
-  - `MessageBuilder`
-  - `base64`
-  - `compose`
-  - `fsReadAll`
-  - `interpolate`
-  - `requireAll`
-  - `resolveDir`
-  - `resolveFrom`
-      
-```ts
-// Earlier
-import {
-  MessageBuilder,
-  base64,
-  compose,
-  fsReadAll,
-  interpolate,
-  requireAll,
-  resolveDir,
-  resolveFrom,
-  safeEqual
-} from '@poppinss/utils'
-
-// After version 3.0
-import {
-MessageBuilder,
-base64,
-compose,
-fsReadAll,
-interpolate,
-requireAll,
-resolveDir,
-resolveFrom,
-safeEqual
-} from '@poppinss/utils/build/helpers'
-
-````
-
-### randomString
-
-The `randomString` is now part of the `string` helpers.
-
-```ts
-// Earlier
-import { randomString } from '@poppinss/utils'
-randomString(32)
-
-// After version 3.0
-import { string } from '@poppinss/utils/build/helpers'
-string.generateRandom(32)
-````
-
-### lodash
-
-The following lodash functions have been removed with new alternatives.
-
-- `snakeCase`
-- `camelCase`
-- `startCase`
-
-```ts
-// Earlier
-import { lodash } from '@poppinss/utils'
-
-lodash.snakeCase()
-lodash.camelCase()
-lodash.startCase()
-
-// After version 3.0
-import { string } from '@poppinss/utils/build/helpers'
-
-string.snakeCase()
-string.camelCase()
-string.titleCase()
-```
-
-</details>
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-## Table of contents
-
-- [Installation](#installation)
-- [Exception](#exception)
-- [esmRequire](#esmrequire)
-- [esmResolver](#esmresolver)
-- [Lodash utilities](#lodash-utilities)
-  - [Exported methods](#exported-methods)
-- [Safe stringify](#safe-stringify)
-- [Safe parse](#safe-parse)
-- [defineStaticProperty](#definestaticproperty)
-- [flatten](#flatten)
-- [Helpers](#helpers)
-  - [fsReadAll](#fsreadall)
-  - [requireAll](#requireall)
-  - [resolveFrom](#resolvefrom)
-  - [resolveDir](#resolvedir)
-  - [interpolate](#interpolate)
-  - [Base 64 Encode/Decode](#base-64-encodedecode)
-    - [encode](#encode)
-    - [decode](#decode)
-    - [urlEncode](#urlencode)
-    - [urlDecode](#urldecode)
-  - [Safe equal](#safe-equal)
-  - [Message Builder](#message-builder)
-  - [compose](#compose)
-    - [Mixins gotchas](#mixins-gotchas)
-  - [string](#string)
-    - [camelCase](#camelcase)
-    - [snakeCase](#snakecase)
-    - [dashCase](#dashcase)
-    - [pascalCase](#pascalcase)
-    - [capitalCase](#capitalcase)
-    - [sentenceCase](#sentencecase)
-    - [dotCase](#dotcase)
-    - [noCase](#nocase)
-    - [titleCase](#titlecase)
-    - [pluralize](#pluralize)
-    - [truncate](#truncate)
-    - [excerpt](#excerpt)
-    - [condenseWhitespace](#condensewhitespace)
-    - [escapeHTML](#escapehtml)
-    - [encodeSymbols](#encodesymbols)
-    - [toSentence](#tosentence)
-    - [prettyBytes](#prettybytes)
-    - [toBytes](#tobytes)
-    - [prettyMs](#prettyms)
-    - [toMs](#toms)
-    - [ordinalize](#ordinalize)
-    - [generateRandom](#generaterandom)
-    - [isEmpty](#isempty)
-  - [Types](#types)
-    - [lookup](#lookup)
-    - [isNull](#isnull)
-    - [isBoolean](#isboolean)
-    - [isBuffer](#isbuffer)
-    - [isNumber](#isnumber)
-    - [isString](#isstring)
-    - [isArguments](#isarguments)
-    - [isObject](#isobject)
-    - [isDate](#isdate)
-    - [isArray](#isarray)
-    - [isRegexp](#isregexp)
-    - [isError](#iserror)
-    - [isFunction](#isfunction)
-    - [isClass](#isclass)
-    - [isInteger](#isinteger)
-    - [isFloat](#isfloat)
-    - [isDecimal](#isdecimal)
-  - [ObjectBuilder](#objectbuilder)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+## Why this package exists? 
 
-## Installation
-
-Install the package from npm registry as follows:
-
-```sh
-npm i @poppinss/utils
-
-# yarn
-yarn add @poppinss/utils
-```
-
-and then use it as follows:
-
-```ts
-import { requireAll } from '@poppinss/utils'
-requireAll(__dirname)
-```
-
-## Exception
-
-A custom exception class that extends the `Error` class to add support for defining `status` and `error codes`.
+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.
 
-```ts
-import { Exception } from '@poppinss/utils'
+- 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.
+- 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`.
+- 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
 
-throw new Exception('Something went wrong', 500, 'E_RUNTIME_EXCEPTION')
-throw new Exception('Route not found', 404, 'E_ROUTE_NOT_FOUND')
-```
+> **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.
 
-## esmRequire
+> **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.
 
-Utility to require script files wihtout worrying about `CommonJs` and `ESM` exports. This is how it works.
+## Other packages to use
+A note to self and others to consider the following packages.
 
-- Returns the exported value for `module.exports`.
-- Returns the default value is an ESM module has `export default`.
-- Returns all exports if is an ESM module and doesn't have `export default`.
-
-**foo.js**
-
-```ts
-module.exports = {
-  greeting: 'Hello world',
-}
-```
+| Package | Description |
+|---------|-------------|
+| [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 |
 
-**foo.default.js**
+## 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.
 
-```ts
-export default {
-  greeting: 'Hello world',
-}
-```
+|                 |                 |
+|------------------|-----------------|
+| Source code size | `272K` (approx) |
+| Dependencies size | `432K` (approx) |
 
-**foo.esm.js**
+## Installation
 
-```ts
-export const greeting = {
-  greeting: 'hello world',
-}
-```
+Install the package from the npm registry as follows:
 
-```ts
-import { esmRequire } from '@poppinss/utils'
+```sh
+npm i @poppinss/utils
 
-esmRequire('./foo.js') // { greeting: 'hello world' }
-esmRequire('./foo.default.js') // { greeting: 'hello world' }
-esmRequire('./foo.esm.js') // { greeting: { greeting: 'hello world' } }
+# Yarn lovers
+yarn add @poppinss/utils
 ```
 
-## esmResolver
+## Exported modules
 
-The `esmResolver` method works similar to `esmRequire`. However, instead of requiring the file, it accepts the object and returns the exported as per the same logic defined above.
+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
-import { esmRequire } from '@poppinss/utils'
+// string sub-module
+import string from '@poppinss/utils/string'
 
-esmResolver({ greeting: 'hello world' }) // { greeting: 'hello world' }
+// json sub-module
+import json from '@poppinss/utils/json'
 
-esmResolver({
-  default: { greeting: 'hello world' },
-  __esModule: true,
-}) // { greeting: 'hello world' }
+// lodash sub-module
+import lodash from '@poppinss/utils/lodash'
 
-esmResolver({
-  greeting: { greeting: 'hello world' },
-  __esModule: true,
-}) // { greeting: { greeting: 'hello world' } }
+// main module
+import { base64, Exception, fsReadAll } from '@poppinss/utils'
 ```
 
-## Lodash utilities
+### String helpers
 
-Lodash itself is a bulky library and most of the times, we don't need all the functions from it.
-
-Also, all of the lodash functions are published as individual modules on npm. However, most of those individual packages are outdated and using them is not an option.
-
-Instead, we decided to pick some individual utilities that we need inside AdonisJS ecosystem and export them from the lodash package, as each function is exposed in its own separate file.
+A collection of helpers to perform operations on/related to a string value.
 
 ```ts
-import { lodash } from '@poppinss/utils'
-lodash.get({ name: 'virk' }, 'name') // virk
+import string from '@poppinss/utils/string'
 ```
 
-### Exported methods
-
-Following is the list of exported helpers.
-
-- [pick](https://lodash.com/docs/latest#pick)
-- [omit](https://lodash.com/docs/latest#omit)
-- [has](https://lodash.com/docs/latest#has)
-- [get](https://lodash.com/docs/latest#get)
-- [set](https://lodash.com/docs/latest#set)
-- [unset](https://lodash.com/docs/latest#unset)
-- [mergeWith](https://lodash.com/docs/latest#mergeWith)
-- [merge](https://lodash.com/docs/latest#merge)
-- [size](https://lodash.com/docs/latest#size)
-- [clone](https://lodash.com/docs/latest#clone)
-- [cloneDeep](https://lodash.com/docs/latest#cloneDeep)
-
-## Safe stringify
+#### excerpt
 
-Similar to `JSON.stringify`, but also handles Circular references by removing them.
+Generate an excerpt from a string value. If the input value contains HTML tags, we will remove them from the excerpt.
 
 ```ts
-import { safeStringify } from '@poppinss/utils'
+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>`
 
-const o = { b: 1, a: 0 }
-o.o = o
-
-console.log(safeStringify(o))
-// { "b":1,"a":0 }
-
-console.log(JSON.stringify(o))
-// TypeError: Converting circular structure to JSON
+console.log(string.excerpt(html, 70))
+// AdonisJS is a Node.js framework, and hence it requires Node.js to be i...
 ```
 
-## Safe parse
+| 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 `...` |
 
-Similar to `JSON.parse`, but protects against [Prototype Poisoning](https://medium.com/intrinsic/javascript-prototype-poisoning-vulnerabilities-in-the-wild-7bc15347c96)
+#### 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
-import { safeParse } from '@poppinss/utils'
-
-const input = '{ "user": { "__proto__": { "isAdmin": true } } }'
-
-JSON.parse(input)
-// { user: { __proto__: { isAdmin: true } } }
+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.`
 
-safeParse(input)
-// { user: {} }
+console.log(string.truncate(text, 70))
+// AdonisJS is a Node.js framework, and hence it requires Node.js to be i...
 ```
 
-## defineStaticProperty
+| 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 `...` |
 
-Explicitly define static properties on a class by checking for `hasOwnProperty`. In case of inheritance, the properties from the parent class are cloned vs following the prototypal inheritance.
+#### slug
+Generate slug for a string value. The method is exported directly from the [slugify](https://www.npmjs.com/package/slugify) package.
 
-We use/need this copy from parent class behavior a lot in AdonisJS. Here's an example of Lucid models
-
-You create an application wide base model
+Please check the package documentation for [available options](https://www.npmjs.com/package/slugify#options). 
 
 ```ts
-class AppModel extends BaseModel {
-  @column.datetime()
-  public createdAt: DateTime
-}
+console.log(string.slug('hello ♥ world'))
+// hello-love-world
 ```
 
-AdonisJS will create the `$columnDefinitions` property on the `AppModel` class, that holds all the columns
+You can add custom replacements for Unicode values as follows.
 
 ```ts
-AppModel.$columnDefinitions // { createdAt: { columName: created_at } }
+string.slug.extend({ '☢': 'radioactive' })
+
+console.log(string.slug('unicode ♥ is ☢'))
+// unicode-love-is-radioactive
 ```
 
-Now, lets create another model inheriting the `AppModel`
+#### interpolate
+Interpolate variables inside a string. The variables must be inside double curly braces.
 
 ```ts
-class User extends AppModel {
-  @column()
-  public id: number
-}
-```
+string.interpolate(
+  'hello {{ user.username }}',
+  { user: { username: 'virk' } }
+)
 
-As per the Javascript prototypal inheritance. The `User` model will not contain the columns from the `AppModel`, because we just re-defined the `$columnDefinitions` property. However, we don't want this behavior and instead want to copy the columns from the `AppModel` and then add new columns to it.
+// hello virk
+```
 
-Voila! Use the `defineStaticProperty` helper from this class.
+You can also replace array values by mentioning the array index.
 
 ```ts
-class LucidBaseModel {
-  static boot() {
-    defineStaticProperty(this, LucidBaseModel, {
-      propertyName: '$columnDefinitions',
-      defaultValue: {},
-      strategy: 'inherit',
-    })
-  }
-}
-```
+string.interpolate(
+  'hello {{ users.0 }}',
+  { users: ['virk'] }
+)
 
-The `defineStaticProperty` takes a total of three arguments.
-
-- The first argument is always `this`.
-- The second argument is the root level base class. This will usually be the class exported by your package or module.
-- The third argument takes the `propertyName`, `defaultValue (in case, there is nothing to copy)`, and the `strategy`.
-- The `inherit` strategy will copy the properties from the base class.
-- The `define` strategy will always use the `defaultValue` to define the property on the class. In other words, there is no copy behavior, but prototypal inheritance chain is also breaked by explicitly re-defining the property.
+// hello virk
+```
 
-## flatten
-Flatten an object/array. The method wraps the [flattie](https://github.com/lukeed/flattie) package.
+You can escape the curly braces by prefixing them with `\\`.
 
 ```ts
-import { flatten } from '@poppinss/utils'
+string.interpolate('hello \\{{ users.0 }}', {})
 
-flatten({
-  a: 'hi',
-  b: {
-    a: null,
-    b: ['foo', '', null, 'bar'],
-    d: 'hello',
-    e: {
-      a: 'yo',
-      b: undefined,
-      c: 'sup',
-      d: 0,
-      f: [
-        { foo: 123, bar: 123 },
-        { foo: 465, bar: 456 },
-      ]
-    }
-  },
-  c: 'world'
-});
-// {
-//   'a': 'hi',
-//   'b.b.0': 'foo',
-//   'b.b.1': '',
-//   'b.b.3': 'bar',
-//   'b.d': 'hello',
-//   'b.e.a': 'yo',
-//   'b.e.c': 'sup',
-//   'b.e.d': 0,
-//   'b.e.f.0.foo': 123,
-//   'b.e.f.0.bar': 123,
-//   'b.e.f.1.foo': 465,
-//   'b.e.f.1.bar': 456,
-//   'c': 'world'
-// }
+// hello {{ users.0 }}
 ```
 
-## Helpers
-
-The helpers module is also available in AdonisJS applications as follows:
+#### plural
+Convert a word to its plural form. The method is exported directly from the [pluralize](https://www.npmjs.com/package/pluralize) package.
 
 ```ts
-import { fsReadAll, string, types } from '@ioc:Adonis/Core/Helpers'
+string.plural('test')
+// tests
 ```
 
-The `@poppinss/utils` exposes this module as follows
+#### singular
+Convert a word to its singular form. The method is exported directly from the [pluralize](https://www.npmjs.com/package/pluralize) package.
 
 ```ts
-import { fsReadAll, string, types } from '@poppinss/utils/build/helpers'
+string.singular('tests')
+// test
 ```
 
-### fsReadAll
-
-A utility to recursively read all script files for a given directory. This method is equivalent to
-`readdir + recursive + filter (.js, .json, .ts)`.
+#### pluralize
+This method combines the `singular` and `plural` methods and uses one or the other based on the count. For example:
 
 ```ts
-import { fsReadAll } from '@poppinss/utils/build/helpers'
+string.pluralize('box', 1) // box
+string.pluralize('box', 2) // boxes
+string.pluralize('box', 0) // boxes
 
-const files = fsReadAll(__dirname) // array of strings
+string.pluralize('boxes', 1) // box
+string.pluralize('boxes', 2) // boxes
+string.pluralize('boxes', 0) // boxes
 ```
 
-You can also define your custom filter function. The filter function must return `true` for files to be included.
+The `addPluralRule`, `addSingularRule`, `addIrregularRule`, and `addUncountableRule` methods exposed by the pluralize package can be called as follows.
 
 ```ts
-const files = fsReadAll(__dirname, (file) => {
-  return file.endsWith('.foo.js')
-})
+string.pluralize.addUncountableRule('paper')
+string.pluralize.addSingularRule(/singles$/i, 'singular')
 ```
 
-### requireAll
-
-Same as `fsReadAll`, but instead require the files. Helpful when you want to load all the config files inside a directory on app boot.
+#### isPlural
+Find if a word is already in plural form. The method is exported directly from the [pluralize](https://www.npmjs.com/package/pluralize) package.
 
 ```ts
-import { requireAll } from '@poppinss/utils/build/helpers'
-const config = requireAll(join(__dirname, 'config'))
-
-{
-  file1: {}, // exported object
-  file2: {} // exported object
-}
+string.isPlural('tests') // true
 ```
 
-The method also accepts the following options
+#### 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
-requireAll(join(__dirname, 'config'), recursive, optional, filter)
+string.isSingular('test') // true
 ```
 
-- `recursive` Load all files recursively. Defaults to true.
-- `optional` Do not raise exception when the root directory is missing. Defaults to false.
-- `filter` Cherry pick files to require. By default, all JavaScript, TypeScript and JSON files are required.
-
-### resolveFrom
-
-Works similar to `require.resolve`, however it handles the absolute paths properly.
+#### camelCase
+Convert a string value to camelcase.
 
 ```ts
-import { resolveFrom } from '@poppinss/utils/build/helpers'
-
-resolveFrom(__dirname, 'npm-package') // returns path to package "main" file
-resolveFrom(__dirname, './foo.js') // returns path to `foo.js` (if exists)
-resolveFrom(__dirname, join(__dirname, './foo.js')) // returns path to `foo.js` (if exists)
+string.camelCase('user_name') // userName
 ```
 
-### resolveDir
-
-The `require.resolve` or `resolveFrom` method can only resolve paths to a given file and not the directory. For example: If you pass path to a directory, then it will search for `index.js` inside it and in case of a package, it will be search for `main` entry point.
+Following are some of the conversion examples.
 
-On the other hand, the `resolveDir` method can also resolve path to directories using following resolution.
+| 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' |
 
-- Absolute paths are returned as it is.
-- Relative paths starting with `./` or `.\` are resolved using `path.join`.
-- Path to packages inside `node_modules` are resolved as follows: - Uses `require.resolve` to resolve the `package.json` file. - Then replace the `package-name` with the absolute resolved package path.
+#### capitalCase
+Convert a string value to a capital case.
 
 ```ts
-import { resolveDir } from '@poppinss/utils/build/helpers'
-
-resolveDir(__dirname, './database/migrations')
-// __dirname + /database/migrations
-
-resolveDir(__dirname, 'some-package/database/migrations')
-// {path-to-package}/database/migrations
-
-resolveDir(__dirname, '@some/package/database/migrations')
-// {path-to-package}/database/migrations
+string.capitalCase('helloWorld') // Hello World
 ```
 
-### interpolate
+Following are some of the conversion examples.
 
-A small utility function to interpolate values inside a string.
+| 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' |
 
-```ts
-import { interpolate } from '@poppinss/utils/build/helpers'
-
-interpolate('hello {{ username }}', {
-  username: 'virk',
-})
+#### dashCase
+Convert a string value to a dash case.
 
-interpolate('hello {{ users.0.username }}', {
-  users: [{ username: 'virk' }],
-})
+```ts
+string.dashCase('helloWorld') // hello-world
 ```
 
-If value is missing, it will be replaced with an `'undefined'` string.
-
-Use the `\` to escape a mustache block from getting evaluated.
+Optionally, you can capitalize the first letter of each word.
 
 ```ts
-import { interpolate } from '@poppinss/utils/build/helpers'
-
-interpolate('\\{{ username }} expression evaluates to {{ username }}', {
-  username: 'virk',
-})
-// Output: {{ username }} expression evaluates to virk
+string.dashCase('helloWorld', { capitalize: true }) // Hello-World
 ```
 
-### Base 64 Encode/Decode
+Following are some of the conversion examples.
 
-Following helpers for base64 encoding/decoding also exists.
+| 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' |
 
-#### encode
+#### dotCase
+Convert a string value to a dot case.
 
 ```ts
-import { base64 } from '@poppinss/utils/build/helpers'
-
-base64.encode('hello world')
-base64.encode(Buffer.from('hello world', 'binary'))
+string.dotCase('helloWorld') // hello.World
 ```
 
-#### decode
+Optionally, you can also convert the first letter of all the words to lowercase.
 
 ```ts
-import { base64 } from '@poppinss/utils/build/helpers'
-
-base64.decode(base64.encode('hello world'))
-base64.decode(base64.encode(Buffer.from('hello world', 'binary')), 'binary')
+string.dotCase('helloWorld', { lowerCase: true }) // hello.world
 ```
 
-#### urlEncode
+Following are some of the conversion examples.
 
-Same as `encode`, but safe for URLS and Filenames
+| 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' |
 
-#### urlDecode
+#### noCase
+Remove all sorts of casing from a string value.
 
-Same as `decode`, but decodes the `urlEncode` output values
+```ts
+string.noCase('helloWorld') // hello world
+```
 
-### Safe equal
+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' |
 
-Compares two values by avoid [timing attack](https://en.wikipedia.org/wiki/Timing_attack). Accepts any input that can be passed to `Buffer.from`
+#### pascalCase
+Convert a string value to pascal case. Great for generating JavaScript class names.
 
 ```ts
-import { safeValue } from '@poppinss/utils/build/helpers'
-
-if (safeValue('foo', 'foo')) {
-}
+string.pascalCase('user team') // UserTeam
 ```
 
-### Message Builder
+Following are some of the conversion examples.
 
-Message builder provides a sane API for stringifying objects similar to `JSON.stringify` but has a few advantages.
+| Input | Output |
+|--------|--------|
+| 'test' | 'Test' |
+| 'test string' | 'TestString' |
+| 'Test String' | 'TestString' |
+| 'TestV2' | 'TestV2' |
+| 'version 1.2.10' | 'Version1210' |
+| 'version 1.21.0' | 'Version1210' |
 
-- It is safe from JSON poisoning vulnerability.
-- You can define expiry and purpose for the encoding. The `verify` method will respect these values.
-
-The message builder alone may seem useless, since anyone can decode the object and change its expiry or purpose. However, you can generate an hash of the stringified object and verify the tampering by validating the hash. This is what AdonisJS does for cookies.
+#### sentenceCase
+Convert a value to a sentence.
 
 ```ts
-import { MessageBuilder } from '@poppinss/utils/build/helpers'
-
-const builder = new MessageBuilder()
-const encoded = builder.build({ username: 'virk' }, '1 hour', 'login')
+string.sentenceCase('getting-started-with-adonisjs')
+// Getting started with adonisjs
 ```
 
-Now verify it
+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
-builder.verify(encoded) // returns null, no purpose defined
-builder.verify(encoded, 'register') // returns null, purpose mismatch.
-builder.verify(encoded, 'login') // return { username: 'virk' }
+string.snakeCase('user team') // user_team
 ```
 
-### compose
+Following are some of the conversion examples.
 
-Javascript doesn't have a concept of inherting multiple classes together and neither does Typescript. However, the [official documentation](https://www.typescriptlang.org/docs/handbook/mixins.html) of Typescript does talks about the concept of mixins.
+| 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' |
 
-As per the Typescript docs, you can create and apply mixins as follows.
+#### titleCase
+Convert a string value to title case.
 
 ```ts
-type Constructor = new (...args: any[]) => any
-
-const UserWithEmail = <T extends Constructor>(superclass: T) => {
-  return class extends superclass {
-    public email: string
-  }
-}
-
-const UserWithPassword = <T extends Constructor>(superclass: T) => {
-  return class extends superclass {
-    public password: string
-  }
-}
-
-class BaseModel {}
-class User extends UserWithPassword(UserWithEmail(BaseModel)) {}
+string.titleCase('small word ends on')
+// Small Word Ends On
 ```
 
-Mixins are close to a perfect way of inherting multiple classes. I recommend reading [this article](https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/) for same.
+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' |
 
-However, the syntax of applying multiple mixins is kind of ugly, as you have to apply **mixins over mixins**, creating a nested hierarchy as shown below.
+#### random
+Generate a cryptographically secure random string of a given length. The output value is URL safe base64 encoded string.
 
 ```ts
-UserWithAttributes(UserWithAge(UserWithPassword(UserWithEmail(BaseModel))))
+string.random(32)
+// 8mejfWWbXbry8Rh7u8MW3o-6dxd80Thk
 ```
 
-The `compose` method is a small utility to improve the syntax a bit.
+#### toSentence
+Convert an array of words to a comma-separated sentence. 
 
 ```ts
-import { compose } from '@poppinss/utils/build/helpers'
-
-class User extends compose(
-  BaseModel,
-  UserWithPassword,
-  UserWithEmail,
-  UserWithAge,
-  UserWithAttributes
-) {}
+string.toSentence(['routes', 'controllers', 'middleware'])
+// routes, controllers, and middleware
 ```
 
-#### Mixins gotchas
-
-Typescript has an [open issue](https://github.com/microsoft/TypeScript/issues/37142) related to the constructor arguments of the mixin class or the base class.
-
-Typescript expects all classes used in the mixin chain to have a constructor with only one argument of `...args: any[]`. For example: The following code will work fine at runtime, but the **typescript compiler complains about it**.
+You can replace the `and` with an `or` by specifying the `options.lastSeparator` property.
 
 ```ts
-class BaseModel {
-  constructor(name: string) {}
-}
-
-const UserWithEmail = <T extends typeof BaseModel>(superclass: T) => {
-  return class extends superclass {
-    // ERROR: A mixin class must have a constructor with a single rest parameter of type 'any[]'.ts(2545)
-    public email: string
-  }
-}
-
-class User extends compose(BaseModel, UserWithEmail) {}
+string.toSentence(['routes', 'controllers', 'middleware'], {
+  lastSeparator: ', or '
+})
 ```
 
-You can work around this by overriding the constructor of the base class.
+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
-import { NormalizeConstructor, compose } from '@poppinss/utils/build/helpers'
+string.toSentence(['routes', 'controllers'])
+// routes and controllers
 
-const UserWithEmail = <T extends NormalizeConstructor<typeof BaseModel>>(superclass: T) => {
-  return class extends superclass {
-    public email: string
-  }
-}
+string.toSentence(['routes', 'controllers'], {
+  pairSeparator: ', and '
+})
+// routes, and controllers
 ```
 
-### string
-
-The `string` module includes a bunch of helper methods to work with strings.
-
-#### camelCase
-
-Convert a string to its `camelCase` version.
+#### condenseWhitespace
+Remove multiple whitespaces from a string to a single whitespace.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+string.condenseWhitespace('hello  world')
+// hello world
 
-string.camelCase('hello-world') // helloWorld
+string.condenseWhitespace('  hello  world  ')
+// hello world
 ```
 
-#### snakeCase
-
-Convert a string to its `snake_case` version.
+#### ordinal
+Get the ordinal letter for a given number.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+string.ordinal(1) // 1st
+string.ordinal(2) // '2nd'
+string.ordinal(3) // '3rd'
+string.ordinal(4) // '4th'
 
-string.snakeCase('helloWorld') // hello_world
+string.ordinal(23) // '23rd'
+string.ordinal(24) // '24th'
 ```
 
-#### dashCase
-
-Convert a string to its `dash-case` version. Optionally, you can also capitalize the first letter of each segment.
+#### seconds.(parse/format)
+Parse a string-based time expression to seconds.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.dashCase('helloWorld') // hello-world
-string.dashCase('helloWorld', { capitalize: true }) // Hello-World
+string.seconds.parse('10h') // 36000
+string.seconds.parse('1 day') // 86400
 ```
 
-#### pascalCase
-
-Convert a string to its `PascalCase` version.
+Passing a numeric value to the `parse` method is returned as it is, assuming the value is already in seconds.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.pascalCase('helloWorld') // HelloWorld
+string.seconds.parse(180) // 180
 ```
 
-#### capitalCase
-
-Capitalize a string
+You can format seconds to a pretty string using the `format` method.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.capitalCase('helloWorld') // Hello World
+string.seconds.format(36000) // 10h
+string.seconds.format(36000, true) // 10 hours
 ```
 
-#### sentenceCase
-
-Convert string to a sentence
+#### milliseconds.(parse/format)
+Parse a string-based time expression to milliseconds.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.sentenceCase('hello-world') // Hello world
+string.milliseconds.parse('1 h') // 3.6e6
+string.milliseconds.parse('1 day') // 8.64e7
 ```
 
-#### dotCase
-
-Convert string to its `dot.case` version.
+Passing a numeric value to the `parse` method is returned as it is, assuming the value is already in milliseconds.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.dotCase('hello-world') // hello.world
+string.milliseconds.parse(180) // 180
 ```
 
-#### noCase
-
-Remove all sorts of casing
+Using the `format` method, you can format milliseconds to a pretty string.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.noCase('hello-world') // hello world
-string.noCase('hello_world') // hello world
-string.noCase('helloWorld') // hello world
+string.seconds.format(3.6e6) // 1h
+string.seconds.format(3.6e6, true) // 1 hour
 ```
 
-#### titleCase
-
-Convert a sentence to title case
+#### bytes.(parse/format)
+Parse a string-based unit expression to bytes.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.titleCase('Here is a fox') // Here Is a fox
+string.bytes.parse('1KB') // 1024
+string.bytes.parse('1MB') // 1048576
 ```
 
-#### pluralize
-
-Pluralize a word.
+Passing a numeric value to the `parse` method is returned as it is, assuming the value is already in bytes.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.pluralize('box') // boxes
-string.pluralize('i') // we
+string.bytes.parse(1024) // 1024
 ```
 
-You can also define your own irregular rules using the `string.defineIrregularRule` method.
-
-- The first argument is the singular variation
-- The second argument is the plural variation
+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.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.defineIrregularRule('auth', 'auth')
-string.plural('auth') // auth
+string.bytes.format(1048576) // 1MB
+string.bytes.format(1024 * 1024 * 1000) // 1000MB
+string.bytes.format(1024 * 1024 * 1000, { thousandsSeparator: ',' }) // 1,000MB
 ```
 
-You can also define your own uncountable rules using the `string.defineUncountableRule` method.
+### JSON helpers
+Following are the helpers we use to `stringify` and `parse` JSON.
 
-```ts
-import { string } from '@poppinss/utils/build/helpers'
+#### 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.
 
-string.defineUncountableRule('login')
-string.plural('login') // home
-```
+The method is a wrapper over [secure-json-parse](https://github.com/fastify/secure-json-parse) package.
 
-#### truncate
+#### safeStringify
+The native implementation of `JSON.stringify` cannot handle circular references or language-specific data types like `BigInt`.
 
-Truncate a string after a given number of characters
+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 { string } from '@poppinss/utils/build/helpers'
+import { safeStringify } from '@poppinss/utils/json'
 
-string.truncate('This is a very long, maybe not that long title', 12) // This is a ve...
-```
+const value = {
+  b: 2,
+  c: BigInt(10),
+}
 
-By default, the string is truncated exactly after the given characters. However, you can instruct the method to wait for the words to complete.
+// Circular reference
+value.a = value
 
-```ts
-string.truncate('This is a very long, maybe not that long title', 12, {
-  completeWords: true,
-}) // This is a very...
+safeStringify(value)
+// '{"b":2,"c":10}'
 ```
 
-Also, it is possible to customize the suffix.
+- The circular references are removed from the final JSON string.
+- The BigInt values are converted to a string.
 
-```ts
-string.truncate('This is a very long, maybe not that long title', 12, {
-  completeWords: true,
-  suffix: ' <a href="/1"> Read more </a>',
-}) // This is a very <a href="/1"> Read more </a>
-```
+The `safeStringify` API is the same as the `JSON.stringify` method. 
 
-#### excerpt
+- You can pass a replacer function as the second parameter.
+- And number of spaces as the third parameter.
 
-The `excerpt` method is same as the `truncate` method. However, it strips the HTML from the string.
+### 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.
 
-```ts
-import { string } from '@poppinss/utils/build/helpers'
+> **Why not use something else**: All other helpers I have used are not as accurate or well implemented as lodash.
 
-string.excerpt('<p>This is a <strong>very long</strong>, maybe not that long title</p>', 12) // This is a very...
-```
+- pick
+- omit
+- has
+- get
+- set 
+- unset
+- mergeWith
+- merge
+- size
+- clone
+- cloneDeep
+- toPath
 
-#### condenseWhitespace
-
-Condense whitespaces from a given string. The method removes the whitespace from the `left`, `right` and multiple whitespace in between the words.
+You can use the methods as follows.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+import lodash from '@poppinss/utils/lodash'
 
-string.condenseWhitespace(' hello  world ')
-// hello world
+lodash.pick(collection, keys)
 ```
 
-#### escapeHTML
-
-Escape HTML from the string
+### All other helpers
+The following helpers are exported from the package main module.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.escapeHTML('<p> foo © bar </p>')
-// &lt;p&gt; foo © bar &lt;/p&gt;
+import { base64, compose } from '@poppinss/utils'
 ```
 
-Additonally, you can also encode non-ascii symbols
+#### base64
+Utility methods to base64 encode and decode values.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+import { base64 } from '@poppinss/utils'
 
-string.escapeHTML('<p> foo © bar </p>', {
-  encodeSymbols: true,
-})
-// &lt;p&gt; foo &#xA9; bar &lt;/p&gt;
+base64.encode('hello world')
+// aGVsbG8gd29ybGQ=
 ```
 
-#### encodeSymbols
+Similar to the `encode` method, you can use the `urlEncode` to generate a base64 string safe to pass in a URL.
 
-Encode symbols. Checkout [he](https://npm.im/he) for available options
+The `urlEncode` method performs the following replacements.
 
-```ts
-import { string } from '@poppinss/utils/build/helpers'
+- Replace `+` with `-`.
+- Replace `/` with `_`.
+- And remove the `=` sign from the end of the string.
 
-string.encodeSymbols('foo © bar')
-// foo &#xA9; bar
+```ts
+base64.urlEncode('hello world')
+// aGVsbG8gd29ybGQ
 ```
 
-#### toSentence
-
-Join an array of words with a separator.
+You can use the `decode` and the `urlDecode` methods to decode a previously encoded base64 string.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.toSentence(['route', 'middleware', 'controller']) // route, middleware, and controller
+base64.decode(base64.encode('hello world'))
+// hello world
 
-string.toSentence(['route', 'middleware']) // route and middleware
+base64.urlDecode(base64.urlEncode('hello world'))
+// hello world
 ```
 
-You can also customize
-
-- `separator`: The value between two words except the last one
-- `pairSeparator`: The value between the first and the last word. Used, only when there are two words
-- `lastSeparator`: The value between the second last and the last word. Used, only when there are more than two words
+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.
 
 ```ts
-string.toSentence(['route', 'middleware', 'controller'], {
-  separator: '/ ',
-  lastSeparator: '/or ',
-}) // route/ middleware/or controller
+base64.decode('hello world') // null
+base64.decode('hello world', 'utf-8', true) // raises exception
 ```
 
-#### prettyBytes
-
-Convert bytes value to a human readable string. For options, recommend the [bytes](https://www.npmjs.com/package/bytes) package.
+#### 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.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.prettyBytes(1024) // 1KB
-string.prettyBytes(1024, { unitSeparator: ' ' }) // 1 KB
+class User extends UserWithAttributes(
+  UserWithAge(
+    UserWithPassword(
+      UserWithEmail(BaseModel)
+    )
+  )
+) {}
 ```
 
-#### toBytes
+Following is an example with the `compose` helper.
 
-Convert human readable string to bytes. This method is the opposite of the `prettyBytes` method.
+- There is no nesting.
+- The order of mixins is from left to right. Whereas earlier, it was inside out.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+import { compose } from '@poppinss/utils'
 
-string.toBytes('1KB') // 1024
+class User extends compose(
+  BaseModel,
+  UserWithEmail,
+  UserWithPassword,
+  UserWithAge,
+  UserWithAttributes
+) {}
 ```
 
-#### prettyMs
-
-Convert time in milliseconds to a human readable string
-
-```ts
-import { string } from '@poppinss/utils/build/helpers'
-
-string.prettyMs(60000) // 1min
-string.prettyMs(60000, { long: true }) // 1 minute
-```
+#### defineStaticProperty
+The `defineStaticProperty` method allows you to define static properties on a class with different reference strategies.
 
-#### toMs
+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.
 
-Convert human readable string to milliseconds. This method is the opposite of the `prettyMs` method.
+In the following example, we are not inherting `columns` from the `AppModel`. Instead, we define a new set of columns on the `UserModel`.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+class AppModel {
+  static columns = ['id']
+}
 
-string.toMs('1min') // 60000
+class UserModel extends AppModel {
+  static columns = ['username']
+}
 ```
 
-#### ordinalize
-
-Ordinalize a string or a number value
+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.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+class AppModel {
+  static columns = ['id']
+}
 
-string.ordinalize(1) // 1st
-string.ordinalize(99) // 99th
+class UserModel extends AppModel {}
+UserModel.columns.push('username')
 ```
 
-#### generateRandom
-
-Generate a cryptographically strong random string
+The ideal behavior is to deep clone the `columns` array and then push new values to it.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+import lodash from '@poppinss/utils/lodash'
 
-string.generateRandom(32)
-```
+class AppModel {
+  static columns = ['id']
+}
 
-#### isEmpty
+const inheritedColumns = lodash.cloneDeep(AppModel.columns)
+class UserModel extends AppModel {
+  static columns = inheritedColumns.push('username')
+}
+```
 
-Find if a value is empty. Also checks for empty strings with all whitespace
+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.
 
 ```ts
-import { string } from '@poppinss/utils/build/helpers'
+class UserModel extends AppModel {
+}
 
-string.isEmpty('') // true
-string.isEmpty('      ') // true
+defineStaticProperty(UserModel, 'columns', {
+  strategy: 'inherit',
+  initialValue: [],
+})
 ```
 
-### Types
+- 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.
+
 
-The types module allows distinguishing between different Javascript datatypes. The `typeof` returns the same type for many different values. For example:
+#### 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
-typeof {} // object
-typeof [] // object
-typeof null // object
-```
+import { Exception } from '@poppinss/utils'
 
-WHAT??? Yes, coz everything is an object in Javascript. To have better control, you can make use of the `types.lookup` method.
+class ResourceNotFound extends Exception {
+  static code = 'E_RESOURCE_NOT_FOUND'
+  static status = 404
+  static message = 'Unable to find resource'
+}
 
-#### lookup
+throw new ResourceNotFound()
+```
 
-Returns a more accurate type for a given value.
+Following is an example of creating a dynamic message with interpolation.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+import { Exception } from '@poppinss/utils'
+import string from '@poppinss/utils/string'
 
-types.lookup({}) // object
-types.lookup([]) // array
-types.lookup(Object.create(null)) // object
-types.lookup(null) // null
-types.lookup(function () {}) // function
-types.lookup(class Foo {}) // class
-types.lookup(new Map()) // map
-```
+class ResourceNotFound extends Exception {
+  static code = 'E_RESOURCE_NOT_FOUND'
+  static status = 404
+  static message = 'Unable to find resource with id {{ id }}'
+}
 
-#### isNull
+throw new ResourceNotFound(
+  interpolate(ResourceNotFound.message, { id: 1 })
+)
+```
 
-Find if the given value is null
+#### 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.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+import { flatten } from '@poppinss/utils'
 
-types.isNull(null)) // true
-```
+flatten({
+  a: 'hi',
+  b: {
+    a: null,
+    b: ['foo', '', null, 'bar'],
+    d: 'hello',
+    e: {
+      a: 'yo',
+      b: undefined,
+      c: 'sup',
+      d: 0,
+      f: [
+        { foo: 123, bar: 123 },
+        { foo: 465, bar: 456 },
+      ]
+    }
+  },
+  c: 'world'
+})
 
-#### isBoolean
+// {
+//   'a': 'hi',
+//   'b.b.0': 'foo',
+//   'b.b.1': '',
+//   'b.b.3': 'bar',
+//   'b.d': 'hello',
+//   'b.e.a': 'yo',
+//   'b.e.c': 'sup',
+//   'b.e.d': 0,
+//   'b.e.f.0.foo': 123,
+//   'b.e.f.0.bar': 123,
+//   'b.e.f.1.foo': 465,
+//   'b.e.f.1.bar': 456,
+//   'c': 'world'
+// }
+```
 
-Find if the given value is a boolean
+#### 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 { types } from '@poppinss/utils/build/helpers'
+import { fsReadAll } from '@poppinss/utils'
 
-types.isBoolean(true)) // true
+const files = await fsReadAll(
+  new URL('./config', import.meta.url),
+  { pathType: 'url' }
+)
+await Promise.all(files.map((file) => import(file)))
 ```
 
-#### isBuffer
-
-Find if the given value is a buffer
+You can also pass the options along with the directory path as the second argument.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+type Options = {
+  ignoreMissingRoot?: boolean
+  filter?: (filePath: string, index: number) => boolean
+  sort?: (current: string, next: string) => number
+  pathType?: 'relative' | 'unixRelative' | 'absolute' | 'unixAbsolute' | 'url'
+}
 
-types.isBuffer(new Buffer())) // true
+const options: Partial<Options> = {}
+await fsReadAll(location, options)
 ```
 
-#### isNumber
+| 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'` |
 
-Find if the given value is a number
+#### fsImportAll
+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 { types } from '@poppinss/utils/build/helpers'
+import { fsImportAll } from '@poppinss/utils'
 
-types.isNumber(100)) // true
+const collection = await fsImportAll(new URL('./config', import.meta.url))
+console.log(collection)
 ```
 
-#### isString
-
-Find if the given value is a string
-
-```ts
-import { types } from '@poppinss/utils/build/helpers'
+- 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.
 
-types.isString('hello')) // true
-```
+The second param is the options to customize the import behavior.
 
-#### isArguments
+| 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. |
 
-Find if the given value is an arguments object
+#### 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.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+import { isScriptFile } from '@poppinss/utils'
 
-function foo() {
-  types.isArguments(arguments)) // true
-}
-```
+isScriptFile('foo.js') // true
+isScriptFile('foo/bar.cjs') // true
+isScriptFile('foo/bar.mjs') // true
+isScriptFile('foo.json') // true
 
-#### isObject
+isScriptFile('foo/bar.ts') // true
+isScriptFile('foo/bar.d.ts') // false
+```
 
-Find if the given value is a plain object
+The goal of this method is to use it as a filter with the `fsReadAll` method.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+import { fsReadAll, isScriptFile } from '@poppinss/utils'
 
-types.isObject({})) // true
-```
+const dir = new URL('./config', import.meta.url)
+const options = { pathType: 'url', filter: isScriptFile }
 
-#### isDate
+const files = await fsReadAll(dir, options)
 
-Find if the given value is a date object
-
-```ts
-import { types } from '@poppinss/utils/build/helpers'
+await Promise.all(files.map((file) => {
+  if (file.endsWith('.json')) {
+    return import(file, { assert: { type: 'json' } })
+  }
 
-types.isDate(new Date())) // true
+  return import(file)
+}))
 ```
 
-#### isArray
-
-Find if the given value is an array
+#### naturalSort
+A sorting function to use natural sort for ordering an array.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+import { naturalSort } from '@poppinss/utils'
+
+const values = ['1_foo_bar', '12_foo_bar'].sort()
+// Default sorting: ['12_foo_bar', '1_foo_bar']
 
-types.isArray([1, 2, 3])) // true
+const values = ['1_foo_bar', '12_foo_bar'].sort(naturalSort)
+// Default sorting: ['1_foo_bar', '12_foo_bar']
 ```
 
-#### isRegexp
+#### 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).
 
-Find if the given value is an regular expression
+Under the hood, this method uses Node.js [crypto.timeSafeEqual](https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b) method, with support for comparing string values. *(crypto.timeSafeEqual does not support string comparison)*
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+import { safeEqual } from '@poppinss/utils'
 
-types.isRegexp(/[a-z]+/)) // true
-```
-
-#### isError
+/**
+ * The trusted value, it might be saved inside the db
+ */
+const trustedValue = 'hello world'
 
-Find if the given value is an instance of the error object
+/**
+ * Untrusted user input
+ */
+const userInput = 'hello'
 
-```ts
-import { types } from '@poppinss/utils/build/helpers'
-import { Exception } from '@poppinss/utils'
-
-types.isError(new Error('foo'))) // true
-types.isError(new Exception('foo'))) // true
+if (safeEqual(trustedValue, userInput)) {
+  // both are same
+} else {
+  // value mis-match
+}
 ```
 
-#### isFunction
-
-Find if the given value is a function
+#### slash
+Convert OS-specific file paths to Unix file paths. The method is exported directly from the [slash](https://npm.im/slash) package.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
-
-types.isFunction(function foo() {})) // true
+import { slash } from '@poppinss/utils'
+slash('foo\\bar') // foo/bar
 ```
 
-#### isClass
-
-Find if the given value is a class constructor. Uses regex to distinguish between a function and a class.
+#### MessageBuilder
+Message builder is a convenience layer to stringify JavaScript values with an expiry date and a purpose. For example:
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
+import { MessageBuilder } from '@poppinss/utils'
 
-class User {}
+const builder = new MessageBuilder()
+const encoded = builder.build(
+  {
+    token: string.random(32),
+  },
+  '1 hour',
+  'email_verification'
+)
 
-types.isClass(User) // true
-types.isFunction(User) // true
+/**
+ * {
+ *   "message": {
+ *    "token":"GZhbeG5TvgA-7JCg5y4wOBB1qHIRtX6q"
+ *   },
+ *   "purpose":"email_verification",
+ *   "expiryDate":"2022-10-03T04:07:13.860Z"
+ * }
+ */
 ```
 
-#### isInteger
+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.
 
-Find if the given value is an integer.
+During the email verification, you can decrypt the key and then ask the `MessageBuilder` to verify the payload.
 
 ```ts
-import { types } from '@poppinss/utils/build/helpers'
-
-types.isInteger(22.0) // true
-types.isInteger(22) // true
-types.isInteger(-1) // true
-types.isInteger(-1.0) // true
+const decoded = builder.verify(value, 'email_verification')
+if (!decoded) {
+  return 'Invalid token'
+}
 
-types.isInteger(22.1) // false
-types.isInteger(0.3) // false
-types.isInteger(-0.3) // false
+console.log(decoded.token)
 ```
 
-#### isFloat
-
-Find if the given value is an float number.
+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
-import { types } from '@poppinss/utils/build/helpers'
-
-types.isFloat(22.1) // true
-types.isFloat(-22.1) // true
-types.isFloat(0.3) // true
-types.isFloat(-0.3) // true
-
-types.isFloat(22.0) // false
-types.isFloat(-22.0) // false
-types.isFloat(-22) // false
+const decoded = builder.verify(value, 'reset_password')
 ```
 
-#### isDecimal
-
-Find if the given value has a decimal. The value can be a string or a number. The number values are casted to a string by calling the `toString()` method on the value itself.
-
-The string conversion is peformed to test the value against a regex. Since, there is no way to natively find a decimal value in Javascript.
+#### 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
-import { types } from '@poppinss/utils/build/helpers'
-
-types.isDecimal('22.10') // true
-types.isDecimal(22.1) // true
-
-types.isDecimal('-22.10') // true
-types.isDecimal(-22.1) // true
-
-types.isDecimal('.3') // true
-types.isDecimal(0.3) // true
+const startingObject = {
+  a: 1
+  // Add "b", if it exists
+  ...(b ? { b } : {})
+}
 
-types.isDecimal('-.3') // true
-types.isDecimal(-0.3) // true
+// OR
+if (b) {
+  startingObject.b = b
+}
+```
 
-types.isDecimal('22.00') // true
-types.isDecimal(22.0) // false (gets converted to 22)
+Instead of writing conditionals, your can consider using the Object builder fluent API.
 
-types.isDecimal('-22.00') // true
-types.isDecimal(-22.0) // false (gets converted to -22)
+```ts
+const builder = new ObjectBuilder({ a: 1 })
 
-types.isDecimal('22') // false
-types.isDecimal(22) // false
+// Add property if the value is not undefined.
+builder.add('b', b)
 
-types.isDecimal('0.0000000000001') // true
-types.isDecimal(0.0000000000001) // false (gets converted to 1e-13)
+// Get the plain object back
+const plainObject = builder.toObject()
 ```
 
-### ObjectBuilder
-
-A very simple class to conditionally builder an object. Quite often, I create a new object from an existing one and wants to avoid writing undefined values to it. For example
+By default, only the `undefined` values are ignored. However, you can also ignore `null` values.
 
 ```ts
-const obj = {
-  ...(user.username ? { username: user.username } : {}),
-  ...(user.id ? { id: user.id } : {}),
-  ...(user.createdAt ? { createdAt: user.createdAt.toString() } : {}),
-}
+const ignoreNullValues = true
+const builder = new ObjectBuilder({ a: 1 }, ignoreNullValues)
 ```
 
-Not only the above code is harder to write. It is performance issues as well, since we are destructuring too many objects.
-
-To address this use case, you can make use of the `ObjectBuilder` class as follows
+Following are the available methods on the `ObjectBuilder` class.
 
 ```ts
-import { ObjectBuilder } from '@poppinss/utils/build/helpers'
+builder.remove(key)
+builder.has(key)
+builder.get(key)
+builder.add(key)
 
-const obj = new ObjectBuilder()
-  .add('username', user.username)
-  .add('id', user.id)
-  .add('createdAt', user.createdAt && user.createdAt.toString()).value // returns the underlying object
+builder.toObject() // get plain object
 ```
 
-The `add` method ignores the value if its `undefined`. So it never gets added to the object at all. You can also ignore `null` properties by passing a boolean flag to the constructor.
+#### 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
-new ObjectBuilder(true) // ignore null as well
+import { getDirname, getFilename } from '@poppinss/utils'
+
+const dirname = getDirname(import.meta.url)
+const filename = getFilename(import.meta.url)
 ```
 
 [gh-workflow-image]: https://img.shields.io/github/workflow/status/poppinss/utils/test?style=for-the-badge