namefully 2.0.2 → 2.1.0

package/dist/cjs/builder.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameBuilder = void 0;
-const namefully_js_1 = require("./namefully.js");
 const validator_js_1 = require("./validator.js");
+const namefully_js_1 = require("./namefully.js");
 class Builder {
     prebuild;
     postbuild;
@@ -70,11 +70,11 @@ class NameBuilder extends Builder {
     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];
         validator_js_1.ArrayNameValidator.create().validate(names);
-        this.instance = new namefully_js_1.Namefully(names, config);
+        this.instance = new namefully_js_1.Namefully(names, options);
         this.postbuild?.(this.instance);
         return this.instance;
     }

package/dist/cjs/constants.js

@@ -1,30 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALLOWED_FORMAT_TOKENS = exports.MAX_NUMBER_OF_NAME_PARTS = exports.MIN_NUMBER_OF_NAME_PARTS = exports.VERSION = void 0;
-exports.VERSION = '2.0.2';
+exports.VERSION = '2.1.0';
 exports.MIN_NUMBER_OF_NAME_PARTS = 2;
 exports.MAX_NUMBER_OF_NAME_PARTS = 5;
-exports.ALLOWED_FORMAT_TOKENS = [
-    '.',
-    ',',
-    ' ',
-    '-',
-    '_',
-    'b',
-    'B',
-    'f',
-    'F',
-    'l',
-    'L',
-    'm',
-    'M',
-    'n',
-    'N',
-    'o',
-    'O',
-    'p',
-    'P',
-    's',
-    'S',
-    '$',
-];
+exports.ALLOWED_FORMAT_TOKENS = ` .,_-()[]<>'"bBfFlLmMnNoOpPsS$`;

package/dist/cjs/data.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deserialize = void 0;
+const builder_js_1 = require("./builder.js");
+const name_js_1 = require("./name.js");
+const error_js_1 = require("./error.js");
+function deserialize(data) {
+    try {
+        const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+        if (!parsed || typeof parsed !== 'object') {
+            throw new error_js_1.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 = builder_js_1.NameBuilder.of();
+        if (px)
+            builder.add(name_js_1.Name.prefix(px));
+        if (sx)
+            builder.add(name_js_1.Name.suffix(sx));
+        if (mn)
+            builder.add(...mn.map((n) => name_js_1.Name.middle(n)));
+        builder.add(typeof fn === 'string' ? name_js_1.Name.first(fn) : new name_js_1.FirstName(fn.value, ...(fn.more ?? [])));
+        builder.add(typeof ln === 'string' ? name_js_1.Name.last(ln) : new name_js_1.LastName(ln.father, ln.mother));
+        return builder.build(config);
+    }
+    catch (error) {
+        if (error instanceof error_js_1.NameError)
+            throw error;
+        throw new error_js_1.UnknownError({
+            source: String(data),
+            message: 'could not deserialize data',
+            origin: error instanceof Error ? error : new Error(String(error)),
+        });
+    }
+}
+exports.deserialize = deserialize;

package/dist/cjs/fullname.js

@@ -90,12 +90,34 @@ class FullName {
         this.#suffix = name_js_1.Name.suffix(name instanceof name_js_1.Name ? name.value : name);
         return this;
     }
-    has(namon) {
+    has(key) {
+        const namon = typeof key === 'string' ? types_js_1.Namon.cast(key) : key;
+        if (!namon)
+            return false;
         if (namon.equal(types_js_1.Namon.PREFIX))
             return !!this.#prefix;
         if (namon.equal(types_js_1.Namon.SUFFIX))
             return !!this.#suffix;
         return namon.equal(types_js_1.Namon.MIDDLE_NAME) ? this.#middleName.length > 0 : true;
     }
+    *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);
+    }
 }
 exports.FullName = FullName;

package/dist/cjs/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./builder.js"), exports);
 __exportStar(require("./config.js"), exports);
 var constants_js_1 = require("./constants.js");
 Object.defineProperty(exports, "version", { enumerable: true, get: function () { return constants_js_1.VERSION; } });
+__exportStar(require("./data.js"), exports);
 __exportStar(require("./error.js"), exports);
 __exportStar(require("./fullname.js"), exports);
 __exportStar(require("./name.js"), exports);

package/dist/cjs/name.js

@@ -167,7 +167,7 @@ class LastName extends Name {
                 return this.mother ?? '';
             case types_js_1.Surname.HYPHENATED:
                 return this.hasMother ? `${this.value}-${this.#mother}` : this.value;
-            case types_js_1.Surname.ALL:
+            default:
                 return this.hasMother ? `${this.value} ${this.#mother}` : this.value;
         }
     }

package/dist/cjs/namefully.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Namefully = void 0;
 const constants_js_1 = require("./constants.js");
