namefully 1.0.9 → 1.2.0

package/dist/lib/namefully.js

@@ -1,562 +1,723 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Namefully = void 0;
+const config_1 = require("./config");
+const constants_1 = require("./constants");
+const error_1 = require("./error");
+const parser_1 = require("./parser");
+const types_1 = require("./types");
+const utils_1 = require("./utils");
 /**
- * `Namefully` person name handler
+ * A helper for organizing person names in a particular order, way, or shape.
  *
- * Created on March 03, 2020
- * @author Ralph Florent <ralflornt@gmail.com>
+ * Though `namefully` is easy to use, it does not magically guess which part of
+ * the name is what (prefix, suffix, first, last, or middle names). It relies
+ * actually on how the name parts are indicated (i.e., their roles) so that
+ * it can perform internally certain operations and saves us some extra
+ * calculations/processing. In addition, `Namefully` can be created using
+ * distinct raw data shapes. This is intended to give some flexibility to the
+ * developer so that he or she is not bound to a particular data format.
+ * By following closely the API reference to know how to harness its usability,
+ * this utility aims to save time in formatting names.
  *
- * @license GPL-3.0
- * @see {@link https://github.com/ralflorent/namefully|namefully} for more info.
- */
-const index_1 = require("./core/index");
-const index_2 = require("./models/index");
-const index_3 = require("./validators/index");
-/**
- * Person name handler
- * @class
- * @classdesc
- * `Namefully` does not magically guess which part of the name is what. It relies
- * actually on how the developer indicates the roles of the name parts so that
- * it, internally, can perform certain operations and saves the developer some
- * calculations/processings. Nevertheless, Namefully can be constructed using
- * distinct raw data shape. This is intended to give some flexibility to the
- * developer so that he or she is not bound to a particular data format. Please,
- * do follow closely the APIs to know how to properly use it in order to avoid
- * some errors (mainly validation's).
+ * `namefully` also works like a trapdoor. Once a raw data is provided and
+ * validated, a developer can only *access* in a vast amount of, yet effective
+ * ways the name info. *No editing* is possible. If the name is mistaken, a new
+ * instance of `Namefully` must be created. In other words, it's immutable.
+ * Remember, this utility's primary objective is to help manipulate a person name.
  *
- * `Namefully` also works like a trap door. Once a raw data is provided and
- * validated, a developer can only ACCESS in a vast amount of, yet effective ways
- * the name info. NO EDITING is possible. If the name is mistaken, a new instance
- * of `Namefully` must be created. Remember, this utility's primary objective is
- * to help to **handle** a person name.
+ * Note that the name standards used for the current version of this library
+ * are as follows:
+ *      `[prefix] firstName [middleName] lastName [suffix]`
+ * The opening `[` and closing `]` symbols mean that these parts are optional.
+ * In other words, the most basic and typical case is a name that looks like
+ * this: `John Smith`, where `John` is the first name piece and `Smith`, the last
+ * name piece.
  *
- * Note that the name standards used for the current version of this library are
- * as follows:
- *      [Prefix] Firstname [Middlename] Lastname [Suffix]
- * The opening `[` and closing `]` brackets mean that these parts are optional.
- * In other words, the most basic and typical case is a name that looks like this:
- * `John Smith`, where `John` is the first name and `Smith`, the last name.
  * @see https://departments.weber.edu/qsupport&training/Data_Standards/Name.htm
  * for more info on name standards.
  *
- * **IMPORTANT**: Keep in mind that the order of appearance matters and can be
- * altered through configured parameters, which we will be seeing later on. By
- * default, the order of appearance is as shown above and will be used as a basis
- * for future examples and use cases.
+ * **IMPORTANT**: Keep in mind that the order of appearance (or name order) matters
+ * and may be altered through configured parameters, which will be seen later.
+ * By default, the order of appearance is as shown above and will be used as a
+ * basis for future examples and use cases.
  *
  * Once imported, all that is required to do is to create an instance of
  * `Namefully` and the rest will follow.
  *
  * Some terminologies used across the library are:
- * - namon: piece of a name (e.g., firstname)
- * - nama: pieces of a name (e.g., firstname + lastname)
+ * - namon: 1 piece of name (e.g., first name)
+ * - nama: 2+ pieces of name (e.g., first name + last name)
  *
- * Happy naming!
+ * Happy name handling 😊!
  */
 class Namefully {
     /**
-     * Constructs an instance of the utility and helps to benefit from many helpers
-     * @param {string | string[] | Array<Name> | Nama} raw element to parse or
-     * construct the pieces of the name
-     * @param {Config} options to configure how to run the utility
+     * Creates a name with distinguishable parts from a raw string content.
+     * @param names element to parse.
+     * @param options additional settings.
+     *
+     * An optional configuration may be provided with specifics on how to treat
+     * a full name during its course. By default, all name parts are validated
+     * against some basic validation rules to avoid common runtime exceptions.
      */
-    constructor(raw, options) {
-        // well, first thing first
-        this.configure(options);
-        // let's try to parse this, baby!
-        this.build(raw);
+    constructor(names, options) {
+        this.build(this.toParser(names), options);
     }
     /**
-     * Gets the full name ordered as configured
-     * @param {'firstname'|'lastname'} orderedBy force to order by first or last
-     * name by overriding the preset configuration
-     * @returns {string} the suffix
+     * Constructs a `Namefully` instance from a text.
      *
-     * @see {format} to alter manually the order of appearance of the full name.
-     * For example, ::format('l f m') outputs `lastname firstname middlename`.
-     */
-    getFullname(orderedBy) {
-        orderedBy = orderedBy || this.config.orderedBy; // override config
-        const { titling, ending } = this.config;
-        const pxSep = titling === 'us' ? index_2.Separator.PERIOD : index_2.Separator.EMPTY; // Mr[.]
-        const sxSep = ending !== index_2.Separator.SPACE ? ending : index_2.Separator.EMPTY; // [,] PhD
-        const nama = [];
-        if (this.fullname.prefix)
-            nama.push(index_2.Separator.EMPTY.concat(this.fullname.prefix, pxSep));
-        switch (orderedBy) {
-            case 'firstname':
-                nama.push(this.getFirstname());
-                nama.push(...this.getMiddlenames());
-                nama.push(index_2.Separator.EMPTY.concat(this.getLastname(), sxSep));
-                break;
-            case 'lastname':
-                nama.push(this.getLastname());
-                nama.push(this.getFirstname());
-                nama.push(this.getMiddlenames().join(index_2.Separator.SPACE).concat(sxSep));
-                break;
+     * It works like `parse` except that this function returns `null` where `parse`
+     * would throw a `NameError`.
+     */
+    static tryParse(text) {
+        try {
+            return new this(parser_1.Parser.build(text));
+        }
+        catch (error) {
+            return undefined;
         }
-        if (this.fullname.suffix)
-            nama.push(this.fullname.suffix);
-        return nama.join(index_2.Separator.SPACE);
     }
     /**
-     * Gets the first name part of the full name
-     * @returns {string} the first name
+     * Constructs a `Namefully` instance from a text.
+     *
+     * It throws a `NameError` if the text cannot be parsed. Use `tryParse`
+     * instead if a `null` return is preferred over a throwable error.
+     *
+     * This operation is computed asynchronously, which gives more flexibility at
+     * the time of catching the error (and stack trace if any). The acceptable
+     * text format is a string composed of two or more name pieces. For instance,
+     * `John Lennon`, or `John Winston Ono Lennon` are parsable names and follow
+     * the basic name standard rules (i.e., first-middle-last).
+     *
+     * Keep in mind that prefix and suffix are not considered during the parsing
+     * process.
+     */
+    static parse(text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return parser_1.Parser.buildAsync(text).then((parser) => new Namefully(parser));
+        });
+    }
+    /**
+     * The current configuration.
+     */
+    get config() {
+        return this._config;
+    }
+    /**
+     * The number of characters of the `birthName`, including spaces.
+     */
+    get length() {
+        return this.birth.length;
+    }
+    /**
+     * The prefix part.
+     */
+    get prefix() {
+        var _a;
+        return (_a = this._fullName.prefix) === null || _a === void 0 ? void 0 : _a.toString();
+    }
+    /**
+     * The firt name.
+     */
+    get first() {
+        return this.firstName();
+    }
+    /**
+     * The first middle name if any.
+     */
+    get middle() {
+        return this.hasMiddle ? this.middleName()[0] : undefined;
+    }
+    /**
+     * Returns true if any middle name has been set.
+     */
+    get hasMiddle() {
+        return this._fullName.has(types_1.Namon.MIDDLE_NAME);
+    }
+    /**
+     * The last name.
+     */
+    get last() {
+        return this.lastName();
+    }
+    /**
+     * The suffix part.
+     */
+    get suffix() {
+        var _a;
+        return (_a = this._fullName.suffix) === null || _a === void 0 ? void 0 : _a.toString();
+    }
+    /**
+     * The birth name.
+     */
+    get birth() {
+        return this.birthName();
+    }
+    /**
+     * The shortest version of a person name.
+     */
+    get short() {
+        return this.shorten();
+    }
+    /**
+     * The longest version of a person name.
+     */
+    get long() {
+        return this.birth;
+    }
+    /**
+     * The entire name set.
+     */
+    get full() {
+        return this.fullName();
+    }
+    /**
+     * The first name combined with the last name's initial.
+     */
+    get public() {
+        return this.format('f $l');
+    }
+    /**
+     * Returns the full name as set.
      */
-    getFirstname() {
-        return this.fullname.firstname.tostring();
+    toString() {
+        return this.full;
     }
     /**
-     * Gets the last name part of the full name
-     * @param {LastnameFormat} [format] overrides the how-to format of a surname
-     * output, considering its subparts.
-     * @returns {string} the last name
+     * Fetches the raw form of a name piece.
      */
-    getLastname(format) {
-        return this.fullname.lastname.tostring(format);
+    get(namon) {
+        if (namon.equal(types_1.Namon.PREFIX))
+            return this._fullName.prefix;
+        if (namon.equal(types_1.Namon.FIRST_NAME))
+            return this._fullName.firstName;
+        if (namon.equal(types_1.Namon.MIDDLE_NAME))
+            return this._fullName.middleName;
+        if (namon.equal(types_1.Namon.LAST_NAME))
+            return this._fullName.lastName;
+        if (namon.equal(types_1.Namon.SUFFIX))
+            return this._fullName.suffix;
+        return undefined;
     }
     /**
-     * Gets the middle names part of the full name
-     * @returns {Array<string>} the middle names
+     * Whether this name is equal to another one from a raw-string perspective.
      */
-    getMiddlenames() {
-        return this.fullname.middlename ? this.fullname.middlename.map(n => n.namon) : [];
+    equal(other) {
+        return this.toString() === other.toString();
     }
     /**
-     * Gets the prefix part of the full name
-     * @returns {string} the prefix
+     * Gets a JSON representation of the full name.
      */
-    getPrefix() {
-        const pxSep = this.config.titling === 'us' ? index_2.Separator.PERIOD : index_2.Separator.EMPTY;
-        return this.fullname.prefix ?
-            index_2.Separator.EMPTY.concat(this.fullname.prefix, pxSep) :
-            index_2.Separator.EMPTY;
+    toJson() {
+        return {
+            prefix: this.prefix,
+            firstName: this.first,
+            middleName: this.middleName(),
+            lastName: this.last,
+            suffix: this.suffix,
+        };
     }
     /**
-     * Gets the suffix part of the full name
-     * @returns {string} the suffix
+     * Confirms that a name part has been set.
      */
-    getSuffix() {
-        return this.fullname.suffix || index_2.Separator.EMPTY;
+    has(namon) {
+        return this._fullName.has(namon);
     }
     /**
-     * Gets the initials of the full name
-     * @param {'firstname'|'lastname'} orderedBy force to order by first or last
-     * name by overriding the preset configuration
-     * @param {boolean} [withMid] whether to include middle names's
-     * @returns {Array<string>} the initials
+     * Gets the full name ordered as configured.
      *
-     * @example
-     * Given the names:
-     * - `John Smith` => ['J', 'S']
-     * - `John Ben Smith` => ['J', 'S']
-     * when `withMid` is set to true:
-     * - `John Ben Smith` => ['J', 'B', 'S']
+     * The name order `orderedBy` forces to order by first or last name by
+     * overriding the preset configuration.
      *
-     * **NOTE**:
-     * Ordered by last name obeys the following format:
-     *  `lastname firstname [middlename]`
-     * which means that if no middle name was set, setting `withMid` to true
-     * will output nothing and warn the end user about it.
-     */
-    getInitials(orderedBy, withMid = false) {
-        orderedBy = orderedBy || this.config.orderedBy; // override config
-        const midInits = this.fullname.middlename ?
-            this.fullname.middlename.map(n => n.getInitials()) : [];
-        if (withMid && !this.fullname.middlename) {
-            console.warn('No initials for middle names since none was set.');
+     * `Namefully.format` may also be used to alter manually the order of appearance
+     * of full name.
+     *
+     * For example:
+     * ```ts
+     * const name = new Namefully('Jon Stark Snow');
+     * console.log(name.fullName(NameOrder.LAST_NAME)); // "Snow Jon Stark"
+     * console.log(name.format('l f m')); // "Snow Jon Stark"
+     * ```
+     */
+    fullName(orderedBy) {
+        const sep = this._config.ending ? ',' : '';
+        const names = [];
+        orderedBy = orderedBy || this._config.orderedBy;
+        if (this.prefix)
+            names.push(this.prefix);
+        if (orderedBy === types_1.NameOrder.FIRST_NAME) {
+            names.push(this.first, ...this.middleName(), this.last + sep);
         }
-        const initials = [];
-        switch (orderedBy) {
-            case 'firstname':
-                initials.push(...this.fullname.firstname.getInitials());
-                if (withMid)
-                    midInits.forEach(m => initials.push(...m));
-                initials.push(...this.fullname.lastname.getInitials());
-                break;
-            case 'lastname':
-                initials.push(...this.fullname.lastname.getInitials());
-                initials.push(...this.fullname.firstname.getInitials());
-                if (withMid)
-                    midInits.forEach(m => initials.push(...m));
-                break;
+        else {
+            names.push(this.last, this.first, this.middleName().join(' ') + sep);
         }
-        return initials;
+        if (this.suffix)
+            names.push(this.suffix);
+        return names.join(' ').trim();
+    }
+    /**
+     * Gets the birth name ordered as configured, no `prefix` or `suffix`.
+     *
+     * @param orderedBy forces to order by first or last name by overriding the
+     * preset configuration.
+     */
+    birthName(orderedBy) {
+        orderedBy = orderedBy || this._config.orderedBy;
+        return orderedBy === types_1.NameOrder.FIRST_NAME
+            ? [this.first, ...this.middleName(), this.last].join(' ')
+            : [this.last, this.first, ...this.middleName()].join(' ');
     }
     /**
-     * Gives some descriptive statistics that summarize the central tendency,
-     * dispersion and shape of the characters' distribution.
-     * @param what which variant to use when describe a name part
-     * @returns {string} the stats behind the full name.
+     * Gets the first name part of the `FullName`.
      *
-     * Treated as a categorical dataset, the summary contains the following info:
-     * `count` : the number of *unrestricted* characters of the name;
-     * `frequency` : the highest frequency within the characters;
-     * `top` : the character with the highest frequency;
-     * `unique` : the count of unique characters of the name.
+     * @param withMore determines whether to include other pieces of the first
+     * name.
+     */
+    firstName(withMore = true) {
+        return this._fullName.firstName.toString(withMore);
+    }
+    /**
+     * Gets the middle name part of the `FullName`.
+     */
+    middleName() {
+        return this._fullName.middleName.map((n) => n.value);
+    }
+    /**
+     * Gets the last name part of the `FullName`.
      *
-     * @example
-     * Given the name "Thomas Alva Edison", the summary will output as follows:
+     * @param format overrides the how-to formatting of a surname output,
+     * considering its sub-parts.
+     */
+    lastName(format) {
+        return this._fullName.lastName.toString(format);
+    }
+    /**
+     * Gets the initials of the `FullName`.
      *
-     * Descriptive statistics for "Thomas Alva Edison"
-     *  count    : 16
-     *  frequency: 3
-     *  top      : A
-     *  unique   : 12
+     * @param {options.orderedBy} forces to order by first or last name by
+     * overriding the preset configuration.
+     * @param
      *
-     * **NOTE:**
-     * During the setup, a set of restricted characters can be defined to be removed
-     * from the stats. By default, the only restricted character is the `space`.
-     * That is why the `count` for the example below result in `16` instead of
-     * `16`.
-     * Another thing to consider is that the summary is case *insensitive*. Note
-     * that the letter `a` has the top frequency, be it `3`.
-     */
-    describe(what = 'fullname') {
-        switch (what) {
-            case 'fullname':
-                return this.summary;
-            case 'firstname':
-                return this.fullname.firstname.describe();
-            case 'lastname':
-                return this.fullname.lastname.describe();
-            case 'middlename':
-                return !this.fullname.middlename ? null :
-                    new index_2.Summary(this.fullname.middlename.map(n => n.namon).join(index_2.Separator.SPACE));
+     * For example, given the names:
+     * - `John Smith` => `['J', 'S']`
+     * - `John Ben Smith` => `['J', 'B', 'S']`.
+     */
+    initials(options) {
+        const initials = [];
+        const firstInits = this._fullName.firstName.initials();
+        const midInits = this._fullName.middleName.map((n) => n.initials()[0]);
+        const lastInits = this._fullName.lastName.initials();
+        const mergedOptions = Object.assign({ orderedBy: this._config.orderedBy, only: types_1.NameType.BIRTH_NAME }, options);
+        const { orderedBy, only } = mergedOptions;
+        if (only !== types_1.NameType.BIRTH_NAME) {
+            if (only === types_1.NameType.FIRST_NAME) {
+                initials.push(...firstInits);
+            }
+            else if (only === types_1.NameType.MIDDLE_NAME) {
+                initials.push(...midInits);
+            }
+            else {
+                initials.push(...lastInits);
+            }
+        }
+        else if (orderedBy === types_1.NameOrder.FIRST_NAME) {
+            initials.push(...firstInits, ...midInits, ...lastInits);
+        }
+        else {
+            initials.push(...lastInits, ...firstInits, ...midInits);
         }
+        return initials;
     }
     /**
      * Shortens a complex full name to a simple typical name, a combination of
-     * first name and last name.
-     * @param {'firstname'|'lastname'} orderedBy force to order by first or last
-     * name by overriding the preset configuration
-     * @returns {string} a typical name
+     * first and last name.
+     *
+     * @param orderedBy forces to order by first or last name by overriding the
+     * preset configuration.
      *
-     * @example
      * For a given name such as `Mr Keanu Charles Reeves`, shortening this name
      * is equivalent to making it `Keanu Reeves`.
+     *
+     * As a shortened name, the namon of the first name is favored over the other
+     * names forming part of the entire first names, if any. Meanwhile, for
+     * the last name, the configured `surname` is prioritized.
+     *
+     * For a given `FirstName FatherName MotherName`, shortening this name when
+     * the surname is set as `mother` is equivalent to making it:
+     * `FirstName MotherName`.
      */
     shorten(orderedBy) {
-        orderedBy = orderedBy || this.config.orderedBy; // override config
-        return orderedBy === 'firstname' ?
-            [
-                this.fullname.firstname.namon,
-                this.fullname.lastname.namon,
-            ].join(index_2.Separator.SPACE) :
-            [
-                this.fullname.lastname.namon,
-                this.fullname.firstname.namon,
-            ].join(index_2.Separator.SPACE);
-    }
-    /**
-     * Compresses a name by using different forms of variants
-     * @param {number} [limit] a threshold to limit the number of characters
-     * @param {'firstname'|'lastname'|'middlename'|'firstmid'|'midlast'} [by]
-     * a variant to use when compressing the long name. The last two variants
-     * represent respectively the combination of `firstname + middlename` and
-     * `middlename + lastname`.
-     * @param {boolean} [warning] should warn when the set limit is violated
+        orderedBy = orderedBy || this._config.orderedBy;
+        return orderedBy === types_1.NameOrder.FIRST_NAME
+            ? [this._fullName.firstName.value, this._fullName.lastName.toString()].join(' ')
+            : [this._fullName.lastName.toString(), this._fullName.firstName.value].join(' ');
+    }
+    /**
+     * Flattens a long name using the name types as variants.
+     *
+     * While @param limit sets a threshold as a limited number of characters
+     * supported to flatten a `FullName`, @param by indicates which variant
+     * to use when doing so. By default, a full name gets flattened by
+     * `Flat.MIDDLE_NAME`.
      *
-     * @example
-     * The compressing operation is only executed iff there is valid entry and it
-     * surpasses the limit set. In the examples below, let us assume that the
+     * The flattening operation is only executed iff there is a valid entry and
+     * it surpasses the limit set. In the examples below, let us assume that the
      * name goes beyond the limit value.
      *
-     * Compressing a long name refers to reducing the name to the following forms:
-     * 1. by firstname: 'John Moe Beau Lennon' => 'J. Moe Beau Lennon'
-     * 2. by middlename: 'John Moe Beau Lennon' => 'John M. B. Lennon'
-     * 3. by lastname: 'John Moe Beau Lennon' => 'John Moe Beau L.'
-     * 4. by firstmid: 'John Moe Beau Lennon' => 'J. M. B. Lennon'
-     * 5. by midlast: 'John Moe Beau Lennon' => 'John M. B. L.'
+     * Flattening a long name refers to reducing the name to the following forms.
+     * For example, `John Winston Ono Lennon` flattened by:
+     * * Flat.FIRST_NAME: => 'J. Winston Ono Lennon'
+     * * Flat.MIDDLE_NAME: => 'John W. O. Lennon'
+     * * Flat.LAST_NAME: => 'John Winston Ono L.'
+     * * Flat.FIRST_MID: => 'J. W. O. Lennon'
+     * * Flat.MID_LAST: => 'John W. O. L.'
+     * * Flat.ALL: => 'J. W. O. L.'
      *
-     * By default, it compresses by 'firstmid' variant: 'J. M. B. Lennon'.
-     */
-    compress(limit = 20, by = 'middlename', warning = true) {
-        if (this.getFullname().length <= limit) // no need to compress
-            return this.getFullname();
-        const { firstname: fn, lastname: ln, middlename } = this.fullname;
-        const mn = this.getMiddlenames().join(index_2.Separator.SPACE);
-        const hasmid = Array.isArray(middlename) && middlename.length > 0;
-        const sep = this.config.titling === 'us' ? index_2.Separator.PERIOD : index_2.Separator.EMPTY;
-        const firsts = fn.getInitials().join(sep).concat(sep);
-        const lasts = ln.getInitials().join(sep).concat(sep);
-        const mids = hasmid ? middlename.map(n => n.getInitials()).join(sep).concat(sep) : index_2.Separator.EMPTY;
-        let cname = '';
-        if (this.config.orderedBy === 'firstname') {
+     * With the help of the @param recursive flag, the above operation can happen
+     * recursively in the same order if the name is still too long. For example,
+     * flattening `John Winston Ono Lennon` using the following params:
+     * `flatten({ limit: 18, by: Flat.FIRST_NAME, recursive: true })`
+     * will result in `John W. O. Lennon` and not `J. Winston Ono Lennon`.
+     *
+     * A shorter version of this method is `zip()`.
+     */
+    flatten(options) {
+        if (this.length <= options.limit)
+            return this.full;
+        const mergedOptions = Object.assign({ limit: 20, by: types_1.Flat.MIDDLE_NAME, withPeriod: true, recursive: false, withMore: false }, options);
+        const { by, limit, recursive, withMore, withPeriod, surname } = mergedOptions;
+        const sep = withPeriod ? '.' : '';
+        const fn = this._fullName.firstName.toString();
+        const mn = this.middleName().join(' ');
+        const ln = this._fullName.lastName.toString();
+        const hasMid = this.hasMiddle;
+        const f = this._fullName.firstName.initials(withMore).join(sep + ' ') + sep;
+        const l = this._fullName.lastName.initials(surname).join(sep + ' ') + sep;
+        const m = hasMid ? this._fullName.middleName.map((n) => n.initials()[0]).join(sep + ' ') + sep : '';
+        let name = [];
+        if (this._config.orderedBy === types_1.NameOrder.FIRST_NAME) {
             switch (by) {
-                case 'firstname':
-                    cname = hasmid ?
-                        [firsts, mn, ln.tostring()].join(index_2.Separator.SPACE) :
-                        [firsts, ln.tostring()].join(index_2.Separator.SPACE);
+                case types_1.Flat.FIRST_NAME:
+                    name = hasMid ? [f, mn, ln] : [f, ln];
                     break;
-                case 'lastname':
-                    cname = hasmid ?
-                        [fn.tostring(), mn, lasts].join(index_2.Separator.SPACE) :
-                        [fn.tostring(), lasts].join(index_2.Separator.SPACE);
+                case types_1.Flat.LAST_NAME:
+                    name = hasMid ? [fn, mn, l] : [fn, l];
                     break;
-                case 'middlename':
-                    cname = hasmid ?
-                        [fn.tostring(), mids, ln.tostring()].join(index_2.Separator.SPACE) :
-                        [fn.tostring(), ln.tostring()].join(index_2.Separator.SPACE);
+                case types_1.Flat.MIDDLE_NAME:
+                    name = hasMid ? [fn, m, ln] : [fn, ln];
                     break;
-                case 'firstmid':
-                    cname = hasmid ?
-                        [firsts, mids, ln.tostring()].join(index_2.Separator.SPACE) :
-                        [firsts, ln.tostring()].join(index_2.Separator.SPACE);
+                case types_1.Flat.FIRST_MID:
+                    name = hasMid ? [f, m, ln] : [f, ln];
                     break;
-                case 'midlast':
-                    cname = hasmid ?
-                        [fn.tostring(), mids, lasts].join(index_2.Separator.SPACE) :
-                        [fn.tostring(), lasts].join(index_2.Separator.SPACE);
+                case types_1.Flat.MID_LAST:
+                    name = hasMid ? [fn, m, l] : [fn, l];
+                    break;
+                case types_1.Flat.ALL:
+                    name = hasMid ? [f, m, l] : [f, l];
                     break;
             }
         }
         else {
             switch (by) {
-                case 'firstname':
-                    cname = hasmid ?
-                        [ln.tostring(), firsts, mn].join(index_2.Separator.SPACE) :
-                        [ln.tostring(), firsts].join(index_2.Separator.SPACE);
+                case types_1.Flat.FIRST_NAME:
+                    name = hasMid ? [ln, f, mn] : [ln, f];
+                    break;
+                case types_1.Flat.LAST_NAME:
+                    name = hasMid ? [l, fn, mn] : [l, fn];
                     break;
-                case 'lastname':
-                    cname = hasmid ?
-                        [lasts, fn.tostring(), mn].join(index_2.Separator.SPACE) :
-                        [lasts, fn.tostring()].join(index_2.Separator.SPACE);
+                case types_1.Flat.MIDDLE_NAME:
+                    name = hasMid ? [ln, fn, m] : [ln, fn];
                     break;
-                case 'middlename':
-                    cname = hasmid ?
-                        [ln.tostring(), fn.tostring(), mids].join(index_2.Separator.SPACE) :
-                        [ln.tostring(), fn.tostring()].join(index_2.Separator.SPACE);
+                case types_1.Flat.FIRST_MID:
+                    name = hasMid ? [ln, f, m] : [ln, f];
                     break;
-                case 'firstmid':
-                    cname = hasmid ?
-                        [ln.tostring(), firsts, mids].join(index_2.Separator.SPACE) :
-                        [ln.tostring(), firsts].join(index_2.Separator.SPACE);
+                case types_1.Flat.MID_LAST:
+                    name = hasMid ? [l, fn, m] : [l, fn];
                     break;
-                case 'midlast':
-                    cname = hasmid ?
-                        [lasts, fn.tostring(), mids].join(index_2.Separator.SPACE) :
-                        [lasts, fn.tostring()].join(index_2.Separator.SPACE);
+                case types_1.Flat.ALL:
+                    name = hasMid ? [l, f, m] : [l, f];
                     break;
             }
         }
-        if (warning && cname.length > limit)
-            console.warn(`The compressed name <${cname}> still surpasses the set limit ${limit}`);
-        return cname;
-    }
-    /**
-     * Zips or compresses a name by using different forms of variants
-     * @param by a variant to use when compressing the long name. The last two
-     * variants represent respectively the combination of `firstname + middlename`
-     * and `middlename + lastname`.
-     */
-    zip(by = 'mn') {
-        let v;
-        if (by === 'fn' || by === 'firstname')
-            v = 'firstname';
-        if (by === 'mn' || by === 'middlename')
-            v = 'middlename';
-        if (by === 'ln' || by === 'lastname')
-            v = 'lastname';
-        if (by === 'fm' || by === 'firstmid')
-            v = 'firstmid';
-        if (by === 'ml' || by === 'midlast')
-            v = 'midlast';
-        return this.compress(0, v, false);
-    }
-    /**
-     * Suggests possible (randomly) usernames closest to the name
-     * @returns {Array<string>} a set of usernames
+        const flat = name.join(' ');
+        if (recursive && flat.length > limit) {
+            const next = by === types_1.Flat.FIRST_NAME
+                ? types_1.Flat.MIDDLE_NAME
+                : by === types_1.Flat.MIDDLE_NAME
+                    ? types_1.Flat.LAST_NAME
+                    : by === types_1.Flat.LAST_NAME
+                        ? types_1.Flat.FIRST_MID
+                        : by === types_1.Flat.FIRST_MID
+                            ? types_1.Flat.MID_LAST
+                            : by === types_1.Flat.MID_LAST
+                                ? types_1.Flat.ALL
+                                : by === types_1.Flat.ALL
+                                    ? types_1.Flat.ALL
+                                    : by;
+            if (next === by)
+                return flat;
+            return this.flatten(Object.assign(Object.assign({}, options), { by: next }));
+        }
+        return flat;
+    }
+    /**
+     * Zips or compacts a name using different forms of variants.
+     *
+     * @see `flatten()` for more details.
+     */
+    zip(by = types_1.Flat.MID_LAST, withPeriod = true) {
+        return this.flatten({ limit: 0, by, withPeriod });
+    }
+    /**
+     * Formats the full name as desired.
+     * @param pattern character used to format it.
      *
-     * **NOTE**
-     * The validity of these usernames are not checked against any social media
-     * or web app online.
-     */
-    username() {
-        const unames = [];
-        const { firstname: f, lastname: l } = this.fullname;
-        const p = index_2.Separator.PERIOD;
-        // Given `John Smith`
-        unames.push(f.lower() + l.lower()); // johnsmith
-        unames.push(l.lower() + f.lower()); // smithjohn
-        unames.push(f.lower()[0] + l.lower()); // jsmith
-        unames.push(l.lower()[0] + f.lower()); // sjohn
-        unames.push(f.lower()[0] + p + l.lower()); // j.smith
-        unames.push(l.lower()[0] + p + f.lower()); // s.john
-        unames.push(f.lower().slice(0, 2) + l.lower()); // josmith
-        unames.push(l.lower().slice(0, 2) + f.lower()); // smjohn
-        unames.push(f.lower().slice(0, 2) + p + l.lower()); // jo.smith
-        unames.push(l.lower().slice(0, 2) + p + f.lower()); // sm.john
-        return unames;
-    }
-    /**
-     * Formats the name as desired
-     * @param {string} how to format the full name
-     * @returns {string} the formatted name as specified
+     * string format
+     * -------------
+     * - 'short': typical first + last name
+     * - 'long': birth name (without prefix and suffix)
+     * - 'public': first name combined with the last name's initial.
+     * - 'official': official document format
      *
-     * How to format it?
-     * 'f': first name
-     * 'F': capitalized first name
-     * 'l': last name (official)
-     * 'L': capitalized last name
-     * 'm': middle names
-     * 'M': Capitalized middle names
-     * 'O': official document format
+     * char format
+     * -----------
+     * - 'b': birth name
+     * - 'B': capitalized birth name
+     * - 'f': first name
+     * - 'F': capitalized first name
+     * - 'l': last name
+     * - 'L': capitalized last name
+     * - 'm': middle names
+     * - 'M': capitalized middle names
+     * - 'o': official document format
+     * - 'O': official document format in capital letters
+     * - 'p': prefix
+     * - 'P': capitalized prefix
+     * - 's': suffix
+     * - 'S': capitalized suffix
      *
-     * @example
-     * Given the name `Joe Jim Smith`, call the `format` with the how string.
+     * punctuations
+     * ------------
+     * - '.': period
+     * - ',': comma
+     * - ' ': space
+     * - '-': hyphen
+     * - '_': underscore
+     * - '$': an escape character to select only the initial of the next char.
+     *
+     * Given the name `Joe Jim Smith`, use `format` with the `pattern` string.
      * - format('l f') => 'Smith Joe'
      * - format('L, f') => 'SMITH, Joe'
-     * - format('fml') => 'JoeJimSmith'
-     * - format('FML') => 'JOEJIMSMITH'
-     * - format('L, f m') => 'SMITH, Joe Jim'
-     * - format('O') => 'SMITH, Joe Jim'
-     */
-    format(how) {
-        if (!how)
-            return this.getFullname();
+     * - format('short') => 'Joe Smith'
+     * - format() => 'SMITH, Joe Jim'
+     * - format(r'f $l.') => 'Joe S.'.
+     *
+     * Do note that the escape character is only valid for the birth name parts:
+     * first, middle, and last names.
+     */
+    format(pattern) {
+        var _a;
+        if (pattern === 'short')
+            return this.short;
+        if (pattern === 'long')
+            return this.long;
+        if (pattern === 'public')
+            return this.public;
+        if (pattern === 'official')
+            pattern = 'o';
+        let group = '';
         const formatted = [];
-        const tokens = [
-            '.', ',', ' ', '-', '_', 'f', 'F', 'l', 'L', 'm', 'M',
-            'n', 'N', 'o', 'O', 'p', 'P', 's', 'S'
-        ];
-        for (const c of how) {
-            if (tokens.indexOf(c) === -1)
-                throw new Error(`<${c}> is an invalid character for the formatting.`);
-            formatted.push(this.map(c));
+        for (const char of pattern.split('')) {
+            if (constants_1.ALLOWED_TOKENS.indexOf(char) === -1) {
+                throw new error_1.NotAllowedError({
+                    source: this.full,
+                    operation: 'format',
+                    message: `unsupported character <${char}> from ${pattern}.`,
+                });
+            }
+            group += char;
+            if (char === '$')
+                continue;
+            formatted.push((_a = this.map(group)) !== null && _a !== void 0 ? _a : '');
+            group = '';
         }
-        return formatted.join(index_2.Separator.EMPTY).trim();
+        return formatted.join('').trim();
+    }
+    /**
+     * Flips definitely the name order from the preset/current config.
+     */
+    flip() {
+        if (this._config.orderedBy === types_1.NameOrder.FIRST_NAME) {
+            this._config.updateOrder(types_1.NameOrder.LAST_NAME);
+            console.log(`The name order is now changed to: ${types_1.NameOrder.LAST_NAME}`);
+        }
+        else {
+            this._config.updateOrder(types_1.NameOrder.FIRST_NAME);
+            console.log(`The name order is now changed to: ${types_1.NameOrder.FIRST_NAME}`);
+        }
+    }
+    /**
+     * Splits the name parts of a birth name.
+     * @param separator token for the split.
+     */
+    split(separator = /[' -]/g) {
+        return this.birth.replace(separator, ' ').split(' ');
     }
     /**
-     * Configures how the setup will be working
-     * @param {Config} options for a customized setup
+     * Joins the name parts of a birth name.
+     * @param separator token for the junction.
      */
-    configure(options) {
-        // consider using deepmerge if objects no longer stay shallow
-        this.config = Object.assign(Object.assign({}, index_1.CONFIG), options); // if options, it overrides CONFIG
+    join(separator = '') {
+        return this.split().join(separator);
     }
     /**
-     * Defines the full name by having the pieces (namon) of the names ready
-     * @param parser customized or user-defined parser to get the full name
+     * Transforms a birth name into UPPERCASE
      */
-    initialize(parser) {
-        const { orderedBy, separator, bypass, lastnameFormat } = this.config;
-        this.fullname = parser.parse({ orderedBy, separator, bypass, lastnameFormat });
+    toUpperCase() {
+        return this.birth.toUpperCase();
     }
     /**
-     * Maps a character to a specific piece of the name
-     * @param c character to be mapped
-     * @return {string} piece of name
+     * Transforms a birth name into lowercase
      */
-    map(c) {
-        switch (c) {
+    toLowerCase() {
+        return this.birth.toLowerCase();
+    }
+    /**
+     * Transforms a birth name into camelCase
+     */
+    toCamelCase() {
+        return utils_1.decapitalize(this.toPascalCase());
+    }
+    /**
+     * Transforms a birth name into PascalCase
+     */
+    toPascalCase() {
+        return this.split()
+            .map((n) => utils_1.capitalize(n))
+            .join('');
+    }
+    /**
+     * Transforms a birth name into snake_case
+     */
+    toSnakeCase() {
+        return this.split()
+            .map((n) => n.toLowerCase())
+            .join('_');
+    }
+    /**
+     * Transforms a birth name into hyphen-case
+     */
+    toHyphenCase() {
+        return this.split()
+            .map((n) => n.toLowerCase())
+            .join('-');
+    }
+    /**
+     * Transforms a birth name into dot.case
+     */
+    toDotCase() {
+        return this.split()
+            .map((n) => n.toLowerCase())
+            .join('.');
+    }
+    /**
+     * Transforms a birth name into ToGgLeCaSe
+     */
+    toToggleCase() {
+        return utils_1.toggleCase(this.birth);
+    }
+    build(parser, options) {
+        this._config = config_1.Config.merge(options);
+        this._fullName = parser.parse(this._config);
+    }
+    toParser(raw) {
+        if (raw instanceof parser_1.Parser)
+            return raw;
+        if (typeof raw === 'string')
+            return new parser_1.StringParser(raw);
+        if (utils_1.isStringArray(raw))
+            return new parser_1.ArrayStringParser(raw);
+        if (utils_1.isNameArray(raw))
+            return new parser_1.ArrayNameParser(raw);
+        if (typeof raw === 'object')
+            return new parser_1.NamaParser(raw);
+        throw new error_1.InputError({
+            source: raw,
+            message: 'Cannot parse raw data. Review expected data types.',
+        });
+    }
+    map(char) {
+        var _a, _b;
+        switch (char) {
             case '.':
-                return index_2.Separator.PERIOD;
             case ',':
-                return index_2.Separator.COMMA;
             case ' ':
-                return index_2.Separator.SPACE;
             case '-':
-                return index_2.Separator.HYPHEN;
             case '_':
-                return index_2.Separator.UNDERSCORE;
+                return char;
+            case 'b':
+                return this.birth;
+            case 'B':
+                return this.birth.toUpperCase();
             case 'f':
-                return this.fullname.firstname.namon;
+                return this.first;
             case 'F':
-                return this.fullname.firstname.upper();
+                return this.first.toUpperCase();
             case 'l':
-                return this.fullname.lastname.namon;
+                return this.last;
             case 'L':
-                return this.fullname.lastname.upper();
+                return this.last.toUpperCase();
             case 'm':
-                return this.fullname.middlename
-                    .map(n => n.namon).join(index_2.Separator.SPACE);
             case 'M':
-                return this.fullname.middlename
-                    .map(n => n.upper()).join(index_2.Separator.SPACE);
+                return char === 'm' ? this.middleName().join(' ') : this.middleName().join(' ').toUpperCase();
             case 'o':
             case 'O':
-                const { titling, ending } = this.config;
-                const pxSep = titling === 'us' ? index_2.Separator.PERIOD : index_2.Separator.EMPTY;
-                const sxSep = ending !== index_2.Separator.SPACE ? ending : index_2.Separator.EMPTY;
-                const official = [
-                    this.fullname.prefix ? index_2.Separator.EMPTY.concat(this.fullname.prefix, pxSep) : index_2.Separator.EMPTY,
-                    this.fullname.lastname.upper().concat(index_2.Separator.COMMA),
-                    this.fullname.firstname.tostring(),
-                    this.fullname.middlename.map(n => n.namon).join(index_2.Separator.SPACE).concat(sxSep),
-                    this.fullname.suffix || index_2.Separator.EMPTY,
-                ].join(index_2.Separator.SPACE).trim();
-                return c === 'o' ? official : official.toUpperCase();
+                const sep = this._config.ending ? ',' : '';
+                const names = [];
+                if (this.prefix)
+                    names.push(this.prefix);
+                names.push(`${this.last},`.toUpperCase());
+                if (this.hasMiddle) {
+                    names.push(this.first, this.middleName().join(' ') + sep);
+                }
+                else {
+                    names.push(this.first + sep);
+                }
+                if (this.suffix)
+                    names.push(this.suffix);
+                const nama = names.join(' ').trim();
+                return char === 'o' ? nama : nama.toUpperCase();
             case 'p':
-                return this.fullname.prefix || index_2.Separator.EMPTY;
+                return this.prefix;
             case 'P':
-                return this.fullname.prefix ? this.fullname.prefix.toUpperCase() : index_2.Separator.EMPTY;
+                return (_a = this.prefix) === null || _a === void 0 ? void 0 : _a.toUpperCase();
             case 's':
-                return this.fullname.suffix || index_2.Separator.EMPTY;
+                return this.suffix;
             case 'S':
-                return this.fullname.suffix ? this.fullname.suffix.toUpperCase() : index_2.Separator.EMPTY;
+                return (_b = this.suffix) === null || _b === void 0 ? void 0 : _b.toUpperCase();
+            case '$f':
+            case '$F':
+                return this._fullName.firstName.initials()[0];
+            case '$l':
+            case '$L':
+                return this._fullName.lastName.initials()[0];
+            case '$m':
+            case '$M':
+                return this.hasMiddle ? this.middle[0] : undefined;
             default:
-                return index_2.Separator.EMPTY;
-        }
-    }
-    /**
-     * Builds a high qualitty of data using parsers and validators
-     * @param {string | string[] | Array<Name> | Nama} raw data to parse or
-     * construct the pieces of the name
-     */
-    build(raw) {
-        if (this.config.parser) {
-            this.initialize(this.config.parser);
-        }
-        else if (typeof raw === 'string') { // check for string type
-            this.initialize(new index_1.StringParser(raw));
-        }
-        else if (Array.isArray(raw) && raw.length) { // check for Array<T>
-            if (typeof raw[0] === 'string') { // check for Array<string>
-                for (const key of raw)
-                    if (typeof key !== 'string')
-                        throw new Error(`Cannot parse raw data as array of 'string'`);
-                this.initialize(new index_1.ArrayStringParser(raw));
-            }
-            else if (raw[0] instanceof index_2.Name) { // check for Array<Name>
-                for (const obj of raw)
-                    if (!(obj instanceof index_2.Name))
-                        throw new Error(`Cannot parse raw data as array of '${index_2.Name.name}'`);
-                this.initialize(new index_1.ArrayNameParser(raw));
-            }
-            else {
-                // typescript should stop them, but let's be paranoid (for JS developers)
-                throw new Error(`Cannot parse raw data as arrays that are not of '${index_2.Name.name}' or string`);
-            }
-        }
-        else if (raw instanceof Object) { // check for json object
-            for (const entry of Object.entries(raw)) { // make sure keys are correct
-                const key = entry[0], value = entry[1];
-                if (['firstname', 'lastname', 'middlename', 'prefix', 'suffix'].indexOf(key) === -1)
-                    throw new Error(`Cannot parse raw data as json object that does not contains keys of '${index_2.Namon}'`);
-                if (typeof value !== 'string') // make sure the values are proper string
-                    throw new Error(`Cannot parse raw data. The key <${key}> should be a 'string' type`);
-            }
-            this.initialize(new index_1.NamaParser(raw));
-        }
-        else {
-            // typescript should stop them, but let's be paranoid again (for JS developers)
-            throw new Error(`Cannot parse raw data. Review the data type expected.`);
+                return undefined;
         }
-        // paranoid coder mode: on :P
-        if (!this.config.bypass)
-            new index_3.FullnameValidator().validate(this.fullname);
-        this.summary = new index_2.Summary(this.getFullname());
     }
 }
 exports.Namefully = Namefully;
-Namefully.prototype.full = Namefully.prototype.getFullname;
-Namefully.prototype.fn = Namefully.prototype.getFirstname;
-Namefully.prototype.ln = Namefully.prototype.getLastname;
-Namefully.prototype.mn = Namefully.prototype.getMiddlenames;
-Namefully.prototype.px = Namefully.prototype.getPrefix;
-Namefully.prototype.sx = Namefully.prototype.getSuffix;
-Namefully.prototype.inits = Namefully.prototype.getInitials;
-Namefully.prototype.stats = Namefully.prototype.describe;
 //# sourceMappingURL=namefully.js.map