namefully 2.0.0 → 2.0.2

package/dist/cjs/validator.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Validators = exports.ArrayNameValidator = exports.ArrayStringValidator = exports.NamaValidator = 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 utils_js_1 = require("./utils.js");
+const name_js_1 = require("./name.js");
+const error_js_1 = require("./error.js");
+const constants_js_1 = require("./constants.js");
 class ValidationRule {
     static base = /[a-zA-Z\u00C0-\u00D6\u00D8-\u00f6\u00f8-\u00ff\u0400-\u04FFΆ-ωΑ-ώ]/;
     static namon = new RegExp(`^${ValidationRule.base.source}+(([' -]${ValidationRule.base.source})?${ValidationRule.base.source}*)*$`);
@@ -21,7 +21,7 @@ class ArrayValidator {
         if (values.length === 0 || values.length < constants_js_1.MIN_NUMBER_OF_NAME_PARTS || values.length > constants_js_1.MAX_NUMBER_OF_NAME_PARTS) {
             throw new error_js_1.InputError({
                 source: values.map((n) => n.toString()),
-                message: `expecting a list of ${constants_js_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_js_1.MIN_NUMBER_OF_NAME_PARTS} elements`,
+                message: `expecting a list of ${constants_js_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_js_1.MAX_NUMBER_OF_NAME_PARTS} elements`,
             });
         }
     }
@@ -29,7 +29,7 @@ class ArrayValidator {
 class NamonValidator {
     static #validator;
     static create() {
-        return this.#validator || (this.#validator = new this());
+        return this.#validator || (this.#validator = new NamonValidator());
     }
     validate(value, type) {
         if (value instanceof name_js_1.Name) {
@@ -40,22 +40,19 @@ class NamonValidator {
                 throw new error_js_1.ValidationError({
                     source: value,
                     nameType: 'namon',
-                    message: 'invalid content',
+                    message: 'invalid name content failing namon regex',
                 });
             }
         }
         else {
-            throw new error_js_1.InputError({
-                source: typeof value,
-                message: 'expecting types of string | Name',
-            });
+            throw new error_js_1.InputError({ source: typeof value, message: 'expecting types of string or Name' });
         }
     }
 }
 class FirstNameValidator {
     static #validator;
     static create() {
-        return this.#validator || (this.#validator = new this());
+        return this.#validator || (this.#validator = new FirstNameValidator());
     }
     validate(value) {
         if (value instanceof name_js_1.FirstName) {
@@ -66,22 +63,19 @@ class FirstNameValidator {
                 throw new error_js_1.ValidationError({
                     source: value,
                     nameType: 'firstName',
-                    message: 'invalid content',
+                    message: 'invalid name content failing firstName regex',
                 });
             }
         }
         else {
-            throw new error_js_1.InputError({
-                source: typeof value,
-                message: 'expecting types string | FirstName',
-            });
+            throw new error_js_1.InputError({ source: typeof value, message: 'expecting types string or FirstName' });
         }
     }
 }
 class MiddleNameValidator {
     static #validator;
     static create() {
-        return this.#validator || (this.#validator = new this());
+        return this.#validator || (this.#validator = new MiddleNameValidator());
     }
     validate(value) {
         if (typeof value === 'string') {
@@ -89,7 +83,7 @@ class MiddleNameValidator {
                 throw new error_js_1.ValidationError({
                     source: value,
                     nameType: 'middleName',
-                    message: 'invalid content',
+                    message: 'invalid name content failing middleName regex',
                 });
             }
         }
@@ -110,7 +104,7 @@ class MiddleNameValidator {
         else {
             throw new error_js_1.InputError({
                 source: typeof value,
-                message: 'expecting types of string | string[] | Name[]',
+                message: 'expecting types of string, string[] or Name[]',
             });
         }
     }
@@ -118,7 +112,7 @@ class MiddleNameValidator {
 class LastNameValidator {
     static #validator;
     static create() {
-        return this.#validator || (this.#validator = new this());
+        return this.#validator || (this.#validator = new LastNameValidator());
     }
     validate(value) {
         if (value instanceof name_js_1.LastName) {
@@ -129,36 +123,33 @@ class LastNameValidator {
                 throw new error_js_1.ValidationError({
                     source: value,
                     nameType: 'lastName',
-                    message: 'invalid content',
+                    message: 'invalid name content failing lastName regex',
                 });
             }
         }
         else {
-            throw new error_js_1.InputError({
-                source: typeof value,
-                message: 'expecting types string | LastName',
-            });
+            throw new error_js_1.InputError({ source: typeof value, message: 'expecting types string or LastName' });
         }
     }
 }
 class NameValidator {
     static #validator;
     static create() {
-        return this.#validator || (this.#validator = new this());
+        return this.#validator || (this.#validator = new NameValidator());
     }
     validate(name, type) {
         if (type && name.type !== type) {
             throw new error_js_1.ValidationError({
                 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_js_1.ValidationError({
                 source: name.toString(),
                 nameType: name.type.toString(),
-                message: 'invalid content',
+                message: 'invalid name content failing namon regex',
             });
         }
     }
@@ -166,7 +157,7 @@ class NameValidator {
 class NamaValidator {
     static #validator;
     static create() {
-        return this.#validator || (this.#validator = new this());
+        return this.#validator || (this.#validator = new NamaValidator());
     }
     validate(value) {
         this.validateKeys(value);
@@ -184,20 +175,14 @@ class NamaValidator {
         else if (nama.size < constants_js_1.MIN_NUMBER_OF_NAME_PARTS || nama.size > constants_js_1.MAX_NUMBER_OF_NAME_PARTS) {
             throw new error_js_1.InputError({
                 source: [...nama.values()],
-                message: `expecting ${constants_js_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_js_1.MIN_NUMBER_OF_NAME_PARTS} fields`,
+                message: `expecting ${constants_js_1.MIN_NUMBER_OF_NAME_PARTS}-${constants_js_1.MAX_NUMBER_OF_NAME_PARTS} fields`,
             });
         }
         if (!nama.has(types_js_1.Namon.FIRST_NAME)) {
-            throw new error_js_1.InputError({
-                source: [...nama.values()],
-                message: '"firstName" is a required key',
-            });
+            throw new error_js_1.InputError({ source: [...nama.values()], message: '"firstName" is a required key' });
         }
         if (!nama.has(types_js_1.Namon.LAST_NAME)) {
-            throw new error_js_1.InputError({
-                source: [...nama.values()],
-                message: '"lastName" is a required key',
-            });
+            throw new error_js_1.InputError({ source: [...nama.values()], message: '"lastName" is a required key' });
         }
     }
 }
@@ -227,7 +212,7 @@ exports.ArrayStringValidator = ArrayStringValidator;
 class ArrayNameValidator {
     static #validator;
     static create() {
-        return this.#validator || (this.#validator = new this());
+        return this.#validator || (this.#validator = new ArrayNameValidator());
     }
     validate(value) {
         if (value.length < constants_js_1.MIN_NUMBER_OF_NAME_PARTS) {

package/dist/esm/builder.d.ts

@@ -1,6 +1,6 @@
 import { Name } from './name.js';
-import { Namefully } from './namefully.js';
 import { Config } from './config.js';
+import { Namefully } from './namefully.js';
 type VoidCallback = () => void;
 type Callback<Type, Return> = (value: Type) => Return;
 /**
@@ -44,9 +44,11 @@ declare abstract class Builder<T, I> {
  * 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();
@@ -66,7 +68,7 @@ export declare class NameBuilder extends Builder<Name, Namefully> {
      * 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 NameException.
+     * to complete a fine build. Otherwise, it throws a NameError.
      */
     build(config?: Partial<Config>): Namefully;
 }

package/dist/esm/config.d.ts

@@ -92,6 +92,11 @@ export declare class Config {
     /**
      * 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(order: NameOrder): void;
+    updateOrder(orderedBy: NameOrder): void;
+    /**
+     * Allows the possibility to alter some options after creating a name set.
+     */
+    update({ orderedBy, title, ending }: Partial<Pick<Config, 'orderedBy' | 'title' | 'ending'>>): void;
 }

package/dist/esm/config.js

@@ -43,7 +43,7 @@ export class Config {
     }
     static create(name = defaultName) {
         if (!_a.cache.has(name))
-            _a.cache.set(name, new this(name));
+            _a.cache.set(name, new _a(name));
         return _a.cache.get(name);
     }
     static merge(other) {
@@ -84,10 +84,19 @@ export class Config {
         this.#surname = Surname.FATHER;
         _a.cache.set(this.name, this);
     }
-    updateOrder(order) {
-        if (order && order !== this.#orderedBy) {
-            _a.cache.get(this.name).#orderedBy = order;
-        }
+    updateOrder(orderedBy) {
+        this.update({ orderedBy });
+    }
+    update({ orderedBy, title, ending }) {
+        const config = _a.cache.get(this.name);
+        if (!config)
+            return;
+        if (orderedBy !== this.#orderedBy)
+            config.#orderedBy = orderedBy;
+        if (title !== this.#title)
+            config.#title = title;
+        if (ending !== this.#ending)
+            config.#ending = ending;
     }
     #genNewName(name) {
         return name === this.name || _a.cache.has(name) ? this.#genNewName(name + copyAlias) : name;

package/dist/esm/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "2.0.0";
+export declare const VERSION = "2.0.2";
 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: string[];

package/dist/esm/constants.js

@@ -1,7 +1,7 @@
-export const VERSION = '2.0.0';
+export const VERSION = '2.0.2';
 export const MIN_NUMBER_OF_NAME_PARTS = 2;
 export const MAX_NUMBER_OF_NAME_PARTS = 5;
-export const ALLOWED_TOKENS = [
+export const ALLOWED_FORMAT_TOKENS = [
     '.',
     ',',
     ' ',

package/dist/esm/error.d.ts

@@ -4,9 +4,7 @@ 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.
@@ -29,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
 }
 /**
@@ -44,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.
  *
@@ -54,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;
@@ -62,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. */
@@ -76,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`.
  */
@@ -150,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/esm/error.js

@@ -16,14 +16,11 @@ export class NameError extends Error {
         this.name = 'NameError';
     }
     get sourceAsString() {
-        let input = '';
-        if (!this.source)
-            input = '<undefined>';
         if (typeof this.source === 'string')
-            input = this.source;
+            return this.source;
         if (isStringArray(this.source))
-            input = this.source.join(' ');
-        return input;
+            return this.source.join(' ');
+        return '<undefined>';
     }
     get hasMessage() {
         return this.message.trim().length > 0;
@@ -75,7 +72,7 @@ export class UnknownError extends NameError {
     origin;
     constructor(error) {
         super(error.source, error.message, NameErrorType.UNKNOWN);
-        this.origin = error.error;
+        this.origin = error.origin;
         this.name = 'UnknownError';
     }
     toString() {

package/dist/esm/fullname.d.ts

@@ -1,18 +1,18 @@
 import { Config } from './config.js';
-import { FirstName, LastName, Name, JsonName } from './name.js';
 import { Nullable, Namon } from './types.js';
+import { FirstName, LastName, Name, JsonName } from './name.js';
 /**
  * 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,6 @@ 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.
-     */
+    /** Returns true if a namon has been set. */
     has(namon: Namon): boolean;
 }

package/dist/esm/fullname.js

@@ -1,8 +1,8 @@
 import { Config } from './config.js';
+import { Validators } from './validator.js';
+import { Namon, Title } from './types.js';
 import { NameError, UnknownError } from './error.js';
 import { FirstName, LastName, Name } from './name.js';
-import { Namon, Title } from './types.js';
-import { Validators } from './validator.js';
 export class FullName {
     #prefix;
     #firstName;
@@ -33,13 +33,12 @@ export class FullName {
     }
     static parse(json, config) {
         try {
-            const fullName = new FullName(config);
-            fullName.setPrefix(json.prefix);
-            fullName.setFirstName(json.firstName);
-            fullName.setMiddleName(json.middleName ?? []);
-            fullName.setLastName(json.lastName);
-            fullName.setSuffix(json.suffix);
-            return fullName;
+            return new FullName(config)
+                .setPrefix(json.prefix)
+                .setFirstName(json.firstName)
+                .setMiddleName(json.middleName ?? [])
+                .setLastName(json.lastName)
+                .setSuffix(json.suffix);
         }
         catch (error) {
             if (error instanceof NameError)
@@ -47,7 +46,7 @@ export class FullName {
             throw new UnknownError({
                 source: Object.values(json).join(' '),
                 message: 'could not parse JSON content',
-                error: error instanceof Error ? error : new Error(String(error)),
+                origin: error instanceof Error ? error : new Error(String(error)),
             });
         }
     }
@@ -77,7 +76,7 @@ export class FullName {
             return this;
         if (!this.#config.bypass)
             Validators.middleName.validate(names);
-        this.#middleName = names.map((name) => (name instanceof Name ? name : Name.middle(name)));
+        this.#middleName = names.map((n) => (n instanceof Name ? n : Name.middle(n)));
         return this;
     }
     setSuffix(name) {

package/dist/esm/name.d.ts

@@ -1,7 +1,5 @@
 import { CapsRange, Namon, Surname } from './types.js';
-/**
- * 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,22 +77,20 @@ 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;
     /**
      * 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. */
+    /** 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;
@@ -114,10 +108,8 @@ export declare class LastName extends Name {
         format?: Surname;
     }): LastName;
 }
-export declare function isNameArray(value?: unknown): boolean;
-/**
- * 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;