namefully 1.3.0 → 2.0.0

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,8 +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 { NameIndex } from './utils';
+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.
  *
@@ -86,17 +86,17 @@ export declare class Namefully {
     /** 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. */