namefully 1.2.1 → 1.3.0

package/dist/lib/builder.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NameBuilder = void 0;
+const namefully_1 = require("./namefully");
+const validator_1 = require("./validator");
+class Builder {
+    constructor(prebuild, postbuild, preclear, postclear) {
+        this.prebuild = prebuild;
+        this.postbuild = postbuild;
+        this.preclear = preclear;
+        this.postclear = postclear;
+        this.queue = [];
+        this.instance = null;
+    }
+    get size() {
+        return this.queue.length;
+    }
+    removeFirst() {
+        return this.queue.length > 0 ? this.queue.shift() : undefined;
+    }
+    removeLast() {
+        return this.queue.length > 0 ? this.queue.pop() : undefined;
+    }
+    addFirst(value) {
+        this.queue.unshift(value);
+    }
+    addLast(value) {
+        this.queue.push(value);
+    }
+    add(...values) {
+        this.queue.push(...values);
+    }
+    remove(value) {
+        const index = this.queue.indexOf(value);
+        if (index !== -1) {
+            this.queue.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    removeWhere(callback) {
+        this.queue = this.queue.filter((item) => !callback(item));
+    }
+    retainWhere(callback) {
+        this.queue = this.queue.filter(callback);
+    }
+    clear() {
+        var _a, _b;
+        if (this.instance !== null)
+            (_a = this.preclear) === null || _a === void 0 ? void 0 : _a.call(this, this.instance);
+        this.queue = [];
+        (_b = this.postclear) === null || _b === void 0 ? void 0 : _b.call(this);
+        this.instance = null;
+    }
+}
+class NameBuilder extends Builder {
+    constructor(names, prebuild, postbuild, preclear, postclear) {
+        super(prebuild, postbuild, preclear, postclear);
+        this.add(...names);
+    }
+    static create(name) {
+        return new NameBuilder(name ? [name] : []);
+    }
+    static of(...initialNames) {
+        return new NameBuilder(initialNames);
+    }
+    static use({ names, prebuild, postbuild, preclear, postclear, }) {
+        return new NameBuilder(names !== null && names !== void 0 ? names : [], prebuild, postbuild, preclear, postclear);
+    }
+    build(config) {
+        var _a, _b;
+        (_a = this.prebuild) === null || _a === void 0 ? void 0 : _a.call(this);
+        const names = [...this.queue];
+        validator_1.ArrayNameValidator.create().validate(names);
+        this.instance = new namefully_1.Namefully(names, config);
+        (_b = this.postbuild) === null || _b === void 0 ? void 0 : _b.call(this, this.instance);
+        return this.instance;
+    }
+}
+exports.NameBuilder = NameBuilder;

package/dist/lib/constants.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALLOWED_TOKENS = exports.MAX_NUMBER_OF_NAME_PARTS = exports.MIN_NUMBER_OF_NAME_PARTS = exports.VERSION = void 0;
-exports.VERSION = '1.2.1';
+exports.VERSION = '1.3.0';
 exports.MIN_NUMBER_OF_NAME_PARTS = 2;
 exports.MAX_NUMBER_OF_NAME_PARTS = 5;
 exports.ALLOWED_TOKENS = [

package/dist/lib/index.js

@@ -15,6 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameIndex = exports.Parser = exports.version = void 0;
+const namefully_1 = require("./namefully");
+__exportStar(require("./builder"), exports);
 __exportStar(require("./config"), exports);
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "version", { enumerable: true, get: function () { return constants_1.VERSION; } });
@@ -27,3 +29,4 @@ Object.defineProperty(exports, "Parser", { enumerable: true, get: function () {
 __exportStar(require("./types"), exports);
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "NameIndex", { enumerable: true, get: function () { return utils_1.NameIndex; } });
+exports.default = namefully_1.default;

package/dist/lib/namefully.js

@@ -33,17 +33,17 @@ class Namefully {
         _Namefully_fullName.set(this, void 0);
         __classPrivateFieldSet(this, _Namefully_fullName, __classPrivateFieldGet(this, _Namefully_instances, "m", _Namefully_toParser).call(this, names).parse(options), "f");
     }
-    static tryParse(text) {
+    static tryParse(text, index) {
         try {
-            return new this(parser_1.Parser.build(text));
+            return new Namefully(parser_1.Parser.build(text, index));
         }
-        catch (error) {
+        catch (_a) {
             return undefined;
         }
     }
-    static parse(text) {
+    static parse(text, index) {
         return __awaiter(this, void 0, void 0, function* () {
-            return parser_1.Parser.buildAsync(text).then((parser) => new Namefully(parser));
+            return parser_1.Parser.buildAsync(text, index).then((parser) => new Namefully(parser));
         });
     }
     get config() {
@@ -87,6 +87,9 @@ class Namefully {
     get public() {
         return this.format('f $l');
     }
+    get salutation() {
+        return this.format('p l');
+    }
     toString() {
         return this.full;
     }
@@ -150,12 +153,13 @@ class Namefully {
         return __classPrivateFieldGet(this, _Namefully_fullName, "f").lastName.toString(format);
     }
     initials(options) {
-        const initials = [];
         const firstInits = __classPrivateFieldGet(this, _Namefully_fullName, "f").firstName.initials();
         const midInits = __classPrivateFieldGet(this, _Namefully_fullName, "f").middleName.map((n) => n.initials()[0]);
         const lastInits = __classPrivateFieldGet(this, _Namefully_fullName, "f").lastName.initials();
-        const mergedOptions = Object.assign({ orderedBy: this.config.orderedBy, only: types_1.NameType.BIRTH_NAME }, options);
-        const { orderedBy, only } = mergedOptions;
+        if (options === null || options === void 0 ? void 0 : options.asJson)
+            return { firstName: firstInits, middleName: midInits, lastName: lastInits };
+        const initials = [];
+        const { orderedBy = this.config.orderedBy, only = types_1.NameType.BIRTH_NAME } = options !== null && options !== void 0 ? options : {};
         if (only !== types_1.NameType.BIRTH_NAME) {
             if (only === types_1.NameType.FIRST_NAME) {
                 initials.push(...firstInits);
@@ -184,8 +188,7 @@ class Namefully {
     flatten(options) {
         if (this.length <= options.limit)
             return this.full;
-        const mergedOptions = Object.assign({ limit: 20, by: types_1.Flat.MIDDLE_NAME, withPeriod: true, recursive: false, withMore: false }, options);
-        const { by, limit, recursive, withMore, withPeriod, surname } = mergedOptions;
+        const { by = types_1.Flat.MIDDLE_NAME, limit = 20, recursive = false, withMore = false, withPeriod = true, surname, } = options;
         const sep = withPeriod ? '.' : '';
         const fn = __classPrivateFieldGet(this, _Namefully_fullName, "f").firstName.toString();
         const mn = this.middleName().join(' ');
@@ -372,21 +375,22 @@ _Namefully_fullName = new WeakMap(), _Namefully_instances = new WeakSet(), _Name
             return char === 'm' ? this.middleName().join(' ') : this.middleName().join(' ').toUpperCase();
         case 'o':
         case 'O':
-            const sep = this.config.ending ? ',' : '';
-            const names = [];
-            if (this.prefix)
-                names.push(this.prefix);
-            names.push(`${this.last},`.toUpperCase());
-            if (this.hasMiddle) {
-                names.push(this.first, this.middleName().join(' ') + sep);
-            }
-            else {
-                names.push(this.first + sep);
-            }
-            if (this.suffix)
-                names.push(this.suffix);
-            const nama = names.join(' ').trim();
-            return char === 'o' ? nama : nama.toUpperCase();
+            return ((character) => {
+                const sep = this.config.ending ? ',' : '', names = [];
+                if (this.prefix)
+                    names.push(this.prefix);
+                names.push(`${this.last},`.toUpperCase());
+                if (this.hasMiddle) {
+                    names.push(this.first, this.middleName().join(' ') + sep);
+                }
+                else {
+                    names.push(this.first + sep);
+                }
+                if (this.suffix)
+                    names.push(this.suffix);
+                const nama = names.join(' ').trim();
+                return character === 'o' ? nama : nama.toUpperCase();
+            })(char);
         case 'p':
             return this.prefix;
         case 'P':
@@ -408,3 +412,6 @@ _Namefully_fullName = new WeakMap(), _Namefully_instances = new WeakSet(), _Name
             return undefined;
     }
 };
+exports.default = (names, options) => {
+    return new Namefully(names, options);
+};

package/dist/lib/parser.js

@@ -18,9 +18,15 @@ class Parser {
     constructor(raw) {
         this.raw = raw;
     }
-    static build(text) {
+    static build(text, index) {
         const parts = text.trim().split(types_1.Separator.SPACE.token);
         const length = parts.length;
+        if (index instanceof utils_1.NameIndex) {
+            const names = Object.entries(index.toJson())
+                .filter(([, position]) => position > -1 && position < length)
+                .map(([key, position]) => new name_1.Name(parts[position], types_1.Namon.all.get(key)));
+            return new ArrayNameParser(names);
+        }
         if (length < 2) {
             throw new error_1.InputError({
                 source: text,
@@ -36,9 +42,9 @@ class Parser {
             return new ArrayStringParser([first, middles.join(' '), last]);
         }
     }
-    static buildAsync(text) {
+    static buildAsync(text, index) {
         try {
-            return Promise.resolve(Parser.build(text));
+            return Promise.resolve(Parser.build(text, index));
         }
         catch (error) {
             return Promise.reject(error);

package/dist/lib/utils.js

@@ -51,6 +51,18 @@ class NameIndex {
             }
         }
     }
+    static only({ prefix = -1, firstName, middleName = -1, lastName, suffix = -1 }) {
+        return new this(prefix, firstName, middleName, lastName, suffix);
+    }
+    toJson() {
+        return {
+            prefix: this.prefix,
+            firstName: this.firstName,
+            middleName: this.middleName,
+            lastName: this.lastName,
+            suffix: this.suffix,
+        };
+    }
 }
 exports.NameIndex = NameIndex;
 function capitalize(str, range = types_1.CapsRange.INITIAL) {

package/dist/lib/validator.js

@@ -226,30 +226,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);

package/dist/types/builder.d.ts

@@ -0,0 +1,73 @@
+import { Name } from './name';
+import { Namefully } from './namefully';
+import { Config } from './config';
+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
+ * 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 NameException.
+     */
+    build(config?: Partial<Config>): Namefully;
+}
+export {};

package/dist/types/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "1.2.1";
+export declare const VERSION = "1.3.0";
 export declare const MIN_NUMBER_OF_NAME_PARTS = 2;
 export declare const MAX_NUMBER_OF_NAME_PARTS = 5;
 export declare const ALLOWED_TOKENS: string[];

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/namefully.d.ts

@@ -2,6 +2,7 @@ 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';
 /**
  * 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,7 +80,7 @@ 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. */
@@ -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;

package/dist/types/parser.d.ts

@@ -1,10 +1,11 @@
 import { FullName } from './full-name';
 import { Config } from './config';
+import { NameIndex } from './utils';
 import { Name, JsonName } from './name';
 /**
  * A parser signature that helps to organize the names accordingly.
  */
-export declare abstract class Parser<T = any> {
+export declare abstract class Parser<T = unknown> {
     raw: T;
     /**
      * Constructs a custom parser accordingly.
@@ -15,11 +16,11 @@ export declare abstract class Parser<T = any> {
      * Builds a dynamic `Parser` on the fly and throws a `NameError` when unable
      * to do so. The built parser only knows how to operate birth names.
      */
-    static build(text: string): Parser;
+    static build(text: string, index?: NameIndex): Parser;
     /**
      * Builds asynchronously a dynamic `Parser`.
      */
-    static buildAsync(text: string): Promise<Parser>;
+    static buildAsync(text: string, index?: NameIndex): Promise<Parser>;
     /**
      * Parses the raw data into a `FullName` while considering some options.
      * @param options additional configuration to apply.

package/dist/types/utils.d.ts

@@ -32,7 +32,7 @@ export declare class NameIndex {
     static get min(): number;
     /** The maximum number of parts in a list of names. */
     static get max(): number;
-    private constructor();
+    protected constructor(prefix: number, firstName: number, middleName: number, lastName: number, suffix: number);
     /** The default or base indexing: firstName lastName. */
     static base(): NameIndex;
     /**
@@ -40,6 +40,8 @@ export declare class NameIndex {
      * and their `order` of appearance.
      */
     static when(order: NameOrder, count?: number): NameIndex;
+    static only({ prefix, firstName, middleName, lastName, suffix }: Record<string, number>): NameIndex;
+    toJson(): Record<string, number>;
 }
 /**
  * Capitalizes a string via a `CapsRange` option.