name_bank 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1002b10463391e94b864c3e1ee16e75619338470b7934a7f8dbe3a0b2800b74e
-  data.tar.gz: 48fa865b036403596ec5faad42b1e19ab608229d7bc489bc108c6cce9cfd31db
+  metadata.gz: f9a25e48d0f047db7cb393aa8545f0857daac15e5febc9f941b48c440f957930
+  data.tar.gz: 8ad91e35492cf5e6e703246bbffef2804fa2456ce344bd7425532cb3ef145ae0
 SHA512:
-  metadata.gz: 414c382b0348cda3da80e7e441fb459f7dc67690caea107fb71ef6fc170d018d5f6ae0bf25dfdba37471afda1d68f80fe14865a7a581014d43c24509b8b0a533
-  data.tar.gz: 740263807cc32ba8d090e6e41291170b6862ba8151b80f5b2a968c0824f95f9b452a78e6a6acafbda3686dc5d17818d0e04bf8ab97def983054cf15bedc9e41e
+  metadata.gz: 3ef330f55cd1fdcb87ca7f1391bc3b1c85af3c033e3bb9a4b349bea43651f8eaa4ea9f3ae9c1bac1db5e758ffb331ee403eb6f4639984dbc6246b95a7d78c5e2
+  data.tar.gz: df0010e081ef9c6314934dc15c06f98af62b61aac7395c7c66b3f02a0e9540065b192112c58c109cbd3fa64c745c3f4daa3012f71f88b131cc6a6a271943c448

data/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.5] - 2026-07-24
+
+Metadata and documentation only — no API, data or behaviour change.
+
+### Added
+- `spec.metadata` in the gemspec: source, changelog, documentation and bug
+  tracker links, and `rubygems_mfa_required`.
+- README: "Where it fits" (factory_bot, `db/seeds.rb`, RSpec examples) and
+  "Relation to Faker and FFaker" with a comparison table.
+
+### Changed
+- Gem summary and description rewritten so the gem is findable for fake, test
+  and seed name data, and states how it relates to Faker and FFaker.
+- README intro says 106 countries (was "105+").
+
+## [0.1.4] - 2026-07-24
+
+### Added
+- `script:` keyword on `first_name`, `last_name`, `full_name` (default `:latin`)
+  selecting the Latin or native-script pool; `NameBank.scripts(country:)` lists
+  available scripts. New error `NameBank::UnknownScript`.
+- Native-script pools (Arabic, Cyrillic, Hangul, Han, Kana, Greek, Hebrew,
+  Georgian, Khmer, Bengali) for the countries that use them.
+- `docs/name-counts.md`: per-country pool sizes, linked from the README.
+
+### Changed
+- Re-baked all pools larger (N=6000) and split by script; foreign-script noise
+  removed from Latin pools. Default (`:latin`) output for non-Latin countries is
+  now Latin-only (previously mixed). Curated CN/UA pools unchanged.
+
 ## [0.1.3] - 2026-07-23
 
 ### Added

data/README.md

@@ -1,9 +1,13 @@
 # name_bank
 
-Authentic, gender-matched given and family names for 105+ countries. Deep
+Authentic, gender-matched given and family names for 106 countries. Deep
 pools (up to 1500 per country/gender), uniform sampling, deterministic, no
 runtime dependencies.
 
