name-tools 0.1.0

package/dist/gender/GenderDB-Co_GybwH.d.mts

@@ -0,0 +1,80 @@
+/**
+ * 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;
+}
+
+export { GenderDB as G, type GenderResult as a, type GenderNotFound as b, type GenderLookupResult as c };

package/dist/gender/GenderDB-Co_GybwH.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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;
+}
+
+export { GenderDB as G, type GenderResult as a, type GenderNotFound as b, type GenderLookupResult as c };

package/dist/gender/all.d.mts

@@ -0,0 +1,31 @@
+import { G as GenderDB } from './GenderDB-Co_GybwH.mjs';
+export { c as GenderLookupResult, b as GenderNotFound, a as GenderResult } from './GenderDB-Co_GybwH.mjs';
+
+/**
+ * Full gender probability dataset (100% of names meeting minimum threshold).
+ *
+ * This is the largest dataset with all names that have at least 10 occurrences
+ * across all years in the SSA database.
+ *
+ * Import this for maximum coverage at the cost of larger bundle size.
+ *
+ * Usage:
+ * ```typescript
+ * import { createGenderDB } from 'name-tools/gender/all';
+ * const db = createGenderDB();
+ * const prob = db.getMaleProbability('Ashley');
+ * ```
+ */
+
+/**
+ * Create a GenderDB instance with the full dataset.
+ *
+ * @param options.shared - If true (default), returns a shared singleton instance.
+ *                        If false, creates a new instance each time.
+ * @returns GenderDB instance
+ */
+declare function createGenderDB(options?: {
+    shared?: boolean;
+}): GenderDB;
+
+export { GenderDB, createGenderDB };

package/dist/gender/all.d.ts

@@ -0,0 +1,31 @@
+import { G as GenderDB } from './GenderDB-Co_GybwH.js';
+export { c as GenderLookupResult, b as GenderNotFound, a as GenderResult } from './GenderDB-Co_GybwH.js';
+
+/**
+ * Full gender probability dataset (100% of names meeting minimum threshold).
+ *
+ * This is the largest dataset with all names that have at least 10 occurrences
+ * across all years in the SSA database.
+ *
+ * Import this for maximum coverage at the cost of larger bundle size.
+ *
+ * Usage:
+ * ```typescript
+ * import { createGenderDB } from 'name-tools/gender/all';
+ * const db = createGenderDB();
+ * const prob = db.getMaleProbability('Ashley');
+ * ```
+ */
+
+/**
+ * Create a GenderDB instance with the full dataset.
+ *
+ * @param options.shared - If true (default), returns a shared singleton instance.
+ *                        If false, creates a new instance each time.
+ * @returns GenderDB instance
+ */
+declare function createGenderDB(options?: {
+    shared?: boolean;
+}): GenderDB;
+
+export { GenderDB, createGenderDB };