namefully 1.3.0 → 1.3.1

package/dist/types/full-name.d.ts

@@ -1,18 +1,18 @@
 import { Config } from './config';
-import { FirstName, LastName, Name, JsonName } from './name';
 import { Nullable, Namon } from './types';
+import { FirstName, LastName, Name, JsonName } from './name';
 /**
  * The core component of this utility.
  *
- * This component is comprised of five entities that make it easy to handle a
+ * This component is composed of five entities that make it easy to handle a
  * full name set: prefix, first name, middle name, last name, and suffix.
- * This class is intended for internal processes. However, it is understandable
+ * It is indeed intended for internal processes. However, it is understandable
  * that it might be needed at some point for additional purposes. For this reason,
  * it's made available.
  *
  * It is recommended to avoid using this class unless it is highly necessary or
- * a custom parser is used for uncommon use cases. This utility tries to cover
- * as many use cases as possible.
+ * a custom parser is used for uncommon use cases although this utility tries to
+ * cover as many use cases as possible.
  *
  * Additionally, an optional configuration can be used to indicate some specific
  * behaviors related to that name handling.
@@ -21,7 +21,7 @@ export declare class FullName {
     #private;
     /**
      * Creates a full name as it goes
-     * @param options optional configuration for additional features.
+     * @param options settings for additional features.
      */
     constructor(options?: Partial<Config>);
     /** A snapshot of the configuration used to set up this full name. */
