namefully 1.3.0 → 2.0.1

package/dist/{types → esm}/namefully.d.ts

@@ -1,49 +1,50 @@
-import { Config } from './config';
-import { Name, JsonName } from './name';
-import { Parser } from './parser';
-import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types';
-import { NameIndex } from './utils';
+import { Config } from './config.js';
+import { Name, JsonName } from './name.js';
+import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types.js';
+import { NameIndex } from './utils.js';
+import { Parser } from './parser.js';
 /**
- * A helper for organizing person names in a particular order, way, or shape.
+ * A utility for organizing human names in a particular order, way, or shape.
  *
- * 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.
+ * Though `namefully` is designed to be 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. Additionally, `Namefully` objects may be created using
+ * distinct raw data shapes. This is intended to give some flexibility to you
+ * so that you are not bound to a particular data format (e.g., string).
+ * Follow the API reference to know how to harness its usability as this utility
+ * aims to save time in formatting names.
  *
- * `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 trapdoor. Once some name data is provided and
+ * validated, you may only *access* it but not update any part of it. This
+ * means that *no editing* is possible. If the name is mistaken, a new
+ * instance of `Namefully` must be created. In simple terms, it's immutable.
+ * Remember, this utility's primary objective is to help manipulate human names,
+ * not the opposite.
  *
- * Note that the name standards used for the current version of this library
- * are as follows:
+ * Note that the name standards used for the current version of this utility are
+ * as follows:
  *      `[prefix] firstName [middleName] lastName [suffix]`
- * The opening `[` and closing `]` symbols mean that these parts are optional.
+ * where 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 piece and `Smith`, the last
  * name piece.
  *
- * @see https://www.fbiic.gov/public/2008/nov/Naming_practice_guide_UK_2006.pdf
+ * @see {link https://www.fbiic.gov/public/2008/nov/Naming_practice_guide_UK_2006.pdf}
  * for more info on name standards.
  *
  * **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.
+ * and may be altered through configurable 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.
+ * Once imported, all that is required to do is to create instances of `Namefully`
+ * as you see fit and the rest will follow.
  *
  * Some terminologies used across the library are:
- * - namon: 1 piece of name (e.g., first name)
- * - nama: 2+ pieces of name (e.g., first name + last name)
+ * - namon: 1 piece of name (e.g., prefix)
+ * - nama: a combination of 2+ pieces of name (e.g., first name + last name)
  *
  * Happy name handling 😊!
  */
