pilipinas 0.1.2 → 1.1.0

data/README.md

@@ -1,53 +1,288 @@
 # Pilipinas
 
-It's a collection of Regions, Provinces, Cities/Municipalities & Barangays within Philippines.
+[![CI](https://github.com/denmarkmeralpis/pilipinas/actions/workflows/ci.yml/badge.svg)](https://github.com/denmarkmeralpis/pilipinas/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/pilipinas.svg)](https://badge.fury.io/rb/pilipinas)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-It's a file based PH directory. If you want to get data from db, use `gem pinas`.
+A complete, read-only directory of Philippine geographic divisions:
+
+```
+Region  →  Province  →  City / Municipality  →  Barangay
+(17)         (86)           (1,648)              (42,027)
+```
+
+## Features
+
+- **Zero runtime dependencies** — pure Ruby + stdlib Psych (ships with Ruby).
+- **Lazy-loaded & cached** — YAML is parsed once per class per process and held in a thread-safe, process-lifetime cache. Repeated calls are free.
+- **O(1) look-ups** — separate hash indices keyed by code and by name; no linear scans.
+- **Immutable value objects** — every entity instance is frozen. Safe to share across threads and fibers without copying.
+- **Optional ActiveRecord integration** — a migration generator and Rake task seed the four `pilipinas_*` tables from the bundled YAML data.
+- **Read-only by default** — persisted AR model instances raise `ActiveRecord::ReadOnlyRecord` on accidental writes; opt out per-class via `enforce_readonly = false`.
+- **Test helper included** — `require 'pilipinas/testing/rspec'` disables the read-only guard for the entire RSpec suite with one line.
+- **Ruby ≥ 3.4** required; developed against Ruby 4.0.
+
+---
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'pilipinas'
+gem "pilipinas"
 ```
 
-And then execute:
+Then run:
+
+```sh
+bundle install
+```
 
-    $ bundle
+Or install directly:
 
-Or install it yourself as:
+```sh
+gem install pilipinas
+```
 
-    $ gem install pilipinas
+---
 
 ## Usage
 
+### Require
+
 ```ruby
-# All Regions
-Pilipinas::Region.all
+require "pilipinas"
+```
 
-# All Provinces
-Pilipinas::Province.all
+Rails applications load the gem automatically via Bundler.
 
-# All Cities/Municipalities
-Pilipinas::City.all
+---
+
+### Regions
+
+```ruby
+# All 17 regions (returns a frozen Array)
+Pilipinas::Region.all            # => [#<Region code="1" name="NCR…">, …]
+Pilipinas::Region.count          # => 17
+Pilipinas::Region.first          # => #<Region …>
+Pilipinas::Region.last           # => #<Region …>
 
-# All Barangays
-Pilipinas::Barangay.all
+# Find by code (O(1), case-insensitive)
+Pilipinas::Region.find_by(code: "17744")
+Pilipinas::Region.find_by_code("17744")
 
-# Finding record thru find_by_(code/name) method
-region = Pilipinas::Region.find_by_name("REGION V (Bicol Region)")
+# Find by name (O(1), case-insensitive)
+Pilipinas::Region.find_by(name: "REGION V (Bicol Region)")
+Pilipinas::Region.find_by_name("region v (bicol region)")   # same result
 
-# Get provinces by region
-region.provinces
+# Traverse down the hierarchy
+region = Pilipinas::Region.find_by(name: "REGION V (Bicol Region)")
+region.provinces   # => [#<Province …>, …]
 ```
-## Acknowledgement
 
-The data used in this gem is from `gem pinas`. Kudos!
+---
+
+### Provinces
+
+```ruby
+Pilipinas::Province.all          # => Array of 86 Province objects
+Pilipinas::Province.count        # => 86
+
+province = Pilipinas::Province.find_by(name: "CAMARINES SUR")
+province.cities                  # => Array of City objects
+```
+
+---
+
+### Cities / Municipalities
+
+```ruby
+Pilipinas::City.all              # => Array of 1,648 City objects
+Pilipinas::City.count            # => 1648
+
+city = Pilipinas::City.find_by(name: "NAGA CITY")
+city.barangays                   # => Array of Barangay objects
+```
+
+---
+
+### Barangays
+
+```ruby
+Pilipinas::Barangay.all          # => Array of 42,027 Barangay objects
+Pilipinas::Barangay.count        # => 42027
+
+Pilipinas::Barangay.find_by(code: "21687")
+Pilipinas::Barangay.find_by(name: "Casay")
+```
+
+---
+
+### Entity interface
+
+Every entity object exposes:
+
+| Method     | Returns  | Description                         |
+|------------|----------|-------------------------------------|
+| `#code`    | `String` | Unique geographic code              |
+| `#name`    | `String` | Human-readable name                 |
+| `#to_s`    | `String` | `"Region(code: 1, name: NCR…)"`     |
+| `#inspect` | `String` | `#<Region code="1" name="NCR…">`    |
+| `#==`      | `Boolean`| Equality by class + code            |
+| `#frozen?` | `true`   | Always true — instances are frozen  |
+
+---
+
+### Supported find_by attributes
+
+Both `find_by(attr: value)` and `find_by_attr(value)` accept:
+
+| Attribute | Notes                  |
+|-----------|------------------------|
+| `:code`   | Geographic code string |
+| `:name`   | Human-readable name    |
+
+Any other attribute raises `Pilipinas::UnknownAttribute`.
+
+---
+
+### Error classes
+
+| Class                         | Superclass         | Raised when                          |
+|-------------------------------|--------------------|--------------------------------------|
+| `Pilipinas::Error`            | `StandardError`    | Base class for all Pilipinas errors  |
+| `Pilipinas::UnknownAttribute` | `Pilipinas::Error` | Unsupported attribute in `find_by_*` |
+
+---
+
+## Rails / ActiveRecord integration (optional)
+
+The gem ships with an optional database back-end for applications that prefer SQL queries over in-memory look-ups.
+
+### 1. Generate the migration
+
+```sh
+rails generate pilipinas:migration
+rails db:migrate
+```
+
+This creates four tables: `pilipinas_regions`, `pilipinas_provinces`, `pilipinas_cities`, `pilipinas_barangays`.
+
+### 2. Seed the tables
+
+```sh
+rake pilipinas:load
+```
 
-## TODO
+### 3. Use the AR models
 
-* Add a form helper
+```ruby
+region   = Pilipinas::Db::Region.find_by(code: "17744")
+region.provinces.count   # ActiveRecord query
+
+province = Pilipinas::Db::Province.find_by(name: "CAMARINES SUR")
+province.cities          # has_many association
+```
+
+> **Note:** The AR models are auto-loaded and require `activerecord` to be available.
+
+### Read-only behaviour
+
+All four `Pilipinas::Db::*` models are **read-only by default**. Any attempt to call `update!`, `save`, or `destroy` on a persisted record raises `ActiveRecord::ReadOnlyRecord`. This is intentional — the pilipinas tables are static reference data that should never be mutated after seeding.
+
+New (unsaved) records are always writable, so `create!` works normally in the Loader and in test factories.
+
+#### Opting a subclass out of read-only enforcement
+
+If your application inherits from a Pilipinas DB model and legitimately needs write access, set `enforce_readonly` to `false` on the subclass:
+
+```ruby
+class Locations::Barangay < Pilipinas::Db::Barangay
+  self.enforce_readonly = false
+end
+```
+
+This does not affect the parent class or any other model.
+
+---
+
+## Testing
+
+The gem ships a ready-made RSpec helper that turns off the read-only guard for the entire test suite — no stubbing required.
+
+```ruby
+# spec/rails_helper.rb  (or spec/support/pilipinas.rb)
+require 'pilipinas/testing/rspec'
+```
+
+This sets `enforce_readonly = false` on all four models (`Region`, `Province`, `City`, `Barangay`) inside a `before(:suite)` hook, so FactoryBot factories, fixtures, and any spec that writes to pilipinas tables work without extra setup.
+
+If you only need writable records in a specific context:
+
+```ruby
+around do |example|
+  Locations::Barangay.enforce_readonly = false
+  example.run
+ensure
+  Locations::Barangay.enforce_readonly = true
+end
+```
+
+---
+
+## Advanced
+
+### Cache management
+
+The in-memory cache is global to the process. In long-running processes the data never reloads (intentional — YAML files are static). To force a reload (e.g. in tests):
+
+```ruby
+Pilipinas::Cache.clear
+```
+
+### Thread-safety
+
+All class-level state is initialised through `Pilipinas::Cache`, which uses a `Mutex` with double-checked locking. Entity instances are frozen. The gem is safe to use in multi-threaded applications (Puma, Sidekiq, etc.) without additional synchronisation.
+
+---
+
+## Development
+
+```sh
+git clone https://github.com/denmarkmeralpis/pilipinas
+cd pilipinas
+bin/setup          # install dependencies
+bundle exec rake   # run the full test suite
+bin/console        # start an IRB session with the gem loaded
+```
+
+### Running tests
+
+```sh
+bundle exec rspec                     # all specs
+bundle exec rspec spec/pilipinas/     # unit specs only
+bundle exec rubocop                   # lint
+```
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/denmarkmeralpis/pilipinas).
+
+Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+---
+
+## Acknowledgements
+
+The data used in this gem is from `gem pinas`. Kudos!
 
 ## Development
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 

data/bin/console

@@ -1,14 +1,17 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'bundler/setup'
-require 'pilipinas'
+require "bundler/setup"
+require "pilipinas"
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
+# Convenience aliases for interactive exploration:
+#
+#   Region.all
+#   Province.find_by(name: "CAMARINES SUR")
+#   City.find_by_code("18817").barangays
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
+include Pilipinas # rubocop:disable Style/MixinUsage
 
-require 'irb'
+require "irb"
 IRB.start(__FILE__)
+

data/lib/generators/pilipinas/migration_generator.rb

@@ -1,31 +1,36 @@
+# frozen_string_literal: true
+
 require 'rails/generators/base'
 require 'rails/generators/active_record'
 
 module Pilipinas
+  # Rails generator that creates the four pilipinas_* database tables.
+  #
+  # @example
+  #   rails generate pilipinas:migration
+  #
   class MigrationGenerator < Rails::Generators::Base
     include Rails::Generators::Migration
 
-    source_root File.expand_path('../', __dir__)
+    source_root File.expand_path('..', __dir__)
 
     def generate_migration
-      generate_block_migration
+      migration_template 'templates/migration.rb', 'db/migrate/create_pilipinas_locations.rb'
     end
 
+    # Returns a timestamp-based migration number required by the Rails
+    # migration DSL.
+    #
+    # @param _dir [String] unused (required by the interface)
+    # @return [String]
     def self.next_migration_number(_dir)
       Time.now.utc.strftime('%Y%m%d%H%M%S')
     end
 
     private
 
-    def generate_block_migration
-      migration_template 'templates/migration.rb', 'db/migrate/create_locations.rb'
-    end
-
+    # @return [String, nil] migration version bracket, e.g. "[8.0]"
     def migration_version
-      formatted_version if ActiveRecord::VERSION::MAJOR.to_i >= 5
-    end
-
-    def formatted_version
       "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
     end
   end

data/lib/generators/templates/migration.rb

@@ -1,14 +1,14 @@
-class CreateLocations < ActiveRecord::Migration<%= migration_version %>
+class CreatePilipinasLocations < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :pilipinas_regions do |t|
       t.bigint  :location_id
       t.integer :lft
       t.integer :rgt
-      t.string  :code
-      t.string  :name
+      t.string  :code,      null: false
+      t.string  :name,      null: false
       t.string  :longitude
       t.string  :latitude
-      t.timestamps default: Time.now
+      t.timestamps null: false
     end
 
     create_table :pilipinas_provinces do |t|
@@ -16,11 +16,11 @@ class CreateLocations < ActiveRecord::Migration<%= migration_version %>
       t.bigint  :parent_id
       t.integer :lft
       t.integer :rgt
-      t.string  :code
-      t.string  :name
+      t.string  :code,      null: false
+      t.string  :name,      null: false
       t.string  :longitude
       t.string  :latitude
-      t.timestamps default: Time.now
+      t.timestamps null: false
     end
 
     create_table :pilipinas_cities do |t|
@@ -28,15 +28,15 @@ class CreateLocations < ActiveRecord::Migration<%= migration_version %>
       t.bigint  :parent_id
       t.integer :lft
       t.integer :rgt
-      t.string  :code
-      t.string  :name
-      t.boolean :city, default: false
+      t.string  :code,         null: false
+      t.string  :name,         null: false
+      t.boolean :city,         default: false, null: false
       t.string  :income_class
       t.string  :urban_rural
       t.string  :district
       t.string  :longitude
       t.string  :latitude
-      t.timestamps default: Time.now
+      t.timestamps null: false
     end
 
     create_table :pilipinas_barangays do |t|
@@ -44,29 +44,37 @@ class CreateLocations < ActiveRecord::Migration<%= migration_version %>
       t.bigint  :parent_id
       t.integer :lft
       t.integer :rgt
-      t.string  :code
-      t.string  :name
+      t.string  :code,        null: false
+      t.string  :name,        null: false
       t.string  :urban_rural
-      t.timestamps default: Time.now
+      t.timestamps null: false
     end
 
-    add_index :pilipinas_regions, :location_id, unique: true
-    add_index :pilipinas_regions, :code
-    add_index :pilipinas_regions, :rgt
+    add_index :pilipinas_regions,   :location_id, unique: true
+    add_index :pilipinas_regions,   :code,        unique: true
+    # Composite (lft, rgt) supports nested-set descendant range queries:
+    # WHERE lft >= X AND rgt <= Y  — a single rgt index cannot satisfy this.
+    add_index :pilipinas_regions,   %i[lft rgt], name: 'idx_pilipinas_regions_lft_rgt'
+    # Functional index lets LOWER(name) = LOWER(?) use the index (PostgreSQL).
+    add_index :pilipinas_regions,   'LOWER(name)', name: 'idx_pilipinas_regions_lower_name'
 
     add_index :pilipinas_provinces, :location_id, unique: true
-    add_index :pilipinas_provinces, :code
+    add_index :pilipinas_provinces, :code,        unique: true
     add_index :pilipinas_provinces, :parent_id
-    add_index :pilipinas_provinces, :rgt
+    add_index :pilipinas_provinces, %i[lft rgt], name: 'idx_pilipinas_provinces_lft_rgt'
+    add_index :pilipinas_provinces, 'LOWER(name)', name: 'idx_pilipinas_provinces_lower_name'
 
-    add_index :pilipinas_cities, :location_id, unique: true
-    add_index :pilipinas_cities, :code
-    add_index :pilipinas_cities, :parent_id
-    add_index :pilipinas_cities, :rgt
+    add_index :pilipinas_cities,    :location_id, unique: true
+    add_index :pilipinas_cities,    :code,        unique: true
+    add_index :pilipinas_cities,    :parent_id
+    add_index :pilipinas_cities,    %i[lft rgt], name: 'idx_pilipinas_cities_lft_rgt'
+    add_index :pilipinas_cities,    'LOWER(name)', name: 'idx_pilipinas_cities_lower_name'
 
     add_index :pilipinas_barangays, :location_id, unique: true
-    add_index :pilipinas_barangays, :code
+    add_index :pilipinas_barangays, :code,        unique: true
     add_index :pilipinas_barangays, :parent_id
-    add_index :pilipinas_barangays, :rgt
+    add_index :pilipinas_barangays, %i[lft rgt], name: 'idx_pilipinas_barangays_lft_rgt'
+    add_index :pilipinas_barangays, 'LOWER(name)', name: 'idx_pilipinas_barangays_lower_name'
   end
 end
+

data/lib/pilipinas/barangay.rb

@@ -1,8 +1,22 @@
+# frozen_string_literal: true
+
 module Pilipinas
+  # Represents a barangay (the smallest administrative division) of the
+  # Philippines.
+  #
+  # Barangays belong to a {City} or municipality.
+  #
+  # @example
+  #   Pilipinas::Barangay.count  # => 42_027
+  #   Pilipinas::Barangay.find_by(name: "Casay")
+  #
   class Barangay < Base
     class << self
-      def load_data
-        load_file(File.join(File.dirname(__FILE__), '..', 'data', 'barangays.yml'))
+      private
+
+      # @return [String] absolute path to the barangays YAML file
+      def data_file
+        File.join(Pilipinas::DATA_DIR, 'barangays.yml')
       end
     end
   end