namefully 1.1.0 → 1.2.0

package/dist/lib/namefully.d.ts

@@ -1,302 +1,379 @@
-import { Fullname, Name, Nama, Summary, Config, NameOrder, NameType, LastnameFormat } from './models';
+import { Config } from './config';
+import { Name, JsonName } from './name';
+import { Parser } from './parser';
+import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types';
 /**
- * Person name handler
- * @class
+ * A helper for organizing person names in a particular order, way, or shape.
  *
- * `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).
+ * 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.
  *
- * `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.
+ * `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.
+ *
+ * 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: 1 piece of a name (e.g., firstname)
- * - nama: 2+ 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 handling!
+ * Happy name handling 😊!
  */
 export declare class Namefully {
     /**
-     * Holds a json-like high quality of data
-     * @see {Fullname} description for more details
+     * A copy of high-quality name data.
      */
-    private fullname;
+    private _fullName;
     /**
-     * Holds statistical info on the name
-     * @see {Summary} class description for more details
+     * A copy of the default configuration (combined with a custom one if any).
      */
-    private summary;
+    private _config;
     /**
-     * Holds a json-like copy of the preset configuration
-     * @see {Config} description for more details
+     * 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.
      */
-    private config;
+    constructor(names: string | string[] | Name[] | JsonName | Parser, options?: Partial<Config>);
     /**
-     * Constructs an instance of the utility and helps to benefit from many helpers
-     * @param {string | string[] | Name[] | Nama | Fullname} raw element to parse or
-     * construct the pieces of the name
-     * @param {Config} options to configure how to run the utility
+     * Constructs a `Namefully` instance from a text.
+     *
+     * It works like `parse` except that this function returns `null` where `parse`
+     * would throw a `NameError`.
      */
-    constructor(raw: string | string[] | Name[] | Nama | Fullname, options?: Partial<Config>);
+    static tryParse(text: string): Namefully | undefined;
     /**
-     * Gets the full name ordered as configured
-     * @param {NameOrder} orderedBy force to order by first or last
-     * name by overriding the preset configuration
+     * 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.
      *
-     * @see {format} to alter manually the order of appearance of the full name.
-     * For example, ::format('l f m') outputs `lastname firstname middlename`.
+     * 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: string): Promise<Namefully>;
+    /**
+     * The current configuration.
+     */
+    get config(): Config;
+    /**
+     * The number of characters of the `birthName`, including spaces.
+     */
+    get length(): number;
+    /**
+     * The prefix part.
+     */
+    get prefix(): Nullable<string>;
+    /**
+     * The firt name.
+     */
+    get first(): string;
+    /**
+     * The first middle name if any.
+     */
+    get middle(): Nullable<string>;
+    /**
+     * Returns true if any middle name has been set.
+     */
+    get hasMiddle(): boolean;
+    /**
+     * The last name.
+     */
+    get last(): string;
+    /**
+     * The suffix part.
+     */
+    get suffix(): Nullable<string>;
+    /**
+     * The birth name.
+     */
+    get birth(): string;
+    /**
+     * The shortest version of a person name.
+     */
+    get short(): string;
+    /**
+     * The longest version of a person name.
+     */
+    get long(): string;
+    /**
+     * The entire name set.
      */
-    getFullname(orderedBy?: NameOrder): string;
+    get full(): string;
     /**
-     * Gets the birth name ordered as configured, no prefix or suffix
-     * @param {NameOrder} orderedBy force to order by first or last
-     * name by overriding the preset configuration
+     * The first name combined with the last name's initial.
      */
-    getBirthname(orderedBy?: NameOrder): string;
+    get public(): string;
     /**
-     * Gets the first name part of the full name
-     * @param {boolean} includeAll whether to include other pieces of the first
-     * name
+     * Returns the full name as set.
      */
-    getFirstname(includeAll?: boolean): string;
+    toString(): string;
     /**
-     * Gets the last name part of the full name
-     * @param {LastnameFormat} [format] overrides the how-to format of a surname
-     * output, considering its subparts.
+     * Fetches the raw form of a name piece.
      */
-    getLastname(format?: LastnameFormat): string;
+    get(namon: Namon): Nullable<Name | Name[]>;
     /**
-     * Gets the middle names part of the full name
+     * Whether this name is equal to another one from a raw-string perspective.
      */
-    getMiddlenames(): string[];
+    equal(other: Namefully): boolean;
     /**
-     * Gets the prefix part of the full name
+     * Gets a JSON representation of the full name.
      */
-    getPrefix(): string;
+    toJson(): JsonName;
     /**
-     * Gets the suffix part of the full name
+     * Confirms that a name part has been set.
      */
-    getSuffix(): string;
+    has(namon: Namon): boolean;
     /**
-     * Gets the initials of the full name
-     * @param {NameOrder} orderedBy force to order by first or last name by
-     * overriding the preset configuration
-     * @param {boolean} [withMid] whether to include middle names's
+     * Gets the full name ordered as configured.
+     *
+     * The name order `orderedBy` forces to order by first or last name by
+     * overriding the preset configuration.
      *
-     * @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']
+     * `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?: NameOrder): string;
+    /**
+     * Gets the birth name ordered as configured, no `prefix` or `suffix`.
      *
-     * **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.
+     * @param orderedBy forces to order by first or last name by overriding the
+     * preset configuration.
      */
-    getInitials(orderedBy?: NameOrder, withMid?: boolean): string[];
+    birthName(orderedBy?: NameOrder): string;
     /**
-     * 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
+     * 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;
-     * `distribution` : the characters' distribution.
+     * @param withMore determines whether to include other pieces of the first
+     * name.
+     */
+    firstName(withMore?: boolean): string;
+    /**
+     * Gets the middle name part of the `FullName`.
+     */
+    middleName(): string[];
+    /**
+     * 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?: Surname): string;
+    /**
+     * Gets the initials of the `FullName`.
      *
-     * Descriptive statistics for "Thomas Alva Edison"
-     *  count    : 16
-     *  frequency: 3
-     *  top      : A
-     *  unique   : 12
-     *  distribution: { T: 1, H: 1, O: 2, M: 1, A: 2, S: 2, ' ': 2, L: 1, V: 1,
-     *  E: 1, D: 1, I: 1, N: 1 }
+     * @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`.
+     * For example, given the names:
+     * - `John Smith` => `['J', 'S']`
+     * - `John Ben Smith` => `['J', 'B', 'S']`.
      */
-    describe(what?: NameType): Summary;
+    initials(options?: {
+        orderedBy?: NameOrder;
+        only?: NameType;
+    }): string[];
     /**
      * Shortens a complex full name to a simple typical name, a combination of
-     * first name and last name.
-     * @param {NameOrder} orderedBy force to order by first or last
-     * name by overriding the preset configuration
+     * 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 `lastnameFormat` is prioritized.
+     * the last name, the configured `surname` is prioritized.
      *
-     * @example
-     * For a given `Firstname Fathername Mothername`, shortening this name when
-     * the lastnameFormat is set as `mother` is equivalent to making it:
-     * `Firstname Mothername`.
+     * 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?: NameOrder): string;
     /**
-     * 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
+     * Flattens a long name using the name types as variants.
      *
-     * @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
+     * 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`.
+     *
+     * 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?: number, by?: 'fn' | 'ln' | 'mn' | 'fm' | 'ml' | 'firstname' | 'lastname' | 'middlename' | 'firstmid' | 'midlast', warning?: boolean): string;
-    /**
-     * 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`.
+     * 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()`.
      */
-    zip(by?: 'fn' | 'ln' | 'mn' | 'fm' | 'ml' | 'firstname' | 'lastname' | 'middlename' | 'firstmid' | 'midlast'): string;
+    flatten(options: Partial<{
+        limit: number;
+        by: Flat;
+        withPeriod: boolean;
+        recursive: boolean;
+        withMore: boolean;
+        surname: Surname;
+    }>): string;
     /**
-     * Suggests possible (randomly) usernames closest to the name
+     * Zips or compacts a name using different forms of variants.
      *
-     * **NOTE**
-     * The validity of these usernames are not checked against any social media
-     * or web app online.
+     * @see `flatten()` for more details.
      */
-    username(): string[];
+    zip(by?: Flat, withPeriod?: boolean): string;
     /**
-     * Formats the name as desired
-     * @param {string} how to format the full name
+     * Formats the full name as desired.
+     * @param pattern character used to format it.
      *
-     * How to format it?
      * string format
      * -------------
-     * 'short': typical first + last name
-     * 'long': birth name (without prefix and suffix)
+     * - '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
      *
      * char format
      * -----------
-     * 'b': birth name
-     * 'B': capitalized birth name
-     * '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
-     * 'O': official document format in capital letters
-     * 'p': prefix
-     * 'P': capitalized prefix
-     * 's': suffix
-     * 'S': capitalized suffix
+     * - '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
      *
      * punctuations
      * ------------
-     * '.': period
-     * ',': comma
-     * ' ': space
-     * '-': hyphen
-     * '_': underscore
+     * - '.': period
+     * - ',': comma
+     * - ' ': space
+     * - '-': hyphen
+     * - '_': underscore
+     * - '$': an escape character to select only the initial of the next char.
      *
-     * @example
-     * Given the name `Joe Jim Smith`, call the `format` with the how string.
+     * Given the name `Joe Jim Smith`, use `format` with the `pattern` string.
      * - format('l f') => 'Smith Joe'
      * - format('L, f') => 'SMITH, Joe'
      * - 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(how?: string): string;
+    format(pattern: string): string;
     /**
-     * Returns the count of characters of the birth name, excluding punctuations
+     * Flips definitely the name order from the preset/current config.
      */
-    size(): number;
+    flip(): void;
     /**
-     * Returns an ascii representation of each characters of a name as specified
-     * @param options use specifics to shape conversion
+     * Splits the name parts of a birth name.
+     * @param separator token for the split.
      */
-    ascii(options?: Partial<{
-        nameType: NameType;
-        exceptions: string[];
-    }>): number[];
+    split(separator?: string | RegExp): string[];
     /**
-     * Transforms a birth name to a specific case
-     * @param case which case to convert a birth name to
+     * Joins the name parts of a birth name.
+     * @param separator token for the junction.
      */
-    to(_case: 'upper' | 'lower' | 'camel' | 'pascal' | 'snake' | 'hyphen' | 'dot' | 'toggle'): string;
+    join(separator?: string): string;
     /**
-     * Returns a password-like representation of a name
-     * @param {NameType} [what] which name part
+     * Transforms a birth name into UPPERCASE
      */
-    passwd(what?: NameType): string;
-    private hasMiddlename;
-    private configure;
-    private initialize;
-    private parseNameOrder;
-    private map;
+    toUpperCase(): string;
+    /**
+     * Transforms a birth name into lowercase
+     */
+    toLowerCase(): string;
+    /**
+     * Transforms a birth name into camelCase
+     */
+    toCamelCase(): string;
+    /**
+     * Transforms a birth name into PascalCase
+     */
+    toPascalCase(): string;
+    /**
+     * Transforms a birth name into snake_case
+     */
+    toSnakeCase(): string;
+    /**
+     * Transforms a birth name into hyphen-case
+     */
+    toHyphenCase(): string;
+    /**
+     * Transforms a birth name into dot.case
+     */
+    toDotCase(): string;
+    /**
+     * Transforms a birth name into ToGgLeCaSe
+     */
+    toToggleCase(): string;
     private build;
-}
-/**
- * Aliases for `Namefully`
- */
-export interface Namefully {
-    full: typeof Namefully.prototype.getFullname;
-    birth: typeof Namefully.prototype.getBirthname;
-    fn: typeof Namefully.prototype.getFirstname;
-    ln: typeof Namefully.prototype.getLastname;
-    mn: typeof Namefully.prototype.getMiddlenames;
-    px: typeof Namefully.prototype.getPrefix;
-    sx: typeof Namefully.prototype.getSuffix;
-    inits: typeof Namefully.prototype.getInitials;
-    stats: typeof Namefully.prototype.describe;
+    private toParser;
+    private map;
 }