namefully 2.1.0 → 2.2.0

package/dist/esm/fullname.js

@@ -1,5 +1,6 @@
 import { Config } from './config.js';
 import { Validators } from './validator.js';
+import { ZERO_WIDTH_SPACE } from './constants.js';
 import { Namon, Title } from './types.js';
 import { NameError, UnknownError } from './error.js';
 import { FirstName, LastName, Name } from './name.js';
@@ -31,14 +32,18 @@ export class FullName {
     get suffix() {
         return this.#suffix;
     }
+    get isMono() {
+        return this instanceof Mononym;
+    }
     static parse(json, config) {
         try {
+            const { prefix, firstName: fn, middleName: mn, lastName: ln, suffix } = json;
             return new FullName(config)
-                .setPrefix(json.prefix)
-                .setFirstName(json.firstName)
-                .setMiddleName(json.middleName ?? [])
-                .setLastName(json.lastName)
-                .setSuffix(json.suffix);
+                .setPrefix(prefix)
+                .setFirstName(typeof fn === 'string' ? fn : new FirstName(fn.value, ...(fn.more ?? [])))
+                .setMiddleName(typeof mn === 'string' ? [mn] : (mn ?? []))
+                .setLastName(typeof ln === 'string' ? ln : new LastName(ln.father, ln.mother))
+                .setSuffix(suffix);
         }
         catch (error) {
             if (error instanceof NameError)
@@ -56,7 +61,7 @@ export class FullName {
         if (!this.#config.bypass)
             Validators.prefix.validate(name);
         const prefix = name instanceof Name ? name.value : name;
-        this.#prefix = Name.prefix(this.#config.title === Title.US ? `${prefix}.` : prefix);
+        this.#prefix = Name.prefix(this.#config.title === Title.US && !prefix.endsWith('.') ? `${prefix}.` : prefix);
         return this;
     }
     setFirstName(name) {
@@ -97,6 +102,11 @@ export class FullName {
             return !!this.#suffix;
         return namon.equal(Namon.MIDDLE_NAME) ? this.#middleName.length > 0 : true;
     }
+    toString() {
+        if (this.isMono)
+            return this.value;
+        return Array.from(this.toIterable(true)).join(' ');
+    }
     *toIterable(flat = false) {
         if (this.#prefix)
             yield this.#prefix;
@@ -117,3 +127,37 @@ export class FullName {
         yield* this.toIterable(true);
     }
 }
+export class Mononym extends FullName {
+    #namon;
+    #type;
+    constructor(name, options) {
+        super(options ?? { name: 'mononym', mono: true });
+        this.#namon = name.toString();
+        this.type = name instanceof Name ? name.type : Namon.FIRST_NAME;
+    }
+    set type(type) {
+        this.#type = typeof type === 'string' ? (Namon.cast(type) ?? Namon.FIRST_NAME) : type;
+        this.#build(this.#namon);
+    }
+    get type() {
+        return this.#type;
+    }
+    get value() {
+        return this.#namon;
+    }
+    #build(name) {
+        this.setFirstName(ZERO_WIDTH_SPACE).setLastName(ZERO_WIDTH_SPACE).setMiddleName([]).setPrefix(null).setSuffix(null);
+        if (this.#type.equal(Namon.FIRST_NAME))
+            this.setFirstName(name);
+        else if (this.#type.equal(Namon.LAST_NAME))
+            this.setLastName(name);
+        else if (this.#type.equal(Namon.MIDDLE_NAME))
+            this.setMiddleName([name]);
+        else if (this.#type.equal(Namon.PREFIX))
+            this.setPrefix(name);
+        else if (this.#type.equal(Namon.SUFFIX))
+            this.setSuffix(name);
+        else
+            throw new NameError(name, 'invalid mononym type');
+    }
+}

package/dist/esm/name.d.ts

@@ -112,8 +112,14 @@ 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/esm/namefully.d.ts

@@ -32,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.
@@ -86,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. */
@@ -354,4 +356,5 @@ export type NameOptions = Partial<{
     ending: boolean;
     bypass: boolean;
     surname: Surname | 'father' | 'mother' | 'hyphenated' | 'all';
+    mono: boolean | Namon;
 }>;

package/dist/esm/namefully.js

@@ -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() {
@@ -113,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)
@@ -121,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(' ')
@@ -143,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]);
@@ -160,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
@@ -170,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;
@@ -317,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;
@@ -388,27 +431,6 @@ export class Namefully {
                 return ALLOWED_FORMAT_TOKENS.includes(char) ? char : undefined;
         }
     }
-    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,
-            },
-        };
-    }
 }
 export default (names, options) => {
     return new Namefully(names, options);

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);
@@ -123,3 +128,13 @@ export class ArrayNameParser extends Parser {
         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);
+    }
+}