namefully 2.0.2 → 2.2.0

package/dist/esm/namefully.d.ts

@@ -1,7 +1,8 @@
 import { Config } from './config.js';
+import { SerializedName } from './data.js';
 import { Name, JsonName } from './name.js';
-import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types.js';
 import { NameIndex } from './utils.js';
+import { Flat, NameOrder, NameType, Namon, Nullable, Surname, Separator, Title } from './types.js';
 import { Parser } from './parser.js';
 /**
  * A utility for organizing human names in a particular order, way, or shape.
@@ -31,8 +32,8 @@ import { Parser } from './parser.js';
  * this: `John Smith`, where `John` is the first name piece and `Smith`, the last
  * name piece.
  *
- * @see {@link 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 configurable parameters, which will be seen later.
@@ -59,7 +60,7 @@ export declare class Namefully {
      * 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.
      *
@@ -85,6 +86,8 @@ export declare class Namefully {
     static parse(text: string, index?: NameIndex): Promise<Namefully>;
     /** The configuration dictating this name's behavior. */
     get config(): Config;
+    /** Whether the name is a single word name. */
+    get isMono(): boolean;
     /** The number of characters of the `birthName`, including spaces. */
     get length(): number;
     /** The prefix part of the name set. */
@@ -111,17 +114,40 @@ 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;
     json: () => JsonName;
-    /** Confirms that a name part has been set. */
-    has(namon: Namon): boolean;
+    /** Confirms whether a name component exists. */
+    has(namon: Namon | string): boolean;
     /**
      * Gets the full name ordered as configured.
      *
@@ -129,21 +155,21 @@ export declare class Namefully {
      * name, overriding the preset configuration.
      *
      * `Namefully.format()` may also be used to alter manually the order of appearance
-     * of full name. For example:
+     * 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 {boolean} withMore determines whether to include other pieces of the
@@ -157,7 +183,7 @@ export declare class Namefully {
      * @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`.
      *
@@ -172,8 +198,8 @@ export declare class Namefully {
      * - `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[]>;
     /**
@@ -193,7 +219,7 @@ export declare class Namefully {
      * 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;
+    shorten(orderedBy?: NameOptions['orderedBy']): string;
     /**
      * Flattens long names using the name types as variants.
      *
@@ -225,11 +251,11 @@ export declare class Namefully {
      */
     flatten(options: Partial<{
         limit: number;
-        by: Flat;
+        by: Flat | 'firstName' | 'lastName' | 'middleName' | 'birthName' | 'firstMid' | 'midLast' | 'all' | '*';
         withPeriod: boolean;
         recursive: boolean;
         withMore: boolean;
-        surname: Surname;
+        surname: NameOptions['surname'];
     }>): string;
     /**
      * Zips or compacts a name using different forms of variants.
@@ -263,14 +289,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.
@@ -312,11 +330,31 @@ export declare class Namefully {
     toDotCase(): string;
     /** Transforms a birth name into ToGgLeCaSe. */
     toToggleCase(): string;