-const error_js_1 = require("./error.js");
 const name_js_1 = require("./name.js");
-const types_js_1 = require("./types.js");
+const error_js_1 = require("./error.js");
 const utils_js_1 = require("./utils.js");
+const types_js_1 = require("./types.js");
 const parser_js_1 = require("./parser.js");
 class Namefully {
     #fullName;
@@ -65,25 +65,43 @@ 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(types_js_1.Namon.PREFIX))
+    get(key) {
+        const namon = typeof key === 'string' ? types_js_1.Namon.cast(key) : key;
+        if (namon?.equal(types_js_1.Namon.PREFIX))
             return this.#fullName.prefix;
-        if (namon.equal(types_js_1.Namon.FIRST_NAME))
+        if (namon?.equal(types_js_1.Namon.FIRST_NAME))
             return this.#fullName.firstName;
-        if (namon.equal(types_js_1.Namon.MIDDLE_NAME))
+        if (namon?.equal(types_js_1.Namon.MIDDLE_NAME))
             return this.#fullName.middleName;
-        if (namon.equal(types_js_1.Namon.LAST_NAME))
+        if (namon?.equal(types_js_1.Namon.LAST_NAME))
             return this.#fullName.lastName;
-        if (namon.equal(types_js_1.Namon.SUFFIX))
+        if (namon?.equal(types_js_1.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,
@@ -182,7 +200,7 @@ class Namefully {
                 case types_js_1.Flat.MID_LAST:
                     name = hasMid ? [fn, m, l] : [fn, l];
                     break;
-                case types_js_1.Flat.ALL:
+                default:
                     name = hasMid ? [f, m, l] : [f, l];
                     break;
             }
@@ -204,7 +222,7 @@ class Namefully {
                 case types_js_1.Flat.MID_LAST:
                     name = hasMid ? [l, fn, m] : [l, fn];
                     break;
-                case types_js_1.Flat.ALL:
+                default:
                     name = hasMid ? [l, f, m] : [l, f];
                     break;
             }
@@ -245,7 +263,7 @@ class Namefully {
         let group = '';
         const formatted = [];
         for (const char of pattern) {
-            if (constants_js_1.ALLOWED_FORMAT_TOKENS.indexOf(char) === -1) {
+            if (!constants_js_1.ALLOWED_FORMAT_TOKENS.includes(char)) {
                 throw new error_js_1.NotAllowedError({
                     source: this.full,
                     operation: 'format',
@@ -317,12 +335,6 @@ class Namefully {
     }
     #map(char) {
         switch (char) {
-            case '.':
-            case ',':
-            case ' ':
-            case '-':
-            case '_':
-                return char;
             case 'b':
                 return this.birth;
             case 'B':
@@ -364,18 +376,42 @@ 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 constants_js_1.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,
+            },
+        };
+    }
 }
 exports.Namefully = Namefully;
 exports.default = (names, options) => {

package/dist/cjs/parser.js

@@ -123,8 +123,8 @@ class ArrayNameParser extends Parser {
                 fullName.middleName.push(name);
             }
             else if (name.isLastName) {
-                const lastName = new name_js_1.LastName(name.value, name instanceof name_js_1.LastName ? name.mother : undefined, config.surname);
-                fullName.setLastName(lastName);
+                const mother = name instanceof name_js_1.LastName ? name.mother : undefined;
+                fullName.setLastName(new name_js_1.LastName(name.value, mother, config.surname));
             }
         }
         return fullName;

package/dist/cjs/types.js

@@ -56,6 +56,13 @@ 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;
@@ -64,7 +71,9 @@ 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}`;
@@ -104,6 +113,14 @@ 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}`;
     }

package/dist/esm/builder.d.ts

@@ -1,6 +1,6 @@
 import { Name } from './name.js';
 import { Config } from './config.js';
-import { Namefully } from './namefully.js';
+import { Namefully, NameOptions } from './namefully.js';
 type VoidCallback = () => void;
 type Callback<Type, Return> = (value: Type) => Return;
 /**
@@ -70,6 +70,6 @@ export declare class NameBuilder extends Builder<Name, Namefully> {
      * Regardless of how the names are added, both first and last names must exist
      * to complete a fine build. Otherwise, it throws a NameError.
      */
-    build(config?: Partial<Config>): Namefully;
+    build(options?: NameOptions): Namefully;
 }
 export {};

package/dist/esm/builder.js

@@ -1,5 +1,5 @@
-import { Namefully } from './namefully.js';
 import { ArrayNameValidator } from './validator.js';
+import { Namefully } from './namefully.js';
 class Builder {
     prebuild;
     postbuild;
@@ -67,11 +67,11 @@ export class NameBuilder extends Builder {
     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);
-        this.instance = new Namefully(names, config);
+        this.instance = new Namefully(names, options);
         this.postbuild?.(this.instance);
         return this.instance;
     }

package/dist/esm/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "2.0.2";
+export declare const VERSION = "2.1.0";
 export declare const MIN_NUMBER_OF_NAME_PARTS = 2;
 export declare const MAX_NUMBER_OF_NAME_PARTS = 5;
-export declare const ALLOWED_FORMAT_TOKENS: string[];
+export declare const ALLOWED_FORMAT_TOKENS = " .,_-()[]<>'\"bBfFlLmMnNoOpPsS$";

package/dist/esm/constants.js

@@ -1,27 +1,4 @@
-export const VERSION = '2.0.2';
+export const VERSION = '2.1.0';
 export const MIN_NUMBER_OF_NAME_PARTS = 2;
 export const MAX_NUMBER_OF_NAME_PARTS = 5;
-export const ALLOWED_FORMAT_TOKENS = [
-    '.',
-    ',',
-    ' ',
-    '-',
-    '_',
-    'b',
-    'B',
-    'f',
-    'F',
-    'l',
-    'L',
-    'm',
-    'M',
-    'n',
-    'N',
-    'o',
-    'O',
-    'p',
-    'P',
-    's',
-    'S',
-    '$',
-];
+export const ALLOWED_FORMAT_TOKENS = ` .,_-()[]<>'"bBfFlLmMnNoOpPsS$`;

package/dist/esm/data.d.ts

@@ -0,0 +1,41 @@
+import { type Namefully } from './namefully.js';
+/** Serialized representation of a Namefully instance. */
+export interface SerializedName {
+    /** The name data (with its hierarchy intact). */
+    names: {
+        prefix?: string;
+        firstName: string | {
+            value: string;
+            more?: string[];
+        };
+        middleName?: string[];
+        lastName: string | {
+            father: string;
+            mother?: string;
+        };
+        suffix?: string;
+    };
+    /** The configuration data. */
+    config: {
+        name: string;
+        orderedBy: string;
+        separator: string;
+        title: string;
+        ending: boolean;
+        bypass: boolean;
+        surname: string;
+    };
+}
+/**
+ * Deserializes a JSON object into a Namefully instance.
+ *
+ * This is the inverse operation of `serialize()`, reconstructing a Namefully
+ * instance from a previously serialized JSON object, preserving the name hierarchy.
+ *
+ * @param {SerializedName | string} data the serialized Namefully data (from `serialize()`
+ * or compatible format).
+ * @returns a new Namefully instance.
+ *
+ * @throws {NameError} if the data cannot be parsed or is invalid.
+ */
+export declare function deserialize(data: SerializedName | string): Namefully;

package/dist/esm/data.js

@@ -0,0 +1,35 @@
+import { NameBuilder } from './builder.js';
+import { Name, FirstName, LastName } from './name.js';
+import { InputError, NameError, UnknownError } from './error.js';
+export 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(...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));
+        return builder.build(config);
+    }
+    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)),
+        });
+    }
+}

