unlocodes 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4c9de4b3b24e90847e45242a5199691e8d5284377e8f6476f6fb01b653a729d
-  data.tar.gz: 4903c23bdc9d3336471da5afc6ec1c0e1c711d75824ce822e6a089dbb54970b2
+  metadata.gz: 2a6607eb57e2219a161a11a3a5504d8b5ba3ba727b6a89c27d2a0de65b20dc36
+  data.tar.gz: 43fc8e683ac3af63d1f2a126313c6a9ec935ff6bacd03ecaa3fda39909bcef13
 SHA512:
-  metadata.gz: 2938d6ba840b7b93731afd97081478dce93cbd5b82357eb56032a943c000728a9d484b9fec9a5deffaa30916b99ba4588d33add5ce64e9489cd671d9a2ad0994
-  data.tar.gz: 76333326f2218ed42eebe6c729b05609c3e14b874854c9171dac3260d022c521a52e23e4e290a26565432936a837f548b6ff1a464c064258059741ad2c9ada01
+  metadata.gz: 4e6da102b2aea85d965a601c2539400a4d978ac04723cbc989f8bd867628352ce26d03fa26b181a66ccd652d618f68e13ee5d668a3dac41971058fcacdca25d8
+  data.tar.gz: 9fa6a655a4c2ed962975e2311920264ba3657311163156843be590e639592fa480715493bfee7e7c9f59019d8ccee60c4c29f95cae65e8fec7828b17ef53f7be

data/README.adoc

@@ -1,15 +1,17 @@
-= unlocode
+= unlocodes
 :toc: macro
-:homepage: https://github.com/metanorma/unlocode
+:homepage: https://github.com/metanorma/unlocodes
 
-`unlocode` is a Ruby gem that exposes the UN/LOCODE dataset (United Nations Code for Trade and Transport Locations) as a queryable in-memory registry.
+`unlocodes` is a Ruby gem that exposes the UN/LOCODE dataset (United Nations Code for Trade and Transport Locations) as a queryable in-memory registry.
 
 The dataset is sourced from the UNECE/UNCEFACT LOCODE vocabulary, version-tagged `2025-1`: https://opensource.unicc.org/un/unece/uncefact/vocab-locode/-/tags/2025-1
 
-The full 2025-1 dataset (115,928 LOCODEs across 249 countries) is bundled inside the gem as `lib/unlocode/data/locode.jsonld` and loads lazily into a typed registry on first use.
+The full 2025-1 dataset (115,928 LOCODEs across 249 countries, ~39 MB) is bundled inside the gem as `lib/unlocodes/data/locode.jsonld` and loads lazily into a typed registry on first use.
 
 == Installation
 
+Ruby 3.1 or newer is required.
+
 Add to your Gemfile:
 
 [source,ruby]
@@ -17,18 +19,78 @@ Add to your Gemfile:
 gem 'unlocodes'
 ----
 
+Or install directly:
+
+[source,sh]
+----
+gem install unlocodes
+----
+
 == Usage
 
 [source,ruby]
 ----
 require 'unlocodes'
 
