geo_states 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b757132bddec9472e730189fa998a1ef255440bb12eec76f407c9242b07b685
-  data.tar.gz: 0b5f64fde99b17656d2ced4965c5f766dbcc9b9f533d7ee14389ce83e0c93baa
+  metadata.gz: 8e48781ab93b649cc825612b4f963b053c0398bc7f658d33fff60857331ecf50
+  data.tar.gz: 749026242fb43ca2d91cc26670d8ec1670ec965468eb5e35530db729a1b888fa
 SHA512:
-  metadata.gz: 29f3e3ccc65d2b2f7b5c03f2ec807e754dc4f3c3a4d79b940a2bb91dd32b485e7d5da378a62d511c7e3999cb14babdc661f0b310c7c053870dc4e49a81d897fc
-  data.tar.gz: b06009b62f7580a61cbaba751652c820963046b116d334c0208e45eec37316e45d031c8974caeffd6bb1051f88ed7f0ac28e2cb3bd25c03421526739099c3196
+  metadata.gz: 36318233ab28afa96f3174ad0a893c9966e100b78790739758bdd49d69958d7a5937d8a68e446d76e52881d9ed3291286388c59593f9eda34722f81e0b0002d8
+  data.tar.gz: 1c63dd25eaba4ff9917b62d4ac9d10523e2da4c6e486ae8f77d39dbfd5bcb43c0898b9022cade367cdc43909b157e33f5daa7239942dc8c34f4b00f82b876400

data/README.md

@@ -107,15 +107,17 @@ Example `config/geo_states.yml`:
 
 ```yaml
 MX:
-  state_aliases:
-    CDMX: DF
-    DF: DF
-    DISTRITO FEDERAL: DF
-    CIUDAD DE MEXICO: DF
-    MEXICO CITY: DF
+  CDMX: DF
+  DF: DF
+  DISTRITO FEDERAL: DF
+  CIUDAD DE MEXICO: DF
+  MEXICO CITY: DF
+  _lookup:
+    DF: CMX
 ```
 
-Values map to the `state_code` in the bundled data. For Mexico City the data uses `CMX`; `DF` is a built-in alias that maps to `CMX`. So `CDMX` → `DF` → `CMX` works when you have the config.
+- Aliases map to your preferred `state_code` (e.g. `DF`).
+- `_lookup` maps that preferred value to the actual `state_code` in the bundled data when they differ (e.g. bundled data has `CMX` for Mexico City).
 
 See `config/geo_states.example.yml` for a copy-paste template.
 

data/config/geo_states.example.yml

@@ -2,13 +2,14 @@
 # Copy to config/geo_states.yml or geo_states.yml in your project root.
 # Or set GEO_STATES_CONFIG_PATH to the config file path.
 #
-# Values must map to state_code in bundled data (e.g. CMX for Mexico City).
-# DF is supported as built-in alias for Mexico City (CMX).
+# Aliases map to preferred state_code. Use _lookup when preferred isn't in bundled data.
+# Example: Mexico City has CMX in data; user wants DF in output.
 
 MX:
-  state_aliases:
-    CDMX: DF
-    DF: DF
-    DISTRITO FEDERAL: DF
-    CIUDAD DE MEXICO: DF
-    MEXICO CITY: DF
+  CDMX: DF
+  DF: DF
+  DISTRITO FEDERAL: DF
+  CIUDAD DE MEXICO: DF
+  MEXICO CITY: DF
+  _lookup:
+    DF: CMX

data/lib/geo_states/config_loader.rb

@@ -25,26 +25,50 @@ module GeoStates
         @state_aliases = nil
       end
 
-      # Resolve state identifier via user config. Returns canonical state_code or nil.
+      # Resolve state identifier via user config. Returns alias value or nil.
       # @param country_iso2 [String] e.g. "MX"
       # @param state_id [String] e.g. "CDMX", "DF"
-      # @return [String, nil] resolved state_code (e.g. "CMX") or nil
+      # @return [String, nil] resolved value (e.g. "DF") or nil
       def resolve_alias(country_iso2, state_id)
         return nil if country_iso2.nil? || state_id.nil?
 
         iso2 = country_iso2.to_s.upcase
         id = state_id.to_s.strip
 
-        aliases = state_aliases[iso2]
+        map = alias_map_for(iso2)
+        return nil unless map
+
+        val = map[id] || map[id.upcase]
+        val.to_s if val
+      end
+
+      # Resolve preferred/alias to actual state_code for lookup when it's not in bundled data.
+      # E.g. _lookup: { DF: CMX } — DF (user preference) maps to CMX (in data).
+      # @param country_iso2 [String] e.g. "MX"
+      # @param preferred [String] e.g. "DF"
+      # @return [String, nil] lookup key for bundled data, or nil
+      def resolve_lookup(country_iso2, preferred)
+        return nil if country_iso2.nil? || preferred.nil?
+
+        aliases = state_aliases[country_iso2.to_s.upcase]
+        return nil unless aliases.is_a?(Hash)
+
+        lookup = aliases['_lookup'] || aliases['lookup']
+        return nil unless lookup.is_a?(Hash)
+
+        val = lookup[preferred] || lookup[preferred.to_s.upcase]
+        val.to_s if val
+      end
+
+      # Alias map for a country (excludes _lookup / lookup).
+      def alias_map_for(country_iso2)
+        aliases = state_aliases[country_iso2.to_s.upcase]
         return nil unless aliases.is_a?(Hash)
 