+Realistic fake name data for database seeds, factories, fixtures and demo
+environments — a companion to [Faker](https://github.com/faker-ruby/faker) and
+[FFaker](https://github.com/ffaker/ffaker) for the name part.
+
 ## Installation
 
 Add to your Gemfile:
@@ -42,6 +46,98 @@ Sampling is uniform over each pool and fully deterministic for a given
 `rng` — the same seed always yields the same name. `gender:` is `:male`
 or `:female`.
 
+## Where it fits
+
+A factory_bot factory:
+
+```ruby
+FactoryBot.define do
+  factory :user do
+    transient do
+      country { "DE" }
+      person_gender { :female }
+      rng { Random.new }
+      person { NameBank.full_name(country: country, gender: person_gender, rng: rng) }
+    end
+
+    first_name { person[:firstname] }
+    last_name  { person[:lastname] }
+  end
+end
+```
+
+Database seeds with a fixed seed, so every run produces the same data:
+
+```ruby
+# db/seeds.rb
+rng = Random.new(20_260_724)
+
+%w[DE FR IT ES PL].each do |country|
+  100.times do
+    person = NameBank.full_name(country: country, gender: [:male, :female].sample(random: rng), rng: rng)
+    User.create!(first_name: person[:firstname], last_name: person[:lastname], country: country)
+  end
+end
+```
+
+An RSpec example — the seeded RNG makes the case reproducible:
+
+```ruby
+it "fits a long Cyrillic name into the invoice header" do
+  rng = Random.new(1234)
+  customer = NameBank.full_name(country: "RU", gender: :female, rng: rng, script: :native)
+
+  header = InvoicePdf.new(customer).header
+
+  expect(header).to include(customer[:lastname])
+end
+```
+
+## Relation to Faker and FFaker
+
+Faker and FFaker are full fake-data suites — addresses, companies, lorem ipsum,
+and much more. name_bank does one thing: people names. Use it alongside them,
+not instead of them.
+
+|                      | Faker                                                        | FFaker                                     | name_bank                                                   |
+| -------------------- | ------------------------------------------------------------ | ------------------------------------------ | ----------------------------------------------------------- |
+| Scope                | full fake-data suite                                          | full fake-data suite                        | people names only                                            |
+| Names addressed by   | 58 language/region locales (`de`, `de-AT`, `en-US`)           | 30 language modules (`FFaker::NameDE`)      | 106 ISO country codes (`DE`, `RU`, `JP`)                     |
+| Gendered given names | in about 24 of those locales                                  | in 17 of the 30 name modules                | in every country                                             |
+| Pool depth           | uneven: `en` 1219 m / 4271 f, `de` 574 / 585, `ru` 52 / 56, `ko` 21 | varies per module                     | up to 1500 per country, gender and script; 89 of 106 at the cap |
+| Native script        | one form per locale                                           | one form per module                         | Latin and native as separate pools, 35 countries             |
+| Randomness           | global `Faker::Config.random`                                 | global `FFaker::Random.seed`                | `rng:` passed in per call, no global state                   |
+
+Counts measured against `faker` and `ffaker` `main` on 2026-07-24.
+
+Moving a name call over:
+
+```ruby
+Faker::Name.first_name
+FFaker::NameDE.first_name
+# both: gender-agnostic, locale/module picked from global state
+
+NameBank.first_name(country: "DE", gender: :female, rng: rng)
+# country and gender explicit, RNG explicit
+```
+
+## Scripts
+
+Names come in Latin (default) and, for countries with a non-Latin writing
+system, their native script. Pass `script:`:
+
+```ruby
+NameBank.first_name(country: "RU", gender: :male, rng: rng)                  # => "Dmitry"
+NameBank.first_name(country: "RU", gender: :male, rng: rng, script: :native) # => "Алексей"
+
+NameBank.scripts(country: "RU")   # => [:latin, :native]
+NameBank.scripts(country: "DE")   # => [:latin]   (Latin is Germany's script)
+```
+
+`:latin` and `:native` sample from independent pools. For Latin-script countries
+`:native` returns the same (Latin) pool. Requesting a script with no names
+raises `NameBank::UnknownScript`.
+
 ## Variants
 
 Some countries offer an alternate cultural name pool layered on the default.
@@ -72,6 +168,14 @@ Africa, South Korea, Spain, Sudan, Sweden, Switzerland, Syria, Taiwan, Tunisia,
 Turkey, Turkmenistan, Ukraine, United Arab Emirates, United Kingdom, United
 States, Uruguay, Yemen.
 
+## Pool sizes
+
+Each country provides up to 1500 given names per gender and up to 1500
+surnames; 89 of the 106 countries reach that cap on all three Latin pools, and
+the rest are as large as the source data allows. 35 countries also carry a
+native-script pool. Full per-country counts (Latin and native):
+[docs/name-counts.md](docs/name-counts.md).
+
 ## License
 
 Apache-2.0.