-Unlocodes.find('CNSHA')                          # => #<Unlocodes::Entry code="CNSHA" ...>
-Unlocodes.find('NLRTM').functions.map(&:code)    # => ["B", "R", "T", "A", "P"]
-Unlocodes.where(country: 'CN').count             # => 1670
-Unlocodes.where(function: 'B').count             # => 17912  (sea ports)
-Unlocodes.where(function: 'A').count             # => 9009   (airports)
-Unlocodes.find('CNPDG').coordinates              # => #<Coordinates lat=31.2333 lon=121.5000>
+# Lookup by 5-char LOCODE (case-insensitive)
+Unlocodes.find('CNSHA')                    # => #<Unlocodes::Entry code="CNSHA" name="Shanghai Hongqiao International Apt">
+Unlocodes['NLRTM'].name                    # => "Rotterdam" ([] is an alias for find)
+
+# Filters — single value or array (any-of)
+Unlocodes.where(country: 'CN').count       # => 1670
+Unlocodes.where(country: %w[CN HK]).count  # => entries in China OR Hong Kong
+Unlocodes.where(function: 'B').count       # => 17912 (sea ports)
+Unlocodes.where(function: 'A').count       # => 9009  (airports)
+Unlocodes.where(function: %w[B A]).count   # => 25136 (port OR airport)
+Unlocodes.where(subdivision: 'CNSH').count # => entries in the Shanghai subdivision
+
+# Filters combine
+Unlocodes.where(country: 'CN', function: 'A').count  # => CN airports
+
+# Name search — Regexp (substring) or String (case-insensitive equality)
+Unlocodes.where(name: /shanghai/i).map(&:code)
+Unlocodes.where(name: 'rotterdam').map(&:code)
+
+# Iteration
+Unlocodes.each { |e| puts e.code if e.port? }
+
+# Country listing
+Unlocodes.countries                        # => ["AD", "AE", ..., "ZW"] (249 codes)
+Unlocodes.counts_by_country.first(5)       # => [["US", 20852], ["FR", 14325], ...]
+
+# Indexed lookups (faster than `where` for a single value)
+Unlocodes.registry.by_country('CN').size   # => 1670
+Unlocodes.registry.by_function('B').size   # => 17912
+----
+
+=== What's in an Entry
+
+Each `Unlocodes::Entry` exposes the fields the JSON-LD vocabulary populates:
+
+[cols="1,2", options="header"]
+|===
+|Attribute|Description
+|`code`|5-char LOCODE (ISO country + 3-char location)
+|`country`|ISO 3166-1 alpha-2 country code
+|`subdivision`|ISO 3166-2 country subdivision code (e.g. `CNSH`)
+|`name`|Display name
+|`function_codes`|Array of single-letter function codes (see below)
+|`latitude`, `longitude`|WGS-84 decimal degrees
+|===
+
+Convenience predicates and value-type accessors:
+
+[source,ruby]
+----
+entry = Unlocodes.find('NLRTM')
+
+entry.port?             # => true  (function code B)
+entry.airport?          # => true  (function code A)
+entry.rail_terminal?    # => true  (function code R)
+entry.road_terminal?    # => true  (function code T)
+entry.functions.map(&:code)        # => ["B", "R", "T", "A", "P"]
+entry.functions.first.description  # => "Port (sea)"
+entry.coordinates       # => #<Unlocodes::Coordinates ...>
 ----
 
 === Function codes
@@ -49,40 +111,89 @@ The vocabulary publishes functions as `unlcdf:1`..`unlcdf:9`. The gem maps them
 |9|O|Other / border crossing
 |===
 
-Use the letters in `where(function: ...)`:
+Use the letters in `where(function: ...)`. Passing an array matches any-of (OR), not all-of (AND):
 
 [source,ruby]
 ----
 Unlocodes.where(function: 'B').count             # sea ports
-Unlocodes.where(function: %w[B A]).count         # entries that are both port and airport
+Unlocodes.where(function: %w[B A]).count         # port OR airport (union)
+# For AND (entries that are BOTH port AND airport), filter in Ruby:
+Unlocodes.entries.count { |e| e.port? && e.airport? }  # => 1785
 ----
 
-=== Distances
+=== Coordinates and distances
 
 [source,ruby]
 ----
-shanghai = Unlocodes.find('CNPDG').coordinates
+shanghai = Unlocodes.find('CNPDG').coordinates   # Shanghai Pudong
 rotterdam = Unlocodes.find('NLRTM').coordinates
-shanghai.distance_to(rotterdam)                 # => 8922.0 (km, great-circle)
+
+shanghai.to_s              # => "31.2333 121.5000"
+shanghai.distance_to(rotterdam)  # => 8922.7 (km, great-circle via haversine)
 ----
 
-== Data refresh
+=== Fields NOT in the bundled vocabulary
 
-To refresh the bundled dataset when a new UNCEFACT edition is released:
+The JSON-LD vocabulary only publishes `code`, `country`, `subdivision`, `name`, `functions`, and coordinates. The UN/LOCODE manual additionally defines a `status` change indicator (AA, RL, XX, …), IATA code, change date, and remarks — these are in the per-country CSV files upstream, not the JSON-LD vocab, and are intentionally not modelled here.
+
+Calling `where(status: ...)` or `where(iata: ...)` raises `ArgumentError` rather than silently returning empty results.
+
+=== Which edition is bundled?
+
+[source,ruby]
+----
+Unlocodes.data_tag  # => "2025-1"
+----
+
+This reads `lib/unlocodes/data/SOURCE_TAG` at runtime. The `Unlocodes::Status` value type is still shipped for callers who want to consult the manual's status-code descriptions out-of-band.
+
+== Staying current with upstream
+
+UN/LOCODE is published twice-yearly (typically `YYYY-1` around Q1, `YYYY-2` around Q3). The gem ships two workflows to keep the bundled data fresh:
+
+=== `check-upstream` (scheduled, weekly)
+
+`.github/workflows/check-upstream.yml` runs every Monday, asks the upstream GitLab project for its latest tag, and compares against the bundled `SOURCE_TAG`. When a new edition is detected it opens a GitHub issue labelled `data-update` describing the diff and the next steps. The workflow also runs on manual dispatch.
+
+=== `update-data` (manual dispatch)
+
+`.github/workflows/update-data.yml` is what a maintainer runs after `check-upstream` flags a new edition. It takes the new tag as input, fetches the data, commits to a branch, and opens a PR. Merging that PR does not, by itself, publish a new gem — it just lands the new data on `main`. To ship a new gem version, trigger the `release` workflow (see below).
+
+End-to-end refresh flow:
+
+. `check-upstream` opens issue: "new tag `2025-2` available, bundled is `2025-1`"
+. Maintainer runs `update-data` workflow with `tag=2025-2`
+. Workflow opens PR `chore/data-2025-2` with the refreshed `locode.jsonld` and `SOURCE_TAG`
+. Maintainer reviews and merges the PR
+. Maintainer triggers the `release` workflow with `next_version=patch` to publish a new gem version
+
+Manual local equivalent of the workflow:
 
 [source,sh]
 ----
