namefully 1.1.0 → 1.2.0

package/dist/lib/src/full-name.d.ts

@@ -0,0 +1,71 @@
+import { Config } from './config';
+import { FirstName, LastName, Name, JsonName } from './name';
+import { Nullable, Namon } from './types';
+/**
+ * The core component of this utility.
+ *
+ * This component is comprised 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
+ * 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.
+ *
+ * Additionally, an optional configuration can be used to indicate some specific
+ * behaviors related to that name handling.
+ */
+export declare class FullName {
+    private _prefix;
+    private _firstName;
+    private _middleName;
+    private _lastName;
+    private _suffix;
+    private _config;
+    /**
+     * Creates a full name as it goes
+     * @param options optional configuration for additional features.
+     */
+    constructor(options?: Partial<Config>);
+    /**
+     * A snapshot of the configuration used to set up this full name.
+     */
+    get config(): Config;
+    /**
+     * The prefix part of the full name.
+     */
+    get prefix(): Nullable<Name>;
+    /**
+     * The first name part of the full name.
+     */
+    get firstName(): FirstName;
+    /**
+     * The last name part of the full name.
+     */
+    get lastName(): LastName;
+    /**
+     * The middle name part of the full name.
+     */
+    get middleName(): Name[];
+    /**
+     * The suffix part of the full name.
+     */
+    get suffix(): Nullable<Name>;
+    setPrefix(name: Nullable<string | Name>): FullName;
+    setFirstName(name: string | FirstName): 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.
+     */
+    has(namon: Namon): boolean;
+    /**
+     * Parses a json name into a full name.
+     * @param json parsable name element
+     * @param config optional configuration for additional features.
+     */
+    static parse(json: JsonName, config?: Config): FullName;
+}

package/dist/lib/src/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Welcome to namefully!
+ *
+ * `namefully` is a JavaScript utility for handing person names.
+ *
+ * Sources
+ * - repo: https://github.com/ralflorent/namefully
+ * - docs: https://namefully.netlify.app
+ * - npm: https://npmjs.com/package/namefully
+ *
+ * @license MIT
+ */
+export * from './config';
+export * from './error';
+export * from './full-name';
+export * from './name';
+export * from './namefully';
+export { Parser } from './parser';
+export * from './types';
+export { NameIndex } from './utils';

package/dist/lib/src/name.d.ts

