geo_states 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23f5adf00ed40e770fefae1b152febf5de3f6cf0e3fd0db046f749040372582a
-  data.tar.gz: 9bd7ee1dcb2378dc300d8ac94a0aa08fb76bce1d74daa0629865607efe0e27cb
+  metadata.gz: 8e48781ab93b649cc825612b4f963b053c0398bc7f658d33fff60857331ecf50
+  data.tar.gz: 749026242fb43ca2d91cc26670d8ec1670ec965468eb5e35530db729a1b888fa
 SHA512:
-  metadata.gz: f141eeec003f3b685b15ea5f1d56c0c529f167426cba1e989bbee07df14dcd539dc50dc8b2b37ab5ca45328d54ee5a95f9f8f944f1d0c8cc044626f56c8e1096
-  data.tar.gz: 0ea2455867a0d1e41eb3e82c2c5630aadb5b54fc62043af7c8bbd5ffe948d6f1f15d16ec41839f3ee97ec6e0f7c3351348d314d3f329e0f8d82b34a8472c8ceb
+  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.4'
+  VERSION = '0.1.5'
 end

data/lib/geo_states.rb

@@ -90,7 +90,8 @@ module GeoStates
     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
@@ -100,16 +101,11 @@ module GeoStates
     return [nil, nil, false] if id.empty?
 
     from_config = ConfigLoader.resolve_alias(iso2, id)
-    canonical = from_config || id
-
-    # Built-in: Mexico DF -> CMX (bundled data uses CMX; user config may map CDMX => DF)
-    if iso2.to_s.upcase == 'MX' && canonical.to_s.upcase == 'DF'
-      return ['CMX', 'DF', true]
-    end
-
-    # When from config, use that as preferred and mark as from_alias
+    preferred = from_config || id
     from_alias = !from_config.nil?
-    preferred = from_config || canonical
-    [canonical, preferred, from_alias]
+
+    # 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.4
+  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.