@@ -37,9 +37,9 @@ export declare class FullName {
     /** The suffix part of the full name. */
     get suffix(): Nullable<Name>;
     /**
-     * Parses a json name into a full name.
-     * @param json parsable name element
-     * @param config optional configuration for additional features.
+     * Parses a JSON name into a full name.
+     * @param {JsonName} json parsable name element
+     * @param {Config} config for additional features.
      */
     static parse(json: JsonName, config?: Config): FullName;
     setPrefix(name: Nullable<string | Name>): FullName;
@@ -47,8 +47,11 @@ export declare class FullName {
     setLastName(name: string | LastName): FullName;
     setMiddleName(names: string[] | Name[]): FullName;
     setSuffix(name: Nullable<string | Name>): FullName;
-    /**
-     * Returns true if a namon has been set.
-     */
-    has(namon: Namon): boolean;
+    /** Returns true if a namon has been set. */
+    has(key: Namon | string): boolean;
+    toString(): string;
+    /** Returns an `Iterable` of existing `Name`s. */
+    toIterable(flat?: boolean): Iterable<Name>;
+    /** Returns the default iterator for this name set (enabling for-of statements). */
+    [Symbol.iterator](): Iterator<Name>;
 }

package/dist/types/name.d.ts

@@ -1,7 +1,5 @@
 import { CapsRange, Namon, Surname } from './types';
-/**
- * Representation of a string type name with some extra capabilities.
- */
+/** Representation of a string type name with some extra capabilities. */
 export declare class Name {
     #private;
     readonly type: Namon;
@@ -9,9 +7,9 @@ export declare class Name {
     protected capsRange: CapsRange;
     /**
      * Creates augmented names by adding extra functionality to a string name.
-     * @param type must be indicated to categorize the name so it can be
+     * @param {Namon} type must be indicated to categorize the name so it can be
      * treated accordingly.
-     * @param capsRange determines how the name should be capitalized initially.
+     * @param {CapsRange} capsRange determines how the name should be capitalized initially.
      */
     constructor(value: string, type: Namon, capsRange?: CapsRange);
     set value(newValue: string);
@@ -51,16 +49,14 @@ export declare class Name {
     decaps(range?: CapsRange): Name;
     protected validate(name?: string): void;
 }
-/**
- * Representation of a first name with some extra functionality.
- */
+/** Representation of a first name with some extra functionality. */
 export declare class FirstName extends Name {
     #private;
     /**
      * Creates an extended version of `Name` and flags it as a first name `type`.
      *
      * Some may consider `more` additional name parts of a given name as their
-     * first names, but not as their middle names. Though, it may mean the same,
+     * first names, but not as their middle names. Though it may mean the same,
      * `more` provides the freedom to do it as it pleases.
      */
     constructor(value: string, ...more: string[]);
@@ -81,30 +77,28 @@ export declare class FirstName extends Name {
         more?: string[];
     }): FirstName;
 }
-/**
- * Representation of a last name with some extra functionality.
- */
+/** Representation of a last name with some extra functionality. */
 export declare class LastName extends Name {
     #private;
-    readonly format: Surname;
+    readonly format: Surname | 'father' | 'mother' | 'hyphenated' | 'all';
     /**
      * Creates an extended version of `Name` and flags it as a last name `type`.
      *
-     * Some people may keep their `mother`'s surname and want to keep a clear cut
-     * from their `father`'s surname. However, there are no clear rules about it.
+     * Some people may keep their @param mother's surname and want to keep a clear cut
+     * from their @param father's surname. However, there are no clear rules about it.
      */
-    constructor(father: string, mother?: string, format?: Surname);
-    /** The surname inherited from a father side. */
+    constructor(father: string, mother?: string, format?: Surname | 'father' | 'mother' | 'hyphenated' | 'all');
+    /** The surname inherited from the father side. */
     get father(): string;
-    /** The surname inherited from a mother side. */
+    /** The surname inherited from the mother side. */
     get mother(): string | undefined;
     /** Returns `true` if the mother's surname is defined. */
     get hasMother(): boolean;
     get length(): number;
     /** Returns a combined version of the `father` and `mother` if any. */
     get asNames(): Name[];
-    toString(format?: Surname): string;
-    initials(format?: Surname): string[];
+    toString(format?: Surname | 'father' | 'mother' | 'hyphenated' | 'all'): string;
+    initials(format?: Surname | 'father' | 'mother' | 'hyphenated' | 'all'): string[];
     caps(range?: CapsRange): LastName;
     decaps(range?: CapsRange): LastName;
     /** Makes a copy of the current name. */
@@ -114,13 +108,18 @@ export declare class LastName extends Name {
         format?: Surname;
     }): LastName;
 }
-/**
- * JSON signature for `FullName` data.
- */
+export declare function isNameArray(value?: unknown): value is Name[];
+/** JSON signature for `FullName` data. */
 export interface JsonName {
     prefix?: string;
-    firstName: string;
-    middleName?: string[];
-    lastName: string;
+    firstName: string | {
+        value: string;
+        more?: string[];
+    };
+    middleName?: string | string[];
+    lastName: string | {
+        father: string;
+        mother?: string;
+    };
     suffix?: string;
 }

package/dist/types/namefully.d.ts

@@ -1,74 +1,76 @@
 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 { Flat, NameOrder, NameType, Namon, Nullable, Surname, Separator, Title } from './types';
+import { Parser } from './parser';
 /**
- * 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
- * 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, 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
@@ -81,27 +83,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;
@@ -109,93 +111,114 @@ export declare class Namefully {
     get public(): string;
     /** The combination of prefix and last name. */
     get salutation(): string;
-    /** Returns the full name as set. */
+    /**
+     * 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;
+        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
@@ -229,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
      * -------------
@@ -264,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.
@@ -285,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.
@@ -294,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. */
@@ -319,5 +333,15 @@ export declare class Namefully {
  * @param names element to parse.
  * @param options additional settings.
  */
-declare const _default: (names: string | string[] | Name[] | JsonName | Parser, options?: Partial<Config>) => Namefully;
+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,6 +1,6 @@
-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.
@@ -12,20 +12,18 @@ export declare abstract class Parser<T = unknown> {
      * @param raw data to be parsed
      */
     constructor(raw: T);
+    /**
+     * Parses raw data into a `FullName` while applying some options.
+     * @param options for additional configuration to apply.
+     */
+    abstract parse(options?: Partial<Config>): FullName;
     /**
      * 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, index?: NameIndex): Parser;
-    /**
-     * Builds asynchronously a dynamic `Parser`.
-     */
+    /** Builds asynchronously a dynamic `Parser`. */
     static buildAsync(text: string, index?: NameIndex): Promise<Parser>;
-    /**
-     * Parses the raw data into a `FullName` while considering some options.
-     * @param options additional configuration to apply.
-     */
-    abstract parse(options?: Partial<Config>): FullName;
 }
 export declare class StringParser extends Parser<string> {
     parse(options: Partial<Config>): FullName;
@@ -34,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[]> {