ziptz 5.1.2 → 6.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b310de1d20cfb9b20cba87249ee230e5baff3efbab063fd7c87b21e7c5e458af
-  data.tar.gz: 7434225f05490776ced760c84f522b41b7ff2afc903a2cb4c1729c7b5a71d748
+  metadata.gz: 8e148a6e535c92aee764520b3741c8c550719d2c430df9c18f84252e233eb17a
+  data.tar.gz: 1d56d7416206c48354f30f0b544639d99e86ed68908a9214ee654cdee7cbf70a
 SHA512:
-  metadata.gz: ded78e81fcfcad3917c824512de4c0e8eb902ef37f45fc7300610796100e4d367a338fabe1e4aa18b8237012208268bb3c55efc016021099b055ffddcd3ab34c
-  data.tar.gz: 81050bfeefe7dc5aa8ad492cece4975c8382178037a445f97957005e11f9242f1d6291073650031687fa90fa79df87403587368946b23c33787200789a33a8fe
+  metadata.gz: 69974ccd6732bb9043f9c4c7ab5f77ec9d5cc4991b07170b7ea92630f9910a24df9eb7fdc941930f092c188d480b967dfc3e83a99eb1462fd6c1f2e2a4298fe8
+  data.tar.gz: 1665d43f017697702ed8d3c4d8468d06e33bd46bc6f3e172fb39a4f342f05bd95b9eb7b3a4da93cdfe581a38ba5e610ee71b11f23473302838eee56361fd503d

