name-tools 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,796 @@
+/**
+ * Combined list of all particles
+ */
+declare const PARTICLES: readonly string[];
+/**
+ * Multi-word particles that should be kept together
+ * These are checked before single-word particles
+ */
+declare const MULTI_WORD_PARTICLES: readonly ["von und zu", "de la", "de los", "de las", "van der", "van den", "van de", "de le", "da la"];
+/**
+ * Check if a string is a known surname particle
+ */
+declare function isParticle(str: string): boolean;
+/**
+ * Check if a sequence of words forms a multi-word particle
+ */
+declare function isMultiWordParticle(words: string[]): string | null;
+
+/**
+ * Combined list of common surnames
+ */
+declare const COMMON_SURNAMES: readonly string[];
+/**
+ * Common first names to avoid false positives
+ * (names that could be either first or last)
+ */
+declare const COMMON_FIRST_NAMES: readonly ["mary", "john", "william", "james", "anne", "sarah", "marie", "jean", "george", "paul", "lee", "billy", "bob", "thomas", "robert", "michael", "david", "martin", "pierre", "maria", "jose", "josé"];
+/**
+ * Check if a string is a known common surname
+ */
+declare function isCommonSurname(str: string): boolean;
+/**
+ * Check if a string is a common first name
+ */
+declare function isCommonFirstName(str: string): boolean;
+
+/**
+ * The kind of entity detected in a name field
+ */
+type NameKind = 'person' | 'family' | 'household' | 'compound' | 'organization' | 'unknown' | 'rejected';
+/**
+ * Confidence level in classification (0 = no confidence, 1 = certain)
+ */
+type Confidence = 0 | 0.25 | 0.5 | 0.75 | 1;
+/**
+ * Machine-readable reason codes explaining classification decisions
+ */
+type ReasonCode = 'ORG_LEGAL_SUFFIX' | 'ORG_COMMA_LEGAL' | 'ORG_INSTITUTION_PHRASE' | 'ORG_DBA' | 'ORG_CARE_OF' | 'ORG_WEAK_KEYWORD' | 'FAMILY_ENDS_WITH_FAMILY' | 'FAMILY_STARTS_WITH_THE' | 'FAMILY_PLURAL_SURNAME' | 'FAMILY_HAS_FAMILY_WORD' | 'COMPOUND_CONNECTOR' | 'COMPOUND_SHARED_FAMILY' | 'COMPOUND_PAIRED_HONORIFIC' | 'COMPOUND_PLURAL_HONORIFIC' | 'PERSON_STANDARD_FORMAT' | 'PERSON_REVERSED_FORMAT' | 'PERSON_HAS_HONORIFIC' | 'PERSON_HAS_SUFFIX' | 'AMBIGUOUS_THE_PLURAL' | 'AMBIGUOUS_SHORT_NAME' | 'HAS_PUNCTUATION_SIGNALS' | 'HAS_PAREN_ANNOTATION' | 'HAS_ALLCAPS' | 'HAS_EMAIL_OR_HANDLE' | 'HAS_ROLE_OR_TITLE';
+/**
+ * Metadata about the parsing process
+ */
+interface ParseMeta {
+    /** Exact input string */
+    raw: string;
+    /** Normalized string used for parsing */
+    normalized: string;
+    /** Overall confidence in classification */
+    confidence: Confidence;
+    /** Reason codes explaining the classification */
+    reasons: ReasonCode[];
+    /** Human-readable warnings */
+    warnings?: string[];
+    /** Locale hint (default: "en") */
+    locale?: string;
+}
+/**
+ * Base interface for all entity types
+ */
+interface BaseEntity {
+    kind: NameKind;
+    meta: ParseMeta;
+}
+/**
+ * Legal form suffixes for organizations
+ */
+type LegalForm = 'Inc' | 'Incorporated' | 'Corp' | 'Corporation' | 'LLC' | 'LLP' | 'LP' | 'Ltd' | 'Limited' | 'PLC' | 'GmbH' | 'SA' | 'SAS' | 'BV' | 'AG' | 'Oy' | 'SRL' | 'SpA' | 'Trust' | 'TrustCompany' | 'Bank' | 'CreditUnion' | 'Foundation' | 'University' | 'Hospital' | 'Church' | 'Government' | 'Nonprofit' | 'Company' | 'Co' | 'UnknownLegalForm';
+/**
+ * Organization entity (company, institution, trust, etc.)
+ */
+interface OrganizationName extends BaseEntity {
+    kind: 'organization';
+    /** Base name without legal suffix */
+    baseName: string;
+    /** Detected legal form */
+    legalForm?: LegalForm;
+    /** Raw legal suffix as written */
+    legalSuffixRaw?: string;
+    /** Additional qualifiers ("of", "for", etc.) */
+    qualifiers?: string[];
+    /** Alternate names (d/b/a) */
+    aka?: string[];
+}
+/**
+ * Style of family name
+ */
+type FamilyStyle = 'familyWord' | 'pluralSurname';
+/**
+ * Family or household entity
+ */
+interface FamilyName extends BaseEntity {
+    kind: 'family' | 'household';
+    /** Leading article if present */
+    article?: 'The';
+    /** Core family/surname */
+    familyName: string;
+    /** How the family was expressed */
+    style: FamilyStyle;
+    /** The word used (Family, Household) */
+    familyWord?: 'Family' | 'Household';
+}
+/**
+ * Connector used in compound names
+ */
+type CompoundConnector = '&' | 'and' | '+' | 'et' | 'unknown';
+/**
+ * Compound entity (multiple people in one field)
+ */
+interface CompoundName extends BaseEntity {
+    kind: 'compound';
+    /** The connector detected */
+    connector: CompoundConnector;
+    /** Parsed members (may be PersonName or UnknownName) */
+    members: Array<PersonName | UnknownName>;
+    /** Shared family name if inferred */
+    sharedFamily?: string;
+}
+/**
+ * Person entity (individual human)
+ */
+interface PersonName extends BaseEntity {
+    kind: 'person';
+    /** Title/honorific (Dr., Mr., etc.) */
+    honorific?: string;
+    /** Given/first name */
+    given?: string;
+    /** Full given name if explicitly provided (e.g. from parenthetical: "Thomas A. (Thomas Alva) Edison") */
+    fullGiven?: string;
+    /** Middle name(s) */
+    middle?: string;
+    /** Family/last name */
+    family?: string;
+    /** Suffix (Jr., PhD, etc.) */
+    suffix?: string;
+    /** Nickname */
+    nickname?: string;
+    /** Surname particles (von, de, etc.) */
+    particles?: string[];
+    /** Whether name was in reversed format */
+    reversed?: boolean;
+}
+/**
+ * Unknown entity (could not be classified)
+ */
+interface UnknownName extends BaseEntity {
+    kind: 'unknown';
+    /** Best-effort normalized text */
+    text: string;
+    /** Best guess at what it might be */
+    guess?: Exclude<NameKind, 'unknown' | 'rejected'>;
+}
+/**
+ * Rejected entity (strict mode rejection)
+ */
+interface RejectedName extends BaseEntity {
+    kind: 'rejected';
+    /** What kind it would have been classified as */
+    rejectedAs: Exclude<NameKind, 'rejected'>;
+}
+/**
+ * Union of all entity types returned by parseName
+ */
+type ParsedNameEntity = PersonName | FamilyName | CompoundName | OrganizationName | UnknownName | RejectedName;
+/**
+ * Options for parseName
+ */
+interface ParseOptions {
+    /** Locale hint (default: "en") */
+    locale?: string;
+    /** If set, reject non-person entities */
+    strictKind?: 'person';
+}
+/**
+ * Parsed recipient from a list (email To/CC line)
+ */
+interface ParsedRecipient {
+    /** Original raw string */
+    raw: string;
+    /** Parsed display name */
+    display?: ParsedNameEntity;
+    /** Extracted email address */
+    email?: string;
+    /** Raw address string before normalization */
+    addressRaw?: string;
+    /** Metadata about parsing */
+    meta: {
+        confidence: Confidence;
+        reasons: ReasonCode[];
+        warnings?: string[];
+    };
+}
+/**
+ * Options for parseNameList
+ */
+interface ParseListOptions extends ParseOptions {
+}
+/**
+ * Represents a person's name broken down into its component parts
+ */
+type NameAffixTokenType = 'honorific' | 'style' | 'religious' | 'military' | 'judicial' | 'professional' | 'education' | 'generational' | 'dynasticNumber' | 'postnominalHonor' | 'other';
+interface NameAffixToken {
+    type: NameAffixTokenType;
+    value: string;
+    normalized?: string;
+    entryId?: string;
+    canonicalShort?: string;
+    canonicalLong?: string;
+    isAbbrev?: boolean;
+    requiresCommaBefore?: boolean;
+}
+type NameTokenType = 'prefix' | 'given' | 'middle' | 'family' | 'particle' | 'suffix' | 'nickname' | 'literal';
+interface NameToken {
+    type: NameTokenType;
+    value: string;
+    normalized?: string;
+    noBreakAfter?: boolean;
+    noBreakBefore?: boolean;
+}
+interface ParsedName {
+    prefix?: string;
+    first?: string;
+    fullGiven?: string;
+    middle?: string;
+    last?: string;
+    suffix?: string;
+    nickname?: string;
+    prefixTokens?: NameAffixToken[];
+    suffixTokens?: NameAffixToken[];
+    familyParts?: string[];
+    familyParticle?: string;
+    familyParticleBehavior?: 'attach' | 'separate' | 'localeDefault';
+    preferredGiven?: string;
+    sort?: {
+        key?: string;
+        display?: string;
+    };
+    tokens?: NameToken[];
+}
+type NamePreset = 'display' | 'informal' | 'formalFull' | 'formalShort' | 'expandedFull' | 'alphabetical' | 'library' | 'initialed' | 'firstOnly' | 'preferredFirst' | 'preferredDisplay';
+type NameFormatOptions = {
+    preset?: NamePreset;
+    locale?: string | string[];
+    output?: 'text' | 'html';
+    typography?: 'plain' | 'ui' | 'fine';
+    noBreak?: 'none' | 'smart' | 'all';
+    join?: 'none' | 'list' | 'couple';
+    conjunction?: 'and' | '&' | string;
+    oxfordComma?: boolean;
+    shareLastName?: 'auto' | 'never' | 'whenSame';
+    sharePrefix?: 'auto' | 'never' | 'whenSame';
+    shareSuffix?: 'auto' | 'never' | 'whenSame';
+    prefer?: 'auto' | 'nickname' | 'first' | 'fullGiven';
+    middle?: 'full' | 'initial' | 'none';
+    prefix?: 'include' | 'omit' | 'auto';
+    suffix?: 'include' | 'omit' | 'auto';
+    order?: 'given-family' | 'family-given' | 'auto';
+    prefixForm?: 'short' | 'long' | 'asInput';
+    suffixForm?: 'short' | 'long' | 'asInput';
+    capitalization?: 'canonical' | 'preserve' | 'lower' | 'upper';
+    punctuation?: 'canonical' | 'strip' | 'preserve';
+    apostrophes?: 'canonical' | 'ascii' | 'preserve';
+};
+
+/**
+ * Parse a name string into a classified entity
+ *
+ * This is the main entry point for name parsing. It classifies the input as:
+ * - person: Individual human name
+ * - organization: Company, institution, trust, etc.
+ * - family: Family or household (e.g., "The Smith Family")
+ * - compound: Multiple people (e.g., "Bob & Mary Smith")
+ * - unknown: Could not be classified
+ * - rejected: Strict mode rejection
+ *
+ * @param input - The name string to parse
+ * @param options - Parsing options
+ * @returns Classified entity with metadata
+ */
+declare function parseName(input: string, options?: ParseOptions): ParsedNameEntity;
+/**
+ * Parse a full name string into its component parts using international name parsing rules
+ * (Legacy function for internal use by formatName)
+ *
+ * Supports:
+ * - Surname particles (van, von, de, da, etc.)
+ * - Compound surnames (García Márquez)
+ * - Nicknames in quotes or parentheses
+ * - Complex suffixes and titles
+ *
+ * @param fullName - The full name to parse
+ * @returns Object containing parsed name components
+ * @internal
+ */
+declare function parsePersonName(fullName: string): ParsedName;
+/**
+ * Extract first name from a full name
+ * Uses the legacy person parser for compatibility
+ */
+declare function getFirstName(fullName: string): string | undefined;
+/**
+ * Extract last name from a full name
+ * Uses the legacy person parser for compatibility
+ */
+declare function getLastName(fullName: string): string | undefined;
+/**
+ * Extract nickname from a full name
+ * Uses the legacy person parser for compatibility
+ */
+declare function getNickname(fullName: string): string | undefined;
+/**
+ * Convert a ParsedNameEntity to a ParsedName (legacy format)
+ * Useful for formatName compatibility when working with new API
+ */
+declare function entityToLegacy(entity: ParsedNameEntity): ParsedName | null;
+
+/**
+ * Recipient list parsing for To/CC lines and bulk input
+ */
+
+/**
+ * Parse a recipient list (To/CC line or bulk input)
+ *
+ * @param input - The recipient list string
+ * @param options - Parsing options
+ * @returns Array of parsed recipients
+ */
+declare function parseNameList(input: string, options?: ParseListOptions): ParsedRecipient[];
+
+/**
+ * Classify a name string into an entity type
+ * Priority order:
+ * 1. Organization (legal suffixes, institution phrases override everything)
+ * 2. Compound (& / and / + connectors with name-like tokens)
+ * 3. Family/Household ("Family" word, "The" + plural surname)
+ * 4. Person (standard and reversed formats)
+ * 5. Unknown (fallback)
+ */
+declare function classifyName(input: string, options?: ParseOptions): ParsedNameEntity;
+/**
+ * Check if an entity is a person
+ */
+declare function isPerson(entity: ParsedNameEntity): entity is PersonName;
+/**
+ * Check if an entity is an organization
+ */
+declare function isOrganization(entity: ParsedNameEntity): entity is OrganizationName;
+/**
+ * Check if an entity is a family
+ */
+declare function isFamily(entity: ParsedNameEntity): entity is FamilyName;
+/**
+ * Check if an entity is a compound
+ */
+declare function isCompound(entity: ParsedNameEntity): entity is CompoundName;
+/**
+ * Check if an entity is unknown
+ */
+declare function isUnknown(entity: ParsedNameEntity): entity is UnknownName;
+/**
+ * Check if an entity was rejected (strict mode)
+ */
+declare function isRejected(entity: ParsedNameEntity): entity is RejectedName;
+
+type FormatInput = string | ParsedName | ParsedNameEntity;
+/**
+ * Public formatting entry point (single name or array of names).
+ *
+ * Accepts:
+ * - string: Will be parsed as a person name
+ * - ParsedName: Legacy parsed name object
+ * - ParsedNameEntity: Entity from parseName() (person, organization, family, compound, etc.)
+ * - Array of any of the above
+ */
+declare function formatName(input: FormatInput | Array<FormatInput>, options?: NameFormatOptions): string;
+
+/**
+ * Pronoun role - the grammatical function of the pronoun
+ */
+type PronounRole = 'subject' | 'object' | 'possessiveDeterminer' | 'possessivePronoun' | 'reflexive';
+/**
+ * A complete set of pronouns for all grammatical roles.
+ *
+ * Fields are intentionally explicit for legal document and template generation.
+ */
+interface PronounSet {
+    /** Stable identifier (e.g., "he", "she", "they", "ze-hir") */
+    id: string;
+    /** Short human-readable label (e.g., "he/him", "she/her", "they/them") */
+    label: string;
+    /** Subjective case: he, she, they, ze */
+    subject: string;
+    /** Objective case: him, her, them, zir */
+    object: string;
+    /** Possessive determiner: his, her, their (as in "their book") */
+    possessiveDeterminer: string;
+    /** Possessive pronoun: his, hers, theirs (as in "the book is theirs") */
+    possessivePronoun: string;
+    /** Reflexive: himself, herself, themselves */
+    reflexive: string;
+    /** Optional notes about usage */
+    notes?: string;
+}
+/**
+ * Capitalization options for formatting pronouns
+ */
+type Capitalization = 'lower' | 'title' | 'upper';
+/**
+ * Options for formatting pronouns
+ */
+interface FormatOptions {
+    /** How to capitalize the pronoun (default: 'lower') */
+    capitalization?: Capitalization;
+}
+/**
+ * Result of extracting pronouns from a name string
+ */
+interface PronounExtractionResult {
+    /** The name with pronouns removed */
+    name: string;
+    /** Extracted pronoun set, if found */
+    pronouns?: PronounSet;
+    /** Raw pronoun spec as written (e.g., "they/them") */
+    rawPronounSpec?: string;
+}
+
+/**
+ * Built-in pronoun sets commonly in use.
+ *
+ * Includes standard pronouns (he, she, they, it), common neopronouns,
+ * and special pseudo-sets for "any pronouns" and "use name only".
+ */
+declare const BUILT_IN_PRONOUNS: Record<string, PronounSet>;
+/**
+ * Alias map for common shorthand specs.
+ *
+ * Maps normalized input strings to built-in pronoun set IDs.
+ * Handles variations like "He/Him", "he/his", "she/hers", etc.
+ */
+declare const SPEC_ALIASES: Record<string, string>;
+
+/**
+ * Parse a slash-separated pronoun spec into a PronounSet.
+ *
+ * Supports various formats:
+ * - 2 tokens: "he/him" → subject, object (others derived)
+ * - 3 tokens: "she/her/hers" → subject, object, possessive
+ * - 4 tokens: "they/them/their/theirs" → full set minus reflexive
+ * - 5 tokens: "ze/zir/zir/zirs/zirself" → fully specified
+ *
+ * @param spec - The pronoun specification string
+ * @returns A complete PronounSet
+ * @throws Error if the spec is invalid (empty or no tokens)
+ */
+declare function parsePronounSpec(spec: string): PronounSet;
+/**
+ * Get a PronounSet by ID or shorthand specification.
+ *
+ * This is the main entry point for pronoun lookup. Accepts:
+ * - Built-in IDs: "he", "she", "they", "ze-hir", etc.
+ * - Common specs: "he/him", "she/her", "they/them", etc.
+ * - Custom specs: "ey/em/eir/eirs/emself"
+ * - An existing PronounSet (returns a copy)
+ *
+ * @param input - A pronoun ID, spec string, or existing PronounSet
+ * @returns A complete PronounSet
+ * @throws Error if input is empty or invalid
+ *
+ * @example
+ * ```typescript
+ * const hePronouns = getPronounSet('he');
+ * const shePronouns = getPronounSet('she/her');
+ * const theyPronouns = getPronounSet('they/them');
+ * const customPronouns = getPronounSet('xe/xem/xyr/xyrs/xemself');
+ * ```
+ */
+declare function getPronounSet(input: string | PronounSet): PronounSet;
+
+/**
+ * Get a single pronoun from a set, with optional capitalization.
+ *
+ * @param set - The pronoun set to extract from
+ * @param role - Which grammatical role to get
+ * @param options - Formatting options
+ * @returns The formatted pronoun string
+ *
+ * @example
+ * ```typescript
+ * const pronouns = getPronounSet('she');
+ * formatPronoun(pronouns, 'subject', { capitalization: 'title' }); // "She"
+ * formatPronoun(pronouns, 'object');                               // "her"
+ * formatPronoun(pronouns, 'reflexive', { capitalization: 'upper' }); // "HERSELF"
+ * ```
+ */
+declare function formatPronoun(set: PronounSet, role: PronounRole, options?: FormatOptions): string;
+/**
+ * Fill pronoun placeholders in a template string.
+ *
+ * Supported placeholders:
+ * - `{{subject}}` - subjective pronoun (he, she, they)
+ * - `{{object}}` - objective pronoun (him, her, them)
+ * - `{{possDet}}` or `{{possessiveDeterminer}}` - possessive determiner (his, her, their)
+ * - `{{possPron}}` or `{{possessivePronoun}}` - possessive pronoun (his, hers, theirs)
+ * - `{{reflexive}}` - reflexive pronoun (himself, herself, themselves)
+ *
+ * @param template - The template string with placeholders
+ * @param set - The pronoun set to use for replacements
+ * @param options - Formatting options (capitalization applies to all replacements)
+ * @returns The filled template string
+ *
+ * @example
+ * ```typescript
+ * const template = '{{subject}} signed {{possDet}} name and identified {{reflexive}}.';
+ * const borrower = getPronounSet('she');
+ *
+ * fillPronounTemplate(template, borrower);
+ * // "she signed her name and identified herself."
+ *
+ * fillPronounTemplate(template, borrower, { capitalization: 'title' });
+ * // "She signed Her name and identified Herself."
+ * ```
+ */
+declare function fillPronounTemplate(template: string, set: PronounSet, options?: FormatOptions): string;
+/**
+ * Fill pronoun placeholders with smart capitalization.
+ *
+ * Unlike `fillPronounTemplate`, this version detects sentence-initial positions
+ * and applies title case only there, keeping other occurrences lowercase.
+ *
+ * @param template - The template string with placeholders
+ * @param set - The pronoun set to use
+ * @returns The filled template with smart capitalization
+ *
+ * @example
+ * ```typescript
+ * const template = '{{subject}} read the document. Then {{subject}} signed it.';
+ * const pronouns = getPronounSet('she');
+ *
+ * fillPronounTemplateSmart(template, pronouns);
+ * // "She read the document. Then she signed it."
+ * ```
+ */
+declare function fillPronounTemplateSmart(template: string, set: PronounSet): string;
+
+/**
+ * GenderDB - Efficient gender probability lookup using a binary trie structure.
+ *
+ * This class provides O(k) name lookup where k is the length of the name.
+ * It uses a compact binary format with implicit child pointers for minimal memory usage.
+ *
+ * Binary format:
+ * - Header: 8 bytes (Magic 'GNDR' + node count)
+ * - Nodes: 4 bytes each (packed char, flags, sibling pointer)
+ * - Probs: 1 byte each (gender probability 1-255)
+ */
+interface GenderResult {
+    /** Probability that the name is male (0.0 = female, 1.0 = male) */
+    maleProbability: number;
+    /** Raw probability value from database (1-255) */
+    rawValue: number;
+    /** Whether the name was found in the database */
+    found: true;
+}
+interface GenderNotFound {
+    found: false;
+}
+type GenderLookupResult = GenderResult | GenderNotFound;
+/**
+ * Gender probability database using optimized binary trie storage.
+ */
+declare class GenderDB {
+    private nodes;
+    private probs;
+    private readonly nodeCount;
+    /**
+     * Create a GenderDB instance from a binary ArrayBuffer.
+     * @param buffer - ArrayBuffer containing the binary trie data
+     */
+    constructor(buffer: ArrayBuffer);
+    /**
+     * Get the number of nodes in the trie.
+     */
+    get size(): number;
+    /**
+     * Look up the male probability for a given name.
+     *
+     * @param name - The first name to look up (case-insensitive)
+     * @returns GenderLookupResult with probability if found, or { found: false }
+     */
+    lookup(name: string): GenderLookupResult;
+    /**
+     * Convenience method to get male probability as a number.
+     * Returns null if name not found.
+     *
+     * @param name - The first name to look up
+     * @returns Male probability (0.0-1.0) or null if not found
+     */
+    getMaleProbability(name: string): number | null;
+    /**
+     * Convenience method to get female probability as a number.
+     * Returns null if name not found.
+     *
+     * @param name - The first name to look up
+     * @returns Female probability (0.0-1.0) or null if not found
+     */
+    getFemaleProbability(name: string): number | null;
+    /**
+     * Make an informed guess about the likely gender based on probability threshold.
+     *
+     * @param name - The first name to look up
+     * @param threshold - Confidence threshold for guessing (default 0.8, meaning 80% confidence required)
+     * @returns 'male', 'female', 'unknown', or null if name not found in database
+     */
+    guessGender(name: string, threshold?: number): 'male' | 'female' | 'unknown' | null;
+    /**
+     * Check if a name exists in the database.
+     *
+     * @param name - The first name to check
+     * @returns true if the name exists in the database
+     */
+    has(name: string): boolean;
+}
+
+/**
+ * Get default pronouns based on a gender guess result.
+ *
+ * Maps the output of `GenderDB.guessGender()` to appropriate pronouns:
+ * - 'male' → he/him
+ * - 'female' → she/her
+ * - 'unknown' or null → they/them (safe default)
+ *
+ * @param gender - Result from guessGender()
+ * @returns The appropriate PronounSet
+ *
+ * @example
+ * ```typescript
+ * const db = createGenderDB();
+ * const gender = db.guessGender('John'); // 'male'
+ * const pronouns = getDefaultPronouns(gender); // he/him
+ * ```
+ */
+declare function getDefaultPronouns(gender: 'male' | 'female' | 'unknown' | null): PronounSet;
+/**
+ * Get default pronouns for any parsed entity.
+ *
+ * Entity kind determines pronouns:
+ * - `person` → they/them (use getPronounsForPerson for gender-aware lookup)
+ * - `organization` → they/them
+ * - `family` / `household` → they/them
+ * - `compound` → they/them
+ * - `unknown` / `rejected` → they/them
+ *
+ * For person entities, this returns they/them as a safe default.
+ * Use `getPronounsForPerson()` with a GenderDB for gender-aware pronouns.
+ *
+ * @param entity - The parsed name entity
+ * @returns The appropriate PronounSet
+ *
+ * @example
+ * ```typescript
+ * const org = classifyName('Acme Inc.');
+ * getPronounsForEntity(org); // they/them
+ *
+ * const family = classifyName('The Smiths');
+ * getPronounsForEntity(family); // they/them
+ * ```
+ */
+declare function getPronounsForEntity(entity: ParsedNameEntity): PronounSet;
+/**
+ * Options for getting pronouns for a person entity
+ */
+interface GetPronounsForPersonOptions {
+    /** Optional gender database for name-based gender lookup */
+    genderDB?: GenderDB;
+    /** Explicit pronouns override (user-specified, takes priority) */
+    explicitPronouns?: string | PronounSet;
+    /** Custom default when gender is unknown (default: they/them) */
+    defaultOnUnknown?: PronounSet;
+    /** Threshold for gender guessing (default: 0.8) */
+    genderThreshold?: number;
+}
+/**
+ * Get pronouns for a person entity with optional gender lookup.
+ *
+ * Priority order:
+ * 1. Explicit pronouns (if provided)
+ * 2. Gender-based pronouns (if genderDB provided and given name exists)
+ * 3. Custom default or they/them
+ *
+ * @param entity - The person entity
+ * @param options - Options including optional GenderDB
+ * @returns The appropriate PronounSet
+ *
+ * @example
+ * ```typescript
+ * const genderDB = createGenderDB();
+ * const person = parseName('John Smith') as PersonName;
+ *
+ * // With gender lookup
+ * getPronounsForPerson(person, { genderDB });
+ * // Returns he/him (John is typically male)
+ *
+ * // With explicit override
+ * getPronounsForPerson(person, { explicitPronouns: 'they/them' });
+ * // Returns they/them regardless of name
+ *
+ * // Without gender lookup
+ * getPronounsForPerson(person);
+ * // Returns they/them (safe default)
+ * ```
+ */
+declare function getPronounsForPerson(entity: PersonName, options?: GetPronounsForPersonOptions): PronounSet;
+/**
+ * Get pronouns for any entity with full integration.
+ *
+ * This is a convenience function that handles all entity types:
+ * - For person entities, uses gender lookup if genderDB is provided
+ * - For all other entities, returns they/them
+ *
+ * @param entity - Any parsed name entity
+ * @param options - Options for person entity handling
+ * @returns The appropriate PronounSet
+ *
+ * @example
+ * ```typescript
+ * const genderDB = createGenderDB();
+ *
+ * const person = classifyName('Jane Smith');
+ * getPronouns(person, { genderDB }); // she/her
+ *
+ * const org = classifyName('Acme Inc.');
+ * getPronouns(org, { genderDB }); // they/them (ignores genderDB)
+ * ```
+ */
+declare function getPronouns(entity: ParsedNameEntity, options?: GetPronounsForPersonOptions): PronounSet;
+
+/**
+ * Extract pronouns from a name string if present.
+ *
+ * Looks for pronoun specifications in parentheses at the end of names:
+ * - "Alex Johnson (they/them)"
+ * - "Sam Smith (he/his)"
+ * - "Jordan Lee (she/her/hers)"
+ *
+ * Does NOT extract non-pronoun parentheticals:
+ * - "John Smith (billing)" → not extracted
+ * - "The Smith Family (cabin)" → not extracted
+ *
+ * @param nameWithPronouns - The name string potentially containing pronouns
+ * @returns Object with cleaned name and optional pronouns
+ *
+ * @example
+ * ```typescript
+ * extractPronouns('Alex Johnson (they/them)');
+ * // { name: 'Alex Johnson', pronouns: {...}, rawPronounSpec: 'they/them' }
+ *
+ * extractPronouns('John Smith (billing)');
+ * // { name: 'John Smith (billing)' } - not extracted
+ *
+ * extractPronouns('Jane Doe');
+ * // { name: 'Jane Doe' } - no pronouns found
+ * ```
+ */
+declare function extractPronouns(nameWithPronouns: string): PronounExtractionResult;
+/**
+ * Check if a name string appears to contain pronouns.
+ *
+ * Useful for conditional logic without extracting.
+ *
+ * @param name - The name string to check
+ * @returns true if the name appears to contain pronouns
+ */
+declare function hasPronouns(name: string): boolean;
+/**
+ * Use extracted or inferred pronouns to hint at gender.
+ *
+ * Maps pronoun sets to gender hints:
+ * - he/him → 'male'
+ * - she/her → 'female'
+ * - they/them, neopronouns → 'unknown'
+ * - name-only, any → 'unknown'
+ *
+ * @param rawSpec - The raw pronoun spec string
+ * @returns Gender hint or 'unknown'
+ */
+declare function pronounsToGenderHint(rawSpec: string): 'male' | 'female' | 'unknown';
+
+export { BUILT_IN_PRONOUNS, type BaseEntity, COMMON_FIRST_NAMES, COMMON_SURNAMES, type Capitalization, type CompoundConnector, type CompoundName, type Confidence, type FamilyName, type FamilyStyle, type FormatOptions, type GetPronounsForPersonOptions, type LegalForm, MULTI_WORD_PARTICLES, type NameAffixToken, type NameAffixTokenType, type NameFormatOptions, type NameKind, type NamePreset, type NameToken, type NameTokenType, type OrganizationName, PARTICLES, type ParseListOptions, type ParseMeta, type ParseOptions, type ParsedName, type ParsedNameEntity, type ParsedRecipient, type PersonName, type PronounExtractionResult, type PronounRole, type PronounSet, type ReasonCode, type RejectedName, SPEC_ALIASES, type UnknownName, classifyName, entityToLegacy, extractPronouns, fillPronounTemplate, fillPronounTemplateSmart, formatName, formatPronoun, getDefaultPronouns, getFirstName, getLastName, getNickname, getPronounSet, getPronouns, getPronounsForEntity, getPronounsForPerson, hasPronouns, isCommonFirstName, isCommonSurname, isCompound, isFamily, isMultiWordParticle, isOrganization, isParticle, isPerson, isRejected, isUnknown, parseName, parseNameList, parsePersonName, parsePronounSpec, pronounsToGenderHint };