geo_states 0.1.0

data/lib/geo_states/data_loader.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GeoStates
+  # Loads country/state data from bundled JSON (no external API at runtime).
+  module DataLoader
+    DATA_DIR = File.expand_path("data", __dir__)
+    COUNTRIES_FILE = File.join(DATA_DIR, "countries.json")
+
+    class << self
+      def load_countries
+        @countries = nil
+        raw = File.read(COUNTRIES_FILE)
+        list = JSON.parse(raw)
+        list.map { |c| normalize_country(c) }
+      end
+
+      def countries
+        @countries ||= load_countries
+      end
+
+      def find_by_iso2(iso2)
+        countries.find { |c| c[:iso2].to_s.casecmp(iso2.to_s) == 0 }
+      end
+
+      def find_by_iso3(iso3)
+        countries.find { |c| c[:iso3].to_s.casecmp(iso3.to_s) == 0 }
+      end
+
+      def find_by_name(name)
+        countries.find { |c| c[:country].to_s.casecmp(name.to_s) == 0 }
+      end
+
+      def find_by_m49(m49)
+        code = m49.to_s.strip
+        return nil if code.empty?
+        code = code.rjust(3, "0") if code.length < 3
+        countries.find { |c| c[:m49].to_s == code }
+      end
+
+      private
+
+      def normalize_country(raw)
+        states = (raw["states"] || []).map { |s| normalize_state(s) }
+        {
+          country: raw["name"],
+          m49: raw["m49"],
+          iso3: raw["iso3"],
+          iso2: raw["iso2"],
+          currency: raw["currency"],
+          currency_symbol: raw["currency_symbol"],
+          phone_code: raw["phone_code"],
+          flag: raw["flag"],
+          states: states
+        }
+      end
+
+      def normalize_state(raw)
+        code = raw["state_code"].to_s
+        iso2 = code.length >= 2 ? code[0, 2].upcase : code.upcase
+        {
+          name: raw["name"],
+          state_code: code,
+          iso3: raw["iso3"] || code,
+          iso2: raw["iso2"] || iso2
+        }
+      end
+    end
+  end
+end

data/lib/geo_states/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GeoStates
+  VERSION = "0.1.0"
+end

data/lib/geo_states.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "geo_states/version"
+
+module GeoStates
+  class Error < StandardError; end
+
+  # All countries with states (from bundled data, no network).
+  # @return [Array<Hash>]
+  def self.all_countries
+    DataLoader.countries
+  end
+
+  # Find country by ISO 3166-1 alpha-2 (e.g. "MX", "US").
+  # @param iso2 [String]
+  # @return [Hash, nil]
+  def self.find_country(iso2)
+    DataLoader.find_by_iso2(iso2)
+  end
+
+  # Find country by ISO 3166-1 alpha-3 (e.g. "MEX", "USA").
+  # @param iso3 [String]
+  # @return [Hash, nil]
+  def self.find_country_by_iso3(iso3)
+    DataLoader.find_by_iso3(iso3)
+  end
+
+  # Find country by name (case-insensitive).
+  # @param name [String]
+  # @return [Hash, nil]
+  def self.find_country_by_name(name)
+    DataLoader.find_by_name(name)
+  end
+
+  # States for a country (by iso2, iso3, or country name).
+  # @param identifier [String] ISO2, ISO3, or country name
+  # @return [Array<Hash>]
+  def self.states_for(identifier)
+    country = find_country(identifier) ||
+              find_country_by_iso3(identifier) ||
+              find_country_by_name(identifier)
+    country&.dig(:states) || []
+  end
+end

data/sig/geo_states.rbs

@@ -0,0 +1,9 @@
+module GeoStates
+  VERSION: String
+
+  def self.all_countries: () -> Array[Hash[Symbol, untyped]]
+  def self.find_country: (String iso2) -> Hash[Symbol, untyped]?
+  def self.find_country_by_iso3: (String iso3) -> Hash[Symbol, untyped]?
+  def self.find_country_by_name: (String name) -> Hash[Symbol, untyped]?
+  def self.states_for: (String identifier) -> Array[Hash[Symbol, untyped]]
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: geo_states
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alberto Osnaya (@elosnaya)
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-17 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.
+email:
+- luisosnet@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- geo_states/data/countries.json
+- lib/geo_states.rb
+- lib/geo_states/data/countries.json
+- lib/geo_states/data_loader.rb
+- lib/geo_states/version.rb
+- sig/geo_states.rbs
+homepage: https://github.com/trasmisora/GeoStates
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/trasmisora/GeoStates
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Countries and states/subdivisions from bundled data (no external API at runtime).
+test_files: []