-        # Support both flat and nested structure:
-        # MX: { CDMX: CMX } or MX: { state_aliases: { CDMX: CMX } }
         map = aliases['state_aliases'] || aliases
         return nil unless map.is_a?(Hash)
 
-        val = map[id] || map[id.upcase]
-        val.to_s if val
+        map.except('_lookup', 'lookup')
       end
 
       private

data/lib/geo_states/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GeoStates
-  VERSION = '0.1.3'
+  VERSION = '0.1.5'
 end

data/lib/geo_states.rb

@@ -59,8 +59,9 @@ module GeoStates
     country&.dig(:states) || []
   end
 
-  # Find a state within a country. Accepts user YAML config for aliases (e.g. CDMX => CMX).
+  # Find a state within a country. Accepts user YAML config for aliases (e.g. CDMX => DF).
   # Config file: config/geo_states.yml or geo_states.yml, or GEO_STATES_CONFIG_PATH env.
+  # When resolved via alias (config or built-in), the returned hash uses the alias as state_code (e.g. "DF").
   # @param country_id [String] ISO2, ISO3, M49, or country name (e.g. "MX", "Mexico")
   # @param state_id [String] state_code, name, or alias from user config (e.g. "CMX", "CDMX", "Mexico City")
   # @return [Hash, nil] state hash with :name, :state_code, :iso2, :iso3, or nil
@@ -68,28 +69,43 @@ module GeoStates
     country = find_country(country_id)
     return nil unless country
 
-    canonical = resolve_state_id(country[:iso2], state_id.to_s)
-    return nil if canonical.nil? || canonical.empty?
+    lookup_key, preferred_state_code, from_alias = resolve_state_id(country[:iso2], state_id.to_s)
+    return nil if lookup_key.nil? || lookup_key.empty?
 
     states = country[:states] || []
-    states.find do |s|
-      s[:state_code].to_s.casecmp(canonical) == 0 ||
-        s[:name].to_s.casecmp(canonical) == 0
+    state = states.find do |s|
+      s[:state_code].to_s.casecmp(lookup_key) == 0 ||
+        s[:name].to_s.casecmp(lookup_key) == 0
     end
+    return nil unless state
+
+    # Use alias value (e.g. DF) in result when resolved via config or built-in alias
+    if from_alias && preferred_state_code && preferred_state_code != state[:state_code]
+      state = state.merge(
+        state_code: preferred_state_code,
+        iso3: preferred_state_code,
+        iso2: preferred_state_code.length >= 2 ? preferred_state_code[0, 2].upcase : preferred_state_code.upcase
+      )
+    end
+    state
   end
 
-  # Resolve state identifier: user config first, then built-in aliases (e.g. DF -> CMX for Mexico).
+  # Resolve state identifier: user config aliases. Use _lookup in config to map
+  # preferred values (e.g. DF) to actual state_code in bundled data (e.g. CMX).
+  # Returns [lookup_key, preferred_state_code, from_alias].
   # @param iso2 [String] country ISO2
   # @param state_id [String] user input
-  # @return [String] canonical state_code for lookup
+  # @return [Array] [lookup_key, preferred_state_code, from_alias]
   def self.resolve_state_id(iso2, state_id)
     id = state_id.to_s.strip
-    return nil if id.empty?
+    return [nil, nil, false] if id.empty?
 
-    canonical = ConfigLoader.resolve_alias(iso2, id) || id
-    # Built-in: Mexico DF -> CMX (bundled data uses CMX; user config may map CDMX => DF)
-    return 'CMX' if iso2.to_s.upcase == 'MX' && canonical.to_s.upcase == 'DF'
+    from_config = ConfigLoader.resolve_alias(iso2, id)
+    preferred = from_config || id
+    from_alias = !from_config.nil?
 
-    canonical
+    # When preferred isn't in bundled data, check _lookup (e.g. DF => CMX for MX)
+    lookup_key = ConfigLoader.resolve_lookup(iso2, preferred) || preferred
+    [lookup_key, preferred, from_alias]
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geo_states
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Alberto Osnaya (@elosnaya)
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-20 00:00:00.000000000 Z
+date: 2026-02-21 00:00:00.000000000 Z
 dependencies: []
 description: Lists countries and their states (or provinces, regions) in a consistent
   format. Data is bundled with the gem.