namefully 1.2.1 → 1.3.1

package/dist/types/namefully.d.ts

@@ -1,74 +1,76 @@
 import { Config } from './config';
 import { Name, JsonName } from './name';
+import { NameIndex } from './utils';
+import { Flat, NameOrder, NameType, Namon, Nullable, Surname, Separator, Title } from './types';
 import { Parser } from './parser';
-import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types';
 /**
- * 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://departments.weber.edu/qsupport&training/Data_Standards/Name.htm
- * for more info on name standards.
+ * @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 😊!
  */
 export declare class Namefully {
     #private;
     /**
-     * Creates a name with distinguishable parts from a raw string content.
+     * Creates a name with distinguishable parts.
      * @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 one (1) character
+     * to proceed. That is the only requirement/validation of namefully.
      */
-    constructor(names: string | string[] | Name[] | JsonName | Parser, options?: Partial<Config>);
+    constructor(names: string | string[] | Name[] | JsonName | Parser, options?: NameOptions);
     /**
      * 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): Namefully | undefined;
+    static tryParse(text: string, index?: NameIndex): Namefully | undefined;
     /**
      * Constructs a `Namefully` instance from a text.
      *
-     * It throws a `NameError` if the text cannot be parsed. Use `tryParse`
+     * @throws a `NameError` if the @param 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
@@ -80,119 +82,143 @@ export declare class Namefully {
      * Keep in mind that prefix and suffix are not considered during the parsing
      * process.
      */
-    static parse(text: string): Promise<Namefully>;
-    /** The current configuration. */
+    static parse(text: string, index?: NameIndex): Promise<Namefully>;
+    /** 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;
     /** The first name combined with the last name's initial. */
     get public(): string;
-    /** Returns the full name as set. */
+    /** The combination of prefix and last name. */
+    get salutation(): string;
+    /**
+     * Returns an iterable of the name components in their natural form.
+     *
+     * Regardless of the order of appearance, this method will always return the
+     * existing `Name`s according to the name standards upon which this library
+     * is based.
+     *
+     * This is useful for iterating over the name parts in a consistent manner and
+     * this automatically enables operations such as mapping, filtering, etc.
+     */
+    get parts(): Iterable<Name>;
+    /** The number of name components. */
+    get size(): number;
+    /**
+     * Makes the name set iterable (i.e., for-of statements).
+     *
+     * This is similar to `parts` with the exception that all name components are
+     * returned as `Name` classes (instead of their natural form - e.g., `FirstName`)
+     * to maintain certain homogeneity and consistency across each name piece.
+     */
+    [Symbol.iterator](): Iterator<Name>;
+    /** Gets a string representation of the full name. */
     toString(): string;
     /** Fetches the raw form of a name piece. */
-    get(namon: Namon): Nullable<Name | Name[]>;
+    get(key: Namon | string): Nullable<Name | Name[]>;
     /** Whether this name is equal to another one from a raw-string perspective. */
     equal(other: Namefully): boolean;
+    /** Whether this name is equal to another one from a component perspective. */
+    deepEqual(other: Namefully): boolean;
     /** Gets a JSON representation of the full name. */
     toJson(): JsonName;
-    /** Confirms that a name part has been set. */
-    has(namon: Namon): boolean;
+    json: () => JsonName;
+    /** Confirms whether a name component exists. */
+    has(namon: Namon | string): 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 a 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;
+    fullName(orderedBy?: NameOptions['orderedBy']): string;
     /**
      * 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?: NameOrder): string;
+    birthName(orderedBy?: NameOptions['orderedBy']): 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;
+    lastName(format?: NameOptions['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']`
      * - `John Ben Smith` => `['J', 'B', 'S']`.
      */
     initials(options?: {
-        orderedBy?: NameOrder;
-        only?: NameType;
-    }): string[];
+        orderedBy?: NameOptions['orderedBy'];
+        only?: NameType | 'firstName' | 'lastName' | 'middleName' | 'birthName';
+        asJson?: boolean;
+    }): string[] | Record<string, string[]>;
     /**
      * 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;
+    shorten(orderedBy?: NameOptions['orderedBy']): 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
@@ -226,17 +252,16 @@ export declare class Namefully {
         withPeriod: boolean;
         recursive: boolean;
         withMore: boolean;
-        surname: Surname;
+        surname: NameOptions['surname'];
     }>): 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
      * -------------
@@ -261,14 +286,6 @@ export declare class Namefully {
      * - 'P': capitalized prefix
      * - 's': suffix
      * - 'S': capitalized suffix
-     *
-     * 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.
@@ -282,7 +299,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.
@@ -291,7 +308,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. */
@@ -311,3 +328,20 @@ export declare class Namefully {
     /** Transforms a birth name into ToGgLeCaSe. */
     toToggleCase(): string;
 }
