tzf2 0.0.1

data/README.md

@@ -0,0 +1,146 @@
+# tzf2
+
+Offline latitude and longitude to IANA timezone lookup for Ruby. The gem wraps [tzf-rs](https://github.com/ringsaturn/tzf-rs) 2.0 and embeds current ocean-inclusive boundary data from [tzf-dist](https://github.com/ringsaturn/tzf-dist). Lookups do not use the network.
+
+This gem is a drop-in successor to [`tzf`](https://github.com/HarlemSquirrel/tzf-rb) for Rails apps that already call `TZF.tz_name(lat, lng)`. The published gem name is `tzf2` so it does not collide with HarlemSquirrel's gem.
+
+## Install
+
+You need Ruby 3.2 or newer (including 4.0).
+
+Precompiled native gems ship for `x86_64-linux`, `aarch64-linux`, `x86_64-darwin`, and `arm64-darwin`. Other platforms compile from source and need clang plus Rust 1.88 or newer.
+
+```ruby
+# Gemfile
+gem "tzf2"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+`require "tzf2"` and `require "tzf"` both load the `TZF` module.
+
+## Usage
+
+Arguments are latitude first, then longitude. That matches the existing `tzf` gem. It is the opposite of the Rust and Python APIs.
+
+```ruby
+require "tzf2"
+
+TZF.tz_name(40.7477, -73.9935)
+# => "America/New_York"
+
+TZF.tz_names(44.04, 87.416)
+# => ["Asia/Shanghai", "Asia/Urumqi"]
+
+TZF.data_version
+# => "2026c"
+
+TZF.engine_version
+# => "2.0.0"
+```
+
+`tz_name` returns one IANA identifier. `tz_names` returns every match, sorted, which matters on shared borders.
+
+Invalid coordinates raise `TZF::InvalidCoordinatesError`.
+
+```ruby
+TZF.tz_name(91, 0)
+# TZF::InvalidCoordinatesError: latitude 91.0 is outside -90..90
+```
+
+A valid point with no covering polygon raises `TZF::UncoveredCoordinateError`. Rescue that in the application if you need a fallback. This gem does not guess a neighbor zone.
+
+```ruby
+TZF.tz_name(-54.1, -36.1)
+# TZF::UncoveredCoordinateError: no timezone covers latitude -54.1, longitude -36.1
+```
+
+`raw_tz_name` and `raw_tz_names` return the engine result without raising (`""` / `[]` on a miss).
+
+## Global coverage
+
+The embedded dataset is timezone-boundary-builder `timezones-with-oceans` as packaged by tzf-dist release `2026c`. That product includes land zones, territorial waters, polar regions, and open-ocean `Etc/GMT*` zones. It does not tile the sphere without gaps.
+
+Lite simplification and a few source/encoding slivers leave hairline holes. A 10-degree grid is fully covered in `spec/fixtures/differential_baseline.json`. A 0.1-degree walk is not. Full-precision `tzf-dist` data closes some lite holes and still misses others.
+
+This gem returns `UncoveredCoordinateError` on those points. It does not snap to a neighbor.
+
+This release reports 444 timezone names.
+
+The default dataset is the lite `.tzb` file. Simplified boundaries stay within about 111 m of the full-precision border. See the [tzf-rs accuracy notes](https://github.com/ringsaturn/tzf-rs#accuracy).
+
+## Ocean timezone semantics
+
+Open ocean uses POSIX-signed `Etc/GMT*` identifiers.
+
+- `Etc/GMT+8` is UTC-08:00.
+- `Etc/GMT-5` is UTC+05:00.
+
+Point Nemo (`-48.876667, -123.393333`) returns `Etc/GMT+8`. Coastal points inside territorial waters keep the land zone.
+
+## Data provenance
+
+| Layer | Source | License |
+| --- | --- | --- |
+| Ruby and Rust wrapper | this repository | MIT, see `LICENSE` |
+| Lookup engine | [tzf-rs](https://github.com/ringsaturn/tzf-rs) 2.0.0 | MIT |
+| Packed `.tzb` data | [tzf-dist](https://github.com/ringsaturn/tzf-dist) `2026c` | ODbL, see `LICENSE_DATA` |
+| Original boundaries | [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder) | ODbL |
+
+The original database is built from OpenStreetMap. `NOTICE` names both upstreams.
+
+## Version reporting
+
+- `TZF::VERSION` is this gem.
+- `TZF.engine_version` is the compiled `tzf-rs` crate.
+- `TZF.data_version` is the tzf-dist / timezone-boundary-builder release inside the binary.
+
+Pin all three when you record a production lookup result.
+
+## Upgrades
+
+1. Bump `tzf-rs` in `ext/tzf2/Cargo.toml`.
+2. Run `cargo update -p tzf-rs` and `bundle exec rake compile`.
+3. Run `bundle exec rake spec`.
+4. Run `bundle exec ruby bin/differential`.
+5. If the report lists timezone-id, timezone-names, UTC-offset, newly covered, or uncovered points, decide whether the new data is intended.
+6. To accept the new table, run `bundle exec rake differential:write` and update `spec/fixtures/locations.yml`.
+7. Set `TZF.engine_version` in `ext/tzf2/src/lib.rs` to the new crate version.
+
+## Testing
+
+```bash
+bin/setup
+bundle exec rake
+bundle exec rake differential
+```
+
+Specs cover major cities, ocean zones including Point Nemo, polar and antimeridian points, shared borders, latitude/longitude order, invalid input, and thread safety.
+
+A 10-degree world grid and a 0.1-degree world grid are looked up in a standalone Rust binary (`crates/grid_parity`) and again through `TZF.raw_tz_name` / `TZF.raw_tz_names`. The answers must match, including empty engine results. That checks the Ruby wrapper against tzf-rs, not against a pinned Ruby table.
+
+The differential suite compares the current engine to `spec/fixtures/differential_baseline.json`. It reports timezone-id changes, all-match list changes, UTC-offset changes at `2026-01-15T12:00:00Z`, and points that gained or lost coverage.
+
+## Rollback
+
+Keep the previous `tzf2` git SHA in the Gemfile if a data upgrade changes production answers.
+
+```ruby
+gem "tzf2", github: "joseph-lozano/tzf-2-rb", ref: "<known-good-sha>"
+```
+
+To go back to HarlemSquirrel's gem, restore `gem "tzf"` and `require "tzf"`. The call shape is the same. Answers can differ because that gem still tracks tzf-rs 1.x.
+
+## Supported platforms
+
+CI compiles and tests Ruby 3.2, 3.3, 3.4, and 4.0 on Ubuntu, plus Ruby 3.4 on `ubuntu-24.04-arm`, `macos-15-intel`, and `macos-latest`.
+
+Release builds precompiled gems for Linux x86_64, Linux ARM64, Intel Mac, and Apple Silicon. Windows is not supported.
+
+## License
+
+MIT for the wrapper. ODbL for the embedded boundary database. See `LICENSE`, `LICENSE_DATA`, and `NOTICE`.

data/ext/tzf2/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "tzf2"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = { version = "0.8" }
+tzf-rs = { version = "2.0.0", default-features = false, features = ["bundled"] }
+rb-sys = { version = "0.9", default-features = false, features = [
+    "stable-api-compiled-fallback",
+] }

data/ext/tzf2/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("tzf2/tzf2")

data/ext/tzf2/src/lib.rs

@@ -0,0 +1,39 @@
+use std::sync::LazyLock;
+
+use magnus::{function, prelude::*, Error, Ruby};
+use tzf_rs::DefaultFinder;
+
+static FINDER: LazyLock<DefaultFinder> = LazyLock::new(DefaultFinder::new);
+
+const ENGINE_VERSION: &str = "2.0.0";
+
+fn raw_tz_name(lat: f64, lng: f64) -> &'static str {
+    FINDER.get_tz_name(lng, lat)
+}
+
+fn raw_tz_names(lat: f64, lng: f64) -> Vec<&'static str> {
+    FINDER.get_tz_names(lng, lat)
+}
+
+fn raw_data_version() -> &'static str {
+    FINDER.data_version()
+}
+
+fn raw_engine_version() -> &'static str {
+    ENGINE_VERSION
+}
+
+fn raw_timezone_names() -> Vec<&'static str> {
+    FINDER.timezonenames()
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("TZF")?;
+    module.define_singleton_method("raw_tz_name", function!(raw_tz_name, 2))?;
+    module.define_singleton_method("raw_tz_names", function!(raw_tz_names, 2))?;
+    module.define_singleton_method("raw_data_version", function!(raw_data_version, 0))?;
+    module.define_singleton_method("raw_engine_version", function!(raw_engine_version, 0))?;
+    module.define_singleton_method("raw_timezone_names", function!(raw_timezone_names, 0))?;
+    Ok(())
+}

data/lib/tzf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "tzf2"

data/lib/tzf2/coordinates.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TZF
+  class Coordinates
+    attr_reader :latitude, :longitude
+
+    def self.parse(latitude, longitude)
+      new(latitude, longitude)
+    end
+
+    def initialize(latitude, longitude)
+      @latitude = finite_float(latitude, "latitude")
+      @longitude = finite_float(longitude, "longitude")
+      unless (-90.0..90.0).cover?(@latitude)
+        raise InvalidCoordinatesError, "latitude #{@latitude} is outside -90..90"
+      end
+      unless (-180.0..180.0).cover?(@longitude)
+        raise InvalidCoordinatesError, "longitude #{@longitude} is outside -180..180"
+      end
+    end
+
+    private
+
+    def finite_float(value, name)
+      unless value.is_a?(Numeric)
+        raise InvalidCoordinatesError, "#{name} must be numeric, got #{value.class}"
+      end
+
+      float = Float(value)
+      unless float.finite?
+        raise InvalidCoordinatesError, "#{name} must be a finite number"
+      end
+
+      float
+    end
+  end
+end

data/lib/tzf2/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TZF
+  class Error < StandardError; end
+
+  class InvalidCoordinatesError < Error; end
+
+  class UncoveredCoordinateError < Error; end
+end

data/lib/tzf2/version.rb

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

data/lib/tzf2.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "tzf2/version"
+require_relative "tzf2/errors"
+require_relative "tzf2/coordinates"
+
+ruby_minor_version = RUBY_VERSION.split(".")[0..1].join(".")
+versioned = File.join(__dir__, "tzf2", ruby_minor_version, "tzf2")
+if File.exist?("#{versioned}.bundle") || File.exist?("#{versioned}.so")
+  require versioned
+else
+  require_relative "tzf2/tzf2"
+end
+
+module TZF
+  class << self
+    def tz_name(latitude, longitude)
+      coords = Coordinates.parse(latitude, longitude)
+      name = raw_tz_name(coords.latitude, coords.longitude)
+      raise uncovered_error(coords) if name.empty?
+
+      name
+    end
+
+    def tz_names(latitude, longitude)
+      coords = Coordinates.parse(latitude, longitude)
+      names = raw_tz_names(coords.latitude, coords.longitude)
+      raise uncovered_error(coords) if names.empty?
+
+      names
+    end
+
+    def data_version
+      raw_data_version
+    end
+
+    def engine_version
+      raw_engine_version
+    end
+
+    def timezone_names
+      raw_timezone_names
+    end
+
+    private
+
+    def uncovered_error(coords)
+      UncoveredCoordinateError.new(
+        "no timezone covers latitude #{coords.latitude}, longitude #{coords.longitude}"
+      )
+    end
+  end
+end

data/sig/tzf.rbs

@@ -0,0 +1,26 @@
+module TZF
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class InvalidCoordinatesError < Error
+  end
+
+  class UncoveredCoordinateError < Error
+  end
+
+  class Coordinates
+    attr_reader latitude: Float
+    attr_reader longitude: Float
+
+    def self.parse: (Numeric latitude, Numeric longitude) -> Coordinates
+    def initialize: (Numeric latitude, Numeric longitude) -> void
+  end
+
+  def self.tz_name: (Numeric latitude, Numeric longitude) -> String
+  def self.tz_names: (Numeric latitude, Numeric longitude) -> Array[String]
+  def self.data_version: () -> String
+  def self.engine_version: () -> String
+  def self.timezone_names: () -> Array[String]
+end

data/tzf2.gemspec

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "lib/tzf2/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "tzf2"
+  spec.version = TZF::VERSION
+  spec.authors = ["Joseph Lozano"]
+  spec.email = ["me@lozanojoseph.com"]
+
+  spec.summary = "Offline latitude/longitude to IANA timezone lookup via tzf-rs 2"
+  spec.description = <<~DESC
+    Ruby wrapper around tzf-rs v2 for offline timezone lookup from WGS84
+    coordinates. Embeds current ocean-inclusive timezone-boundary-builder data
+    from tzf-dist. No runtime network access.
+  DESC
+  spec.homepage = "https://github.com/joseph-lozano/tzf-2-rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_rubygems_version = ">= 3.4.6"
+
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.files = %w[
+    CHANGELOG.md
+    Cargo.lock
+    Cargo.toml
+    LICENSE
+    LICENSE_DATA
+    NOTICE
+    README.md
+    ext/tzf2/Cargo.toml
+    ext/tzf2/extconf.rb
+    ext/tzf2/src/lib.rs
+    lib/tzf.rb
+    lib/tzf2.rb
+    lib/tzf2/coordinates.rb
+    lib/tzf2/errors.rb
+    lib/tzf2/version.rb
+    sig/tzf.rbs
+    tzf2.gemspec
+  ]
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.extensions = ["ext/tzf2/extconf.rb"]
+
+  spec.add_dependency "rb_sys", "~> 0.9.117"
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: tzf2
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Joseph Lozano
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.117
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.117
+description: |
+  Ruby wrapper around tzf-rs v2 for offline timezone lookup from WGS84
+  coordinates. Embeds current ocean-inclusive timezone-boundary-builder data
+  from tzf-dist. No runtime network access.
+email:
+- me@lozanojoseph.com
+executables: []
+extensions:
+- ext/tzf2/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE
+- LICENSE_DATA
+- NOTICE
+- README.md
+- ext/tzf2/Cargo.toml
+- ext/tzf2/extconf.rb
+- ext/tzf2/src/lib.rs
+- lib/tzf.rb
+- lib/tzf2.rb
+- lib/tzf2/coordinates.rb
+- lib/tzf2/errors.rb
+- lib/tzf2/version.rb
+- sig/tzf.rbs
+- tzf2.gemspec
+homepage: https://github.com/joseph-lozano/tzf-2-rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/joseph-lozano/tzf-2-rb/issues
+  changelog_uri: https://github.com/joseph-lozano/tzf-2-rb/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/joseph-lozano/tzf-2-rb
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+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: 3.4.6
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Offline latitude/longitude to IANA timezone lookup via tzf-rs 2
+test_files: []