import { Config } from './config.js';
import { SerializedName } from './data.js';
import { Name, JsonName } from './name.js';
import { NameIndex } from './utils.js';
import { Flat, NameOrder, NameType, Namon, Nullable, Surname, Separator, Title } from './types.js';
import { Parser } from './parser.js';
/**
 * A utility for organizing human names in a particular order, way, or shape.
 *
 * Though `namefully` is designed to be 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. Additionally, `Namefully` objects may be created using
 * distinct raw data shapes. This is intended to give some flexibility to you
 * so that you are not bound to a particular data format (e.g., string).
 * Follow the API reference to know how to harness its usability as this utility
 * aims to save time in formatting names.
 *
 * `namefully` also works like a trapdoor. Once some name data is provided and
 * validated, you may only *access* it but not update any part of it. This
 * means that *no editing* is possible. If the name is mistaken, a new
 * instance of `Namefully` must be created. In simple terms, it's immutable.
 * Remember, this utility's primary objective is to help manipulate human names,
 * not the opposite.
 *
 * Note that the name standards used for the current version of this utility are
 * as follows:
 *      `[prefix] firstName [middleName] lastName [suffix]`
 * where the opening `[` and closing `]` brackets 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 {@link 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
 * and may be altered through configurable 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 instances of `Namefully`
 * as you see fit and the rest will follow.
 *
 * Some terminologies used across the library are:
 * - namon: 1 piece of name (e.g., prefix)
 * - nama: a combination of 2+ pieces of name (e.g., first name + last name)
 *
 * Happy name handling 😊!
 */
export declare class Namefully {
    #private;
    /**
     * Creates a name with distinguishable parts.
     * @param names element to parse.
     * @param options additional settings.
     *
     * Optional parameters may be provided with specifics on how to treat a full
     * name during its existence. All name parts must have at least one (1) character
     * to proceed. That is the only requirement/validation of namefully.
     */
    constructor(names: string | string[] | Name[] | JsonName | Parser, options?: NameOptions);
    /**
     * Constructs a `Namefully` instance from a text.
     *
     * It works like `parse` except that this function returns `undefined` when
     * `parse` would throw a `NameError`.
     */
    static tryParse(text: string, index?: NameIndex): Namefully | undefined;
    /**
     * Constructs a `Namefully` instance from a text.
     *
     * @throws a `NameError` if the @param 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, index?: NameIndex): Promise<Namefully>;
    /** The configuration dictating this name's behavior. */
    get config(): Config;
    /** Whether the name is a single word name. */
    get isMono(): boolean;
    /** The number of characters of the `birthName`, including spaces. */
    get length(): number;
    /** The prefix part of the name set. */
    get prefix(): string | undefined;
    /** The firt name part of the name set. */
    get first(): string;
    /** The first middle name part of the name set if any. */
    get middle(): string | undefined;
    /** Returns true if any middle name has been set. */
    get hasMiddle(): boolean;
    /** The last name part of the name set. */
    get last(): string;
    /** The suffix part of the name set. */
    get suffix(): string | undefined;
    /** The birth name part of the name set. */
    get birth(): string;
    /** The shortest version of a human name (first + last name). */
    get short(): string;
    /** The longest version of a human name (a.k.a birth name). */
    get long(): string;
    /** The entire name set. */
    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 an iterable of the name components in their natural form.
     *
     * Regardless of the order of appearance, this method will always return the
     * existing `Name`s according to the name standards upon which this library
     * is based.
     *
     * This is useful for iterating over the name parts in a consistent manner and
     * this automatically enables operations such as mapping, filtering, etc.
     */
    get parts(): Iterable<Name>;
    /** The number of name components. */
    get size(): number;
    /**
     * Makes the name set iterable (i.e., for-of statements).
     *
     * This is similar to `parts` with the exception that all name components are
     * returned as `Name` classes (instead of their natural form - e.g., `FirstName`)
     * to maintain certain homogeneity and consistency across each name piece.
     */
    [Symbol.iterator](): Iterator<Name>;
    /** Gets a string representation of the full name. */
    toString(): string;
    /** Fetches the raw form of a name piece. */
    get(key: Namon | string): Nullable<Name | Name[]>;
    /** Whether this name is equal to another one from a raw-string perspective. */
    equal(other: Namefully): boolean;
    /** Whether this name is equal to another one from a component perspective. */
    deepEqual(other: Namefully): boolean;
    /** Gets a JSON representation of the full name. */
    toJson(): JsonName;
    json: () => JsonName;
    /** Confirms whether a name component exists. */
    has(namon: Namon | string): boolean;
    /**
     * Gets the full name ordered as configured.
     *
     * @param {NameOrder} orderedBy forces to arrange a name set by first or last
     * name, overriding the preset configuration.
     *
     * `Namefully.format()` may also be used to alter manually the order of appearance
     * of a 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?: NameOptions['orderedBy']): 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?: NameOptions['orderedBy']): string;
    /**
     * Gets the first name part of the `FullName`.
     * @param {boolean} 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 {Surname} format overrides the how-to formatting of a surname output,
     * considering its sub-parts.
     */
    lastName(format?: NameOptions['surname']): string;
    /**
     * Gets the initials of the `FullName`.
     *
     * @param {object} options when getting the initials.
     * @param {NameOrder} options.orderedBy forces to order by first or last name by
     * overriding the preset configuration.
     * @param {NameType} options.only selects initials of only certain name parts.
     * @param {boolean} options.asJson whether to return initials as an array or JSON.
     *
     * For example, given the names:
     * - `John Smith` => `['J', 'S']`
     * - `John Ben Smith` => `['J', 'B', 'S']`.
     */
    initials(options?: {
        orderedBy?: NameOptions['orderedBy'];
        only?: NameType | 'firstName' | 'lastName' | 'middleName' | 'birthName';
        asJson?: boolean;
    }): string[] | Record<string, string[]>;
    /**
     * Shortens a complex full name to a simple typical name, a combination of
     * first and last name.
     *
     * @param {NameOrder} orderedBy forces to order by first or last name, 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?: NameOptions['orderedBy']): string;
    /**
     * Flattens long names 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 | 'firstName' | 'lastName' | 'middleName' | 'birthName' | 'firstMid' | 'midLast' | 'all' | '*';
        withPeriod: boolean;
        recursive: boolean;
        withMore: boolean;
        surname: NameOptions['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 {string} 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
     * - '$': 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 or swaps 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 {string} 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;
    /**
     * Serializes this Namefully instance to a JSON object.
     *
     * This includes both the name data (with full hierarchy for FirstName and LastName)
     * and the configuration, allowing for complete reconstruction of the Namefully instance.
     *
     * @returns a JSON-serializable object containing name data and config.
     */
    serialize(): SerializedName;
}
/**
 * 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?: NameOptions) => Namefully;
export default _default;
/** Optional namefully parameters (@see {@linkcode Config} for more details). */
export type NameOptions = Partial<{
    name: string;
    orderedBy: NameOrder | 'firstName' | 'lastName';
    separator: Separator;
    title: Title | 'UK' | 'US';
    ending: boolean;
    bypass: boolean;
    surname: Surname | 'father' | 'mother' | 'hyphenated' | 'all';
    mono: boolean | Namon;
}>;