namefully 1.1.0 → 1.2.1

package/dist/types/namefully.d.ts

@@ -0,0 +1,313 @@
+import { Config } from './config';
+import { Name, JsonName } from './name';
+import { Parser } from './parser';
+import { Flat, NameOrder, NameType, Namon, Nullable, Surname } from './types';
+/**
+ * A helper for organizing person names in a particular order, way, or shape.
+ *
+ * Though `namefully` is easy to use, it does not magically guess which part of
+ * the name is what (prefix, suffix, first, last, or middle names). It relies
+ * actually on how the name parts are indicated (i.e., their roles) so that
+ * it can perform internally certain operations and saves us some extra
+ * calculations/processing. In addition, `Namefully` can be created using
+ * distinct raw data shapes. This is intended to give some flexibility to the
+ * developer so that he or she is not bound to a particular data format.
+ * By following closely the API reference to know how to harness its usability,
+ * this utility aims to save time in formatting names.
+ *
+ * `namefully` also works like a trapdoor. Once a raw data is provided and
+ * validated, a developer can only *access* in a vast amount of, yet effective
+ * ways the name info. *No editing* is possible. If the name is mistaken, a new
+ * instance of `Namefully` must be created. In other words, it's immutable.
+ * Remember, this utility's primary objective is to help manipulate a person name.
+ *
+ * Note that the name standards used for the current version of this library
+ * are as follows:
+ *      `[prefix] firstName [middleName] lastName [suffix]`
+ * The opening `[` and closing `]` symbols mean that these parts are optional.
+ * In other words, the most basic and typical case is a name that looks like
+ * 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
+ * for more info on name standards.
+ *
+ * **IMPORTANT**: Keep in mind that the order of appearance (or name order) matters
+ * and may be altered through configured parameters, which will be seen later.
+ * By default, the order of appearance is as shown above and will be used as a
+ * basis for future examples and use cases.
+ *
+ * Once imported, all that is required to do is to create an instance of
+ * `Namefully` and the rest will follow.
+ *
+ * Some terminologies used across the library are:
+ * - namon: 1 piece of name (e.g., first name)
+ * - nama: 2+ pieces of name (e.g., first name + last name)
+ *
+ * Happy name handling 😊!
+ */
+export declare class Namefully {
+    #private;
+    /**
+     * Creates a name with distinguishable parts from a raw string content.
+     * @param names element to parse.
+     * @param options additional settings.
+     *
+     * An optional configuration may be provided with specifics on how to treat
+     * a full name during its course. By default, all name parts are validated
+     * against some basic validation rules to avoid common runtime exceptions.
+     */
+    constructor(names: string | string[] | Name[] | JsonName | Parser, options?: Partial<Config>);
+    /**
+     * Constructs a `Namefully` instance from a text.
+     *
+     * It works like `parse` except that this function returns `null` where `parse`
+     * would throw a `NameError`.
+     */
+    static tryParse(text: string): Namefully | undefined;
+    /**
+     * Constructs a `Namefully` instance from a text.
+     *
+     * It throws a `NameError` if the text cannot be parsed. Use `tryParse`
+     * instead if a `null` return is preferred over a throwable error.
+     *
+     * This operation is computed asynchronously, which gives more flexibility at
+     * the time of catching the error (and stack trace if any). The acceptable
+     * text format is a string composed of two or more name pieces. For instance,
+     * `John Lennon`, or `John Winston Ono Lennon` are parsable names and follow
+     * the basic name standard rules (i.e., first-middle-last).
+     *
+     * Keep in mind that prefix and suffix are not considered during the parsing
+     * process.
+     */
+    static parse(text: string): 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>;
+    /** The firt name part. */
+    get first(): string;
+    /** The first middle name part if any. */
+    get middle(): Nullable<string>;
+    /** 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>;
+    /** The birth name part. */
+    get birth(): string;
+    /** The shortest version of a person name. */
+    get short(): string;
+    /** The longest version of a person name. */
+    get long(): string;
+    /** The entire name set. */
+    get full(): string;
+    /** The first name combined with the last name's initial. */
+    get public(): string;
+    /** Returns the full name as set. */
+    toString(): string;
+    /** Fetches the raw form of a name piece. */
+    get(namon: Namon): Nullable<Name | Name[]>;
+    /** Whether this name is equal to another one from a raw-string perspective. */
+    equal(other: Namefully): boolean;
+    /** Gets a JSON representation of the full name. */
+    toJson(): JsonName;
+    /** Confirms that a name part has been set. */
+    has(namon: Namon): boolean;
+    /**
+     * Gets the full name ordered as configured.
+     *
+     * The name order `orderedBy` forces to order by first or last name by
+     * overriding the preset configuration.
+     *
+     * `Namefully.format` may also be used to alter manually the order of appearance
+     * of full name.
+     *
+     * For example:
+     * ```ts
+     * const name = new Namefully('Jon Stark Snow');
+     * console.log(name.fullName(NameOrder.LAST_NAME)); // "Snow Jon Stark"
+     * console.log(name.format('l f m')); // "Snow Jon Stark"
+     * ```
+     */
+    fullName(orderedBy?: NameOrder): string;
+    /**
+     * Gets the birth name ordered as configured, no `prefix` or `suffix`.
+     *
+     * @param orderedBy forces to order by first or last name by overriding the
+     * preset configuration.
+     */
+    birthName(orderedBy?: NameOrder): string;
+    /**
+     * Gets the first name part of the `FullName`.
+     *
+     * @param withMore determines whether to include other pieces of the first
+     * name.
+     */
+    firstName(withMore?: boolean): string;
+    /** Gets the middle name part of the `FullName`. */
+    middleName(): string[];
+    /**
+     * Gets the last name part of the `FullName`.
+     *
+     * @param format overrides the how-to formatting of a surname output,
+     * considering its sub-parts.
+     */
+    lastName(format?: Surname): string;
+    /**
+     * Gets the initials of the `FullName`.
+     *
+     * @param {options.orderedBy} forces to order by first or last name by
+     * overriding the preset configuration.
+     * @param
+     *
+     * For example, given the names:
+     * - `John Smith` => `['J', 'S']`
+     * - `John Ben Smith` => `['J', 'B', 'S']`.
+     */
+    initials(options?: {
+        orderedBy?: NameOrder;
+        only?: NameType;
+    }): string[];
+    /**
+     * Shortens a complex full name to a simple typical name, a combination of
+     * first and last name.
+     *
+     * @param orderedBy forces to order by first or last name by overriding the
+     * preset configuration.
+     *
+     * For a given name such as `Mr Keanu Charles Reeves`, shortening this name
+     * is equivalent to making it `Keanu Reeves`.
+     *
+     * As a shortened name, the namon of the first name is favored over the other
+     * names forming part of the entire first names, if any. Meanwhile, for
+     * the last name, the configured `surname` is prioritized.
+     *
+     * For a given `FirstName FatherName MotherName`, shortening this name when
+     * the surname is set as `mother` is equivalent to making it:
+     * `FirstName MotherName`.
+     */
+    shorten(orderedBy?: NameOrder): string;
+    /**
+     * Flattens a long name using the name types as variants.
+     *
+     * While @param limit sets a threshold as a limited number of characters
+     * supported to flatten a `FullName`, @param by indicates which variant
+     * to use when doing so. By default, a full name gets flattened by
+     * `Flat.MIDDLE_NAME`.
+     *
+     * The flattening operation is only executed iff there is a valid entry and
+     * it surpasses the limit set. In the examples below, let us assume that the
+     * name goes beyond the limit value.
+     *
+     * Flattening a long name refers to reducing the name to the following forms.
+     * For example, `John Winston Ono Lennon` flattened by:
+     * * Flat.FIRST_NAME: => 'J. Winston Ono Lennon'
+     * * Flat.MIDDLE_NAME: => 'John W. O. Lennon'
+     * * Flat.LAST_NAME: => 'John Winston Ono L.'
+     * * Flat.FIRST_MID: => 'J. W. O. Lennon'
+     * * Flat.MID_LAST: => 'John W. O. L.'
+     * * Flat.ALL: => 'J. W. O. L.'
+     *
+     * With the help of the @param recursive flag, the above operation can happen
+     * recursively in the same order if the name is still too long. For example,
+     * flattening `John Winston Ono Lennon` using the following params:
+     * `flatten({ limit: 18, by: Flat.FIRST_NAME, recursive: true })`
+     * will result in `John W. O. Lennon` and not `J. Winston Ono Lennon`.
+     *
+     * A shorter version of this method is `zip()`.
+     */
+    flatten(options: Partial<{
+        limit: number;
+        by: Flat;
+        withPeriod: boolean;
+        recursive: boolean;
+        withMore: boolean;
+        surname: Surname;
+    }>): string;
+    /**
+     * Zips or compacts a name using different forms of variants.
+     *
+     * @see `flatten()` for more details.
+     */
+    zip(by?: Flat, withPeriod?: boolean): string;
+    /**
+     * Formats the full name as desired.
+     * @param pattern character used to format it.
+     *
+     * string format
+     * -------------
+     * - 'short': typical first + last name
+     * - 'long': birth name (without prefix and suffix)
+     * - 'public': first name combined with the last name's initial.
+     * - 'official': official document format
+     *
+     * char format
+     * -----------
+     * - 'b': birth name
+     * - 'B': capitalized birth name
+     * - 'f': first name
+     * - 'F': capitalized first name
+     * - 'l': last name
+     * - 'L': capitalized last name
+     * - 'm': middle names
+     * - 'M': capitalized middle names
+     * - 'o': official document format
+     * - 'O': official document format in capital letters
+     * - 'p': prefix
+     * - 'P': capitalized prefix
+     * - 's': suffix
+     * - 'S': capitalized suffix
+     *
+     * punctuations
+     * ------------
+     * - '.': period
+     * - ',': comma
+     * - ' ': space
+     * - '-': hyphen
+     * - '_': underscore
+     * - '$': an escape character to select only the initial of the next char.
+     *
+     * Given the name `Joe Jim Smith`, use `format` with the `pattern` string.
+     * - format('l f') => 'Smith Joe'
+     * - format('L, f') => 'SMITH, Joe'
+     * - format('short') => 'Joe Smith'
+     * - format() => 'SMITH, Joe Jim'
+     * - format(r'f $l.') => 'Joe S.'.
+     *
+     * Do note that the escape character is only valid for the birth name parts:
+     * first, middle, and last names.
+     */
+    format(pattern: string): string;
+    /** Flips definitely the name order from the preset/current config. */
+    flip(): void;
+    /**
+     * Splits the name parts of a birth name.
+     * @param separator token for the split.
+     */
+    split(separator?: string | RegExp): string[];
+    /**
+     * Joins the name parts of a birth name.
+     * @param separator token for the junction.
+     */
+    join(separator?: string): string;
+    /** Transforms a birth name into UPPERCASE. */
+    toUpperCase(): string;
+    /** Transforms a birth name into lowercase. */
+    toLowerCase(): string;
+    /** Transforms a birth name into camelCase. */
+    toCamelCase(): string;
+    /** Transforms a birth name into PascalCase. */
+    toPascalCase(): string;
+    /** Transforms a birth name into snake_case. */
+    toSnakeCase(): string;
+    /** Transforms a birth name into hyphen-case. */
+    toHyphenCase(): string;
+    /** Transforms a birth name into dot.case. */
+    toDotCase(): string;
+    /** Transforms a birth name into ToGgLeCaSe. */
+    toToggleCase(): string;
+}

