namefully 1.2.1 → 2.0.0

package/dist/esm/error.js

@@ -0,0 +1,87 @@
+import { isStringArray } from './utils.js';
+export var NameErrorType;
+(function (NameErrorType) {
+    NameErrorType[NameErrorType["INPUT"] = 0] = "INPUT";
+    NameErrorType[NameErrorType["VALIDATION"] = 1] = "VALIDATION";
+    NameErrorType[NameErrorType["NOT_ALLOWED"] = 2] = "NOT_ALLOWED";
+    NameErrorType[NameErrorType["UNKNOWN"] = 3] = "UNKNOWN";
+})(NameErrorType || (NameErrorType = {}));
+export class NameError extends Error {
+    source;
+    type;
+    constructor(source, message, type = NameErrorType.UNKNOWN) {
+        super(message);
+        this.source = source;
+        this.type = type;
+        this.name = 'NameError';
+    }
+    get sourceAsString() {
+        let input = '';
+        if (!this.source)
+            input = '<undefined>';
+        if (typeof this.source === 'string')
+            input = this.source;
+        if (isStringArray(this.source))
+            input = this.source.join(' ');
+        return input;
+    }
+    get hasMessage() {
+        return this.message.trim().length > 0;
+    }
+    toString() {
+        let report = `${this.name} (${this.sourceAsString})`;
+        if (this.hasMessage)
+            report = `${report}: ${this.message}`;
+        return report;
+    }
+}
+export class InputError extends NameError {
+    constructor(error) {
+        super(error.source, error.message, NameErrorType.INPUT);
+        this.name = 'InputError';
+    }
+}
+export class ValidationError extends NameError {
+    nameType;
+    constructor(error) {
+        super(error.source, error.message, NameErrorType.VALIDATION);
+        this.nameType = error.nameType;
+        this.name = 'ValidationError';
+    }
+    toString() {
+        let report = `${this.name} (${this.nameType}='${this.sourceAsString}')`;
+        if (this.hasMessage)
+            report = `${report}: ${this.message}`;
+        return report;
+    }
+}
+export class NotAllowedError extends NameError {
+    operation;
+    constructor(error) {
+        super(error.source, error.message, NameErrorType.NOT_ALLOWED);
+        this.operation = error.operation;
+        this.name = 'NotAllowedError';
+    }
+    toString() {
+        let report = `${this.name} (${this.sourceAsString})`;
+        if (this.operation && this.operation.trim().length > 0)
+            report = `${report} - ${this.operation}`;
+        if (this.hasMessage)
+            report = `${report}: ${this.message}`;
+        return report;
+    }
+}
+export class UnknownError extends NameError {
+    origin;
+    constructor(error) {
+        super(error.source, error.message, NameErrorType.UNKNOWN);
+        this.origin = error.error;
+        this.name = 'UnknownError';
+    }
+    toString() {
+        let report = super.toString();
+        if (this.origin)
+            report += `\n${this.origin.toString()}`;
+        return report;
+    }
+}

package/dist/{types/full-name.d.ts → esm/fullname.d.ts}

