zip_to_tz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0681e9467076100fc6da8cfdc5f163d7cfa47901c374b35398a59d22cc275ed5'
+  data.tar.gz: 7d0c91741d0b2e5bd31804601bed3fae9caaad4c35d13ae44c9267918980fed8
+SHA512:
+  metadata.gz: ac0db3eff352bc9ba29a12b4bec7423de3ace46de24b32e81dfa1d2cf57528a6400486cb8faa4a8bffc34da2531070e681b9fff7da77906f7b2ada9378ab6e54
+  data.tar.gz: b47a7273adc93a573e74ef66ea4930d7be75fc332d0378145cd653126ffc83dfa5eaba01c4ab115f6f96f8a527fdf7b63f0fe43ccffd1cd397ecfb8fe45a04a0

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.rspec_status
+Gemfile.lock
+pkg/
+*.gem

data/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+## What this is
+
+`zip_to_tz` is a Ruby gem, a port of the Node.js [zipToTz](https://github.com/pmmonier/zipToTz)
+library. It maps a US zip code to a timezone — either the full IANA name (`America/New_York`) or
+a short abbreviation (`EDT`).
+
+## Structure
+
+- `lib/zip_to_tz.rb` — module entry point. `ZipToTz.full`/`ZipToTz.short` are convenience methods
+  backed by one memoized `Converter` instance.
+- `lib/zip_to_tz/converter.rb` — `ZipToTz::Converter`, the actual lookup logic.
+- `lib/zip_to_tz/errors.rb` — `ZipToTz::Error` and its two subclasses, `InvalidZipCodeError` and
+  `NotFoundError`.
+- `lib/zip_to_tz/data/timezones_to_zipcodes.yml` — the only data file. Maps each IANA timezone
+  name to its list of zip codes (~83k entries total). `Converter` inverts this into a
+  zip → timezone hash on first use, cached at the class level (`Converter.index`), shared by all
+  instances.
+- `spec/` — RSpec tests, mirrors `lib/` layout (`spec/zip_to_tz_spec.rb` for the module-level API,
+  `spec/zip_to_tz/converter_spec.rb` for the `Converter` class).
+
+## How `short` works
+
+There is no separate short-name data file. `Converter::ABBREVIATIONS` is a small hard-coded table
+(one entry per timezone actually present in the dataset) mapping full IANA name → abbreviation.
+`#short` calls `#full` and looks up the result in that table, so the two methods can never
+disagree. (Upstream ships two independently-maintained YAML files for this and they had drifted
+out of sync for one zip code — that's why this port collapses them into one source of truth.)
+
+The abbreviations are static per-zone, not date-aware — e.g. `America/New_York` is always `EDT`
+here, never `EST`, matching upstream's behavior. This is a known simplification, not a bug to fix
+unless asked.
+
+## Dev workflow
+
+```bash
+bundle install          # install dependencies
+bundle exec rspec       # run the test suite
+gem build zip_to_tz.gemspec   # build the .gem
+gem install ./zip_to_tz-<version>.gem   # install it locally
+```
+
+Run `bundle exec rspec` after any change to `lib/` or the data file before considering the work
+done — the converter spec includes a full-dataset consistency check (`short` vs `full` for every
+one of the ~83k zip codes), which is cheap to run and catches data regressions immediately.
+
+## Data file gotchas
+
+The YAML data mixes quoted (`'00100'`) and unquoted (`00108`) zip-code scalars, carried over from
+upstream. This matters because YAML 1.1 parsers can misread a leading-zero numeric-looking scalar
+as an octal integer. It happens to be safe as-is: every unquoted entry in the current file fails
+Ruby's octal pattern (it contains an 8 or 9), so Psych always resolves it back to a string. If the
+data file is ever regenerated or replaced, re-verify this — a quick way is to round-trip every zip
+in the file through `Converter#full` and assert the key format survives (`\A\d{5}\z`).
+
+## Error semantics (must stay compatible with upstream's intent)
+
+- Non-5-digit or non-numeric input → `ZipToTz::InvalidZipCodeError` ("Invalid format or zipCode
+  length" in upstream).
+- Valid-format zip with no mapping → `ZipToTz::NotFoundError` ("Not found" in upstream).
+
+Both inherit from `ZipToTz::Error`.

data/CLAUDE.md

@@ -0,0 +1,14 @@
+@AGENTS.md
+
+## Claude-specific instructions
+
+- Don't add error handling, validation, or abstractions beyond what's described in AGENTS.md —
+  this is a small, deliberately minimal port. Three similar lines beat a premature helper.
+- Default to no comments in code; the one exception already made (`Converter::ABBREVIATIONS`) is
+  there because the reasoning (why these specific 7 zones, why static per-zone) isn't obvious
+  from the code alone.
+- Never regenerate or hand-edit `lib/zip_to_tz/data/timezones_to_zipcodes.yml` without re-running
+  the round-trip check described in AGENTS.md's "Data file gotchas" section — a bad edit here
+  fails silently (wrong timezone returned) rather than raising.
+- Before reporting any change to `lib/` or the data file as complete, run `bundle exec rspec` and
+  confirm all examples pass, including the full-dataset consistency spec.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2026 Jeff Miller
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,97 @@
+# ZipToTz
+
+A Ruby port of the Node.js [zipToTz](https://github.com/pmmonier/zipToTz) library. Looks up the
+IANA timezone name or abbreviation for a US zip code, using an updated (2020) zip code list.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add zip_to_tz
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install zip_to_tz
+```
+
+## Usage
+
+```ruby
+require "zip_to_tz"
+
+ZipToTz.full("33487")  # => "America/New_York"
+ZipToTz.short("33487") # => "EDT"
+```
+
+Or use the `Converter` class directly:
+
+```ruby
+converter = ZipToTz::Converter.new
+converter.full("33487")  # => "America/New_York"
+converter.short("33487") # => "EDT"
+```
+
+### Input format
+
+The zip code must be exactly 5 digits (whitespace is stripped first). ZIP+4 codes are not
+truncated — `"33487-1234"` raises `InvalidZipCodeError` rather than being treated as `"33487"`.
+
+### Supported timezones
+
+Only US zip codes are covered, spanning these seven zones:
+
+| IANA name             | Abbreviation |
+| ---------------------- | ------------ |
+| `America/New_York`     | `EDT`        |
+| `America/Chicago`      | `CDT`        |
+| `America/Denver`       | `MDT`        |
+| `America/Los_Angeles`  | `PDT`        |
+| `America/Phoenix`      | `MST`        |
+| `America/Anchorage`    | `AKDT`       |
+| `Pacific/Honolulu`     | `HST`        |
+
+`short` always returns the abbreviation above, even in months when the zone is actually on
+standard time — e.g. `ZipToTz.short("33487")` returns `EDT` year-round, never `EST`. Arizona and
+Hawaii don't observe daylight saving, so their zones use a standard-time abbreviation instead.
+This is a known simplification inherited from upstream, not a date-aware lookup.
+
+### Errors
+
+- `ZipToTz::InvalidZipCodeError` — raised if the input isn't exactly 5 digits.
+- `ZipToTz::NotFoundError` — raised if the zip code has no timezone mapping.
+
+Both inherit from `ZipToTz::Error`.
+
+```ruby
+begin
+  ZipToTz.full("abc")
+rescue ZipToTz::Error => e
+  # handle error
+end
+```
+
+### Data
+
+`short` is derived from `full`, so both are always consistent for a given zip code — see
+[AGENTS.md](AGENTS.md) for why and how.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to
+run the tests. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Credit
+
+Ported from the original JavaScript/TypeScript implementation by
+[pmmonier](https://github.com/pmmonier/zipToTz).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/zip_to_tz/converter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module ZipToTz
+  # Looks up IANA timezone names or abbreviations for US zip codes.
+  #
+  # tz = ZipToTz::Converter.new
+  # tz.full("33487")  # => "America/New_York"
+  # tz.short("33487") # => "EDT"
+  class Converter
+    DATA_FILE = File.expand_path("data/timezones_to_zipcodes.yml", __dir__)
+    ZIP_FORMAT = /\A\d{5}\z/
+
+    # The upstream zip list only spans the timezones below, each pinned to a
+    # single abbreviation (Arizona and Hawaii don't observe daylight saving,
+    # so their zones keep a standard-time abbreviation year-round).
+    ABBREVIATIONS = {
+      "America/New_York" => "EDT",
+      "America/Chicago" => "CDT",
+      "America/Denver" => "MDT",
+      "America/Los_Angeles" => "PDT",
+      "America/Phoenix" => "MST",
+      "Pacific/Honolulu" => "HST",
+      "America/Anchorage" => "AKDT"
+    }.freeze
+
+    def full(zip)
+      self.class.index.fetch(normalize(zip)) { raise NotFoundError, "Not found" }
+    end
+
+    def short(zip)
+      timezone = full(zip)
+      ABBREVIATIONS.fetch(timezone) { raise NotFoundError, "Not found" }
+    end
+
+    private
+
+    def normalize(zip)
+      value = zip.to_s.gsub(/\s/, "")
+      raise InvalidZipCodeError, "Invalid format or zipCode length" unless value.match?(ZIP_FORMAT)
+
+      value
+    end
+
+    class << self
+      # Shared across all instances: the zip list is static, so there's no
+      # reason for every Converter.new to re-parse and re-index the data.
+      def index
+        @index ||= build_index
+      end
+
+      private
+
+      def build_index
+        data = YAML.safe_load_file(DATA_FILE, permitted_classes: [Integer])
+        index = {}
+        data.each do |timezone, zips|
+          zips.each { |zip| index[zip.to_s] = timezone }
+        end
+        index.freeze
+      end
+    end
+  end
+end