@@ -53,16 +54,16 @@ export declare class Namefully {
      * @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.
+     * Optional parameters may be provided with specifics on how to treat a full
+     * name during its existence. All name parts must have at least two (2) characters
+     * or more to be considered a potential. That is the only requirement of namefully.
      */
     constructor(names: string | string[] | Name[] | JsonName | Parser, options?: Partial<Config>);
     /**
      * Constructs a `Namefully` instance from a text.
      *
-     * It works like `parse` except that this function returns `null` where `parse`
-     * would throw a `NameError`.
+     * It works like `parse` except that this function returns `undefined` when
+     * `parse` would throw a `NameError`.
      */
     static tryParse(text: string, index?: NameIndex): Namefully | undefined;
     /**
@@ -81,27 +82,27 @@ export declare class Namefully {
      * process.
      */
     static parse(text: string, index?: NameIndex): Promise<Namefully>;
-    /** The current configuration. */
+    /** The configuration dictating this name's behavior. */
     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 part. */
+    /** The prefix part of the name set. */
+    get prefix(): string | undefined;
+    /** The firt name part of the name set. */
     get first(): string;
-    /** The first middle name part if any. */
-    get middle(): Nullable<string>;
+    /** The first middle name part of the name set if any. */
+    get middle(): string | undefined;
     /** Returns true if any middle name has been set. */
     get hasMiddle(): boolean;
-    /** The last name part. */
+    /** The last name part of the name set. */
     get last(): string;
-    /** The suffix part. */
-    get suffix(): Nullable<string>;
-    /** The birth name part. */
+    /** The suffix part of the name set. */
+    get suffix(): string | undefined;
+    /** The birth name part of the name set. */
     get birth(): string;
-    /** The shortest version of a person name. */
+    /** The shortest version of a human name (first + last name). */
     get short(): string;
-    /** The longest version of a person name. */
+    /** The longest version of a human name (a.k.a birth name). */
     get long(): string;
     /** The entire name set. */
     get full(): string;
@@ -117,18 +118,17 @@ export declare class Namefully {
     equal(other: Namefully): boolean;
     /** Gets a JSON representation of the full name. */
     toJson(): JsonName;
+    json: () => JsonName;
     /** Confirms that a name part has been set. */
     has(namon: Namon): boolean;
     /**
      * Gets the full name ordered as configured.
      *
-     * The name order `orderedBy` forces to order by first or last name by
-     * overriding the preset configuration.
-     *
-     * `Namefully.format` may also be used to alter manually the order of appearance
-     * of full name.
+     * @param {NameOrder} orderedBy forces to arrange a name set by first or last
+     * name, overriding the preset configuration.
      *
-     * For example:
+     * `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"
@@ -145,26 +145,26 @@ export declare class Namefully {
     birthName(orderedBy?: NameOrder): string;
     /**
      * Gets the first name part of the `FullName`.
-     *
-     * @param withMore determines whether to include other pieces of the first
-     * name.
+     * @param {boolean} 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`.
-     *
-     * @param format overrides the how-to formatting of a surname output,
+     * @param {Surname} format overrides the how-to formatting of a surname output,
      * considering its sub-parts.
      */
     lastName(format?: Surname): string;
     /**
      * Gets the initials of the `FullName`.
      *
-     * @param {options.orderedBy} forces to order by first or last name by
+     * @param {object} options when getting the initials.
+     * @param {NameOrder} options.orderedBy forces to order by first or last name by
      * overriding the preset configuration.
-     * @param
+     * @param {NameType} options.only selects initials of only certain name parts.
+     * @param {boolean} options.asJson whether to return initials as an array or JSON.
      *
      * For example, given the names:
      * - `John Smith` => `['J', 'S']`
@@ -179,23 +179,22 @@ export declare class Namefully {
      * Shortens a complex full name to a simple typical name, a combination of
      * first and last name.
      *
-     * @param orderedBy forces to order by first or last name by overriding the
-     * preset configuration.
+     * @param {NameOrder} orderedBy forces to order by first or last name, overriding
+     * the preset configuration.
      *
      * 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.
+     * 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`.
+     * the surname is set as `mother` is equivalent to making it: `FirstName MotherName`.
      */
     shorten(orderedBy?: NameOrder): string;
     /**
-     * Flattens a long name using the name types as variants.
+     * Flattens long names 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
@@ -233,13 +232,12 @@ export declare class Namefully {
     }>): string;
     /**
      * Zips or compacts a name using different forms of variants.
-     *
      * @see `flatten()` for more details.
      */
     zip(by?: Flat, withPeriod?: boolean): string;
     /**
      * Formats the full name as desired.
-     * @param pattern character used to format it.
+     * @param {string} pattern character used to format it.
      *
      * string format
      * -------------
@@ -285,7 +283,7 @@ export declare class Namefully {
      * first, middle, and last names.
      */
     format(pattern: string): string;
-    /** Flips definitely the name order from the preset/current config. */
+    /** Flips or swaps the name order from the preset/current config. */
     flip(): void;
     /**
      * Splits the name parts of a birth name.
@@ -294,7 +292,7 @@ export declare class Namefully {
     split(separator?: string | RegExp): string[];
     /**
      * Joins the name parts of a birth name.
-     * @param separator token for the junction.
+     * @param {string} separator token for the junction.
      */
     join(separator?: string): string;
     /** Transforms a birth name into UPPERCASE. */

package/dist/esm/namefully.js

@@ -0,0 +1,379 @@
+import { ALLOWED_TOKENS } from './constants.js';
+import { InputError, NotAllowedError } from './error.js';
+import { isNameArray } from './name.js';
+import { Flat, NameOrder, NameType, Namon } from './types.js';
+import { capitalize, decapitalize, isStringArray, toggleCase } from './utils.js';
+import { ArrayNameParser, ArrayStringParser, NamaParser, Parser, StringParser } from './parser.js';
+export class Namefully {
+    #fullName;
+    constructor(names, options) {
+        this.#fullName = this.#toParser(names).parse(options);
+    }
+    static tryParse(text, index) {
+        try {
+            return new Namefully(Parser.build(text, index));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    static async parse(text, index) {
+        return Parser.buildAsync(text, index).then((parser) => new Namefully(parser));
+    }
+    get config() {
+        return this.#fullName.config;
+    }
+    get length() {
+        return this.birth.length;
+    }
+    get prefix() {
+        return this.#fullName.prefix?.toString();
+    }
+    get first() {
+        return this.firstName();
+    }
+    get middle() {
+        return this.hasMiddle ? this.middleName()[0] : undefined;
+    }
+    get hasMiddle() {
+        return this.#fullName.has(Namon.MIDDLE_NAME);
+    }
+    get last() {
+        return this.lastName();
+    }
+    get suffix() {
+        return this.#fullName.suffix?.toString();
+    }
+    get birth() {
+        return this.birthName();
+    }
+    get short() {
+        return this.shorten();
+    }
+    get long() {
+        return this.birth;
+    }
+    get full() {
+        return this.fullName();
+    }
+    get public() {
+        return this.format('f $l');
+    }
+    get salutation() {
+        return this.format('p l');
+    }
+    toString() {
+        return this.full;
+    }
+    get(namon) {
+        if (namon.equal(Namon.PREFIX))
+            return this.#fullName.prefix;
+        if (namon.equal(Namon.FIRST_NAME))
+            return this.#fullName.firstName;
+        if (namon.equal(Namon.MIDDLE_NAME))
+            return this.#fullName.middleName;
+        if (namon.equal(Namon.LAST_NAME))
+            return this.#fullName.lastName;
+        if (namon.equal(Namon.SUFFIX))
+            return this.#fullName.suffix;
+        return undefined;
+    }
+    equal(other) {
+        return this.toString() === other.toString();
+    }
+    toJson() {
+        return {
+            prefix: this.prefix,
+            firstName: this.first,
+            middleName: this.middleName(),
+            lastName: this.last,
+            suffix: this.suffix,
+        };
+    }
+    json = this.toJson;
+    has(namon) {
+        return this.#fullName.has(namon);
+    }
+    fullName(orderedBy) {
+        const sep = this.config.ending ? ',' : '';
+        const names = [];
+        if (this.prefix)
+            names.push(this.prefix);
+        if ((orderedBy ?? this.config.orderedBy) === NameOrder.FIRST_NAME) {
+            names.push(this.first, ...this.middleName(), this.last + sep);
+        }
+        else {
+            names.push(this.last, this.first, this.middleName().join(' ') + sep);
+        }
+        if (this.suffix)
+            names.push(this.suffix);
+        return names.join(' ').trim();
+    }
+    birthName(orderedBy) {
+        orderedBy ??= this.config.orderedBy;
+        return orderedBy === NameOrder.FIRST_NAME
+            ? [this.first, ...this.middleName(), this.last].join(' ')
+            : [this.last, this.first, ...this.middleName()].join(' ');
+    }
+    firstName(withMore = true) {
+        return this.#fullName.firstName.toString(withMore);
+    }
+    middleName() {
+        return this.#fullName.middleName.map((n) => n.value);
+    }
+    lastName(format) {
+        return this.#fullName.lastName.toString(format);
+    }
+    initials(options) {
+        const { orderedBy = this.config.orderedBy, only = NameType.BIRTH_NAME, asJson } = options ?? {};
+        const firstInits = this.#fullName.firstName.initials();
+        const midInits = this.#fullName.middleName.map((n) => n.value[0]);
+        const lastInits = this.#fullName.lastName.initials();
+        if (asJson)
+            return { firstName: firstInits, middleName: midInits, lastName: lastInits };
+        if (only !== NameType.BIRTH_NAME) {
+            return only === NameType.FIRST_NAME ? firstInits : only === NameType.MIDDLE_NAME ? midInits : lastInits;
+        }
+        else if (orderedBy === NameOrder.FIRST_NAME) {
+            return [...firstInits, ...midInits, ...lastInits];
+        }
+        else {
+            return [...lastInits, ...firstInits, ...midInits];
+        }
+    }
+    shorten(orderedBy) {
+        orderedBy ??= this.config.orderedBy;
+        const { firstName, lastName } = this.#fullName;
+        return orderedBy === NameOrder.FIRST_NAME
+            ? [firstName.value, lastName.toString()].join(' ')
+            : [lastName.toString(), firstName.value].join(' ');
+    }
+    flatten(options) {
+        const { by = Flat.MIDDLE_NAME, limit = 20, recursive = false, withMore = false, withPeriod = true, surname, } = options;
+        if (this.length <= limit)
+            return this.full;
+        const { firstName, lastName, middleName } = this.#fullName;
+        const sep = withPeriod ? '.' : '';
+        const hasMid = this.hasMiddle;
+        const fn = firstName.toString();
+        const mn = this.middleName().join(' ');
+        const ln = lastName.toString();
+        const f = firstName.initials(withMore).join(sep + ' ') + sep;
+        const l = lastName.initials(surname).join(sep + ' ') + sep;
+        const m = hasMid ? middleName.map((n) => n.value[0]).join(sep + ' ') + sep : '';
+        let name = [];
+        if (this.config.orderedBy === NameOrder.FIRST_NAME) {
+            switch (by) {
+                case Flat.FIRST_NAME:
+                    name = hasMid ? [f, mn, ln] : [f, ln];
+                    break;
+                case Flat.LAST_NAME:
+                    name = hasMid ? [fn, mn, l] : [fn, l];
+                    break;
+                case Flat.MIDDLE_NAME:
+                    name = hasMid ? [fn, m, ln] : [fn, ln];
+                    break;
+                case Flat.FIRST_MID:
+                    name = hasMid ? [f, m, ln] : [f, ln];
+                    break;
+                case Flat.MID_LAST:
+                    name = hasMid ? [fn, m, l] : [fn, l];
+                    break;
+                case Flat.ALL:
+                    name = hasMid ? [f, m, l] : [f, l];
+                    break;
+            }
+        }
+        else {
+            switch (by) {
+                case Flat.FIRST_NAME:
+                    name = hasMid ? [ln, f, mn] : [ln, f];
+                    break;
+                case Flat.LAST_NAME:
+                    name = hasMid ? [l, fn, mn] : [l, fn];
+                    break;
+                case Flat.MIDDLE_NAME:
+                    name = hasMid ? [ln, fn, m] : [ln, fn];
+                    break;
+                case Flat.FIRST_MID:
+                    name = hasMid ? [ln, f, m] : [ln, f];
+                    break;
+                case Flat.MID_LAST:
+                    name = hasMid ? [l, fn, m] : [l, fn];
+                    break;
+                case Flat.ALL:
+                    name = hasMid ? [l, f, m] : [l, f];
+                    break;
+            }
+        }
+        const flat = name.join(' ');
+        if (recursive && flat.length > limit) {
+            const next = by === Flat.FIRST_NAME
+                ? Flat.MIDDLE_NAME
+                : by === Flat.MIDDLE_NAME
+                    ? Flat.LAST_NAME
+                    : by === Flat.LAST_NAME
+                        ? Flat.FIRST_MID
+                        : by === Flat.FIRST_MID
+                            ? Flat.MID_LAST
+                            : by === Flat.MID_LAST
+                                ? Flat.ALL
+                                : by === Flat.ALL
+                                    ? Flat.ALL
+                                    : by;
+            if (next === by)
+                return flat;
+            return this.flatten({ ...options, by: next });
+        }
+        return flat;
+    }
+    zip(by = Flat.MID_LAST, withPeriod = true) {
+        return this.flatten({ limit: 0, by, withPeriod });
+    }
+    format(pattern) {
+        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 = [];
+        for (const char of pattern) {
+            if (ALLOWED_TOKENS.indexOf(char) === -1) {
+                throw new NotAllowedError({
+                    source: this.full,
+                    operation: 'format',
+                    message: `unsupported character <${char}> from ${pattern}.`,
+                });
+            }
+            group += char;
+            if (char === '$')
+                continue;
+            formatted.push(this.#map(group) ?? '');
+            group = '';
+        }
+        return formatted.join('').trim();
+    }
+    flip() {
+        const order = this.config.orderedBy === NameOrder.FIRST_NAME ? NameOrder.LAST_NAME : NameOrder.FIRST_NAME;
+        this.config.update({ orderedBy: order });
+    }
+    split(separator = /[' -]/g) {
+        return this.birth.replace(separator, ' ').split(' ');
+    }
+    join(separator = '') {
+        return this.split().join(separator);
+    }
+    toUpperCase() {
+        return this.birth.toUpperCase();
+    }
+    toLowerCase() {
+        return this.birth.toLowerCase();
+    }
+    toCamelCase() {
+        return decapitalize(this.toPascalCase());
+    }
+    toPascalCase() {
+        return this.split()
+            .map((n) => capitalize(n))
+            .join('');
+    }
+    toSnakeCase() {
+        return this.split()
+            .map((n) => n.toLowerCase())
+            .join('_');
+    }
+    toHyphenCase() {
+        return this.split()
+            .map((n) => n.toLowerCase())
+            .join('-');
+    }
+    toDotCase() {
+        return this.split()
+            .map((n) => n.toLowerCase())
+            .join('.');
+    }
+    toToggleCase() {
+        return toggleCase(this.birth);
+    }
+    #toParser(raw) {
+        if (raw instanceof Parser)
+            return raw;
+        if (typeof raw === 'string')
+            return new StringParser(raw);
+        if (isStringArray(raw))
+            return new ArrayStringParser(raw);
+        if (isNameArray(raw))
+            return new ArrayNameParser(raw);
+        if (typeof raw === 'object')
+            return new NamaParser(raw);
+        throw new InputError({ source: raw, message: 'Cannot parse raw data; review expected data types.' });
+    }
+    #map(char) {
+        switch (char) {
+            case '.':
+            case ',':
+            case ' ':
+            case '-':
+            case '_':
+                return char;
+            case 'b':
+                return this.birth;
+            case 'B':
+                return this.birth.toUpperCase();
+            case 'f':
+                return this.first;
+            case 'F':
+                return this.first.toUpperCase();
+            case 'l':
+                return this.last;
+            case 'L':
+                return this.last.toUpperCase();
+            case 'm':
+            case 'M':
+                return char === 'm' ? this.middleName().join(' ') : this.middleName().join(' ').toUpperCase();
+            case 'o':
+            case 'O':
+                return ((character) => {
+                    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 character === 'o' ? nama : nama.toUpperCase();
+                })(char);
+            case 'p':
+                return this.prefix;
+            case 'P':
+                return this.prefix?.toUpperCase();
+            case 's':
+                return this.suffix;
+            case 'S':
+                return this.suffix?.toUpperCase();
+            case '$f':
+            case '$F':
+                return this.#fullName.firstName.value[0];
+            case '$l':
+            case '$L':
+                return this.#fullName.lastName.value[0];
+            case '$m':
+            case '$M':
+                return this.hasMiddle ? this.middle[0] : undefined;
+            default:
+                return undefined;
+        }
+    }
+}
+export default (names, options) => {
+    return new Namefully(names, options);
+};

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/dist/{types → esm}/parser.d.ts

@@ -1,7 +1,7 @@
-import { FullName } from './full-name';
-import { Config } from './config';
-import { NameIndex } from './utils';
-import { Name, JsonName } from './name';
+import { Config } from './config.js';
+import { NameIndex } from './utils.js';
+import { FullName } from './fullname.js';
+import { Name, JsonName } from './name.js';
 /**
  * A parser signature that helps to organize the names accordingly.
  */