@@ -0,0 +1,177 @@
+import { CapsRange, Namon, Surname } from './types';
+/**
+ * Representation of a string type name with some extra capabilities.
+ */
+export declare class Name {
+    readonly type: Namon;
+    private namon;
+    protected initial: string;
+    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
+     * treated accordingly.
+     * @param capsRange determines how the name should be capitalized initially.
+     */
+    constructor(value: string, type: Namon, capsRange?: CapsRange);
+    set value(newValue: string);
+    /**
+     * The piece of string treated as a name.
+     */
+    get value(): string;
+    /**
+     * The length of the name.
+     */
+    get length(): number;
+    /**
+     * Whether the name is a prefix.
+     */
+    get isPrefix(): boolean;
+    /**
+     * Whether the name is a first name.
+     */
+    get isFirstName(): boolean;
+    /**
+     * Whether the name is a middle name.
+     */
+    get isMiddleName(): boolean;
+    /**
+     * Whether the name is a last name.
+     */
+    get isLastName(): boolean;
+    /**
+     * Whether the name is a suffix.
+     */
+    get isSuffix(): boolean;
+    /**
+     * Creates a prefix.
+     */
+    static prefix(value: string): Name;
+    /**
+     * Creates a first name.
+     */
+    static first(value: string): Name;
+    /**
+     * Creates a middle name.
+     */
+    static middle(value: string): Name;
+    /**
+     * Creates a last name.
+     */
+    static last(value: string): Name;
+    /**
+     * Creates a suffix.
+     */
+    static suffix(value: string): Name;
+    /**
+     * Gets the initials (first character) of this name.
+     */
+    initials(): string[];
+    /**
+     * String representation of this object.
+     */
+    toString(): string;
+    /**
+     * Returns true if the other is equal to this name.
+     */
+    equal(other: Name | unknown): boolean;
+    /**
+     * Capitalizes the name.
+     */
+    caps(range?: CapsRange): Name;
+    /**
+     * De-capitalizes the name.
+     */
+    decaps(range?: CapsRange): Name;
+}
+/**
+ * Representation of a first name with some extra functionality.
+ */
+export declare class FirstName extends Name {
+    private _more;
+    /**
+     * 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,
+     * `more` provides the freedom to do it as it pleases.
+     */
+    constructor(value: string, ...more: string[]);
+    /**
+     * Determines whether a first name has `more` name parts.
+     */
+    get hasMore(): boolean;
+    get length(): number;
+    /**
+     * Returns a combined version of the `value` and `more` if any.
+     */
+    get asNames(): Name[];
+    /**
+     * The additional name parts of the first name.
+     */
+    get more(): string[];
+    toString(withMore?: boolean): string;
+    initials(withMore?: boolean): string[];
+    caps(range?: CapsRange): FirstName;
+    decaps(range?: CapsRange): FirstName;
+    /**
+     * Makes a copy of the current name.
+     */
+    copyWith(values?: {
+        first?: string;
+        more?: string[];
+    }): FirstName;
+}
+/**
+ * Representation of a last name with some extra functionality.
+ */
+export declare class LastName extends Name {
+    readonly format: Surname;
+    private _mother?;
+    /**
+     * 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.
+     */
+    constructor(father: string, mother?: string, format?: Surname);
+    /**
+     * The surname inherited from a father side.
+     */
+    get father(): string;
+    /**
+     * The surname inherited from a mother side.
+     */
+    get mother(): string | undefined;
+    /**
+     * Returns `true` if the mother's surname is defined.
+     */
+    get hasMother(): boolean;
+    get length(): number;
+    /**
+     * Returns a combined version of the `father` and `mother` if any.
+     */
+    get asNames(): Name[];
+    toString(format?: Surname): string;
+    initials(format?: Surname): string[];
+    caps(range?: CapsRange): LastName;
+    decaps(range?: CapsRange): LastName;
+    /**
+     * Makes a copy of the current name.
+     */
+    copyWith(values?: {
+        father?: string;
+        mother?: string;
+        format?: Surname;
+    }): LastName;
+}
+/**
+ * JSON signature for `FullName` data.
+ */
+export interface JsonName {
+    prefix?: string;
+    firstName: string;
+    middleName?: string[];
+    lastName: string;
+    suffix?: string;
+}

package/dist/lib/src/namefully.d.ts

@@ -0,0 +1,379 @@
+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 {
+    /**
+     * A copy of high-quality name data.
+     */
+    private _fullName;
+    /**
+     * A copy of the default configuration (combined with a custom one if any).
+     */
+    private _config;
+    /**
+     * 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.
+     */
+    get first(): string;
+    /**
+     * The first middle name if any.
+     */
+    get middle(): Nullable<string>;
+    /**
+     * Returns true if any middle name has been set.
+     */
+    get hasMiddle(): boolean;
+    /**
+     * The last name.
+     */
+    get last(): string;
+    /**
+     * The suffix part.
+     */
+    get suffix(): Nullable<string>;
+    /**
+     * The birth name.
+     */
+    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:
+     * ```typescript
+     * 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;
+    private build;
+    private toParser;
+    private map;
+}

package/dist/lib/src/parser.d.ts

@@ -0,0 +1,46 @@
+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);
+    /**
+     * Parses the raw data into a `FullName` while considering some options.
+     * @param options additional configuration to apply.
+     */
+    abstract parse(options?: Partial<Config>): FullName;
+    /**
+     * 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>;
+}
+export declare class StringParser extends Parser<string> {
+    constructor(raw: string);
+    parse(options: Partial<Config>): FullName;
+}
+export declare class ArrayStringParser extends Parser<string[]> {
+    constructor(raw: string[]);
+    parse(options: Partial<Config>): FullName;
+    private split;
+}
+export declare class NamaParser extends Parser<JsonName> {
+    constructor(raw: JsonName);
+    parse(options: Partial<Config>): FullName;
+    private asNama;
+}
+export declare class ArrayNameParser extends Parser<Name[]> {
+    constructor(raw: Name[]);
+    parse(options: Partial<Config>): FullName;
+}