data/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 6.2.0 - 2026-08-14
+
+### Added
+
+- Automated gem publication via
+  [RubyGems trusted publishing](https://guides.rubygems.org/trusted-publishing/):
+  pushing a `v*` tag builds and publishes the gem from GitHub Actions.
+- Gemspec metadata links (`source_code_uri`, `changelog_uri`,
+  `bug_tracker_uri`) and this changelog.
+- Zip codes may now be passed as Integers; they are zero-padded to 5 digits
+  (`z.time_zone_name(601)` looks up `00601`). Previously an Integer raised
+  `NoMethodError`.
+- `Ziptz#close` closes the cached SQLite connection for the instance's
+  database on the current thread. Closing is idempotent and a new connection
+  is opened automatically on the next query.
+
+### Fixed
+
+- Database connections are cached per database path, so multiple `Ziptz`
+  instances pointing at different databases no longer share a connection.
+- The packaged gem no longer includes the spec suite and its 2.7 MB fixture
+  database, shrinking the gem from ~2.7 MB to a few KB.
+
+### Changed
+
+- CI now enforces RuboCop and runs tests against Ruby 3.3, 3.4, and 4.0.
+- `Ziptz::VERSION` moved from `lib/version.rb` to the conventional
+  `lib/ziptz/version.rb`.
+- README documents the supported Rubies (3.3/3.4/4.0); copyright years
+  updated through 2026.
+
+### Removed
+
+- Leftover development dependencies from the long-removed data-import
+  pipeline (activerecord, mysql2, tty-spinner).
+
+## 6.1.0 - 2026-04-09
+
+### Changed
+
+- Unknown, invalid, and nil zip codes now raise `Ziptz::ZipNotFound` instead
+  of returning nil.
+
+### Removed
+
+- Dropped support for Ruby 3.1 and 3.2; Ruby >= 3.3 is now required.
+
+## 6.0.0 - 2024-12-27
+
+### Changed
+
+- **Breaking:** the gem no longer bundles zip code time zone data. Supply
+  your own SQLite database and pass its path to `Ziptz.new`. See the
+  [ZIP Code Time Zones Dataset](https://www.infused-data.com/zip-code-time-zones/).
+- Database connections are cached per thread for thread safety.
+
+### Removed
+
+- The `Ziptz.instance` class method.
+
+## 5.1.0 - 2024-04-28
+
+### Changed
+
+- sqlite3 dependency updated from `~> 1.6` to `~> 2.0` (#11).
+
+## 5.0.0 - 2023-12-28
+
+### Removed
+
+- Dropped support for Rubies older than 3.1.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2024 Keith Morrison <keithm@infused.org>
+Copyright (c) 2015-2026 Keith Morrison <keithm@infused.org>
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,6 +1,6 @@
 # Ziptz
 [![Version](http://img.shields.io/gem/v/ziptz.svg?style=flat)](https://rubygems.org/gems/ziptz)
-[![Build Status](https://github.com/infused/ziptz/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/infused/ziptz/actions/workflows/build.yml)
+[![Build Status](https://github.com/infused/ziptz/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/infused/ziptz/actions/workflows/build.yml)
 [![Total Downloads](https://img.shields.io/gem/dt/ziptz.svg)](https://rubygems.org/gems/ziptz/)
 [![License](https://img.shields.io/github/license/infused/ziptz.svg)](https://github.com/infused/ziptz)
 
@@ -12,7 +12,7 @@ Get time zone, daylight saving time, and base offset for any US ZIP code.
 
 Ziptz is tested to work with the following versions of Ruby:
 
-* Ruby 3.1.x, 3.2.x, 3.3.x
+* Ruby 3.3.x, 3.4.x, 4.0.x
 
 ## Installation
 
@@ -20,13 +20,29 @@ Add the gem to your Gemfile:
 
     gem 'ziptz'
 
+## Data File Requirement
+
+Starting with version 6.0.0, you'll need to supply your own time zone SQLite database file. You can subscribe to the required dataset here:
+[ZIP Code Time Zones Dataset](https://www.infused-data.com/zip-code-time-zones/)
+
 ## Usage
 
+First, initialize Ziptz with the path to your time zone database file:
+
+    z = Ziptz.new('/path/to/your/tz.db')
+    # or using keyword argument
+    z = Ziptz.new(db: '/path/to/your/tz.db')
+
 Get the time zone name for any ZIP code:
 
-    z = Ziptz.new
     z.time_zone_name('97213') #=> "America/Los_Angeles"
 
+ZIP codes may be passed as strings or integers. Integers are zero-padded
+to 5 digits, and 9-digit ZIP+4 strings are truncated to their first 5 digits:
+
+    z.time_zone_name(601)          #=> "America/Puerto_Rico" (looks up 00601)
+    z.time_zone_name('97213-4704') #=> "America/Los_Angeles"
+
 Get the time zone offset for any ZIP code:
 
     z.time_zone_offset('97213') #=> -28800
@@ -41,6 +57,17 @@ Get all the zip codes in a time zone:
 
     z.zips('Pacific/Chuuk') #=> ["96942", "96943"]
 
+Lookups for unknown, invalid, or nil ZIP codes raise `Ziptz::ZipNotFound`
+(since version 6.1.0; earlier versions returned nil):
+
+    z.time_zone_name('00000') #=> raises Ziptz::ZipNotFound
+
+Database connections are opened lazily and cached per thread. Call `close`
+to close the current thread's connection; the next lookup reopens it
+automatically:
+
+    z.close
+
 
 ## Supported Time Zones
 
@@ -159,7 +186,7 @@ Time zone names now reflect standard tz-database names.
 
 ## License
 
-  Copyright (c) 2015-2024 Keith Morrison <<keithm@infused.org>>
+  Copyright (c) 2015-2026 Keith Morrison <<keithm@infused.org>>
 
   Permission is hereby granted, free of charge, to any person
   obtaining a copy of this software and associated documentation

data/lib/ziptz/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Ziptz
+  VERSION = '6.2.0'
+end

data/lib/ziptz.rb

@@ -1,36 +1,45 @@
+# frozen_string_literal: true
+
 require 'sqlite3'
-require 'version'
+require_relative 'ziptz/version'
 
 class Ziptz
-  def self.instance
-    @instance ||= new
+  class ZipNotFound < StandardError; end
+
+  def initialize(path = nil, db: nil)
+    @db_path = path || db
+    raise ArgumentError, 'Database path is required' if @db_path.nil? || @db_path.empty?
+    raise ArgumentError, 'Database file does not exist' unless File.exist?(@db_path)
   end
 
   def db
-    @db ||= begin
-      db = SQLite3::Database.open(tz_data_path)
+    connections = Thread.current[:ziptz_db] ||= {}
+    connections[@db_path] ||= begin
+      db = SQLite3::Database.open(@db_path)
       db.results_as_hash = true
       db
     end
   end
 
+  def close
+    Thread.current[:ziptz_db]&.delete(@db_path)&.close
+    nil
+  end
+
   def time_zone_name(zip)
-    time_zone_info(zip)&.dig('time_zone')
+    time_zone_info(zip)['time_zone']
   end
 
   def time_zone_offset(zip)
-    time_zone_info(zip)&.dig('offset')
+    time_zone_info(zip)['offset']
   end
 
   def time_zone_uses_dst?(zip)
-    tz_info = time_zone_info(zip)
-    return unless tz_info
-
-    tz_info['observes_dst'] == 1
+    time_zone_info(zip)['observes_dst'] == 1
   end
 
   def zips(tz_name)
-    sql = <<-SQL
+    sql = <<~SQL
       select zip_code
       from zip_codes
       where time_zone = ?
@@ -43,15 +52,15 @@ class Ziptz
     "#<#{self.class}:#{object_id}>"
   end
 
-  protected
+  private
 
   def time_zone_info(zip)
-    return unless zip
+    raise ZipNotFound, "Zip code not found: #{zip.inspect}" if zip.nil?
 
-    db.get_first_row('select * from zip_codes where zip_code = ? limit 1', zip[0, 5])
-  end
+    zip_code = zip.is_a?(Integer) ? format('%05d', zip) : zip.to_s[0, 5]
+    result = db.get_first_row('select * from zip_codes where zip_code = ? limit 1', zip_code)
+    raise ZipNotFound, "Zip code not found: #{zip}" unless result
 
-  def tz_data_path
-    File.join(File.dirname(__FILE__), '..', 'data', 'tz.db')
+    result
   end
 end

data/ziptz.gemspec

@@ -1,6 +1,6 @@
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
-require 'version'
+# frozen_string_literal: true
+
+require_relative 'lib/ziptz/version'
 
 Gem::Specification.new do |s|
   s.name = 'ziptz'
@@ -8,16 +8,21 @@ Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.authors = ['Keith Morrison']
   s.email = 'keithm@infused.org'
-  s.homepage = 'http://github.com/infused/ziptz'
+  s.homepage = 'https://github.com/infused/ziptz'
   s.summary = 'TimeZone info for any 5-digit US zip code'
   s.description = 'Get timezone info for all 5-digit US zip codes'
   s.license = 'MIT'
 
   s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = ['README.md', 'LICENSE']
-  s.files = Dir['README.md', 'LICENSE', '{data,lib,spec}/**/*', 'ziptz.gemspec']
+  s.files = Dir['README.md', 'CHANGELOG.md', 'LICENSE', 'lib/**/*', 'ziptz.gemspec']
   s.require_paths = ['lib']
-  s.required_ruby_version = '>= 3.1.0'
-  s.metadata['rubygems_mfa_required'] = 'true'
+  s.required_ruby_version = '>= 3.3.0'
+  s.metadata = {
+    'source_code_uri' => 'https://github.com/infused/ziptz',
+    'changelog_uri' => 'https://github.com/infused/ziptz/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/infused/ziptz/issues',
+    'rubygems_mfa_required' => 'true'
+  }
   s.add_dependency 'sqlite3', '~> 2.0'
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ziptz
 version: !ruby/object:Gem::Version
-  version: 5.1.2
+  version: 6.2.0
 platform: ruby
 authors:
 - Keith Morrison
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
@@ -29,23 +28,23 @@ email: keithm@infused.org
 executables: []
 extensions: []
 extra_rdoc_files:
-- README.md
 - LICENSE
+- README.md
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
-- data/tz.db
-- lib/version.rb
 - lib/ziptz.rb
-- spec/spec_helper.rb
-- spec/ziptz_spec.rb
+- lib/ziptz/version.rb
 - ziptz.gemspec
-homepage: http://github.com/infused/ziptz
+homepage: https://github.com/infused/ziptz
 licenses:
 - MIT
 metadata:
+  source_code_uri: https://github.com/infused/ziptz
+  changelog_uri: https://github.com/infused/ziptz/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/infused/ziptz/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options:
 - "--charset=UTF-8"
 require_paths:
@@ -54,15 +53,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: TimeZone info for any 5-digit US zip code
 test_files: []

data/lib/version.rb

@@ -1,3 +0,0 @@
-class Ziptz
-  VERSION = '5.1.2'.freeze
-end

data/spec/spec_helper.rb

@@ -1,8 +0,0 @@
-require 'ziptz'
-require 'yaml'
-require 'rspec'
-
-RSpec.configure do |config|
-  config.order = :random
-  config.disable_monkey_patching!
-end

data/spec/ziptz_spec.rb

@@ -1,119 +0,0 @@
-require 'spec_helper'
-
-RSpec.describe Ziptz do
-  let(:ziptz) { described_class.new }
-
-  describe 'when inspected' do
-    it 'does not show internal instance variables' do
-      expect(ziptz.inspect).to match(/#<Ziptz:\d+>/)
-    end
-  end
-
-  describe '#time_zone_name' do
-    context 'when given a 5-digit zipcode' do
-      it 'returns the time zone number' do
-        expect(ziptz.time_zone_name('97034')).to eq 'America/Los_Angeles'
-      end
-    end
-
-    context 'when given a 9-digit zipcode' do
-      it 'returns the time zone number' do
-        expect(ziptz.time_zone_name('97034-1234')).to eq 'America/Los_Angeles'
-      end
-    end
-
-    context 'when there is no matching zipcode' do
-      it 'returns nil' do
-        expect(ziptz.time_zone_name('xyz')).to be_nil
-      end
-    end
-
-    context 'when nil is passed' do
-      it 'returns nil' do
-        expect(ziptz.time_zone_name(nil)).to be_nil
-      end
-    end
-  end
-
-  describe '#time_zone_uses_dst?' do
-    context 'when given a valid 5-digit zipcode' do
-      it 'returns true' do
-        expect(ziptz.time_zone_uses_dst?('97034')).to eq true
-      end
-    end
-
-    context 'when given an invalid 5-digit zipcode' do
-      it 'returns false' do
-        expect(ziptz.time_zone_uses_dst?('85004')).to eq false
-      end
-    end
-
-    context 'when given a valid 9-digit zipcode' do
-      it 'returns a true' do
-        expect(ziptz.time_zone_uses_dst?('97034-1234')).to eq true
-      end
-    end
-
-    context 'when given an invalid 9-digit zipcode' do
-      it 'returns false' do
-        expect(ziptz.time_zone_uses_dst?('85004-1234')).to eq false
-      end
-    end
-
-    context 'when there is no matching zipcode' do
-      it 'returns nil' do
-        expect(ziptz.time_zone_uses_dst?('xyz')).to be_nil
-      end
-    end
-  end
-
-  describe '#time_zone_offset' do
-    context 'when given a 5-digit zipcode' do
-      it 'returns the time zone number' do
-        expect(ziptz.time_zone_offset('97034')).to eq(-28_800)
-      end
-    end
-
-    context 'when given a 9-digit zipcode' do
-      it 'returns the time zone number' do
-        expect(ziptz.time_zone_offset('97034-1234')).to eq(-28_800)
-      end
-    end
-
-    context 'when there is no matching zipcode' do
-      it 'returns nil' do
-        expect(ziptz.time_zone_offset('xyz')).to be_nil
-      end
-    end
-  end
-
-  describe '#zips' do
-    context 'when given a time zone' do
-      it 'returns an array of zip codes' do
-        expect(ziptz.zips('Pacific/Pago_Pago')).to eq %w[96799]
-      end
-
-      it 'is case-insensitive' do
-        expect(ziptz.zips('pacific/pago_pago')).to eq %w[96799]
-      end
-
-      it 'returns empty array for unknown time zones' do
-        expect(ziptz.zips('Glark')).to be_empty
-      end
-    end
-  end
-
-  describe '#instance' do
-    context 'when given a 5 digit zip code' do
-      it 'matches the behavior of Ziptz.new' do
-        expect(described_class.instance.time_zone_name('97034')).to eq ziptz.time_zone_name('97034')
-      end
-    end
-
-    context 'when called twice' do
-      it 'returns identical instances' do
-        expect(described_class.instance.object_id).to eq described_class.instance.object_id
-      end
-    end
-  end
-end