geopolitical 4.1.1 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c83de7fa358edf3032e002afa160eb629022a374f589f89a4e1c061d4113586
-  data.tar.gz: e262aefcfd984280b32c4aeddea8f64fd600fd130a303f10dc7631dbaddfb167
+  metadata.gz: d9d53d656a3190699410d4bdd673d9cb59ebc8ff25c9bca39bf7bde033f28e31
+  data.tar.gz: 14c19318010902ce4988843a63333a71dc1cb2596524a84a13208ea2c21dba78
 SHA512:
-  metadata.gz: 15b0754ffb716100a94ef4f539e605de42a543e17144c0a200187468fb9bce6855b4be25f0b62789ae0b3a291543ee190bf67f015d9d5ee94fdc45d77e3b0951
-  data.tar.gz: ed2410dfb3547275426197641976c1c1b9a7a0c54e687465e4ea3bc79fd9f5692b6ce68aefa8ac83024b61b838833aa70f76ff0b351cce6eb962e79eb950089e
+  metadata.gz: 38cb57c04db412f24dc8d0843b93fcc2e96f022c58ae3d9973b95c1f1add9d461070a728b2091ac3e114e7d7a23a7d53bb512c2d1d42944a427927f9d1f0ca1f
+  data.tar.gz: b4d3a57a2762bdb5ea9b5abb635efa90346d91165f742487987fb6c56838fcb4341e7ffb42de298ae83ff9b1b6555583244379fe7e29e53de1d9b38211b9e601

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.2.0
+
+- `City` includes `Mongoid::Geospatial::Geom` — the pin is the gem's, `within(geom, km)` too.
+- Indexes match the queries (README § The models). Gone, nothing read them: `name_1` on all four (`name` is localized, Mongoid asks `name.<locale>`), `cities.name_1_nation_id_1`, `cities.nation_id_1` (the unique compound leads with it), `regions.abbr_1` (every abbr lookup carries its nation), `code_1` on nations, regions and hoods (only City's is read, and stays). Hosts: `DROP_INDEXES=1` on the next deploy sheds them.
+- `Nation` checks a taken `abbr` as an equality on `abbr_1` (its writer upcases), not `/\ABR\z/i`.
+- `City` and `Hood` validate `slug` uniqueness: a taken slug is a 422 with its message, not an E11000 (a 500 in any form). Slugs are unique within a nation, not across: BR and AR both have a BA.
+- Every uniqueness message lives in the locales, en and pt (`mongoid.errors.models.<model>.attributes.<field>.taken`), no English literal in the models.
+- `Geopolitical::Postal.city` finds a slug in the address's own nation only: an Argentine "Salvador" in BA got Bahia's.
+- `.search` matches `\A`, not `^`: bson sends a Ruby regexp multiline, so `^` scanned all of `slug_1`. Now it reads the prefix's keys only.
+
 ## 4.1.0
 
 - Engine views are ERB; the `haml` gem is gone.

data/README.md

@@ -112,7 +112,9 @@ Region.ordered                  # by name
 ### Addresses — `Geopolitical::Postal`
 
 Two ways in, one answer out: a `Found` with the street, number, hood, postal
-code and the `City` (found, or made under its state's `Region`).
+code and the `City` (found, or made under its state's `Region`). Found in
+the address's own nation only: Brazil and Argentina both have a `BA`, and an
+Argentine "Salvador" never gets Bahia's `salvador-ba`.
 
 ```
   typing "av paulista 1578"  ──suggest──►  [Suggestion(ref, text), …]   free, nothing kept
@@ -179,6 +181,26 @@ Every model shares (via the `Geopolitocracy` concern):
 `name` & `alt` (localized), `abbr`, `nick`, `ascii`, `code`, `slug`,
 `souls`/`population`, `postal`, `phone`, `.search`, `.ordered`, `to_s`, `==`, `<=>`.
 
+The indexes, and the query each one is for (`Model.create_indexes` builds them):
+
+```
+nations  slug (u) · abbr (u)                    Nation['br'] is the _id
+regions  nation+name (u) · nation+abbr (u, when abbr) · nation+slug (u) · slug
+cities   slug (u) · nation+region+name (u) · region · souls · code · geom 2dsphere
+hoods    city+name (u) · slug (u)
+```
+
+A lookup by nation rides the unique compound it leads; a Region's abbr is
+always asked with its nation. `.search` is a slug prefix, `\A`, never `^`:
+bson sends a Ruby regexp multiline, and `^` there bounds no index.
+
+`name` is localized, so Mongoid asks for `name.<locale>` (`where`, `order_by`,
+the uniqueness check) and no index on the bare `name` hash could answer it.
+Only the unique ones key it: they referee two creates of the same name. A
+uniqueness the model validates is a unique index here, and a unique index
+here is a validation there: a clash is a 422 with its message, never an
+E11000.
+
 Names get titleized only when you shout or mumble: `'new york'` and
 `'NEW YORK'` become `"New York"`; `'McAllen'` stays `"McAllen"`.
 

data/app/models/city.rb

@@ -10,17 +10,14 @@
 # abbreviation to ensure uniqueness across regions.
 class City
   include Mongoid::Document
-  include Mongoid::Geospatial # For GIS capabilities like `geom` field and spatial queries
+  include Mongoid::Geospatial::Geom
   include Geopolitocracy
 
   # @!attribute [rw] area
   #   @return [Integer] The square area of the city in square meters (m2).
   field :area, type: Integer
 
-  # @!attribute [rw] geom
-  #   @return [Point] [lng, lat], 2dsphere — `nearby` is `$nearSphere`.
-  #
-  field :geom, type: Point, sphere: true
+  # geom — [lng, lat], 2dsphere. `City.nearby` / `City.within(point, km)`.
 
   # @!attribute [rw] rbbr
   #   @return [String] Cached abbreviation of the city's region.
@@ -50,7 +47,8 @@ class City
 
   before_validation :ensure_derived_fields_and_slug
 
-  validates :name, uniqueness: { scope: %i[nation_id region_id], message: 'must be unique within its region' }
+  validates :name, uniqueness: { scope: %i[nation_id region_id] }
+  validates :slug, uniqueness: true # slug_1 refuses a twin anyway; this says so before the E11000
   validates :nation, presence: true
   validate :region_inside_nation_if_region_present
 
@@ -59,11 +57,11 @@ class City
   scope :population, -> { order_by(souls: :desc) }
 
   index({ slug: 1 }, unique: true)
-  index({ name: 1, nation_id: 1 }) # For lookups by name within a nation
-  index({ nation_id: 1, region_id: 1, name: 1 }, { unique: true }) # Backs the name uniqueness validation
-  index({ nation_id: 1 }) # For finding all cities in a nation
+  # Backs the name uniqueness validation; its nation_id prefix is every lookup by nation.
+  index({ nation_id: 1, region_id: 1, name: 1 }, { unique: true })
   index({ region_id: 1 }, sparse: true) # For finding cities in a region, sparse if region is optional
   index({ souls: -1 }) # For sorting by population count
+  index({ code: 1 }, sparse: true) # The IBGE code: Geopolitical::Postal.city, fiscal documents
 
   # Validates that if a city is associated with a region, that region
   # belongs to the same nation as the city.
@@ -111,8 +109,10 @@ class City
       self.slug = name
     end
 
-    # 3. Suffix the slug so it is unique planet-wide: the region abbr where there
-    #    is a region ("santos-sp"), the nation abbr otherwise ("singapore-sg").
+    # 3. Suffix the slug: the region abbr where there is a region ("santos-sp"),
+    #    the nation abbr otherwise ("singapore-sg"). Unique within a nation, not
+    #    across them: BR and AR both have a BA, so a second "salvador-ba" is a
+    #    taken slug (the validation's message), never a silent twin.
     suffix = region_abbr.presence || nation&.abbr
     return if suffix.blank? || slug.blank?
 

data/app/models/concerns/geopolitocracy.rb

@@ -76,13 +76,11 @@ module Geopolitocracy
     validates :slug, presence: true # Uniqueness will be handled by including models with appropriate scope
     # @!endgroup
 
-    # @!group Indexes
-    # NOTE: no slug or abbr index here — each model declares its own (unique where
-    # it can be). Mongoid keys a declaration on the fields alone, so a second
-    # `index({ abbr: 1 }, unique: true)` in a model would be silently ignored.
-    index({ name: 1 }) # For sorting and lookups by name
-    index({ code: 1 }, { sparse: true }) # Sparse as code can be nil
-    # @!endgroup
+    # No index here: each model declares the ones its queries read (README
+    # § The models). Mongoid keys a declaration on the fields alone, so one
+    # here would silently win over a model's own on the same key. `name` is
+    # localized: Mongoid asks name.<locale>, and no index on the bare hash
+    # answers that.
 
     before_validation :ensure_slug_is_generated
 
@@ -140,7 +138,7 @@ module Geopolitocracy
       if exact # matches the exact slug
         where(slug: parameterized_query)
       else
-        where(slug: /^#{Regexp.escape(parameterized_query)}/)
+        where(slug: /\A#{Regexp.escape(parameterized_query)}/) # \A: bson sends ^ multiline, unbounded
       end
     end
     # @!endgroup

data/app/models/geopolitical/postal.rb

@@ -77,9 +77,13 @@ module Geopolitical
       return if region.nil? || name.blank?
 
       slug = "#{Geopolitocracy.slugify(name)}-#{Geopolitocracy.slugify(region.abbr)}"
-      City.where(slug: slug).first || make_city(name, code, region) || City.where(slug: slug).first
+      town(region, slug) || make_city(name, code, region) || town(region, slug)
     end
 
+    # A slug is unique within a nation, not across (BR and AR both have a
+    # BA): never another nation's town.
+    def town(region, slug) = City.where(nation_id: region.nation_id, slug: slug).first
+
     def region(nation, state)
       country = Nation[nation] or return
       Region.where(nation_id: country.id, abbr: state.to_s.upcase).first

data/app/models/hood.rb

@@ -18,14 +18,11 @@ class Hood
   belongs_to :city
 
   validates :city, presence: true
-  validates :name, uniqueness: { scope: :city_id, message: 'must be unique within its city' }
-  # `abbr` (from Geopolitocracy) could also be validated for uniqueness within the city if used.
-  # validates :abbr,
-  #           uniqueness: { scope: :city_id, allow_nil: true, message: "must be unique within its city if provided" }
+  validates :name, uniqueness: { scope: :city_id }
+  validates :slug, uniqueness: true # slug_1 refuses a twin anyway; this says so before the E11000
 
   index({ city_id: 1, name: 1 }, { unique: true })
-  # index({ city_id: 1, abbr: 1 }, { unique: true, sparse: true }) # If abbr is used and needs to be unique
-  index({ slug: 1 }, { unique: true }) # Hood slugs are globally unique due to city_slug prefix
+  index({ slug: 1 }, { unique: true }) # The city slug prefixes it, so two names that slugify alike collide
 
   before_validation :ensure_slug_for_hood
 

data/app/models/nation.rb

@@ -45,8 +45,8 @@ class Nation
   # alias iso_3166_3= code3=
 
   validates :abbr, presence: true # Name presence is validated in Geopolitocracy
-  validates_uniqueness_of :abbr, case_sensitive: false
-  validates :slug, uniqueness: { message: 'must be unique' } # Slug presence is validated in Geopolitocracy
+  validates_uniqueness_of :abbr # an equality: abbr= upcases, so the case is already one
+  validates :slug, uniqueness: true # Slug presence is validated in Geopolitocracy
 
   # @!attribute [rw] capital
   #   @return [City] The capital city of this nation.
@@ -59,7 +59,6 @@ class Nation
   #   @return [Mongoid::Relations::Targets::Enumerable<City>] The cities within this nation.
   has_many :cities,  dependent: :destroy
 
-  index({ name: 1 }) # Index for sorting by name, common operation
   index({ slug: 1 }, { unique: true }) # Slugs must be globally unique for nations
   index({ abbr: 1 }, { unique: true }) # abbr is upcased by its writer, so plain unique is case-insensitive
 

data/app/models/region.rb

@@ -27,18 +27,17 @@ class Region
   belongs_to :capital, inverse_of: :region_governancy, class_name: 'City', optional: true
 
   validates :nation, presence: true
-  validates :name, uniqueness: { scope: :nation_id, message: 'must be unique within its nation' }
-  # `abbr` (from Geopolitocracy) should also be unique within its nation if present.
-  validates :abbr,
-            uniqueness: { scope: :nation_id, allow_blank: true, message: 'must be unique within its nation if provided' }
-  # Slug (from Geopolitocracy) should be unique within its nation. Presence is already validated by Geopolitocracy.
-  validates :slug, uniqueness: { scope: :nation_id, message: 'must be unique within its nation' }
+  # Each message is mongoid.errors.models.region.attributes.<field>.taken (en, pt).
+  validates :name, uniqueness: { scope: :nation_id }
+  validates :abbr, uniqueness: { scope: :nation_id, allow_blank: true }
+  validates :slug, uniqueness: { scope: :nation_id }
 
   index({ slug: 1 }) # For .search; global uniqueness is not required, see the compound index below
-  index({ abbr: 1 }, { sparse: true }) # Sparse index as abbr can be nil
   index({ nation_id: 1, name: 1 }, { unique: true }) # Enforce uniqueness of name within nation
   # Partial, not sparse: nation_id is always set, so a sparse compound index
-  # still indexes every abbr-less region and the second one collides.
+  # still indexes every abbr-less region and the second one collides. Every
+  # abbr lookup carries its nation (an abbr alone is ambiguous: BR and AR both
+  # have a BA), so this is the abbr index too, `$in` included.
   index({ nation_id: 1, abbr: 1 }, { unique: true, partial_filter_expression: { abbr: { '$gt' => '' } } })
   index({ nation_id: 1, slug: 1 }, { unique: true }) # Enforce uniqueness of slug within nation
 

data/config/locales/geopolitical.en.yml

@@ -56,6 +56,32 @@ en:
         souls: Population
         postal: Postal
         phone: Phone
+    errors:
+      models:
+        nation:
+          attributes:
+            slug:
+              taken: must be unique
+        region:
+          attributes:
+            name:
+              taken: must be unique within its nation
+            abbr:
+              taken: must be unique within its nation if provided
+            slug:
+              taken: must be unique within its nation
+        city:
+          attributes:
+            name:
+              taken: must be unique within its region
+            slug:
+              taken: is taken by another city
+        hood:
+          attributes:
+            name:
+              taken: must be unique within its city
+            slug:
+              taken: is taken by another hood
   geopolitical:
     title: Geopolitical
     actions:

data/config/locales/geopolitical.pt.yml

@@ -56,6 +56,32 @@ pt:
         souls: População
         postal: CEP
         phone: Telefone
+    errors:
+      models:
+        nation:
+          attributes:
+            slug:
+              taken: já está em uso
+        region:
+          attributes:
+            name:
+              taken: já existe neste país
+            abbr:
+              taken: já existe neste país
+            slug:
+              taken: já existe neste país
+        city:
+          attributes:
+            name:
+              taken: já existe nesta região
+            slug:
+              taken: já está em uso por outra cidade
+        hood:
+          attributes:
+            name:
+              taken: já existe nesta cidade
+            slug:
+              taken: já está em uso por outro bairro
   geopolitical:
     title: Geopolítico
     actions:

data/geopolitical.gemspec

@@ -21,5 +21,5 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 3.2.0'
 
   s.add_dependency 'mongoid', '>= 8.0.0'
-  s.add_dependency 'mongoid-geospatial', '>= 7.0.0'
+  s.add_dependency 'mongoid-geospatial', '>= 7.2.0'
 end

data/lib/geopolitical/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Geopolitical
-  VERSION = '4.1.1'
+  VERSION = '4.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geopolitical
 version: !ruby/object:Gem::Version
-  version: 4.1.1
+  version: 4.2.0
 platform: ruby
 authors:
 - Marcos Piccinini
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 7.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 7.2.0
 description: 'The whole planet as four Mongoid models: hierarchy, i18n names, unicode-safe
   slugs, geo queries, phone/postal fallbacks and an admin engine.'
 email:
@@ -123,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Nation, Region, City and Hood models for Mongoid.
 test_files: []