namefully 2.0.2 → 2.2.0

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,6 @@
-import { Namefully } from './namefully.js';
+import { Config } from './config.js';
 import { ArrayNameValidator } from './validator.js';
+import { Namefully } from './namefully.js';
 class Builder {
     prebuild;
     postbuild;
@@ -67,10 +68,12 @@ 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);
+        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;

package/dist/esm/config.d.ts

@@ -1,4 +1,4 @@
-import { NameOrder, Separator, Title, Surname } from './types.js';
+import { NameOrder, Namon, Separator, Title, Surname } from './types.js';
 /**
  * The Configuration to use across the other components.
  *
@@ -61,6 +61,8 @@ export declare class Config {
      * prioritized and viewed as the source of truth for future considerations.
      */
     get surname(): Surname;
+    /** Whether to parse a single word name as a mononym. */
+    get mono(): boolean | Namon;
     /** The name of the cached configuration. */
     get name(): string;
     private constructor();
@@ -89,14 +91,6 @@ export declare class Config {
     clone(): Config;
     /** Resets the configuration by setting it back to its default values. */
     reset(): void;
-    /**
-     * Alters the name order between the first and last name, and rearrange the
-     * order of appearance of a name set.
-     * @deprecated use `update()` method instead.
-     */
-    updateOrder(orderedBy: NameOrder): void;
-    /**
-     * Allows the possibility to alter some options after creating a name set.
-     */
+    /** Allows the possibility to alter behavior-related options after creating a name set. */
     update({ orderedBy, title, ending }: Partial<Pick<Config, 'orderedBy' | 'title' | 'ending'>>): void;
 }

package/dist/esm/config.js

@@ -10,6 +10,7 @@ export class Config {
     #ending;
     #bypass;
     #surname;
+    #mono;
     static cache = new Map();
     get orderedBy() {
         return this.#orderedBy;
@@ -29,10 +30,13 @@ export class Config {
     get surname() {
         return this.#surname;
     }
+    get mono() {
+        return this.#mono;
+    }
     get name() {
         return this.#name;
     }
-    constructor(name, orderedBy = NameOrder.FIRST_NAME, separator = Separator.SPACE, title = Title.UK, ending = false, bypass = true, surname = Surname.FATHER) {
+    constructor(name, orderedBy = NameOrder.FIRST_NAME, separator = Separator.SPACE, title = Title.UK, ending = false, bypass = true, surname = Surname.FATHER, mono = false) {
         this.#name = name;
         this.#orderedBy = orderedBy;
         this.#separator = separator;
@@ -40,6 +44,7 @@ export class Config {
         this.#ending = ending;
         this.#bypass = bypass;
         this.#surname = surname;
+        this.#mono = mono;
     }
     static create(name = defaultName) {
         if (!_a.cache.has(name))
@@ -58,11 +63,12 @@ export class Config {
             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;
@@ -70,6 +76,7 @@ export class Config {
         config.#ending = ending ?? this.ending;
         config.#bypass = bypass ?? this.bypass;
         config.#surname = surname ?? this.surname;
+        config.#mono = mono ?? this.mono;
         return config;
     }
     clone() {
@@ -82,11 +89,9 @@ export class Config {
         this.#ending = false;
         this.#bypass = true;
         this.#surname = 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)

package/dist/esm/constants.d.ts

@@ -1,4 +1,5 @@
-export declare const VERSION = "2.0.2";
+export declare const VERSION = "2.2.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$";
+export declare const ZERO_WIDTH_SPACE: string;

package/dist/esm/constants.js

@@ -1,27 +1,5 @@
-export const VERSION = '2.0.2';
+export const VERSION = '2.2.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$`;
+export const ZERO_WIDTH_SPACE = String.fromCharCode(8203);

package/dist/esm/data.d.ts

@@ -0,0 +1,31 @@
+import { JsonName } from './name.js';
+import { type Namefully } from './namefully.js';
+/** Serialized representation of a Namefully instance. */
+export interface SerializedName {
+    /** The name data (with its hierarchy intact). */
+    names: JsonName;
+    /** The configuration data. */
+    config: {
+        name: string;
+        orderedBy: string;
+        separator: string;
+        title: string;
+        ending: boolean;
+        bypass: boolean;
+        surname: string;
+        mono: boolean | 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,38 @@
+import { NameBuilder } from './builder.js';
+import { Namon, Separator } from './types.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(...(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)),
+        });
+    }
+}

package/dist/esm/fullname.d.ts

@@ -36,6 +36,8 @@ export declare class FullName {
     get middleName(): Name[];
     /** The suffix part of the full name. */
     get suffix(): Nullable<Name>;
+    /** Whether the full name is a single word name. */
+    get isMono(): boolean;
     /**
      * Parses a JSON name into a full name.
      * @param {JsonName} json parsable name element
@@ -48,5 +50,40 @@ 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;
+    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>;
+}
+/**
+ * A single word name or mononym.
+ *
+ * This is a special case of `FullName` that is used to represent mononyms. This contradicts
+ * the original purpose of this library such as shaping and organizing name pieces accordingly.
+ *
+ * When enabled via `Config.mono`, this becomes the full name of a human. And as a single name,
+ * most of the `Namefully` methods become irrelevant.
+ */
+export declare class Mononym extends FullName {
+    #private;
+    /**
+     * Constructs a mononym from a piece of string.
+     * @param {string | Name} name to be used to construct the mononym.
+     */
+    constructor(name: string | Name, options?: Partial<Config>);
+    /**
+     * Re-assigns which name type is being used to represent the mononym.
+     *
+     * Ideally, this doesn't really matter as the mononym is always a single piece of name.
+     * When used as `string`, it must be a valid `Namon` type or else it will default to
+     * `Namon.FIRST_NAME`.
+     * @param {string | Namon} type of name to use.
+     */
+    set type(type: string | Namon);
+    /** The type of name being used to represent the mononym. */
+    get type(): Namon;
+    /** The piece of string treated as a name. */
+    get value(): string;
 }

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) {
@@ -87,11 +92,72 @@ 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;
     }
+    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);
+    }
+}
+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/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. */
@@ -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/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;
         }
     }