@@ -1,6 +1,6 @@
-import { Config } from './config';
-import { FirstName, LastName, Name, JsonName } from './name';
-import { Nullable, Namon } from './types';
+import { Config } from './config.js';
+import { FirstName, LastName, Name, JsonName } from './name.js';
+import { Nullable, Namon } from './types.js';
 /**
  * The core component of this utility.
  *

package/dist/esm/fullname.js

@@ -0,0 +1,98 @@
+import { Config } from './config.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;
+    #middleName = [];
+    #lastName;
+    #suffix;
+    #config;
+    constructor(options) {
+        this.#config = Config.merge(options);
+    }
+    get config() {
+        return this.#config;
+    }
+    get prefix() {
+        return this.#prefix;
+    }
+    get firstName() {
+        return this.#firstName;
+    }
+    get lastName() {
+        return this.#lastName;
+    }
+    get middleName() {
+        return this.#middleName;
+    }
+    get suffix() {
+        return this.#suffix;
+    }
+    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;
+        }
+        catch (error) {
+            if (error instanceof NameError)
+                throw error;
+            throw new UnknownError({
+                source: Object.values(json).join(' '),
+                message: 'could not parse JSON content',
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    setPrefix(name) {
+        if (!name)
+            return this;
+        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);
+        return this;
+    }
+    setFirstName(name) {
+        if (!this.#config.bypass)
+            Validators.firstName.validate(name);
+        this.#firstName = name instanceof FirstName ? name : new FirstName(name);
+        return this;
+    }
+    setLastName(name) {
+        if (!this.#config.bypass)
+            Validators.lastName.validate(name);
+        this.#lastName = name instanceof LastName ? name : new LastName(name);
+        return this;
+    }
+    setMiddleName(names) {
+        if (!Array.isArray(names))
+            return this;
+        if (!this.#config.bypass)
+            Validators.middleName.validate(names);
+        this.#middleName = names.map((name) => (name instanceof Name ? name : Name.middle(name)));
+        return this;
+    }
+    setSuffix(name) {
+        if (!name)
+            return this;
+        if (!this.#config.bypass)
+            Validators.suffix.validate(name);
+        this.#suffix = Name.suffix(name instanceof Name ? name.value : name);
+        return this;
+    }
+    has(namon) {
+        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;
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Welcome to namefully!
+ *
+ * `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.js';
+export * from './builder.js';
+export * from './config.js';
+export { VERSION as version } from './constants.js';
+export * from './error.js';
+export * from './fullname.js';
+export * from './name.js';
+export * from './namefully.js';
+export { Parser } from './parser.js';
+export * from './types.js';
+export { NameIndex } from './utils.js';
+export default namefully;

package/dist/esm/index.js

@@ -0,0 +1,12 @@
+import namefully from './namefully.js';
+export * from './builder.js';
+export * from './config.js';
+export { VERSION as version } from './constants.js';
+export * from './error.js';
+export * from './fullname.js';
+export * from './name.js';
+export * from './namefully.js';
+export { Parser } from './parser.js';
+export * from './types.js';
+export { NameIndex } from './utils.js';
+export default namefully;

package/dist/{types → esm}/name.d.ts

@@ -1,4 +1,4 @@
-import { CapsRange, Namon, Surname } from './types';
+import { CapsRange, Namon, Surname } from './types.js';
 /**
  * Representation of a string type name with some extra capabilities.
  */
@@ -114,6 +114,7 @@ export declare class LastName extends Name {
         format?: Surname;
     }): LastName;
 }
+export declare function isNameArray(value?: unknown): boolean;
 /**
  * JSON signature for `FullName` data.
  */

package/dist/esm/name.js