-bundle exec rake unlocode:fetch          # default tag: 2025-1
-UNLOCODE_TAG=2025-2 rake unlocode:fetch
+bundle exec rake unlocodes:fetch         # default tag: 2025-1
+UNLOCODE_TAG=2025-2 bundle exec rake unlocodes:fetch
 ----
 
 If the upstream tag layout changes, point `UNLOCODE_PATH` at the full JSON-LD URL:
 
 [source,sh]
 ----
-UNLOCODE_PATH=https://example.org/path/unlocode.jsonld rake unlocode:fetch
+UNLOCODE_PATH=https://example.org/path/unlocode.jsonld bundle exec rake unlocodes:fetch
 ----
 
+== Development
+
+[source,sh]
+----
+bundle install                       # install dev deps
+bundle exec rake                     # spec + rubocop
+bundle exec rspec spec/path/to_spec.rb:42   # one example
+bundle exec rake unlocodes:fetch     # refresh bundled data
+----
+
+The 39 MB dataset at `lib/unlocodes/data/locode.jsonld` is committed so the gem works offline. The first call to `Unlocodes.registry` in a process pays the parse cost (~3-5 s); subsequent calls are cached.
+
 == License
 
 BSD-2-Clause. See link:LICENSE[].

data/lib/unlocodes/data/SOURCE_TAG

@@ -0,0 +1 @@
+2025-1

data/lib/unlocodes/data/fetcher.rb

@@ -7,18 +7,23 @@ require 'fileutils'
 module Unlocodes
   module Data
     # Downloads the UNCEFACT UN/LOCODE vocabulary from the upstream GitLab
-    # repository and stores it as `lib/unlocode/data/locode.jsonld`.
+    # repository and stores it as `lib/unlocodes/data/locode.jsonld`.
     #
     # The upstream tag (e.g. "2025-1") points at a snapshot of the
     # `vocab-locode` project whose `vocab/unlocode.jsonld` is the canonical
     # full dataset. Override the source URL with the `UNLOCODE_PATH` env
     # variable if a different edition's path layout applies.
+    #
+    # After a successful fetch, the tag is written to `SOURCE_TAG` next to
+    # the data file so the gem (and the check-upstream workflow) always
+    # knows which edition is bundled.
     module Fetcher
       UPSTREAM_HOST = 'opensource.unicc.org'
       UPSTREAM_TAG_PATH = '/un/unece/uncefact/vocab-locode/-/raw/%<tag>s'
-      OUTPUT_PATH = File.expand_path('locode.jsonld', __dir__)
+      DATA_DIR = File.expand_path(__dir__)
+      OUTPUT_PATH = File.join(DATA_DIR, 'locode.jsonld')
+      SOURCE_TAG_PATH = File.join(DATA_DIR, 'SOURCE_TAG')
 
