namefully 1.2.1 → 1.3.1

package/dist/lib/validator.js

@@ -13,11 +13,11 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
 var _a, _NamonValidator_validator, _b, _FirstNameValidator_validator, _c, _MiddleNameValidator_validator, _d, _LastNameValidator_validator, _e, _NameValidator_validator, _f, _NamaValidator_validator, _ArrayNameValidator_instances, _g, _ArrayNameValidator_validator, _ArrayNameValidator_hasBasicNames;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Validators = exports.ArrayNameValidator = exports.ArrayStringValidator = exports.NamaValidator = void 0;
-const constants_1 = require("./constants");
-const error_1 = require("./error");
-const name_1 = require("./name");
 const types_1 = require("./types");
 const utils_1 = require("./utils");
+const name_1 = require("./name");
+const error_1 = require("./error");
+const constants_1 = require("./constants");
 class ValidationRule {
 }
 ValidationRule.base = /[a-zA-Z\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\u0400-\u04FFΆ-ωΑ-ώ]/;
@@ -25,19 +25,22 @@ ValidationRule.namon = new RegExp(`^${ValidationRule.base.source}+(([' -]${Valid
 ValidationRule.firstName = ValidationRule.namon;
 ValidationRule.middleName = new RegExp(`^${ValidationRule.base.source}+(([' -]${ValidationRule.base.source})?${ValidationRule.base.source}*)*$`);
 ValidationRule.lastName = ValidationRule.namon;
+const toNameSource = (values) => {
+    return (0, name_1.isNameArray)(values) ? values.map((n) => n.toString()).join(' ') : '';
+};
 class ArrayValidator {
     validate(values) {
         if (values.length === 0 || values.length < constants_1.MIN_NUMBER_OF_NAME_PARTS || values.length > constants_1.MAX_NUMBER_OF_NAME_PARTS) {
             throw new error_1.InputError({
                 source: values.map((n) => n.toString()),
-                message: `expecting a list of ${constants_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_1.MIN_NUMBER_OF_NAME_PARTS} elements`,
+                message: `expecting a list of ${constants_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_1.MAX_NUMBER_OF_NAME_PARTS} elements`,
             });
         }
     }
 }
 class NamonValidator {
     static create() {
-        return __classPrivateFieldGet(this, _a, "f", _NamonValidator_validator) || (__classPrivateFieldSet(this, _a, new this(), "f", _NamonValidator_validator));
+        return __classPrivateFieldGet(this, _a, "f", _NamonValidator_validator) || (__classPrivateFieldSet(this, _a, new _a(), "f", _NamonValidator_validator));
     }
     validate(value, type) {
         if (value instanceof name_1.Name) {
@@ -48,15 +51,12 @@ class NamonValidator {
                 throw new error_1.ValidationError({
                     source: value,
                     nameType: 'namon',
-                    message: 'invalid content',
+                    message: 'invalid name content failing namon regex',
                 });
             }
         }
         else {
-            throw new error_1.InputError({
-                source: typeof value,
-                message: 'expecting types of string | Name',
-            });
+            throw new error_1.InputError({ source: typeof value, message: 'expecting types of string or Name' });
         }
     }
 }
@@ -64,7 +64,7 @@ _a = NamonValidator;
 _NamonValidator_validator = { value: void 0 };
 class FirstNameValidator {
     static create() {
-        return __classPrivateFieldGet(this, _b, "f", _FirstNameValidator_validator) || (__classPrivateFieldSet(this, _b, new this(), "f", _FirstNameValidator_validator));
+        return __classPrivateFieldGet(this, _b, "f", _FirstNameValidator_validator) || (__classPrivateFieldSet(this, _b, new _b(), "f", _FirstNameValidator_validator));
     }
     validate(value) {
         if (value instanceof name_1.FirstName) {
@@ -75,15 +75,12 @@ class FirstNameValidator {
                 throw new error_1.ValidationError({
                     source: value,
                     nameType: 'firstName',
-                    message: 'invalid content',
+                    message: 'invalid name content failing firstName regex',
                 });
             }
         }
         else {
-            throw new error_1.InputError({
-                source: typeof value,
-                message: 'expecting types string | FirstName',
-            });
+            throw new error_1.InputError({ source: typeof value, message: 'expecting types string or FirstName' });
         }
     }
 }
@@ -91,7 +88,7 @@ _b = FirstNameValidator;
 _FirstNameValidator_validator = { value: void 0 };
 class MiddleNameValidator {
     static create() {
-        return __classPrivateFieldGet(this, _c, "f", _MiddleNameValidator_validator) || (__classPrivateFieldSet(this, _c, new this(), "f", _MiddleNameValidator_validator));
+        return __classPrivateFieldGet(this, _c, "f", _MiddleNameValidator_validator) || (__classPrivateFieldSet(this, _c, new _c(), "f", _MiddleNameValidator_validator));
     }
     validate(value) {
         if (typeof value === 'string') {
@@ -99,7 +96,7 @@ class MiddleNameValidator {
                 throw new error_1.ValidationError({
                     source: value,
                     nameType: 'middleName',
-                    message: 'invalid content',
+                    message: 'invalid name content failing middleName regex',
                 });
             }
         }
@@ -111,7 +108,7 @@ class MiddleNameValidator {
             }
             catch (error) {
                 throw new error_1.ValidationError({
-                    source: value,
+                    source: toNameSource(value),
                     nameType: 'middleName',
                     message: error === null || error === void 0 ? void 0 : error.message,
                 });
@@ -120,7 +117,7 @@ class MiddleNameValidator {
         else {
             throw new error_1.InputError({
                 source: typeof value,
-                message: 'expecting types of string | string[] | Name[]',
+                message: 'expecting types of string, string[] or Name[]',
             });
         }
     }
@@ -129,7 +126,7 @@ _c = MiddleNameValidator;
 _MiddleNameValidator_validator = { value: void 0 };
 class LastNameValidator {
     static create() {
-        return __classPrivateFieldGet(this, _d, "f", _LastNameValidator_validator) || (__classPrivateFieldSet(this, _d, new this(), "f", _LastNameValidator_validator));
+        return __classPrivateFieldGet(this, _d, "f", _LastNameValidator_validator) || (__classPrivateFieldSet(this, _d, new _d(), "f", _LastNameValidator_validator));
     }
     validate(value) {
         if (value instanceof name_1.LastName) {
@@ -140,15 +137,12 @@ class LastNameValidator {
                 throw new error_1.ValidationError({
                     source: value,
                     nameType: 'lastName',
-                    message: 'invalid content',
+                    message: 'invalid name content failing lastName regex',
                 });
             }
         }
         else {
-            throw new error_1.InputError({
-                source: typeof value,
-                message: 'expecting types string | LastName',
-            });
+            throw new error_1.InputError({ source: typeof value, message: 'expecting types string or LastName' });
         }
     }
 }
@@ -156,21 +150,21 @@ _d = LastNameValidator;
 _LastNameValidator_validator = { value: void 0 };
 class NameValidator {
     static create() {
-        return __classPrivateFieldGet(this, _e, "f", _NameValidator_validator) || (__classPrivateFieldSet(this, _e, new this(), "f", _NameValidator_validator));
+        return __classPrivateFieldGet(this, _e, "f", _NameValidator_validator) || (__classPrivateFieldSet(this, _e, new _e(), "f", _NameValidator_validator));
     }
     validate(name, type) {
         if (type && name.type !== type) {
             throw new error_1.ValidationError({
-                source: [name],
+                source: name.toString(),
                 nameType: name.type.toString(),
-                message: 'wrong type',
+                message: 'wrong name type; only Namon types are supported',
             });
         }
         if (!ValidationRule.namon.test(name.value)) {
             throw new error_1.ValidationError({
-                source: [name],
+                source: name.toString(),
                 nameType: name.type.toString(),
-                message: 'invalid content',
+                message: 'invalid name content failing namon regex',
             });
         }
     }
@@ -179,18 +173,16 @@ _e = NameValidator;
 _NameValidator_validator = { value: void 0 };
 class NamaValidator {
     static create() {
-        return __classPrivateFieldGet(this, _f, "f", _NamaValidator_validator) || (__classPrivateFieldSet(this, _f, new this(), "f", _NamaValidator_validator));
+        return __classPrivateFieldGet(this, _f, "f", _NamaValidator_validator) || (__classPrivateFieldSet(this, _f, new _f(), "f", _NamaValidator_validator));
     }
     validate(value) {
         this.validateKeys(value);
         Validators.firstName.validate(value.get(types_1.Namon.FIRST_NAME));
         Validators.lastName.validate(value.get(types_1.Namon.LAST_NAME));
-        if (value.has(types_1.Namon.PREFIX)) {
+        if (value.has(types_1.Namon.PREFIX))
             Validators.namon.validate(value.get(types_1.Namon.PREFIX));
-        }
-        if (value.has(types_1.Namon.SUFFIX)) {
+        if (value.has(types_1.Namon.SUFFIX))
             Validators.namon.validate(value.get(types_1.Namon.SUFFIX));
-        }
     }
     validateKeys(nama) {
         if (!nama.size) {
@@ -199,20 +191,14 @@ class NamaValidator {
         else if (nama.size < constants_1.MIN_NUMBER_OF_NAME_PARTS || nama.size > constants_1.MAX_NUMBER_OF_NAME_PARTS) {
             throw new error_1.InputError({
                 source: [...nama.values()],
-                message: `expecting ${constants_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_1.MIN_NUMBER_OF_NAME_PARTS} fields`,
+                message: `expecting ${constants_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_1.MAX_NUMBER_OF_NAME_PARTS} fields`,
             });
         }
         if (!nama.has(types_1.Namon.FIRST_NAME)) {
-            throw new error_1.InputError({
-                source: [...nama.values()],
-                message: '"firstName" is a required key',
-            });
+            throw new error_1.InputError({ source: [...nama.values()], message: '"firstName" is a required key' });
         }
         if (!nama.has(types_1.Namon.LAST_NAME)) {
-            throw new error_1.InputError({
-                source: [...nama.values()],
-                message: '"lastName" is a required key',
-            });
+            throw new error_1.InputError({ source: [...nama.values()], message: '"lastName" is a required key' });
         }
     }
 }
@@ -226,30 +212,14 @@ class ArrayStringValidator extends ArrayValidator {
     }
     validate(values) {
         this.validateIndex(values);
-        switch (values.length) {
-            case 2:
-                Validators.firstName.validate(values[this.index.firstName]);
-                Validators.lastName.validate(values[this.index.lastName]);
-                break;
-            case 3:
-                Validators.firstName.validate(values[this.index.firstName]);
-                Validators.middleName.validate(values[this.index.middleName]);
-                Validators.lastName.validate(values[this.index.lastName]);
-                break;
-            case 4:
-                Validators.namon.validate(values[this.index.prefix]);
-                Validators.firstName.validate(values[this.index.firstName]);
-                Validators.middleName.validate(values[this.index.middleName]);
-                Validators.lastName.validate(values[this.index.lastName]);
-                break;
-            case 5:
-                Validators.namon.validate(values[this.index.prefix]);
-                Validators.firstName.validate(values[this.index.firstName]);
-                Validators.middleName.validate(values[this.index.middleName]);
-                Validators.lastName.validate(values[this.index.lastName]);
-                Validators.namon.validate(values[this.index.suffix]);
-                break;
-        }
+        Validators.firstName.validate(values[this.index.firstName]);
+        Validators.lastName.validate(values[this.index.lastName]);
+        if (values.length >= 3)
+            Validators.middleName.validate(values[this.index.middleName]);
+        if (values.length >= 4)
+            Validators.namon.validate(values[this.index.prefix]);
+        if (values.length === 5)
+            Validators.namon.validate(values[this.index.suffix]);
     }
     validateIndex(values) {
         super.validate(values);
@@ -261,18 +231,18 @@ class ArrayNameValidator {
         _ArrayNameValidator_instances.add(this);
     }
     static create() {
-        return __classPrivateFieldGet(this, _g, "f", _ArrayNameValidator_validator) || (__classPrivateFieldSet(this, _g, new this(), "f", _ArrayNameValidator_validator));
+        return __classPrivateFieldGet(this, _g, "f", _ArrayNameValidator_validator) || (__classPrivateFieldSet(this, _g, new _g(), "f", _ArrayNameValidator_validator));
     }
     validate(value) {
         if (value.length < constants_1.MIN_NUMBER_OF_NAME_PARTS) {
             throw new error_1.InputError({
-                source: value,
+                source: toNameSource(value),
                 message: `expecting at least ${constants_1.MIN_NUMBER_OF_NAME_PARTS} elements`,
             });
         }
         if (!__classPrivateFieldGet(this, _ArrayNameValidator_instances, "m", _ArrayNameValidator_hasBasicNames).call(this, value)) {
             throw new error_1.InputError({
-                source: value,
+                source: toNameSource(value),
                 message: 'both first and last names are required',
             });
         }

package/dist/types/builder.d.ts

@@ -0,0 +1,75 @@
+import { Name } from './name';
+import { Config } from './config';
+import { Namefully } from './namefully';
+type VoidCallback = () => void;
+type Callback<Type, Return> = (value: Type) => Return;
+/**
+ * A generic builder class that provides common functionality for building instances.
+ */
+declare abstract class Builder<T, I> {
+    protected readonly prebuild?: VoidCallback;
+    protected readonly postbuild?: Callback<I, void>;
+    protected readonly preclear?: Callback<I, void>;
+    protected readonly postclear?: VoidCallback;
+    protected queue: T[];
+    protected instance: I | null;
+    constructor(prebuild?: VoidCallback, postbuild?: Callback<I, void>, preclear?: Callback<I, void>, postclear?: VoidCallback);
+    /** Gets the current size of the builder. */
+    get size(): number;
+    /** Removes and returns the first element of the queue. */
+    removeFirst(): T | undefined;
+    /** Removes and returns the last element of the queue. */
+    removeLast(): T | undefined;
+    /** Adds a value at the beginning of the queue. */
+    addFirst(value: T): void;
+    /** Adds a value at the end of the queue. */
+    addLast(value: T): void;
+    /** Adds a value at the end of the queue. */
+    add(...values: T[]): void;
+    /** Removes a single instance of a value from the queue. */
+    remove(value: T): boolean;
+    /** Removes all elements matched by the test function from the queue. */
+    removeWhere(callback: Callback<T, boolean>): void;
+    /** Removes all elements not matched by the test function from the queue. */
+    retainWhere(callback: Callback<T, boolean>): void;
+    /** Removes all elements in the queue. */
+    clear(): void;
+    /** Builds the desired instance with optional parameters. */
+    abstract build(options?: Partial<Config>): I;
+}
+/**
+ * An on-the-fly name builder.
+ *
+ * The builder uses a lazy-building method while capturing all necessary Names
+ * to finally construct a complete Namefully instance.
+ *
+ * @example
+ * ```js
+ * const builder = NameBuilder.of([Name.first('Thomas'), Name.last('Edison')]);
+ * builder.add(Name.middle('Alva'));
+ * console.log(builder.build()); // 'Thomas Alva Edison'
+ * ```
+ */
+export declare class NameBuilder extends Builder<Name, Namefully> {
+    private constructor();
+    /** Creates a base builder from one Name to construct Namefully later. */
+    static create(name?: Name): NameBuilder;
+    /** Creates a base builder from many Names to construct Namefully later. */
+    static of(...initialNames: Name[]): NameBuilder;
+    /** Creates a base builder from many Names with lifecycle hooks. */
+    static use({ names, prebuild, postbuild, preclear, postclear, }: {
+        names?: Name[];
+        prebuild?: VoidCallback;
+        postbuild?: Callback<Namefully, void>;
+        preclear?: Callback<Namefully, void>;
+        postclear?: VoidCallback;
+    }): NameBuilder;
+    /**
+     * Builds an instance of Namefully from the previously collected names.
+     *
+     * 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;
+}
+export {};

package/dist/types/config.d.ts

@@ -89,9 +89,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.
-     */
-    updateOrder(order: NameOrder): void;
+    /** 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/types/constants.d.ts

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

package/dist/types/error.d.ts

@@ -1,13 +1,10 @@
-import { Name } from './name';
 import { Nullable } from './types';
-type NameSource = Nullable<string | string[] | Name[]>;
+type NameSource = Nullable<string | string[]>;
 interface ErrorMessage {
     source: NameSource;
     message?: string;
 }
-/**
- * The error types supported by `Namefully`.
- */
+/** The error types supported by `Namefully`. */
 export declare enum NameErrorType {
     /**
      * Thrown when a name entry/argument is incorrect.
@@ -30,9 +27,7 @@ export declare enum NameErrorType {
      * See also: `NotAllowedError`, `Namefully.format`.
      */
     NOT_ALLOWED = 2,
-    /**
-     * Thrown by any other unknown sources or unexpected situation.
-     */
+    /** Thrown by any other unknown sources or unexpected situation. */
     UNKNOWN = 3
 }
 /**
@@ -45,8 +40,8 @@ export declare enum NameErrorType {
  * program failure. Au contraire, it is expected that a programmer using this utility
  * would consider validating a name using its own business rules. That is not
  * this utility's job to guess those rules. So, the predefined `ValidationRules`
- * obey some common validation techniques when it comes to sanitizing a person
- * name. For this reason, the [Config.bypass] is set to `true` by default,
+ * obey some common validation techniques when it comes to sanitizing a personal
+ * name. For this reason, the `Config.bypass` is set to `true` by default,
  * indicating that those predefined rules should be skipped for the sake of the
  * program.
  *
@@ -55,7 +50,7 @@ export declare enum NameErrorType {
  *
  * A name error intends to provide useful information about what causes the error
  * and let the user take initiative on what happens next to the given name:
- * reconstructing it or skipping it.
+ * reconstructing it or discarding it.
  */
 export declare class NameError extends Error {
     readonly source: NameSource;
@@ -63,8 +58,8 @@ export declare class NameError extends Error {
     /**
      * Creates an error with a message describing the issue for a name source.
      * @param source name input that caused the error
-     * @param message a message describing the failure.
-     * @param type of `NameErrorType`
+     * @param message describing the failure.
+     * @param type of error via `NameErrorType`
      */
     constructor(source: NameSource, message?: string, type?: NameErrorType);
     /** The actual source input which caused the error. */
@@ -77,9 +72,9 @@ export declare class NameError extends Error {
 /**
  * An error thrown when a name source input is incorrect.
  *
- * A `Name` is a name for this utility under certain criteria (i.e., 2+ chars),
+ * A `Name` is a name for this utility under certain criteria (i.e., 1+ chars),
  * hence, a wrong input will cause this kind of error. Another common reason
- * may be a wrong key in a Json name parsing mechanism.
+ * may be a wrong key in a JSON name parsing mechanism.
  *
  * Keep in mind that this error is different from a `ValidationError`.
  */
@@ -151,7 +146,7 @@ export declare class UnknownError extends NameError {
      * Optionally, the original error revealing the true nature of the failure.
      */
     constructor(error: ErrorMessage & {
-        error?: Error;
+        origin?: Error;
     });
     toString(): string;
 }

package/dist/types/full-name.d.ts

@@ -1,18 +1,18 @@
 import { Config } from './config';
-import { FirstName, LastName, Name, JsonName } from './name';
 import { Nullable, Namon } from './types';
+import { FirstName, LastName, Name, JsonName } from './name';
 /**
  * The core component of this utility.
  *
- * This component is comprised of five entities that make it easy to handle a
+ * This component is composed of five entities that make it easy to handle a
  * full name set: prefix, first name, middle name, last name, and suffix.
- * This class is intended for internal processes. However, it is understandable
+ * It is indeed intended for internal processes. However, it is understandable
  * that it might be needed at some point for additional purposes. For this reason,
  * it's made available.
  *
  * It is recommended to avoid using this class unless it is highly necessary or
- * a custom parser is used for uncommon use cases. This utility tries to cover
- * as many use cases as possible.
+ * a custom parser is used for uncommon use cases although this utility tries to
+ * cover as many use cases as possible.
  *
  * Additionally, an optional configuration can be used to indicate some specific
  * behaviors related to that name handling.
@@ -21,7 +21,7 @@ export declare class FullName {
     #private;
     /**
      * Creates a full name as it goes
-     * @param options optional configuration for additional features.
+     * @param options settings for additional features.
      */
     constructor(options?: Partial<Config>);
     /** A snapshot of the configuration used to set up this full name. */
@@ -37,9 +37,9 @@ export declare class FullName {
     /** The suffix part of the full name. */
     get suffix(): Nullable<Name>;
     /**
-     * Parses a json name into a full name.
-     * @param json parsable name element
-     * @param config optional configuration for additional features.
+     * Parses a JSON name into a full name.
+     * @param {JsonName} json parsable name element
+     * @param {Config} config for additional features.
      */
     static parse(json: JsonName, config?: Config): FullName;
     setPrefix(name: Nullable<string | Name>): FullName;
@@ -47,8 +47,11 @@ export declare class FullName {
     setLastName(name: string | LastName): FullName;
     setMiddleName(names: string[] | Name[]): FullName;
     setSuffix(name: Nullable<string | Name>): FullName;
-    /**
-     * Returns true if a namon has been set.
-     */
-    has(namon: Namon): boolean;
+    /** Returns true if a namon has been set. */
+    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>;
 }

package/dist/types/index.d.ts

@@ -1,15 +1,18 @@
 /**
  * Welcome to namefully!
  *
- * `namefully` is a JavaScript utility for handing person names.
+ * `namefully` is a JavaScript utility for handling personal names.
  *
  * Sources
  * - repo: https://github.com/ralflorent/namefully
  * - docs: https://namefully.netlify.app
  * - npm: https://npmjs.com/package/namefully
+ * - jsr: https://jsr.io/@ralflorent/namefully
  *
  * @license MIT
  */
+import namefully from './namefully';
+export * from './builder';
 export * from './config';
 export { VERSION as version } from './constants';
 export * from './error';
@@ -19,3 +22,4 @@ export * from './namefully';
 export { Parser } from './parser';
 export * from './types';
 export { NameIndex } from './utils';
+export default namefully;

package/dist/types/name.d.ts

@@ -1,7 +1,5 @@
 import { CapsRange, Namon, Surname } from './types';
-/**
- * Representation of a string type name with some extra capabilities.
- */
+/** Representation of a string type name with some extra capabilities. */
 export declare class Name {
     #private;
     readonly type: Namon;
@@ -9,9 +7,9 @@ export declare class Name {
     protected capsRange: CapsRange;
     /**
      * Creates augmented names by adding extra functionality to a string name.
-     * @param type must be indicated to categorize the name so it can be
+     * @param {Namon} type must be indicated to categorize the name so it can be
      * treated accordingly.
-     * @param capsRange determines how the name should be capitalized initially.
+     * @param {CapsRange} capsRange determines how the name should be capitalized initially.
      */
     constructor(value: string, type: Namon, capsRange?: CapsRange);
     set value(newValue: string);
@@ -51,16 +49,14 @@ export declare class Name {
     decaps(range?: CapsRange): Name;
     protected validate(name?: string): void;
 }
-/**
- * Representation of a first name with some extra functionality.
- */
+/** Representation of a first name with some extra functionality. */
 export declare class FirstName extends Name {
     #private;
     /**
      * Creates an extended version of `Name` and flags it as a first name `type`.
      *
      * Some may consider `more` additional name parts of a given name as their
-     * first names, but not as their middle names. Though, it may mean the same,
+     * first names, but not as their middle names. Though it may mean the same,
      * `more` provides the freedom to do it as it pleases.
      */
     constructor(value: string, ...more: string[]);
@@ -81,30 +77,28 @@ export declare class FirstName extends Name {
         more?: string[];
     }): FirstName;
 }
-/**
- * Representation of a last name with some extra functionality.
- */
+/** 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 `mother`'s surname and want to keep a clear cut
-     * from their `father`'s surname. However, there are no clear rules about it.
+     * 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);
-    /** The surname inherited from a father side. */
+    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 a mother side. */
+    /** The surname inherited from the mother side. */
     get mother(): string | undefined;
     /** Returns `true` if the mother's surname is defined. */
     get hasMother(): boolean;
     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. */
@@ -114,13 +108,18 @@ export declare class LastName extends Name {
         format?: Surname;
     }): LastName;
 }
-/**
- * JSON signature for `FullName` data.
- */
+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;
 }