@@ -0,0 +1,211 @@
+import { InputError } from './error.js';
+import { CapsRange, Namon, Surname } from './types.js';
+import { capitalize, decapitalize } from './utils.js';
+export class Name {
+    type;
+    #namon;
+    initial;
+    capsRange;
+    constructor(value, type, capsRange) {
+        this.type = type;
+        this.capsRange = capsRange ?? CapsRange.INITIAL;
+        this.value = value;
+        if (capsRange)
+            this.caps(capsRange);
+    }
+    set value(newValue) {
+        this.validate(newValue);
+        this.#namon = newValue;
+        this.initial = newValue[0];
+    }
+    get value() {
+        return this.#namon;
+    }
+    get length() {
+        return this.#namon.length;
+    }
+    get isPrefix() {
+        return this.type === Namon.PREFIX;
+    }
+    get isFirstName() {
+        return this.type === Namon.FIRST_NAME;
+    }
+    get isMiddleName() {
+        return this.type === Namon.MIDDLE_NAME;
+    }
+    get isLastName() {
+        return this.type === Namon.LAST_NAME;
+    }
+    get isSuffix() {
+        return this.type === Namon.SUFFIX;
+    }
+    static prefix(value) {
+        return new this(value, Namon.PREFIX);
+    }
+    static first(value) {
+        return new this(value, Namon.FIRST_NAME);
+    }
+    static middle(value) {
+        return new this(value, Namon.MIDDLE_NAME);
+    }
+    static last(value) {
+        return new this(value, Namon.LAST_NAME);
+    }
+    static suffix(value) {
+        return new this(value, Namon.SUFFIX);
+    }
+    initials() {
+        return [this.initial];
+    }
+    toString() {
+        return this.#namon;
+    }
+    equal(other) {
+        return other instanceof Name && other.value === this.value && other.type === this.type;
+    }
+    caps(range) {
+        this.value = capitalize(this.#namon, range ?? this.capsRange);
+        return this;
+    }
+    decaps(range) {
+        this.value = decapitalize(this.#namon, range ?? this.capsRange);
+        return this;
+    }
+    validate(name) {
+        if (name && name?.trim()?.length < 2) {
+            throw new InputError({ source: name, message: 'must be 2+ characters' });
+        }
+    }
+}
+export class FirstName extends Name {
+    #more;
+    constructor(value, ...more) {
+        super(value, Namon.FIRST_NAME);
+        more.forEach((n) => this.validate(n));
+        this.#more = more;
+    }
+    get hasMore() {
+        return this.#more.length > 0;
+    }
+    get length() {
+        return super.length + (this.hasMore ? this.#more.reduce((acc, n) => acc + n).length : 0);
+    }
+    get asNames() {
+        const names = [Name.first(this.value)];
+        if (this.hasMore) {
+            names.push(...this.#more.map((n) => Name.first(n)));
+        }
+        return names;
+    }
+    get more() {
+        return this.#more;
+    }
+    toString(withMore = false) {
+        return withMore && this.hasMore ? `${this.value} ${this.#more.join(' ')}`.trim() : this.value;
+    }
+    initials(withMore = false) {
+        const inits = [this.initial];
+        if (withMore && this.hasMore) {
+            inits.push(...this.#more.map((n) => n[0]));
+        }
+        return inits;
+    }
+    caps(range) {
+        range = range || this.capsRange;
+        this.value = capitalize(this.value, range);
+        if (this.hasMore)
+            this.#more = this.#more.map((n) => capitalize(n, range));
+        return this;
+    }
+    decaps(range) {
+        range = range || this.capsRange;
+        this.value = decapitalize(this.value, range);
+        if (this.hasMore)
+            this.#more = this.#more.map((n) => decapitalize(n, range));
+        return this;
+    }
+    copyWith(values) {
+        return new FirstName(values?.first ?? this.value, ...(values?.more ?? this.#more));
+    }
+}
+export class LastName extends Name {
+    format;
+    #mother;
+    constructor(father, mother, format = Surname.FATHER) {
+        super(father, Namon.LAST_NAME);
+        this.format = format;
+        this.validate(mother);
+        this.#mother = mother;
+    }
+    get father() {
+        return this.value;
+    }
+    get mother() {
+        return this.#mother;
+    }
+    get hasMother() {
+        return !!this.#mother;
+    }
+    get length() {
+        return super.length + (this.#mother?.length ?? 0);
+    }
+    get asNames() {
+        const names = [Name.last(this.value)];
+        if (this.#mother)
+            names.push(Name.last(this.#mother));
+        return names;
+    }
+    toString(format) {
+        format = format ?? this.format;
+        switch (format) {
+            case Surname.FATHER:
+                return this.value;
+            case Surname.MOTHER:
+                return this.mother ?? '';
+            case Surname.HYPHENATED:
+                return this.hasMother ? `${this.value}-${this.#mother}` : this.value;
+            case Surname.ALL:
+                return this.hasMother ? `${this.value} ${this.#mother}` : this.value;
+        }
+    }
+    initials(format) {
+        format = format || this.format;
+        const inits = [];
+        switch (format) {
+            case Surname.MOTHER:
+                if (this.#mother)
+                    inits.push(this.#mother[0]);
+                break;
+            case Surname.HYPHENATED:
+            case Surname.ALL:
+                inits.push(this.initial);
+                if (this.#mother)
+                    inits.push(this.#mother[0]);
+                break;
+            case Surname.FATHER:
+            default:
+                inits.push(this.initial);
+        }
+        return inits;
+    }
+    caps(range) {
+        range = range || this.capsRange;
+        this.value = capitalize(this.value, range);
+        if (this.hasMother)
+            this.#mother = capitalize(this.#mother, range);
+        return this;
+    }
+    decaps(range) {
+        range = range || this.capsRange;
+        this.value = decapitalize(this.value, range);
+        if (this.hasMother)
+            this.#mother = decapitalize(this.#mother, range);
+        return this;
+    }
+    copyWith(values) {
+        return new LastName(values?.father ?? this.value, values?.mother ?? this.mother, values?.format ?? this.format);
+    }
+}
+export function isNameArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((e) => e instanceof Name);
+}

package/dist/{types → esm}/namefully.d.ts

@@ -1,7 +1,8 @@
-import { Config } from './config';
-import { Name, JsonName } from './name';
-import { Parser } from './parser';
-import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types';
+import { Config } from './config.js';
+import { Name, JsonName } from './name.js';
+import { Parser } from './parser.js';
+import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types.js';
+import { NameIndex } from './utils.js';
 /**
  * A helper for organizing person names in a particular order, way, or shape.
  *
@@ -29,7 +30,7 @@ import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types';
  * this: `John Smith`, where `John` is the first name piece and `Smith`, the last
  * name piece.
  *
- * @see https://departments.weber.edu/qsupport&training/Data_Standards/Name.htm
+ * @see https://www.fbiic.gov/public/2008/nov/Naming_practice_guide_UK_2006.pdf
  * for more info on name standards.
  *
  * **IMPORTANT**: Keep in mind that the order of appearance (or name order) matters
@@ -48,8 +49,7 @@ import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types';
  */
 export declare class Namefully {
     #private;
-    /**
-     * Creates a name with distinguishable parts from a raw string content.
+    /** Creates a name with distinguishable parts from a raw string content.
      * @param names element to parse.
      * @param options additional settings.
      *
@@ -64,7 +64,7 @@ export declare class Namefully {
      * It works like `parse` except that this function returns `null` where `parse`
      * would throw a `NameError`.
      */
-    static tryParse(text: string): Namefully | undefined;
+    static tryParse(text: string, index?: NameIndex): Namefully | undefined;
     /**
      * Constructs a `Namefully` instance from a text.
      *
@@ -80,23 +80,23 @@ export declare class Namefully {
      * Keep in mind that prefix and suffix are not considered during the parsing
      * process.
      */
-    static parse(text: string): Promise<Namefully>;
+    static parse(text: string, index?: NameIndex): Promise<Namefully>;
     /** The current configuration. */
     get config(): Config;
     /** The number of characters of the `birthName`, including spaces. */
     get length(): number;
     /** The prefix part. */
-    get prefix(): Nullable<string>;
+    get prefix(): string | undefined;
     /** The firt name part. */
     get first(): string;
     /** The first middle name part if any. */
-    get middle(): Nullable<string>;
+    get middle(): string | undefined;
     /** Returns true if any middle name has been set. */
     get hasMiddle(): boolean;
     /** The last name part. */
     get last(): string;
     /** The suffix part. */
-    get suffix(): Nullable<string>;
+    get suffix(): string | undefined;
     /** The birth name part. */
     get birth(): string;
     /** The shortest version of a person name. */
@@ -107,6 +107,8 @@ export declare class Namefully {
     get full(): string;
     /** The first name combined with the last name's initial. */
     get public(): string;
+    /** The combination of prefix and last name. */
+    get salutation(): string;
     /** Returns the full name as set. */
     toString(): string;
     /** Fetches the raw form of a name piece. */
@@ -171,7 +173,8 @@ export declare class Namefully {
     initials(options?: {
         orderedBy?: NameOrder;
         only?: NameType;
-    }): string[];
+        asJson?: boolean;
+    }): string[] | Record<string, string[]>;
     /**
      * Shortens a complex full name to a simple typical name, a combination of
      * first and last name.
@@ -311,3 +314,10 @@ export declare class Namefully {
     /** Transforms a birth name into ToGgLeCaSe. */
     toToggleCase(): string;
 }
+/**
+ * A default export for the `namefully` utility.
+ * @param names element to parse.
+ * @param options additional settings.
+ */
+declare const _default: (names: string | string[] | Name[] | JsonName | Parser, options?: Partial<Config>) => Namefully;
+export default _default;