package/dist/esm/fullname.d.ts

@@ -48,5 +48,9 @@ export declare class FullName {
     setMiddleName(names: string[] | Name[]): FullName;
     setSuffix(name: Nullable<string | Name>): FullName;
     /** Returns true if a namon has been set. */
-    has(namon: Namon): boolean;
+    has(key: Namon | string): boolean;
+    /** 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/esm/fullname.js

@@ -87,11 +87,33 @@ export class FullName {
         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;
     }
+    *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);
+    }
 }

package/dist/esm/index.d.ts

@@ -15,6 +15,7 @@ import namefully from './namefully.js';
 export * from './builder.js';
 export * from './config.js';
 export { VERSION as version } from './constants.js';
+export * from './data.js';
 export * from './error.js';
 export * from './fullname.js';
 export * from './name.js';

package/dist/esm/index.js

@@ -2,6 +2,7 @@ import namefully from './namefully.js';
 export * from './builder.js';
 export * from './config.js';
 export { VERSION as version } from './constants.js';
+export * from './data.js';
 export * from './error.js';
 export * from './fullname.js';
 export * from './name.js';

package/dist/esm/name.d.ts

@@ -80,14 +80,14 @@ export declare class FirstName extends Name {
 /** 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 @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);
+    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 the mother side. */
@@ -97,8 +97,8 @@ export declare class LastName extends Name {
     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. */

package/dist/esm/name.js

@@ -162,7 +162,7 @@ export class LastName extends Name {
                 return this.mother ?? '';
             case Surname.HYPHENATED:
                 return this.hasMother ? `${this.value}-${this.#mother}` : this.value;
-            case Surname.ALL:
+            default:
                 return this.hasMother ? `${this.value} ${this.#mother}` : this.value;
         }
     }