+    /**
+     * Serializes this Namefully instance to a JSON object.
+     *
+     * This includes both the name data (with full hierarchy for FirstName and LastName)
+     * and the configuration, allowing for complete reconstruction of the Namefully instance.
+     *
+     * @returns a JSON-serializable object containing name data and config.
+     */
+    serialize(): SerializedName;
 }
 /**
  * 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?: 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';
+    mono: boolean | Namon;
+}>;

package/dist/esm/namefully.js

@@ -1,8 +1,8 @@
 import { ALLOWED_FORMAT_TOKENS } from './constants.js';
-import { InputError, NotAllowedError } from './error.js';
 import { isNameArray } from './name.js';
-import { Flat, NameOrder, NameType, Namon } from './types.js';
+import { InputError, NotAllowedError } from './error.js';
 import { capitalize, decapitalize, isStringArray, toggleCase } from './utils.js';
+import { Flat, NameOrder, NameType, Namon } from './types.js';
 import { ArrayNameParser, ArrayStringParser, NamaParser, Parser, StringParser } from './parser.js';
 export class Namefully {
     #fullName;
@@ -23,7 +23,12 @@ export class Namefully {
     get config() {
         return this.#fullName.config;
     }
+    get isMono() {
+        return this.#fullName.isMono;
+    }
     get length() {
+        if (this.isMono)
+            return this.#fullName.toString().length;
         return this.birth.length;
     }
     get prefix() {
@@ -62,25 +67,43 @@ export class Namefully {
     get salutation() {
         return this.format('p l');
     }
+    get parts() {
+        return this.#fullName.toIterable();
+    }
+    get size() {
+        return Array.from(this.parts).length;
+    }
+    *[Symbol.iterator]() {
+        yield* this.#fullName.toIterable(true);
+    }
     toString() {
         return this.full;
     }
-    get(namon) {
-        if (namon.equal(Namon.PREFIX))
+    get(key) {
+        const namon = typeof key === 'string' ? Namon.cast(key) : key;
+        if (namon?.equal(Namon.PREFIX))
             return this.#fullName.prefix;
-        if (namon.equal(Namon.FIRST_NAME))
+        if (namon?.equal(Namon.FIRST_NAME))
             return this.#fullName.firstName;
-        if (namon.equal(Namon.MIDDLE_NAME))
+        if (namon?.equal(Namon.MIDDLE_NAME))
             return this.#fullName.middleName;
-        if (namon.equal(Namon.LAST_NAME))
+        if (namon?.equal(Namon.LAST_NAME))
             return this.#fullName.lastName;
-        if (namon.equal(Namon.SUFFIX))
+        if (namon?.equal(Namon.SUFFIX))
             return this.#fullName.suffix;
         return undefined;
     }
     equal(other) {
         return this.toString() === other.toString();
     }
+    deepEqual(other) {
+        const others = Array.from(other.parts);
+        for (const part of this.parts) {
+            if (!others.some((name) => name.equal(part)))
+                return false;
+        }
+        return true;
+    }
     toJson() {
         return {
             prefix: this.prefix,
@@ -95,6 +118,8 @@ export class Namefully {
         return this.#fullName.has(namon);
     }
     fullName(orderedBy) {
+        if (this.isMono)
+            return this.#fullName.toString();
         const sep = this.config.ending ? ',' : '';
         const names = [];
         if (this.prefix)
@@ -103,13 +128,21 @@ export class Namefully {
             names.push(this.first, ...this.middleName(), this.last + sep);
         }
         else {
-            names.push(this.last, this.first, this.middleName().join(' ') + sep);
+            names.push(this.last);
+            if (this.hasMiddle) {
+                names.push(this.first, this.middleName().join(' ') + sep);
+            }
+            else {
+                names.push(this.first + sep);
+            }
         }
         if (this.suffix)
             names.push(this.suffix);
         return names.join(' ').trim();
     }
     birthName(orderedBy) {
+        if (this.isMono)
+            return this.#fullName.toString();
         orderedBy ??= this.config.orderedBy;
         return orderedBy === NameOrder.FIRST_NAME
             ? [this.first, ...this.middleName(), this.last].join(' ')
@@ -125,6 +158,8 @@ export class Namefully {
         return this.#fullName.lastName.toString(format);
     }
     initials(options) {
+        if (this.isMono)
+            return [this.#fullName.toString()[0]];
         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]);
@@ -142,6 +177,8 @@ export class Namefully {
         }
     }
     shorten(orderedBy) {
+        if (this.isMono)
+            return this.#fullName.toString();
         orderedBy ??= this.config.orderedBy;
         const { firstName, lastName } = this.#fullName;
         return orderedBy === NameOrder.FIRST_NAME
@@ -152,6 +189,8 @@ export class Namefully {
         const { by = Flat.MIDDLE_NAME, limit = 20, recursive = false, withMore = false, withPeriod = true, surname, } = options;
         if (this.length <= limit)
             return this.full;
+        if (this.isMono)
+            return `${this.initials()}${withPeriod ? '.' : ''}`;
         const { firstName, lastName, middleName } = this.#fullName;
         const sep = withPeriod ? '.' : '';
         const hasMid = this.hasMiddle;
@@ -179,7 +218,7 @@ export class Namefully {
                 case Flat.MID_LAST:
                     name = hasMid ? [fn, m, l] : [fn, l];
                     break;
-                case Flat.ALL:
+                default:
                     name = hasMid ? [f, m, l] : [f, l];
                     break;
             }
@@ -201,7 +240,7 @@ export class Namefully {
                 case Flat.MID_LAST:
                     name = hasMid ? [l, fn, m] : [l, fn];
                     break;
-                case Flat.ALL:
+                default:
                     name = hasMid ? [l, f, m] : [l, f];
                     break;
             }
@@ -242,7 +281,7 @@ export class Namefully {
         let group = '';
         const formatted = [];
         for (const char of pattern) {
-            if (ALLOWED_FORMAT_TOKENS.indexOf(char) === -1) {
+            if (!ALLOWED_FORMAT_TOKENS.includes(char)) {
                 throw new NotAllowedError({
                     source: this.full,
                     operation: 'format',
@@ -299,6 +338,28 @@ export class Namefully {
     toToggleCase() {
         return toggleCase(this.birth);
     }
+    serialize() {
+        const { config, firstName: fn, lastName: ln } = this.#fullName;
+        return {
+            names: {
+                prefix: this.prefix,
+                firstName: fn.hasMore ? { value: fn.value, more: fn.more } : fn.value,
+                middleName: this.hasMiddle ? this.middleName() : undefined,
+                lastName: ln.hasMother ? { father: ln.father, mother: ln.mother } : ln.value,
+                suffix: this.suffix,
+            },
+            config: {
+                name: config.name,
+                orderedBy: config.orderedBy,
+                separator: config.separator.token,
+                title: config.title,
+                ending: config.ending,
+                bypass: config.bypass,
+                surname: config.surname,
+                mono: config.mono instanceof Namon ? config.mono.key : config.mono,
+            },
+        };
+    }
     #toParser(raw) {
         if (raw instanceof Parser)
             return raw;
@@ -314,12 +375,6 @@ export class Namefully {
     }
     #map(char) {
         switch (char) {
-            case '.':
-            case ',':
-            case ' ':
-            case '-':
-            case '_':
-                return char;
             case 'b':
                 return this.birth;
             case 'B':
@@ -361,16 +416,19 @@ export class Namefully {
             case 'S':
                 return this.suffix?.toUpperCase();
             case '$f':
-            case '$F':
                 return this.#fullName.firstName.value[0];
+            case '$F':
+                return this.#fullName.firstName.initials(true).join('');
             case '$l':
-            case '$L':
                 return this.#fullName.lastName.value[0];
+            case '$L':
+                return this.#fullName.lastName.initials().join('');
             case '$m':
-            case '$M':
                 return this.hasMiddle ? this.middle[0] : undefined;
+            case '$M':
+                return this.hasMiddle ? this.#fullName.middleName.map((n) => n.value[0]).join('') : undefined;
             default:
-                return undefined;
+                return ALLOWED_FORMAT_TOKENS.includes(char) ? char : undefined;
         }
     }
 }

package/dist/esm/parser.d.ts

@@ -1,6 +1,6 @@
 import { Config } from './config.js';
 import { NameIndex } from './utils.js';
-import { FullName } from './fullname.js';
+import { FullName, Mononym } from './fullname.js';
 import { Name, JsonName } from './name.js';
 /**
  * A parser signature that helps to organize the names accordingly.
@@ -12,6 +12,11 @@ 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.
@@ -19,11 +24,6 @@ export declare abstract class Parser<T = unknown> {
     static build(text: string, index?: NameIndex): 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 for additional configuration to apply.
-     */
-    abstract parse(options?: Partial<Config>): FullName;
 }
 export declare class StringParser extends Parser<string> {
     parse(options: Partial<Config>): FullName;
@@ -37,3 +37,6 @@ export declare class NamaParser extends Parser<JsonName> {
 export declare class ArrayNameParser extends Parser<Name[]> {
     parse(options: Partial<Config>): FullName;
 }
+export declare class MonoParser extends Parser<string | Name> {
+    parse(options: Partial<Config>): Mononym;
+}

package/dist/esm/parser.js

@@ -1,10 +1,10 @@
 import { Config } from './config.js';
 import { NameIndex } from './utils.js';
 import { InputError } from './error.js';
-import { FullName } from './fullname.js';
+import { FullName, Mononym } from './fullname.js';
 import { Namon, Separator } from './types.js';
 import { FirstName, LastName, Name } from './name.js';
-import { ArrayStringValidator, ArrayNameValidator, NamaValidator } from './validator.js';
+import { ArrayStringValidator, ArrayNameValidator, Validators } from './validator.js';
 export class Parser {
     raw;
     constructor(raw) {
@@ -20,10 +20,7 @@ export class Parser {
             return new ArrayNameParser(names);
         }
         if (length < 2) {
-            throw new InputError({
-                source: text,
-                message: 'cannot build from invalid input',
-            });
+            throw new InputError({ source: text, message: 'expecting at least 2 name parts' });
         }
         else if (length === 2 || length === 3) {
             return new StringParser(text);
@@ -47,13 +44,15 @@ export class StringParser extends Parser {
     parse(options) {
         const config = Config.merge(options);
         const names = this.raw.split(config.separator.token);
-        return new ArrayStringParser(names).parse(options);
+        return new ArrayStringParser(names).parse(config);
     }
 }
 export class ArrayStringParser extends Parser {
     parse(options) {
         const config = Config.merge(options);
-        const fullName = new FullName(config);
+        if (this.raw.length === 1 && config.mono) {
+            return new MonoParser(this.raw[0]).parse(config);
+        }
         const raw = this.raw.map((n) => n.trim());
         const index = NameIndex.when(config.orderedBy, raw.length);
         const validator = new ArrayStringValidator(index);
@@ -64,8 +63,9 @@ export class ArrayStringParser extends Parser {
             validator.validate(raw);
         }
         const { firstName, lastName, middleName, prefix, suffix } = index;
-        fullName.setFirstName(new FirstName(raw[firstName]));
-        fullName.setLastName(new LastName(raw[lastName]));
+        const fullName = new FullName(config)
+            .setFirstName(new FirstName(raw[firstName]))
+            .setLastName(new LastName(raw[lastName]));
         if (raw.length >= 3)
             fullName.setMiddleName(raw[middleName].split(config.separator.token));
         if (raw.length >= 4)
@@ -89,10 +89,10 @@ export class NamaParser extends Parser {
             return [namon, value];
         }));
         if (config.bypass) {
-            NamaValidator.create().validateKeys(names);
+            Validators.nama.validateKeys(names);
         }
         else {
-            NamaValidator.create().validate(names);
+            Validators.nama.validate(names);
         }
         return FullName.parse(this.raw, config);
     }
@@ -100,8 +100,13 @@ export class NamaParser extends Parser {
 export class ArrayNameParser extends Parser {
     parse(options) {
         const config = Config.merge(options);
+        if (this.raw.length === 1 && config.mono) {
+            return new MonoParser(this.raw[0]).parse(options);
+        }
+        else {
+            ArrayNameValidator.create().validate(this.raw);
+        }
         const fullName = new FullName(config);
-        ArrayNameValidator.create().validate(this.raw);
         for (const name of this.raw) {
             if (name.isPrefix) {
                 fullName.setPrefix(name);
@@ -116,10 +121,20 @@ export class ArrayNameParser extends Parser {
                 fullName.middleName.push(name);
             }
             else if (name.isLastName) {
-                const lastName = new LastName(name.value, name instanceof LastName ? name.mother : undefined, config.surname);
-                fullName.setLastName(lastName);
+                const mother = name instanceof LastName ? name.mother : undefined;
+                fullName.setLastName(new LastName(name.value, mother, config.surname));
             }
         }
         return fullName;
     }
 }
+export class MonoParser extends Parser {
+    parse(options) {
+        const config = Config.merge(options);
+        if (config.bypass)
+            Validators.namon.validate(this.raw);
+        const type = config.mono instanceof Namon ? config.mono : Namon.FIRST_NAME;
+        const name = this.raw instanceof Name ? this.raw : new Name(this.raw.trim(), type);
+        return new Mononym(name, config);
+    }
+}

package/dist/esm/types.d.ts

@@ -61,6 +61,7 @@ export declare class Namon {
     static readonly values: Namon[];
     /** 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. */
     static has(key: string): boolean;
@@ -90,6 +91,8 @@ export declare class Separator {
     /** All the available tokens. */
     static readonly tokens: string[];
     private constructor();
+    /** Makes a string key a separator type. */
+    static cast(key: string): Nullable<Separator>;
     /** String representation of this object. */
     toString(): string;
 }

package/dist/esm/types.js

@@ -53,6 +53,13 @@ export class Namon {
         [Namon.LAST_NAME.key, Namon.LAST_NAME],
         [Namon.SUFFIX.key, Namon.SUFFIX],
     ]);
+    static aliases = {
+        [Namon.PREFIX.key]: ['prefix', 'px', 'p'],
+        [Namon.FIRST_NAME.key]: ['firstname', 'first', 'fn', 'f'],
+        [Namon.MIDDLE_NAME.key]: ['middlename', 'middle', 'mid', 'mn', 'm'],
+        [Namon.LAST_NAME.key]: ['lastname', 'last', 'ln', 'l'],
+        [Namon.SUFFIX.key]: ['suffix', 'sx', 's'],
+    };
     constructor(index, key) {
         this.index = index;
         this.key = key;
@@ -61,7 +68,9 @@ export class Namon {
         return Namon.all.has(key);
     }
     static cast(key) {
-        return Namon.has(key) ? Namon.all.get(key) : undefined;
+        const searchValue = String(key).toLowerCase();
+        const namon = Object.entries(Namon.aliases).find(([, list]) => list.includes(searchValue))?.[0];
+        return Namon.has(namon ?? '') ? Namon.all.get(key) : undefined;
     }
     toString() {
         return `Namon.${this.key}`;
@@ -100,6 +109,14 @@ export class Separator {
         this.name = name;
         this.token = token;
     }
+    static cast(key) {
+        for (const [name, separator] of Separator.all) {
+            if (separator.token === key || name.toLowerCase() === key.toLowerCase()) {
+                return separator;
+            }
+        }
+        return undefined;
+    }
     toString() {
         return `Separator.${this.name}`;
     }