+/**
+ * A default export for the `namefully` utility.
+ * @param names element to parse.
+ * @param options additional settings.
+ */
+declare const _default: (names: string | string[] | Name[] | JsonName | Parser, options?: NameOptions) => Namefully;
+export default _default;
+/** Optional namefully parameters (@see {@linkcode Config} for more details). */
+export type NameOptions = Partial<{
+    name: string;
+    orderedBy: NameOrder | 'firstName' | 'lastName';
+    separator: Separator;
+    title: Title | 'UK' | 'US';
+    ending: boolean;
+    bypass: boolean;
+    surname: Surname | 'father' | 'mother' | 'hyphenated' | 'all';
+}>;

package/dist/types/parser.d.ts

@@ -1,10 +1,11 @@
-import { FullName } from './full-name';
 import { Config } from './config';
+import { NameIndex } from './utils';
+import { FullName } from './full-name';
 import { Name, JsonName } from './name';
 /**
  * A parser signature that helps to organize the names accordingly.
  */
-export declare abstract class Parser<T = any> {
+export declare abstract class Parser<T = unknown> {
     raw: T;
     /**
      * Constructs a custom parser accordingly.
@@ -12,19 +13,17 @@ export declare abstract class Parser<T = any> {
      */
     constructor(raw: T);
     /**
-     * Builds a dynamic `Parser` on the fly and throws a `NameError` when unable
-     * to do so. The built parser only knows how to operate birth names.
-     */
-    static build(text: string): Parser;
-    /**
-     * Builds asynchronously a dynamic `Parser`.
+     * Parses raw data into a `FullName` while applying some options.
+     * @param options for additional configuration to apply.
      */
-    static buildAsync(text: string): Promise<Parser>;
+    abstract parse(options?: Partial<Config>): FullName;
     /**
-     * Parses the raw data into a `FullName` while considering some options.
-     * @param options additional configuration to apply.
+     * Builds a dynamic `Parser` on the fly and throws a `NameError` when unable
+     * to do so. The built parser only knows how to operate birth names.
      */
-    abstract parse(options?: Partial<Config>): FullName;
+    static build(text: string, index?: NameIndex): Parser;
+    /** Builds asynchronously a dynamic `Parser`. */
+    static buildAsync(text: string, index?: NameIndex): Promise<Parser>;
 }
 export declare class StringParser extends Parser<string> {
     parse(options: Partial<Config>): FullName;
@@ -33,7 +32,6 @@ export declare class ArrayStringParser extends Parser<string[]> {
     parse(options: Partial<Config>): FullName;
 }
 export declare class NamaParser extends Parser<JsonName> {
-    #private;
     parse(options: Partial<Config>): FullName;
 }
 export declare class ArrayNameParser extends Parser<Name[]> {

package/dist/types/types.d.ts

@@ -1,6 +1,4 @@
-/**
- * Make a type nullable.
- */
+/** Make a type nullable. */
 export type Nullable<T> = T | null | undefined;
 /**
  * The abbreviation type to indicate whether or not to add period to a prefix
@@ -23,25 +21,19 @@ export declare enum Surname {
     HYPHENATED = "hyphenated",
     ALL = "all"
 }
-/**
- * The order of appearance of a `FullName`.
- */
+/** The order of appearance of a `FullName`. */
 export declare enum NameOrder {
     FIRST_NAME = "firstName",
     LAST_NAME = "lastName"
 }
-/**
- * The types of name handled in this according the name standards.
- */
+/** The types of name handled in this according the name standards. */
 export declare enum NameType {
     FIRST_NAME = "firstName",
     MIDDLE_NAME = "middleName",
     LAST_NAME = "lastName",
     BIRTH_NAME = "birthName"
 }
-/**
- * The possible variants to indicate how to flatten a `FullName`.
- */
+/** The possible variants to indicate how to flatten a `FullName`. */
 export declare enum Flat {
     FIRST_NAME = "firstName",
     MIDDLE_NAME = "middleName",
@@ -50,17 +42,13 @@ export declare enum Flat {
     MID_LAST = "midLast",
     ALL = "all"
 }
-/**
- * The range to use when capitalizing a string content.
- */
+/** The range to use when capitalizing a string content. */
 export declare enum CapsRange {
     NONE = 0,
     INITIAL = 1,
     ALL = 2
 }
-/**
- * The types of name handled in this utility according the name standards.
- */
+/** The types of name handled in this utility according the name standards. */
 export declare class Namon {
     readonly index: number;
     readonly key: string;
@@ -69,35 +57,22 @@ export declare class Namon {
     static readonly MIDDLE_NAME: Namon;
     static readonly LAST_NAME: Namon;
     static readonly SUFFIX: Namon;
-    /**
-     * The list of supported name types.
-     */
+    /** The list of supported name types. */
     static readonly values: Namon[];
-    /**
-     * All the predefined name types.
-     */
+    /** All the predefined name types. */
     static readonly all: Map<string, Namon>;
+    private static readonly aliases;
     private constructor();
-    /**
-     * Whether this string key is part of the predefined keys.
-     */
+    /** Whether this string key is part of the predefined keys. */
     static has(key: string): boolean;
-    /**
-     * Makes a string key a namon type.
-     */
+    /** Makes a string key a namon type. */
     static cast(key: string): Nullable<Namon>;
-    /**
-     * String representation of this object.
-     */
+    /** String representation of this object. */
     toString(): string;
-    /**
-     * Whether this and the other value are equal.
-     */
+    /** Whether this and the other value are equal. */
     equal(other: Namon | unknown): boolean;
 }
-/**
- * The token used to indicate how to split string values.
- */
+/** The token used to indicate how to split string values. */
 export declare class Separator {
     readonly name: string;
     readonly token: string;
@@ -111,17 +86,13 @@ export declare class Separator {
     static readonly SINGLE_QUOTE: Separator;
     static readonly SPACE: Separator;
     static readonly UNDERSCORE: Separator;
-    /**
-     * All the available separators.
-     */
+    /** All the available separators. */
     static readonly all: Map<string, Separator>;
-    /**
-     * All the available tokens.
-     */
+    /** All the available tokens. */
     static readonly tokens: string[];
     private constructor();
-    /**
-     * String representation of this object.
-     */
+    /** Makes a string key a separator type. */
+    static cast(key: string): Nullable<Separator>;
+    /** String representation of this object. */
     toString(): string;
 }

package/dist/types/utils.d.ts

@@ -1,6 +1,6 @@
 import { NameOrder, CapsRange } from './types';
 /**
- * A fixed set of values to handle specific positions for list of names.
+ * A set of values to handle specific positions for list of names.
  *
  * As for list of names, this helps to follow a specific order based on the
  * count of elements. It is expected that the list has to be between two and
@@ -32,7 +32,7 @@ export declare class NameIndex {
     static get min(): number;
     /** The maximum number of parts in a list of names. */
     static get max(): number;
-    private constructor();
+    protected constructor(prefix: number, firstName: number, middleName: number, lastName: number, suffix: number);
     /** The default or base indexing: firstName lastName. */
     static base(): NameIndex;
     /**
@@ -40,14 +40,14 @@ export declare class NameIndex {
      * and their `order` of appearance.
      */
     static when(order: NameOrder, count?: number): NameIndex;
+    static only({ prefix, firstName, middleName, lastName, suffix }: Record<string, number>): NameIndex;
+    toJson(): Record<string, number>;
+    json: () => Record<string, number>;
 }
-/**
- * Capitalizes a string via a `CapsRange` option.
- */
+/** Capitalizes a string via a `CapsRange` option. */
 export declare function capitalize(str: string, range?: CapsRange): string;
 /** Decapitalizes a string via a `CapsRange` option. */
 export declare function decapitalize(str: string, range?: CapsRange): string;
 /** Toggles a string representation. */
 export declare function toggleCase(str: string): string;
-export declare function isStringArray(value?: unknown): boolean;
-export declare function isNameArray(value?: unknown): boolean;
+export declare function isStringArray(value?: unknown): value is string[];

package/dist/types/validator.d.ts

@@ -1,6 +1,6 @@
-import { FirstName, LastName, Name } from './name';
 import { Namon } from './types';
 import { NameIndex } from './utils';
+import { FirstName, LastName, Name } from './name';
 export interface Validator<T> {
     validate(value: T): void;
 }