usa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5cf7ef01b60f4c0bc0cc59c9e565b999ee8e705c4435e548f61e5b5b187fc545
+  data.tar.gz: 4e7153ac68f27f05cfe8865ea4b227d1857792be082d65808794379048906d50
+SHA512:
+  metadata.gz: 69b120cbcbc243dd1d840426c6a38f760c0f77b6a5e11dff1e571330ecae47a80c76397b79b6827a6dcdaa87821060750d7c26591a75611367cbf63f8b99cb10
+  data.tar.gz: b5ce850cfe280fe816e740952441583e6936b96599e772c1c14b571e8ad733ffe2c971aa131dc955d3b9000fb4fda43b30a5d80b85c64cfd8896040fe5430bf0

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+For more information about changelogs, check [Keep a Changelog](http://keepachangelog.com) and
+[Vandamme](http://tech-angels.github.io/vandamme).
+
+## [Unreleased]
+
+## 0.1.0 - 2026-09-14
+
+* [Feature] `USA::State`, `USA::County` and `USA::ZIP`, on `usa_states`, `usa_counties` and
+  `usa_zips`: the three tables three apps were each keeping, each with a CSV and a backfill of
+  its own. A state has a code, a FIPS and a name; a county a FIPS, a name and a state; a ZIP a
+  code, the city it is addressed as, a time zone named as Rails names one, and one county
+* [Feature] `USA::City` on `usa_cities`, and `USA::CityCounty` on `usa_city_counties`: a city
+  belongs to one state and lies in one or more counties, so `city.counties` and `county.cities`
+  both answer. The place FIPS is unique within a state rather than nationally, which is what the
+  index says
+* [Feature] `google_place_id` on all four, filled for every county and blank elsewhere until a
+  release fills it -- which is a reason `db:usa:seed` exists
+* [Feature] `bin/rails g usa:install`, which copies the six migrations into the host under
+  timestamps of its own, and writes nothing else: there is nothing here to configure
+* [Feature] `USA.seed`, and a `seed` on each model: every write is an upsert keyed on the code
+  or the FIPS, so a second run inserts what is missing, leaves the id of every row a host
+  already had, and does not touch the `updated_at` of a row that did not change
+* [Feature] `bin/rails db:usa:seed`, which is how a database made from `db/schema.rb` gets its
+  rows -- a dump carries none -- and how one catches up with a release that added some
+* [Feature] `usa_states.counties_count` and `usa_counties.zips_count`, counted from the rows
+  after a seed, since an upsert runs no callback, and only where the count moved
+* [Feature] The acronyms `USA`, `ZIP` and `FIPS`, registered before the engine loads, so
+  `USA::ZIP` is the class, `usa_zips` the table and 'ZIP' the heading
+* [Feature] A load hook per model -- `ActiveSupport.on_load(:usa_zip) { ... }` -- and
+  `:usa_record`, where a host says how these tables connect
+
+The data is the current Census vintage: the counties include Connecticut's nine planning
+regions and Alaska's current census areas, and the places come from the 2025 Gazetteer rather
+than the 2010 list one of the three apps was still carrying.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 HouseAccount
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# USA
+
+Every state, county, city and ZIP code of the United States, as five tables a Rails app joins
+to. One copy, held here, rather than a CSV and a backfill in each app that needs an address to
+mean something.
+
+## How to install
+
+To install on your system, run
+
+    gem install usa
+
+To use inside a bundled Ruby project, add this line to the `Gemfile`:
+
+    gem 'usa', '~> 0.1.0'
+
+Below 1.0 the pin stops at the next minor rather than the next major, because that is where a
+breaking change may still land. It becomes `~> 1.0` once the API is settled on purpose.
+
+## Getting the tables
+
+```sh
+bin/rails g usa:install   # six migrations, copied into your app and yours to keep
+bin/rails db:migrate      # the five tables, and every row in them
+```
+
+The last one takes about a minute: it writes 51 states, 3,144 counties, some 32,000 cities and
+some 41,000 ZIPs.
+
+**A database made from `db/schema.rb` has the tables and none of the rows.** A dump carries no
+data, so `db:schema:load`, `db:test:prepare` and a fresh clone all leave the five tables empty.
+Run `bin/rails db:usa:seed`, or call `USA.seed` from your own `db/seeds.rb`. The same command is
+how a database catches up with a release that added rows: every write is an upsert keyed on the
+code or the FIPS, so it inserts what is missing, updates what this gem owns, and leaves the id
+of every row you already had exactly where it was.
+
+## What you get
+
+```ruby
+zip = USA::ZIP.find_by code: '90210'  # => #<USA::ZIP>
+zip.city                              # => 'Beverly Hills'
+zip.time_zone                         # => 'Pacific Time (US & Canada)'
+zip.county                            # => #<USA::County>
+zip.county.fips                       # => '06037'
+zip.county.state.code                 # => 'CA'
+
+county = zip.county
+county.zips_count                     # => 508
+county.cities                         # => [#<USA::City>, ...]
+
+state = county.state
+state.counties_count                  # => 58
+state.counties                        # => [#<USA::County>, ...]
+state.cities                          # => [#<USA::City>, ...]
+```
+
+A state has a `code`, a `fips` and a `name`. A county has a `fips`, a `name` and a state. A city
+has a `fips` -- a Census place code, unique within its state rather than nationally -- a `name`,
+a state, and the one or more counties it lies in, since a city may cross a county line. A ZIP has
+a `code`, the `city` it is addressed as, a `time_zone` named as Rails names one, and one county.
+Every one of the four also has a `google_place_id`, filled for counties and blank elsewhere until
+a release fills it.
+
+Two counter caches are kept by the seed rather than by a callback: `usa_states.counties_count`
+and `usa_counties.zips_count`.
+
+## Making them yours
+
+Each model runs a load hook, so an app adds to it without reopening a file it does not own:
+
+```ruby
+# config/initializers/usa.rb
+ActiveSupport.on_load(:usa_zip) do
+  has_many :bookings, dependent: :destroy
+
+  scope :served, -> { where.not markets_count: 0 }
+end
+```
+
+`:usa_state`, `:usa_county`, `:usa_city` and `:usa_zip` are the four, and `:usa_record` is where
+an app says how all of them connect -- a reading role, say, which these models otherwise know
+nothing about:
+
+```ruby
+ActiveSupport.on_load(:usa_record) { connects_to database: { writing: :primary, reading: :reader } }
+```
+
+Columns of your own go on these tables in a migration of your own. They survive every seed: this
+gem writes only the columns it ships.
+
+## Adopting it in an app that already has these tables
+
+The gem registers `USA`, `ZIP` and `FIPS` as acronyms, so a class of yours called `Zip` stops
+being found the day you install it -- rename it, or reach `USA::ZIP` instead. Point your foreign
+keys at `usa_zips.id` rather than at a `zips` of your own, and where your rows were loaded with
+explicit ids, run `setval` on the sequence before the first seed, or the first insert collides.
+
+The gem does not support an app that sets `ActiveRecord::Base.table_name_prefix`: its migrations
+name `usa_states` while the models would look for the prefix and yours together.
+
+## Development
+
+`bin/setup` gets a clone working, `bin/console` opens a prompt with the library loaded, and
+`bundle exec rake` runs the suite, the linter and the two size limits. The dummy app under
+`test/dummy` is SQLite on purpose: it is a fixture rather than an app, and running the seed's
+upserts and the counter statements on a second adapter, with no server to start, is worth more
+than resembling the apps that install this.
+
+`bin/geocode` is the maintainer's, not the gem's: it fills the blank place ids in one CSV from
+the Google Geocoding API and is not packaged.
+
+## Reference
+
+The API reference is built from what RubyGems holds, at
+[rubydoc.info/gems/usa](https://rubydoc.info/gems/usa). The source is at
+[github.com/claudiob/usa](https://github.com/claudiob/usa).
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/app/models/concerns/usa/seeded.rb

@@ -0,0 +1,22 @@
+# What every table this gem ships knows how to do: write its own rows, twice over if asked.
+module USA::Seeded extend ActiveSupport::Concern
+  # Rows per statement. An upsert inlines its values rather than binding them, so this bounds
+  # how long one statement runs and how many rows are held at once, not a placeholder count.
+  SLICE = 1000
+
+  class_methods do
+    # Writes the rows this release holds that are missing, and the columns of the rest.
+    # @return [void]
+    def seed
+      seeds.each_slice(SLICE) do |slice|
+        upsert_all slice, unique_by: natural_key, record_timestamps: true
+      end
+    end
+
+  private
+
+    def csv(name)
+      CSV.foreach USA::Engine.root.join("db/seeds/#{name}.csv"), headers: true
+    end
+  end
+end

data/app/models/usa/city.rb

@@ -0,0 +1,32 @@
+# A city, town or census designated place: what a street address is addressed to.
+class USA::City < USA::Record
+  include USA::Seeded
+
+  belongs_to :state
+
+  has_many :city_counties, dependent: :delete_all
+  has_many :counties, through: :city_counties
+
+  validates :fips, presence: true, length: { is: 5 },
+    uniqueness: { scope: :state_id }
+  validates :name, presence: true
+
+  # @return [String] the default representation (used in views).
+  def to_s = "#{name} (#{state.code})"
+
+  class << self
+  private
+
+    def natural_key = %i[state_id fips]
+
+    def seeds
+      states = USA::State.pluck(:code, :id).to_h
+      csv('cities').lazy.map do |row|
+        { fips: row['fips'], name: row['name'], state_id: states.fetch(row['state']),
+          google_place_id: row['google_place_id'], }
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :usa_city, USA::City

data/app/models/usa/city_county.rb

@@ -0,0 +1,23 @@
+# Where a city lies: one row per county it reaches into, since a city may span several.
+class USA::CityCounty < USA::Record
+  include USA::Seeded
+
+  belongs_to :city
+  belongs_to :county
+
+  class << self
+  private
+
+    def natural_key = %i[city_id county_id]
+
+    def seeds
+      cities = USA::City.joins(:state).pluck('usa_states.code', :fips, 'usa_cities.id').
+        to_h { |code, fips, id| [ [ code, fips ], id ] }
+      counties = USA::County.pluck(:fips, :id).to_h
+      csv('cities').lazy.flat_map do |row|
+        city_id = cities.fetch [ row['state'], row['fips'] ]
+        row['counties'].split.map { |fips| { city_id:, county_id: counties.fetch(fips) } }
+      end
+    end
+  end
+end

data/app/models/usa/county.rb

@@ -0,0 +1,42 @@
+# A county, parish, borough or census area: the division every ZIP is counted under.
+class USA::County < USA::Record
+  include USA::Seeded
+
+  belongs_to :state, counter_cache: true
+
+  has_many :city_counties, dependent: :delete_all
+  has_many :cities, through: :city_counties
+  has_many :zips, dependent: :destroy
+
+  validates :fips, presence: true, length: { is: 5 }, uniqueness: true
+  validates :name, presence: true
+
+  # How many ZIPs a county holds, asked of the rows: an upsert runs no callback to keep it.
+  ZIPS = 'SELECT COUNT(*) FROM usa_zips WHERE usa_zips.county_id = usa_counties.id'
+
+  # Counts the ZIPs of every county the count is wrong for, and touches none of the others.
+  # @return [void]
+  def self.recount_zips
+    where("zips_count <> (#{ZIPS})").
+      update_all [ "zips_count = (#{ZIPS}), updated_at = ?", Time.current ]
+  end
+
+  # @return [String] the default representation (used in views).
+  def to_s = "#{name} (#{state.code})"
+
+  class << self
+  private
+
+    def natural_key = :fips
+
+    def seeds
+      states = USA::State.pluck(:code, :id).to_h
+      csv('counties').lazy.map do |row|
+        { fips: row['fips'], name: row['name'], state_id: states.fetch(row['state']),
+          google_place_id: row['google_place_id'], }
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :usa_county, USA::County

data/app/models/usa/record.rb

@@ -0,0 +1,6 @@
+# What every record this gem holds descends from, so a host says in one line how they connect.
+class USA::Record < ActiveRecord::Base
+  self.abstract_class = true
+end
+
+ActiveSupport.run_load_hooks :usa_record, USA::Record

data/app/models/usa/state.rb

@@ -0,0 +1,39 @@
+# A state of the United States, or the District of Columbia.
+class USA::State < USA::Record
+  include USA::Seeded
+
+  has_many :counties, dependent: :destroy
+  has_many :cities, dependent: :destroy
+
+  validates :code, presence: true, length: { is: 2 }, uniqueness: true
+  validates :fips, presence: true, length: { is: 2 }, uniqueness: true
+  validates :name, presence: true, uniqueness: true
+
+  # How many counties a state holds, asked of the rows: an upsert runs no callback to keep it.
+  COUNTIES = 'SELECT COUNT(*) FROM usa_counties WHERE usa_counties.state_id = usa_states.id'
+
+  # Counts the counties of every state the count is wrong for, and touches none of the others.
+  # @return [void]
+  def self.recount_counties
+    where("counties_count <> (#{COUNTIES})").
+      update_all [ "counties_count = (#{COUNTIES}), updated_at = ?", Time.current ]
+  end
+
+  # @return [String] the default representation (used in views).
+  def to_s = name
+
+  class << self
+  private
+
+    def natural_key = :code
+
+    def seeds
+      csv('states').lazy.map do |row|
+        { code: row['code'], fips: row['fips'], name: row['name'],
+          google_place_id: row['google_place_id'], }
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :usa_state, USA::State

data/app/models/usa/zip.rb

@@ -0,0 +1,29 @@
+# A ZIP code, and the city, time zone and county the Postal Service delivers it in.
+class USA::ZIP < USA::Record
+  include USA::Seeded
+
+  belongs_to :county, counter_cache: true
+
+  validates :code, presence: true, length: { is: 5 }, uniqueness: true
+  validates :city, presence: true
+  validates :time_zone, inclusion: { in: ActiveSupport::TimeZone.us_zones.map(&:name) }
+
+  # @return [String] the default representation (used in views).
+  def to_s = code
+
+  class << self
+  private
+
+    def natural_key = :code
+
+    def seeds
+      counties = USA::County.pluck(:fips, :id).to_h
+      csv('zips').lazy.map do |row|
+        { code: row['code'], city: row['city'], time_zone: row['time_zone'],
+          county_id: counties.fetch(row['county']), google_place_id: row['google_place_id'], }
+      end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :usa_zip, USA::ZIP

data/db/migrate/20260914120000_create_usa_states.rb

@@ -0,0 +1,12 @@
+class CreateUSAStates < ActiveRecord::Migration[8.1]
+  def change
+    create_table :usa_states do |t|
+      t.string :code, limit: 2, null: false, index: { unique: true }
+      t.string :fips, limit: 2, null: false, index: { unique: true }
+      t.string :name, null: false, index: { unique: true }
+      t.integer :counties_count, default: 0, null: false
+      t.string :google_place_id
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260914120001_create_usa_counties.rb

@@ -0,0 +1,12 @@
+class CreateUSACounties < ActiveRecord::Migration[8.1]
+  def change
+    create_table :usa_counties do |t|
+      t.string :fips, limit: 5, null: false, index: { unique: true }
+      t.string :name, null: false, index: true
+      t.references :state, null: false, foreign_key: { to_table: :usa_states }
+      t.integer :zips_count, default: 0, null: false
+      t.string :google_place_id
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260914120002_create_usa_zips.rb

@@ -0,0 +1,12 @@
+class CreateUSAZips < ActiveRecord::Migration[8.1]
+  def change
+    create_table :usa_zips do |t|
+      t.string :code, limit: 5, null: false, index: { unique: true }
+      t.string :city, null: false, index: true
+      t.string :time_zone, null: false
+      t.references :county, null: false, foreign_key: { to_table: :usa_counties }
+      t.string :google_place_id
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260914120003_create_usa_cities.rb

@@ -0,0 +1,12 @@
+class CreateUSACities < ActiveRecord::Migration[8.1]
+  def change
+    create_table :usa_cities do |t|
+      t.string :fips, limit: 5, null: false
+      t.string :name, null: false, index: true
+      t.references :state, null: false, index: false, foreign_key: { to_table: :usa_states }
+      t.string :google_place_id
+      t.timestamps
+      t.index %i[state_id fips], unique: true
+    end
+  end
+end

data/db/migrate/20260914120004_create_usa_city_counties.rb

@@ -0,0 +1,9 @@
+class CreateUSACityCounties < ActiveRecord::Migration[8.1]
+  def change
+    create_table :usa_city_counties, id: false do |t|
+      t.references :city, null: false, index: false, foreign_key: { to_table: :usa_cities }
+      t.references :county, null: false, foreign_key: { to_table: :usa_counties }
+      t.index %i[city_id county_id], unique: true
+    end
+  end
+end

data/db/migrate/20260914120005_seed_usa.rb

@@ -0,0 +1,5 @@
+class SeedUSA < ActiveRecord::Migration[8.1]
+  def change
+    up_only { USA.seed }
+  end
+end