-      DEFAULT_FILENAME = 'vocab/unlocode.jsonld'
       CANDIDATE_PATHS = [
         'vocab/unlocode.jsonld',
         'vocab/unlocode-vocab.jsonld',
@@ -32,7 +37,7 @@ module Unlocodes
         def call(tag:)
           uri = resolve_uri(tag)
           data = download(uri)
-          write(data)
+          write(data, tag: tag)
           warn "Fetched UN/LOCODE #{tag} (#{data.bytesize} bytes) -> #{OUTPUT_PATH}"
           OUTPUT_PATH
         end
@@ -67,9 +72,10 @@ module Unlocodes
           end
         end
 
-        def write(data)
-          FileUtils.mkdir_p(File.dirname(OUTPUT_PATH))
+        def write(data, tag:)
+          FileUtils.mkdir_p(DATA_DIR)
           File.write(OUTPUT_PATH, data)
+          File.write(SOURCE_TAG_PATH, "#{tag}\n")
         end
       end
     end

data/lib/unlocodes/registry.rb

@@ -18,13 +18,13 @@ module Unlocodes
     def_delegators :@entries, :size, :count, :to_a, :empty?
 
     # Map of `#where` filter keys to the Entry attribute they read.
+    # Limited to attributes the JSON-LD vocabulary actually populates —
+    # status / iata / name_without_diacritics are NOT in the vocab, so
+    # they're intentionally absent here.
     SCALAR_FILTERS = {
       code: :code,
       country: :country,
-      status: :status_code,
-      status_code: :status_code,
-      subdivision: :subdivision,
-      iata: :iata
+      subdivision: :subdivision
     }.freeze
 
     def initialize(entries = [])
@@ -108,10 +108,6 @@ module Unlocodes
       by_function_index[letter.to_s.upcase] || []
     end
 
-    def by_status(code)
-      by_status_index[code.to_s.upcase] || []
-    end
-
     private
 
     def by_code
@@ -132,12 +128,6 @@ module Unlocodes
       end
     end
 
-    def by_status_index
-      @by_status_index ||= entries.each_with_object({}) do |e, h|
-        (h[e.status_code.to_s.upcase] ||= []) << e if e.status_code
-      end
-    end
-
     def apply_filter(scope, key, value)
       if SCALAR_FILTERS.key?(key)
         filter_scalar(scope, SCALAR_FILTERS.fetch(key), value)

data/lib/unlocodes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Unlocodes
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

data/lib/unlocodes.rb

@@ -9,12 +9,18 @@ require_relative 'unlocodes/version'
 # Vendored UN/LOCODE dataset as a queryable Ruby registry.
 #
 # The dataset is sourced from the UNECE/UNCEFACT LOCODE vocabulary published at
-# https://service.unece.org/trade/locode/ and distributed by this gem as a
-# bundled, offline JSON-LD representation. The registry loads once per process
-# and exposes a typed query API over `Unlocodes::Entry` instances.
+# https://opensource.unicc.org/un/unece/uncefact/vocab-locode and distributed
+# by this gem as a bundled, offline JSON-LD representation. The registry loads
+# once per process and exposes a typed query API over `Unlocodes::Entry`
+# instances.
+#
+# Which edition is bundled? See {Unlocodes.data_tag} (read from
+# `lib/unlocodes/data/SOURCE_TAG`).
 module Unlocodes
   extend SingleForwardable
 
+  SOURCE_TAG_PATH = File.expand_path('unlocodes/data/SOURCE_TAG', __dir__)
+
   class << self
     # @return [Unlocodes::Registry] the process-wide registry, loaded lazily
     def registry
@@ -25,6 +31,17 @@ module Unlocodes
     def reset_registry!
       @registry = nil
     end
+
+    # The upstream UNCEFACT vocabulary tag bundled with this gem version
+    # (e.g. "2025-1"). Read from `lib/unlocodes/data/SOURCE_TAG` at runtime.
+    # @return [String, nil]
+    def data_tag
+      return @data_tag if defined?(@data_tag)
+
+      @data_tag = File.read(SOURCE_TAG_PATH, encoding: 'UTF-8').strip
+    rescue Errno::ENOENT
+      nil
+    end
   end
 
   def_delegators :registry, :find, :where, :each, :size, :count, :countries

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unlocodes
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -55,6 +55,7 @@ files:
 - lib/unlocodes/coordinates.rb
 - lib/unlocodes/data.rb
 - lib/unlocodes/data/README.adoc
+- lib/unlocodes/data/SOURCE_TAG
 - lib/unlocodes/data/fetcher.rb
 - lib/unlocodes/data/locode.jsonld
 - lib/unlocodes/entry.rb
@@ -63,13 +64,13 @@ files:
 - lib/unlocodes/registry.rb
 - lib/unlocodes/status.rb
 - lib/unlocodes/version.rb
-homepage: https://github.com/metanorma/unlocode
+homepage: https://github.com/metanorma/unlocodes
 licenses:
 - BSD-2-Clause
 metadata:
-  homepage_uri: https://github.com/metanorma/unlocode
-  source_code_uri: https://github.com/metanorma/unlocode
-  bug_tracker_uri: https://github.com/metanorma/unlocode/issues
+  homepage_uri: https://github.com/metanorma/unlocodes
+  source_code_uri: https://github.com/metanorma/unlocodes
+  bug_tracker_uri: https://github.com/metanorma/unlocodes/issues
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []