namefully 2.0.2 → 2.2.0

package/dist/namefully.js

@@ -4,33 +4,11 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.namefully = {}));
 })(this, (function (exports) { 'use strict';
 
-    const VERSION = '2.0.2';
+    const VERSION = '2.2.0';
     const MIN_NUMBER_OF_NAME_PARTS = 2;
     const MAX_NUMBER_OF_NAME_PARTS = 5;
-    const ALLOWED_FORMAT_TOKENS = [
-        '.',
-        ',',
-        ' ',
-        '-',
-        '_',
-        'b',
-        'B',
-        'f',
-        'F',
-        'l',
-        'L',
-        'm',
-        'M',
-        'n',
-        'N',
-        'o',
-        'O',
-        'p',
-        'P',
-        's',
-        'S',
-        '$',
-    ];
+    const ALLOWED_FORMAT_TOKENS = ` .,_-()[]<>'"bBfFlLmMnNoOpPsS$`;
+    const ZERO_WIDTH_SPACE = String.fromCharCode(8203);
 
     exports.Title = void 0;
     (function (Title) {
@@ -87,6 +65,13 @@
             [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;
@@ -95,7 +80,9 @@
             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}`;
@@ -134,6 +121,14 @@
             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}`;
         }
@@ -472,7 +467,7 @@
                     return this.mother ?? '';
                 case exports.Surname.HYPHENATED:
                     return this.hasMother ? `${this.value}-${this.#mother}` : this.value;
-                case exports.Surname.ALL:
+                default:
                     return this.hasMother ? `${this.value} ${this.#mother}` : this.value;
             }
         }
@@ -527,6 +522,7 @@
         #ending;
         #bypass;
         #surname;
+        #mono;
         static cache = new Map();
         get orderedBy() {
             return this.#orderedBy;
@@ -546,10 +542,13 @@
         get surname() {
             return this.#surname;
         }
+        get mono() {
+            return this.#mono;
+        }
         get name() {
             return this.#name;
         }
-        constructor(name, orderedBy = exports.NameOrder.FIRST_NAME, separator = Separator.SPACE, title = exports.Title.UK, ending = false, bypass = true, surname = exports.Surname.FATHER) {
+        constructor(name, orderedBy = exports.NameOrder.FIRST_NAME, separator = Separator.SPACE, title = exports.Title.UK, ending = false, bypass = true, surname = exports.Surname.FATHER, mono = false) {
             this.#name = name;
             this.#orderedBy = orderedBy;
             this.#separator = separator;
@@ -557,6 +556,7 @@
             this.#ending = ending;
             this.#bypass = bypass;
             this.#surname = surname;
+            this.#mono = mono;
         }
         static create(name = defaultName) {
             if (!_a.cache.has(name))
@@ -575,11 +575,12 @@
                 config.#ending = other.ending ?? config.ending;
                 config.#bypass = other.bypass ?? config.bypass;
                 config.#surname = other.surname ?? config.surname;
+                config.#mono = other.mono ?? config.mono;
                 return config;
             }
         }
         copyWith(options = {}) {
-            const { name, orderedBy, separator, title, ending, bypass, surname } = options;
+            const { name, orderedBy, separator, title, ending, bypass, surname, mono } = options;
             const config = _a.create(this.#genNewName(name ?? this.name + copyAlias));
             config.#orderedBy = orderedBy ?? this.orderedBy;
             config.#separator = separator ?? this.separator;
@@ -587,6 +588,7 @@
             config.#ending = ending ?? this.ending;
             config.#bypass = bypass ?? this.bypass;
             config.#surname = surname ?? this.surname;
+            config.#mono = mono ?? this.mono;
             return config;
         }
         clone() {
@@ -599,11 +601,9 @@
             this.#ending = false;
             this.#bypass = true;
             this.#surname = exports.Surname.FATHER;
+            this.#mono = false;
             _a.cache.set(this.name, this);
         }
-        updateOrder(orderedBy) {
-            this.update({ orderedBy });
-        }
         update({ orderedBy, title, ending }) {
             const config = _a.cache.get(this.name);
             if (!config)
@@ -889,14 +889,18 @@
         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)
@@ -914,7 +918,7 @@
             if (!this.#config.bypass)
                 Validators.prefix.validate(name);
             const prefix = name instanceof Name ? name.value : name;
-            this.#prefix = Name.prefix(this.#config.title === exports.Title.US ? `${prefix}.` : prefix);
+            this.#prefix = Name.prefix(this.#config.title === exports.Title.US && !prefix.endsWith('.') ? `${prefix}.` : prefix);
             return this;
         }
         setFirstName(name) {
@@ -945,13 +949,74 @@
             this.#suffix = Name.suffix(name instanceof Name ? name.value : name);
             return this;
         }
-        has(namon) {
+        has(key) {
+            const namon = typeof key === 'string' ? Namon.cast(key) : key;
+            if (!namon)
+                return false;
             if (namon.equal(Namon.PREFIX))
                 return !!this.#prefix;
             if (namon.equal(Namon.SUFFIX))
                 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;
+            if (flat) {
+                yield* this.#firstName.asNames;
+                yield* this.#middleName;
+                yield* this.#lastName.asNames;
+            }
+            else {
+                yield this.#firstName;
+                yield* this.#middleName;
+                yield this.#lastName;
+            }
+            if (this.#suffix)
+                yield this.#suffix;
+        }
+        *[Symbol.iterator]() {
+            yield* this.toIterable(true);
+        }
+    }
+    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');
+        }
     }
 
     class Parser {
@@ -969,10 +1034,7 @@
                 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);
@@ -996,13 +1058,15 @@
         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);
         }
     }
     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);
@@ -1013,8 +1077,9 @@
                 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)
@@ -1038,10 +1103,10 @@
                 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);
         }
@@ -1049,8 +1114,13 @@
     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);
@@ -1065,13 +1135,23 @@
                     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;
         }
     }
+    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);
+        }
+    }
 
     class Namefully {
         #fullName;
@@ -1092,7 +1172,12 @@
         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() {
@@ -1131,25 +1216,43 @@
         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,
@@ -1164,6 +1267,8 @@
             return this.#fullName.has(namon);
         }
         fullName(orderedBy) {
+            if (this.isMono)
+                return this.#fullName.toString();
             const sep = this.config.ending ? ',' : '';
             const names = [];
             if (this.prefix)
@@ -1172,13 +1277,21 @@
                 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 === exports.NameOrder.FIRST_NAME
                 ? [this.first, ...this.middleName(), this.last].join(' ')
@@ -1194,6 +1307,8 @@
             return this.#fullName.lastName.toString(format);
         }
         initials(options) {
+            if (this.isMono)
+                return [this.#fullName.toString()[0]];
             const { orderedBy = this.config.orderedBy, only = exports.NameType.BIRTH_NAME, asJson } = options ?? {};
             const firstInits = this.#fullName.firstName.initials();
             const midInits = this.#fullName.middleName.map((n) => n.value[0]);
@@ -1211,6 +1326,8 @@
             }
         }
         shorten(orderedBy) {
+            if (this.isMono)
+                return this.#fullName.toString();
             orderedBy ??= this.config.orderedBy;
             const { firstName, lastName } = this.#fullName;
             return orderedBy === exports.NameOrder.FIRST_NAME
@@ -1221,6 +1338,8 @@
             const { by = exports.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;
@@ -1248,7 +1367,7 @@
                     case exports.Flat.MID_LAST:
                         name = hasMid ? [fn, m, l] : [fn, l];
                         break;
-                    case exports.Flat.ALL:
+                    default:
                         name = hasMid ? [f, m, l] : [f, l];
                         break;
                 }
@@ -1270,7 +1389,7 @@
                     case exports.Flat.MID_LAST:
                         name = hasMid ? [l, fn, m] : [l, fn];
                         break;
-                    case exports.Flat.ALL:
+                    default:
                         name = hasMid ? [l, f, m] : [l, f];
                         break;
                 }
@@ -1311,7 +1430,7 @@
             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',
@@ -1368,6 +1487,28 @@
         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;
@@ -1383,12 +1524,6 @@
         }
         #map(char) {
             switch (char) {
-                case '.':
-                case ',':
-                case ' ':
-                case '-':
-                case '_':
-                    return char;
                 case 'b':
                     return this.birth;
                 case 'B':
@@ -1430,16 +1565,19 @@
                 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;
             }
         }
     }
@@ -1514,21 +1652,59 @@
         static use({ names, prebuild, postbuild, preclear, postclear, }) {
             return new NameBuilder(names ?? [], prebuild, postbuild, preclear, postclear);
         }
-        build(config) {
+        build(options) {
             this.prebuild?.();
             const names = [...this.queue];
-            ArrayNameValidator.create().validate(names);
+            const config = Config.merge(options);
+            if (!config.mono)
+                ArrayNameValidator.create().validate(names);
             this.instance = new Namefully(names, config);
             this.postbuild?.(this.instance);
             return this.instance;
         }
     }
 
+    function deserialize(data) {
+        try {
+            const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+            if (!parsed || typeof parsed !== 'object') {
+                throw new InputError({
+                    source: String(data),
+                    message: 'invalid serialized data; must be an object or a string',
+                });
+            }
+            const { names, config } = parsed;
+            const { firstName: fn, lastName: ln, middleName: mn, prefix: px, suffix: sx } = names;
+            const builder = NameBuilder.of();
+            if (px)
+                builder.add(Name.prefix(px));
+            if (sx)
+                builder.add(Name.suffix(sx));
+            if (mn)
+                builder.add(...(typeof mn === 'string' ? [Name.middle(mn)] : mn.map((n) => Name.middle(n))));
+            builder.add(typeof fn === 'string' ? Name.first(fn) : new FirstName(fn.value, ...(fn.more ?? [])));
+            builder.add(typeof ln === 'string' ? Name.last(ln) : new LastName(ln.father, ln.mother));
+            const separator = Separator.cast(config.separator);
+            const mono = typeof config.mono === 'string' ? (Namon.cast(config.mono) ?? false) : config.mono;
+            return builder.build({ ...config, separator, mono });
+        }
+        catch (error) {
+            if (error instanceof NameError)
+                throw error;
+            throw new UnknownError({
+                source: String(data),
+                message: 'could not deserialize data',
+                origin: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+
     exports.Config = Config;
     exports.FirstName = FirstName;
     exports.FullName = FullName;
     exports.InputError = InputError;
     exports.LastName = LastName;
+    exports.Mononym = Mononym;
     exports.Name = Name;
     exports.NameBuilder = NameBuilder;
     exports.NameError = NameError;
@@ -1541,6 +1717,7 @@
     exports.UnknownError = UnknownError;
     exports.ValidationError = ValidationError;
     exports.default = namefully;
+    exports.deserialize = deserialize;
     exports.isNameArray = isNameArray;
     exports.version = VERSION;