package/dist/types/parser.d.ts

@@ -0,0 +1,41 @@
+import { FullName } from './full-name';
+import { Config } from './config';
+import { Name, JsonName } from './name';
+/**
+ * A parser signature that helps to organize the names accordingly.
+ */
+export declare abstract class Parser<T = any> {
+    raw: T;
+    /**
+     * Constructs a custom parser accordingly.
+     * @param raw data to be parsed
+     */
+    constructor(raw: T);
+    /**
+     * 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;
+    /**
+     * Builds asynchronously a dynamic `Parser`.
+     */
+    static buildAsync(text: string): Promise<Parser>;
+    /**
+     * Parses the raw data into a `FullName` while considering some options.
+     * @param options additional configuration to apply.
+     */
+    abstract parse(options?: Partial<Config>): FullName;
+}
+export declare class StringParser extends Parser<string> {
+    parse(options: Partial<Config>): FullName;
+}
+export declare class ArrayStringParser extends Parser<string[]> {
+    parse(options: Partial<Config>): FullName;
+}
+export declare class NamaParser extends Parser<JsonName> {
+    #private;
+    parse(options: Partial<Config>): FullName;
+}
+export declare class ArrayNameParser extends Parser<Name[]> {
+    parse(options: Partial<Config>): FullName;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Make a type nullable.
+ */
+export type Nullable<T> = T | null | undefined;
+/**
+ * The abbreviation type to indicate whether or not to add period to a prefix
+ * using the American or British way.
+ */
+export declare enum Title {
+    US = "US",
+    UK = "UK"
+}
+/**
+ * An option indicating how to format a surname.
+ *
+ * This enum can be set via `Config` or when creating a `LastName`. As this can
+ * become ambiguous at the time of handling it, the value set in `Config` is
+ * prioritized and viewed as the source of truth for future considerations.
+ */
+export declare enum Surname {
+    FATHER = "father",
+    MOTHER = "mother",
+    HYPHENATED = "hyphenated",
+    ALL = "all"
+}
+/**
+ * The order of appearance of a `FullName`.
+ */
+export declare enum NameOrder {
+    FIRST_NAME = "firstName",
+    LAST_NAME = "lastName"
+}
+/**
+ * The types of name handled in this according the name standards.
+ */
+export declare enum NameType {
+    FIRST_NAME = "firstName",
+    MIDDLE_NAME = "middleName",
+    LAST_NAME = "lastName",
+    BIRTH_NAME = "birthName"
+}
+/**
+ * The possible variants to indicate how to flatten a `FullName`.
+ */
+export declare enum Flat {
+    FIRST_NAME = "firstName",
+    MIDDLE_NAME = "middleName",
+    LAST_NAME = "lastName",
+    FIRST_MID = "firstMid",
+    MID_LAST = "midLast",
+    ALL = "all"
+}
+/**
+ * The range to use when capitalizing a string content.
+ */
+export declare enum CapsRange {
+    NONE = 0,
+    INITIAL = 1,
+    ALL = 2
+}
+/**
+ * The types of name handled in this utility according the name standards.
+ */
+export declare class Namon {
+    readonly index: number;
+    readonly key: string;
+    static readonly PREFIX: Namon;
+    static readonly FIRST_NAME: Namon;
+    static readonly MIDDLE_NAME: Namon;
+    static readonly LAST_NAME: Namon;
+    static readonly SUFFIX: Namon;
+    /**
+     * The list of supported name types.
+     */
+    static readonly values: Namon[];
+    /**
+     * All the predefined name types.
+     */
+    static readonly all: Map<string, Namon>;
+    private constructor();
+    /**
+     * Whether this string key is part of the predefined keys.
+     */
+    static has(key: string): boolean;
+    /**
+     * Makes a string key a namon type.
+     */
+    static cast(key: string): Nullable<Namon>;
+    /**
+     * String representation of this object.
+     */
+    toString(): string;
+    /**
+     * Whether this and the other value are equal.
+     */
+    equal(other: Namon | unknown): boolean;
+}
+/**
+ * The token used to indicate how to split string values.
+ */
+export declare class Separator {
+    readonly name: string;
+    readonly token: string;
+    static readonly COMMA: Separator;
+    static readonly COLON: Separator;
+    static readonly DOUBLE_QUOTE: Separator;
+    static readonly EMPTY: Separator;
+    static readonly HYPHEN: Separator;
+    static readonly PERIOD: Separator;
+    static readonly SEMI_COLON: Separator;
+    static readonly SINGLE_QUOTE: Separator;
+    static readonly SPACE: Separator;
+    static readonly UNDERSCORE: Separator;
+    /**
+     * All the available separators.
+     */
+    static readonly all: Map<string, Separator>;
+    /**
+     * All the available tokens.
+     */
+    static readonly tokens: string[];
+    private constructor();
+    /**
+     * String representation of this object.
+     */
+    toString(): string;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,53 @@
+import { NameOrder, CapsRange } from './types';
+/**
+ * A fixed set of values to handle specific positions for list of names.
+ *
+ * As for list of names, this helps to follow a specific order based on the
+ * count of elements. It is expected that the list has to be between two and
+ * five elements. Also, the order of appearance set in the configuration
+ * influences how the parsing is carried out.
+ *
+ * Ordered by first name, the parser works as follows:
+ * - 2 elements: firstName lastName
+ * - 3 elements: firstName middleName lastName
+ * - 4 elements: prefix firstName middleName lastName
+ * - 5 elements: prefix firstName middleName lastName suffix
+ *
+ * Ordered by last name, the parser works as follows:
+ * - 2 elements: lastName firstName
+ * - 3 elements: lastName firstName middleName
+ * - 4 elements: prefix lastName firstName middleName
+ * - 5 elements: prefix lastName firstName middleName suffix
+ *
+ * For example, `Jane Smith` (ordered by first name) is expected to be indexed:
+ * `['Jane', 'Smith']`.
+ */
+export declare class NameIndex {
+    readonly prefix: number;
+    readonly firstName: number;
+    readonly middleName: number;
+    readonly lastName: number;
+    readonly suffix: number;
+    /** The minimum number of parts in a list of names. */
+    static get min(): number;
+    /** The maximum number of parts in a list of names. */
+    static get max(): number;
+    private constructor();
+    /** The default or base indexing: firstName lastName. */
+    static base(): NameIndex;
+    /**
+     * Gets the name index for a list of names based on the `count` of elements
+     * and their `order` of appearance.
+     */
+    static when(order: NameOrder, count?: number): NameIndex;
+}
+/**
+ * Capitalizes a string via a `CapsRange` option.
+ */
+export declare function capitalize(str: string, range?: CapsRange): string;
+/** Decapitalizes a string via a `CapsRange` option. */
+export declare function decapitalize(str: string, range?: CapsRange): string;
+/** Toggles a string representation. */
+export declare function toggleCase(str: string): string;
+export declare function isStringArray(value?: unknown): boolean;
+export declare function isNameArray(value?: unknown): boolean;

package/dist/types/validator.d.ts

@@ -0,0 +1,57 @@
+import { FirstName, LastName, Name } from './name';
+import { Namon } from './types';
+import { NameIndex } from './utils';
+export interface Validator<T> {
+    validate(value: T): void;
+}
+declare class ArrayValidator<T extends string | Name> implements Validator<T[]> {
+    validate(values: T[]): void;
+}
+declare class NamonValidator implements Validator<string | Name> {
+    #private;
+    static create(): NamonValidator;
+    validate(value: string | Name, type?: Namon): void;
+}
+declare class FirstNameValidator implements Validator<string | FirstName> {
+    #private;
+    static create(): FirstNameValidator;
+    validate(value: string | FirstName): void;
+}
+declare class MiddleNameValidator implements Validator<string | string[] | Name[]> {
+    #private;
+    static create(): MiddleNameValidator;
+    validate(value: string | string[] | Name[]): void;
+}
+declare class LastNameValidator implements Validator<string | LastName> {
+    #private;
+    static create(): LastNameValidator;
+    validate(value: string | LastName): void;
+}
+export declare class NamaValidator implements Validator<Map<Namon, string>> {
+    #private;
+    static create(): NamaValidator;
+    validate(value: Map<Namon, string>): void;
+    validateKeys(nama: Map<Namon, string>): void;
+}
+export declare class ArrayStringValidator extends ArrayValidator<string> {
+    readonly index: NameIndex;
+    constructor(index?: NameIndex);
+    validate(values: string[]): void;
+    validateIndex(values: string[]): void;
+}
+export declare class ArrayNameValidator implements Validator<Name[]> {
+    #private;
+    static create(): ArrayNameValidator;
+    validate(value: Name[]): void;
+}
+/** A list of validators for a specific namon. */
+export declare abstract class Validators {
+    static namon: NamonValidator;
+    static nama: NamaValidator;
+    static prefix: NamonValidator;
+    static firstName: FirstNameValidator;
+    static middleName: MiddleNameValidator;
+    static lastName: LastNameValidator;
+    static suffix: NamonValidator;
+}
+export {};