{"_id":"@atmos-financial/str-wizard","name":"@atmos-financial/str-wizard","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@atmos-financial/str-wizard","version":"1.0.0","description":"A powerful string comparison library with advanced algorithms for fuzzy matching, name comparison, and text similarity analysis","keywords":["string","comparison","similarity","fuzzy","matching","levenshtein","jaccard","name","text","algorithm","diacritics","normalization"],"homepage":"","repository":{"type":"git","url":""},"license":"MIT","author":{"name":"Atmos Financial, PBC"},"type":"module","main":"index.mjs","scripts":{"test":"node test.mjs"},"engines":{"node":">=12.0.0"},"gitHead":"c8df21b789ab44954b47ca53848ea824a1017b6b","_id":"@atmos-financial/str-wizard@1.0.0","_nodeVersion":"22.11.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-nw0LXQSlTTi7LqqbLah64ZSoqB5OumICIdJfEDRY3s/Uc00S9Y6C0BoxprD0D5CjNWKLqHjST9YsZGge+vxldA==","shasum":"11d99c58b47a76c043b65fa5c355e7afb34455ac","tarball":"https://registry.npmjs.org/@atmos-financial/str-wizard/-/str-wizard-1.0.0.tgz","fileCount":4,"unpackedSize":20649,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDlrBJ1GywKC4HpKhw5RgsB8x/N7hmvl8B1eK8qExJoZQIgSQKy/7CqW5gAC9qbfqPX6WdAlvgJdORFAFWbrI59C8k="}]},"_npmUser":{"name":"seamoss","email":"sean@noisebeard.com"},"directories":{},"maintainers":[{"name":"seamoss","email":"sean@noisebeard.com"},{"name":"haileybongo","email":"haileyebongo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/str-wizard_1.0.0_1762991263123_0.4246261411940986"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-12T23:47:43.123Z","1.0.0":"2025-11-12T23:47:43.297Z","modified":"2025-11-12T23:47:43.598Z"},"maintainers":[{"name":"seamoss","email":"sean@noisebeard.com"},{"name":"haileybongo","email":"haileyebongo@gmail.com"}],"description":"A powerful string comparison library with advanced algorithms for fuzzy matching, name comparison, and text similarity analysis","keywords":["string","comparison","similarity","fuzzy","matching","levenshtein","jaccard","name","text","algorithm","diacritics","normalization"],"repository":{"type":"git","url":""},"author":{"name":"Atmos Financial, PBC"},"license":"MIT","readme":"# String Wizard\n\nA powerful string comparison library with advanced algorithms for fuzzy matching, name comparison, and text similarity analysis.\n\n## Features\n\n- **Multi-algorithm String Comparison**: Uses a weighted blend of Levenshtein distance, Jaccard similarity, and Longest Common Substring for accurate fuzzy matching\n- **Name Comparison**: Specialized function for comparing people's names with smart handling of honorifics, suffixes, and initials\n- **Diacritic Stripping**: Remove accents and special characters from strings for normalized comparisons\n- **Name Sanitization**: Intelligent normalization of names with support for common honorifics and suffixes\n- **Structural Bonuses**: Extra similarity scoring for matching first initials and last names\n\n## Installation\n\n```bash\nnpm install str-wizard\n```\n\n## Usage\n\nThis package uses ES6 modules. You can import functions using either named imports or default import.\n\n### Basic String Comparison\n\n```javascript\nimport { compareStrings } from 'str-wizard';\n\nconst score = compareStrings(\"hello world\", \"hello there\");\nconsole.log(score); // 0.6 (60% similar)\n\nconst exactMatch = compareStrings(\"test\", \"test\");\nconsole.log(exactMatch); // 1.0 (100% identical)\n```\n\n### Name Comparison\n\n```javascript\nimport { compareNames } from 'str-wizard';\n\n// Handles honorifics and suffixes automatically\nconst score = compareNames(\n  \"Dr. John A. Smith, Jr.\",\n  \"John Smith\"\n);\nconsole.log(score); // ~0.85-0.9\n\n// Works with variations\nconst score2 = compareNames(\n  \"PETER H WILLINGSWORTH\",\n  \"PETER H.E. WILLINGSWORTH SR.\"\n);\nconsole.log(score2); // ~0.86-0.88\n```\n\n### Strip Diacritics\n\n```javascript\nimport { stripDiacritics } from 'str-wizard';\n\nconsole.log(stripDiacritics(\"café\")); // \"cafe\"\nconsole.log(stripDiacritics(\"áéíóú\")); // \"aeiou\"\nconsole.log(stripDiacritics(\"Zürich\")); // \"Zurich\"\n```\n\n### Sanitize Names\n\n```javascript\nimport { sanitizeName } from 'str-wizard';\n\nconsole.log(sanitizeName(\"Mr. John A. Smith, Jr.\"));\n// \"john a smith\"\n\nconsole.log(sanitizeName(\"Dr. Jane M. Doe, Ph.D.\"));\n// \"jane m doe\"\n\n// Handles single-letter initials intelligently\nconsole.log(sanitizeName(\"H E Smith\"));\n// \"he smith\"\n```\n\n### Structural Bonus\n\n```javascript\nimport { structuralBonus } from 'str-wizard';\n\n// Returns bonus score for structural similarities\nconst bonus = structuralBonus(\"john a smith\", \"john b smith\");\nconsole.log(bonus); // 0.07 (matching last name + first initial)\n```\n\n### Import All Functions\n\n```javascript\n// Named imports (recommended)\nimport { compareStrings, compareNames, sanitizeName, stripDiacritics, structuralBonus } from 'str-wizard';\n\n// Or use default import\nimport stringWizard from 'str-wizard';\nconst score = stringWizard.compareStrings(\"hello\", \"hallo\");\n```\n\n## API Reference\n\n### `compareStrings(a, b)`\n\nCompares two strings and returns a similarity score between 0 and 1.\n\n**Parameters:**\n- `a` (string): First string to compare\n- `b` (string): Second string to compare\n\n**Returns:** (number) A similarity score between 0 and 1, where:\n- `1` = identical strings\n- `0` = completely different strings\n\n**Algorithm:** Uses a weighted blend of:\n- Levenshtein distance (50%)\n- Jaccard similarity of word tokens (30%)\n- Longest common substring (20%)\n\n### `compareNames(a, b)`\n\nCompares two names and returns a similarity score between 0 and 1. Automatically handles name variations, honorifics, and suffixes.\n\n**Parameters:**\n- `a` (string): First name to compare\n- `b` (string): Second name to compare\n\n**Returns:** (number) A similarity score between 0 and 1\n\n### `sanitizeName(s)`\n\nSanitizes a name by normalizing and removing common honorifics and suffixes.\n\n**Parameters:**\n- `s` (string|any): The input name to sanitize\n\n**Returns:** (string) The sanitized name with:\n- Lowercase conversion\n- Diacritics stripped\n- Punctuation normalized\n- Honorifics removed (Mr, Mrs, Ms, Dr, Prof, etc.)\n- Suffixes removed (Jr, Sr, PhD, MD, Esq, etc.)\n- Single-letter initials collapsed\n\n### `stripDiacritics(s)`\n\nRemoves diacritical marks (accents) from a string.\n\n**Parameters:**\n- `s` (string): The input string\n\n**Returns:** (string) A new string with all diacritics removed\n\n### `structuralBonus(aSan, bSan)`\n\nCalculates a structural similarity bonus between two sanitized strings.\n\n**Parameters:**\n- `aSan` (string): First sanitized string\n- `bSan` (string): Second sanitized string\n\n**Returns:** (number) Bonus value between 0 and 0.07:\n- `0.05` if last words match\n- `0.02` if first letters of first words match\n- Sum of applicable bonuses\n\n## Use Cases\n\n- **Fuzzy Search**: Find approximate matches in search results\n- **Deduplication**: Identify duplicate entries with slight variations\n- **Name Matching**: Match people's names across different databases\n- **Data Cleaning**: Normalize and compare messy text data\n- **Record Linkage**: Connect related records across systems\n- **Autocomplete**: Provide smart suggestions based on partial input\n\n## Algorithm Details\n\n### Levenshtein Distance\nMeasures the minimum number of single-character edits (insertions, deletions, substitutions) needed to change one string into another.\n\n### Jaccard Similarity\nCompares the similarity between word token sets using the formula: `|intersection| / |union|`\n\n### Longest Common Substring\nFinds the longest contiguous sequence of characters that appear in both strings.\n\n## Requirements\n\n- Node.js >= 12.0.0\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-0aa7d5a48f9fc25b316cf9ec4d718e98"}