name-to-gender 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +79 -28
  2. package/package.json +4 -7
package/README.md CHANGED
@@ -1,8 +1,14 @@
1
1
  # name-to-gender
2
2
 
3
- Guess the gender of a first name from US Social Security birth data. Returns a
4
- **probability** and the **raw birth counts** behind every guess, not just a
5
- label. TypeScript-first, ESM + CJS, **zero runtime dependencies**.
3
+ **Predict the gender of a first name from US Social Security birth data.** A fast, accurate, zero-dependency library for Node.js and TypeScript that turns a name into a gender, a confidence probability, and the raw birth counts behind every guess.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/name-to-gender.svg)](https://www.npmjs.com/package/name-to-gender)
6
+ [![npm downloads](https://img.shields.io/npm/dm/name-to-gender.svg)](https://www.npmjs.com/package/name-to-gender)
7
+ [![bundle size](https://img.shields.io/bundlephobia/minzip/name-to-gender)](https://bundlephobia.com/package/name-to-gender)
8
+ [![license](https://img.shields.io/github/license/michaelcummings12/name-to-gender)](https://github.com/michaelcummings12/name-to-gender/blob/main/LICENSE)
9
+ [![GitHub stars](https://img.shields.io/github/stars/michaelcummings12/name-to-gender?style=social)](https://github.com/michaelcummings12/name-to-gender)
10
+
11
+ `name-to-gender` is a gender detection and gender prediction library that infers gender from a person's first name. Give it a name like `"Adam"` or `"Mary"` and it returns `"male"`, `"female"`, or `"unknown"`, along with a probability you can threshold on. It is data-driven rather than rule-based, ships its dataset offline with the package, and has **zero runtime dependencies**.
6
12
 
7
13
  ```ts
8
14
  import { guessGender } from "name-to-gender";
@@ -16,18 +22,14 @@ guessGender("Adam");
16
22
  // }
17
23
  ```
18
24
 
19
- ## Why another one?
25
+ ## Features
20
26
 
21
- The existing name-gender packages are either inaccurate or unmaintained. Many of
22
- them tag common male names like Adam and Chris as female, and none of the actively-maintained ones return a confidence score you can threshold on.
23
-
24
- | package | data | last updated | confidence | types |
25
- | ---------------------------- | ------------- | ------------ | ---------- | ------- |
26
- | `gender` | US Census | 2013 | yes | no |
27
- | `gender-guess` | SSA 1930–2013 | 2014 | yes | no |
28
- | `gender-detection` | mixed | 2018 | **no** | no |
29
- | `gender-detection-from-name` | mixed | 2025 | **no** | no |
30
- | **`name-to-gender`** | **US SSA** | **fresh** | **yes** | **yes** |
27
+ - **Accurate.** Backed by 91,000+ names and all-time US birth counts, so common names resolve correctly instead of being guessed from spelling.
28
+ - **Confidence scores.** Every result carries a probability and the raw `{ male, female }` counts, so you decide where to draw the line.
29
+ - **Unisex-aware.** Threshold low-confidence names like `Casey` or `Jordan` down to `"unknown"` with a single option.
30
+ - **Forgiving input.** Handles full names, casing, accents, and punctuation out of the box.
31
+ - **TypeScript-first.** Full types, ESM and CommonJS builds, tree-shakeable, **zero dependencies**.
32
+ - **Offline.** No API calls, no network, no rate limits. The data ships in the package.
31
33
 
32
34
  ## Install
33
35
 
@@ -35,10 +37,20 @@ them tag common male names like Adam and Chris as female, and none of the active
35
37
  npm install name-to-gender
36
38
  ```
37
39
 
40
+ ```sh
41
+ pnpm add name-to-gender
42
+ ```
43
+
44
+ ```sh
45
+ yarn add name-to-gender
46
+ ```
47
+
38
48
  ## Usage
39
49
 
40
50
  ### `guessGender(name, options?)`
41
51
 
52
+ The main entry point. Pass a name, get back a gender, a probability, and the counts.
53
+
42
54
  ```ts
43
55
  import { guessGender } from "name-to-gender";
44
56
 
@@ -54,10 +66,9 @@ guessGender("Xyzzy");
54
66
  // { gender: "unknown", probability: 0, counts: { male: 0, female: 0 }, name: "xyzzy" }
55
67
  ```
56
68
 
57
- #### Thresholding unisex names
69
+ ### Thresholding unisex names
58
70
 
59
- Some names are unisex. Pass `minProbability` to treat low-confidence
60
- guesses as `"unknown"` while still seeing the underlying numbers:
71
+ Some names are unisex. Pass `minProbability` to treat low-confidence guesses as `"unknown"` while still seeing the underlying numbers:
61
72
 
62
73
  ```ts
63
74
  guessGender("Casey"); // gender: "male" (≈59% male)
@@ -88,18 +99,58 @@ interface GenderGuess {
88
99
 
89
100
  ## How it works
90
101
 
91
- `name-to-gender` is **data-driven, not rule-based**. It normalizes the input to
92
- a first-name token, looks it up in a table of all-time US births by name and
93
- sex, and reports the majority sex along with its share. There are no `"ends in
94
- -a → female"` heuristics, which is exactly what makes the older packages fail on
95
- names like Adam and Joshua.
102
+ `name-to-gender` is **data-driven, not rule-based**. It normalizes the input to a first-name token, looks it up in a table of all-time US births by name and sex, and reports the majority sex along with its share. There are no `"ends in -a means female"` heuristics, which is why it resolves names like Adam, Joshua, and Andrea correctly.
103
+
104
+ The dataset is built from the public-domain [US Social Security Administration baby-names data](https://www.ssa.gov/oact/babynames/), aggregated across every birth year from 1880 to the present into 91,000+ names. It works best for US and English-context names. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for how to regenerate it from the latest SSA release.
105
+
106
+ ## Comparison with other packages
107
+
108
+ There are several similar packages on npm. Here is how they line up. `name-to-gender` aims to be the best, most current, and typed.
109
+
110
+ | Package | Data | Last updated | Confidence score | TypeScript types |
111
+ | ---------------------------------------------------------------------------------------- | --------------------- | ------------ | ---------------- | ---------------- |
112
+ | [`gender`](https://www.npmjs.com/package/gender) | US Census | 2013 | yes | no |
113
+ | [`gender-guess`](https://www.npmjs.com/package/gender-guess) | SSA 1930–2013 | 2014 | yes | no |
114
+ | [`gender-detection`](https://www.npmjs.com/package/gender-detection) | mixed | 2018 | no | no |
115
+ | [`gender-detection-from-name`](https://www.npmjs.com/package/gender-detection-from-name) | mixed | 2025 | no | no |
116
+ | [**`name-to-gender`**](https://www.npmjs.com/package/name-to-gender) | **US SSA, all years** | **current** | **yes** | **yes** |
117
+
118
+ If you are migrating from one of the packages above, `guessGender(name)` is the closest drop-in. It returns a label like the others, plus the probability and counts they leave out.
119
+
120
+ ## FAQ
121
+
122
+ ### How do I get the gender of a name in JavaScript or TypeScript?
123
+
124
+ Install `name-to-gender` and call `guessGender("Alex")`. You get back `{ gender, probability, counts, name }`. No API key and no network request are required.
125
+
126
+ ### How accurate is it?
127
+
128
+ Accuracy depends on the name. Strongly gendered names like Mary or John resolve at well over 99% confidence. Unisex names like Casey or Jordan land near 50%, and the returned `probability` tells you exactly how confident the guess is so you can threshold accordingly.
129
+
130
+ ### Does it work offline, without an API?
131
+
132
+ Yes. The full dataset is bundled in the package, so every lookup is local, synchronous, and free. There are no rate limits or external calls.
133
+
134
+ ### Can it handle full names, accents, and messy input?
135
+
136
+ Yes. It extracts the first-name token, folds accents (`José` to `jose`), lowercases, and strips punctuation before looking the name up.
137
+
138
+ ### What about unisex or non-binary names?
139
+
140
+ The library reports the statistical male/female split from US birth records. For unisex names the probability sits near 0.5. Use the `minProbability` option to fold low-confidence names into `"unknown"` rather than forcing a binary label.
141
+
142
+ ### What data is it based on?
143
+
144
+ Public-domain [US Social Security Administration baby-names data](https://www.ssa.gov/oact/babynames/), summed across all birth years from 1880 onward. It is tuned for US and English-context names.
145
+
146
+ ## Use cases
96
147
 
97
- The dataset is built from the public-domain
98
- [US Social Security Administration baby-names data](https://www.ssa.gov/oact/babynames/).
99
- It works best for US/English-context names. See
100
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) for how to regenerate it from the latest
101
- SSA release.
148
+ - Personalizing greetings, salutations, and email copy
149
+ - Enriching CRM, analytics, and demographic data
150
+ - Pre-filling or validating form fields
151
+ - Audience segmentation and reporting
152
+ - Cleaning and labeling datasets for machine learning
102
153
 
103
154
  ## License
104
155
 
105
- MIT © Michael Cummings
156
+ MIT © [Michael Cummings](https://www.michaelcummin.gs)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "name-to-gender",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "Guess gender from a first name using US Social Security data. Returns a probability and the raw birth counts. TypeScript, ESM + CJS, zero dependencies.",
5
5
  "homepage": "https://github.com/michaelcummings12/name-to-gender#readme",
6
6
  "type": "module",
@@ -60,14 +60,11 @@
60
60
  "LICENSE"
61
61
  ],
62
62
  "license": "MIT",
63
+ "packageManager": "pnpm@11.20.0",
63
64
  "devDependencies": {
64
65
  "tsup": "^8.5.1",
65
- "tsx": "^4.22.4",
66
+ "tsx": "^4.23.11",
66
67
  "typescript": "^6.0.3",
67
- "vitest": "^4.1.9"
68
- },
69
- "allowScripts": {
70
- "esbuild@0.27.7": true,
71
- "esbuild@0.28.1": true
68
+ "vitest": "^4.1.10"
72
69
  }
73
70
  }