name_bank 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8985bb6db2329f6ae7033a3cd2ca2e9f2f1f4af803bf5904fd4e96d8f0f9034e
-  data.tar.gz: 1fe1d312b363bee756891a16567524d34c845673daa2e2ccb7097d4f1312fc75
+  metadata.gz: f9a25e48d0f047db7cb393aa8545f0857daac15e5febc9f941b48c440f957930
+  data.tar.gz: 8ad91e35492cf5e6e703246bbffef2804fa2456ce344bd7425532cb3ef145ae0
 SHA512:
-  metadata.gz: 4c55c61b735a271ebac955184ea0e6c7f6207c8be04b87b0ee1e041b5f4f9eb542950204a8756c8f862b4fac94072402333f8357f87c5915c6fd631d06b63457
-  data.tar.gz: 07ca279207e64e4282a6088acd2c379bef69e5df4bc3ec14960e86fd497d765eb07d00402b4d027b4bc9191b8239a43f52fabe71dccb2ba586da8fbce3523a10
+  metadata.gz: 3ef330f55cd1fdcb87ca7f1391bc3b1c85af3c033e3bb9a4b349bea43651f8eaa4ea9f3ae9c1bac1db5e758ffb331ee403eb6f4639984dbc6246b95a7d78c5e2
+  data.tar.gz: df0010e081ef9c6314934dc15c06f98af62b61aac7395c7c66b3f02a0e9540065b192112c58c109cbd3fa64c745c3f4daa3012f71f88b131cc6a6a271943c448

data/CHANGELOG.md

@@ -4,6 +4,21 @@ 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

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,81 @@ 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

data/lib/name_bank/pool_schema.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module NameBank
+  # The pool-key schema: the base YAML keys, how native-script keys are named,
+  # and how a gender maps to its key. Shared by the runtime Repository and the
+  # build-time SplitScripts tool so the key names live in one place.
+  module PoolSchema
+    KEYS = %w[firstnames_male firstnames_female lastnames].freeze
+
+    module_function
+
+    def native_key(key)
+      "#{key}_native"
+    end
+
+    def gender_key(gender)
+      case gender
+      when :male then "firstnames_male"
+      when :female then "firstnames_female"
+      else raise ArgumentError, "gender must be :male or :female, got #{gender.inspect}"
+      end
+    end
+  end
+end

data/lib/name_bank/repository.rb

@@ -5,8 +5,6 @@ require "yaml"
 module NameBank
   # Lazy, memoized loader of per-country name pools stored as YAML in data_dir.
   class Repository
-    KEYS = %w[firstnames_male firstnames_female lastnames].freeze
-
     def initialize(data_dir:)
       @data_dir = data_dir
       @countries_cache = {}
@@ -14,7 +12,7 @@ module NameBank
     end
 
     def firstnames(country:, gender:, variant: nil, script: :latin)
-      pool(load(country, variant), gender_key(gender), script, country)
+      pool(load(country, variant), PoolSchema.gender_key(gender), script, country)
     end
 
     def lastnames(country:, variant: nil, script: :latin)
@@ -23,7 +21,7 @@ module NameBank
 
     def scripts(country:)
       data = load(country, nil)
-      KEYS.any? { |k| data["#{k}_native"]&.any? } ? %i[latin native] : %i[latin]
+      PoolSchema::KEYS.any? { |k| data[PoolSchema.native_key(k)]&.any? } ? %i[latin native] : %i[latin]
     end
 
     def countries
@@ -36,20 +34,12 @@ module NameBank
 
     private
 
-    def gender_key(gender)
-      case gender
-      when :male then "firstnames_male"
-      when :female then "firstnames_female"
-      else raise ArgumentError, "gender must be :male or :female, got #{gender.inspect}"
-      end
-    end
-
     def pool(data, key, script, country)
       names =
         case script
         when :latin then data.fetch(key)
         when :native
-          native = data["#{key}_native"]
+          native = data[PoolSchema.native_key(key)]
           native && !native.empty? ? native : data.fetch(key)
         else
           raise ArgumentError, "script must be :latin or :native, got #{script.inspect}"

data/lib/name_bank/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NameBank
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

data/lib/name_bank.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "name_bank/version"
+require_relative "name_bank/pool_schema"
 require_relative "name_bank/repository"
 
 module NameBank

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: name_bank
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Patrick Bartels
@@ -37,9 +37,16 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: A fast, dependency-free generator of authentic, gender-matched given
-  names and surnames for 105+ countries, plus hand-curated pools and cultural variants.
-  Uniform, deterministic sampling from a caller-supplied RNG.
+description: 'NameBank generates authentic, gender-matched given names and surnames
+  for 106 countries, addressed by ISO alpha-2 country code, including native-script
+  pools (Cyrillic, Arabic, Han, Hangul, Kana, Greek, Hebrew and more) for 35 of them.
+  Pools hold up to 1500 names per country, gender and script. Use it for realistic
+  fake name data in database seeds, factory_bot factories, RSpec fixtures, demo and
+  staging data. It complements the general-purpose fake data gems Faker and FFaker
+  rather than replacing them: keep those for addresses, companies and lorem ipsum,
+  and use name_bank where you need per-country, gender-matched people names with deep
+  pools. Sampling is uniform and deterministic from a caller-supplied RNG — no global
+  locale or random state. No runtime dependencies.'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -157,12 +164,18 @@ files:
 - data/variants/US/african_american.yml
 - docs/name-counts.md
 - lib/name_bank.rb
+- lib/name_bank/pool_schema.rb
 - lib/name_bank/repository.rb
 - lib/name_bank/version.rb
 homepage: https://github.com/roughneck/name_bank
 licenses:
 - Apache-2.0
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/roughneck/name_bank
+  changelog_uri: https://github.com/roughneck/name_bank/blob/master/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/name_bank
+  bug_tracker_uri: https://github.com/roughneck/name_bank/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -179,5 +192,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Authentic, gender-matched given and family names for 105+ countries.
+summary: Authentic, gender-matched given names and surnames for 106 countries — fake
+  name data for seeds, factories and tests.
 test_files: []