pilipinas 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a0d4e9bce22ec277d0dc496465c5f78ac9f6470c8ea579832191b2bcecba289
-  data.tar.gz: 188a8a2c3d853c01da1eaa3d0609688b0a6612cd0db46fe600b5754d58864753
+  metadata.gz: 3191d97a140c01be0e95c6f1045d54fbd4e4e4ca0bf84783520d67c865376dee
+  data.tar.gz: 8216cefb4c6d5d81af30087d6f13a32f5feb79b729f74c194f00c17da7c37e2e
 SHA512:
-  metadata.gz: c4d3910367c067e84aaae374d27a39de44acaf1eba461150f84e019f8e9e0f6fb0ff2341fe44101e4cfb3c7c3ac0b7a23495d8d285adf7ad53af96bccc51285e
-  data.tar.gz: f17c36621d5afce588b5bcf95eea17cea461abb0d5c2dfc6caac8b8905c5e9fe71827f33e469dc3616ca40f188f030544776393c921af7e6fa40f0d9339af658
+  metadata.gz: 4a917e6a92b3f12506b6cf08e7c09c2cd37a6db31bdf6f8d6fb6cd9b1317fa1f23002e4839829ba023a6aeb80e68f74c92a91feb66bc0c4d6a9c8ed0178209e7
+  data.tar.gz: faea923c4f805a2b2cbb43d89676cb66b95c2e9df643f6aedb8125c4d1cd8d1cad1f0a946d39a70a8edac2d165d068ec1e06046d33390d3cff481e60cabeded5

data/CHANGELOG.md

@@ -0,0 +1,79 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.1.0] - 2026-05-13
+
+### Added
+
+- `enforce_readonly` class attribute on the `StaticRecord` concern (default: `true`).
+  Subclasses can opt out of the read-only guard without stubbing:
+  ```ruby
+  class Locations::Barangay < Pilipinas::Db::Barangay
+    self.enforce_readonly = false
+  end
+  ```
+- `lib/pilipinas/testing/rspec.rb` — a ready-made RSpec helper that disables
+  the read-only guard on all four DB models for the entire test suite.
+  Require it once in `rails_helper.rb`:
+  ```ruby
+  require 'pilipinas/testing/rspec'
+  ```
+- Spec coverage for `StaticRecord` — 8 examples covering default behaviour,
+  `enforce_readonly = false`, subclass inheritance, and class-level isolation.
+
+### Changed
+
+- `readonly?` now gates on `self.class.enforce_readonly && !new_record?` instead
+  of unconditionally returning `!new_record?`.
+
+---
+
+## [1.0.0] - 2026-05-12
+
+Complete rewrite of the gem. Zero runtime dependencies.
+
+### Added
+
+- In-memory layer with thread-safe `Pilipinas::Cache` (Mutex + double-checked
+  locking) and O(1) look-ups via separate code/name hash indices.
+- Immutable value objects — every entity instance is frozen.
+- `Pilipinas::Region`, `Province`, `City`, `Barangay` with `.all`, `.count`,
+  `.first`, `.last`, `.find_by`, `.find_by_code`, `.find_by_name`.
+- Hierarchy traversal: `region.provinces`, `province.cities`, `city.barangays`.
+- Optional ActiveRecord layer (`Pilipinas::Db::*`) with memory-efficient scopes
+  (`.lite`, `.by_code`, `.by_name`, `.find_lite_by_code`, `.find_lite_by_name`).
+- `StaticRecord` concern: disables STI, adds lean SELECT scopes, enforces
+  read-only on persisted records.
+- Migration generator (`rails generate pilipinas:migration`) and
+  `rake pilipinas:load` seeding task.
+- Full RSpec suite (57 examples).
+- GitHub Actions CI pipeline.
+
+### Changed
+
+- Requires Ruby ≥ 3.4 (developed against Ruby 4.0).
+- Removed all runtime gem dependencies (previously depended on `yaml_db` and
+  others).
+
+---
+
+## [0.0.1] - 2019-01-26
+
+### Added
+
+- Initial release.
+- YAML data for Philippine regions, provinces, cities, and barangays.
+- ActiveRecord models backed by `pilipinas_*` tables.
+- Migration template and Rake loader task.
+- Rails generator for migrations.
+- Railtie for automatic Rake task loading in Rails apps.
+
+[1.1.0]: https://github.com/denmarkmeralpis/pilipinas/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/denmarkmeralpis/pilipinas/compare/v0.0.1...v1.0.0
+[0.0.1]: https://github.com/denmarkmeralpis/pilipinas/releases/tag/v0.0.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pilipinas (1.0.0)
+    pilipinas (1.1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -295,7 +295,7 @@ CHECKSUMS
   nokogiri (1.19.3-x86_64-linux-musl) sha256=248c906d2166eca5efb56d52fdee5f9a1f51d69a72e2b64fdac647b4ce39ea3f
   parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
   parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
-  pilipinas (1.0.0)
+  pilipinas (1.1.0)
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85

data/README.md

@@ -18,6 +18,8 @@ Region  →  Province  →  City / Municipality  →  Barangay
 - **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.
 
 ---
@@ -184,6 +186,48 @@ 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
@@ -238,54 +282,8 @@ The gem is available as open source under the terms of the [MIT License](LICENSE
 
 ## Acknowledgements
 
-The geographic data used in this gem is derived from the Philippine Standard Geographic Code (PSGC) published by the Philippine Statistics Authority.
-
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'pilipinas'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install pilipinas
-
-## Usage
-
-```ruby
-# All Regions
-Pilipinas::Region.all
-
-# All Provinces
-Pilipinas::Province.all
-
-# All Cities/Municipalities
-Pilipinas::City.all
-
-# All Barangays
-Pilipinas::Barangay.all
-
-# Finding record thru find_by_(code/name) method
-region = Pilipinas::Region.find_by_name("REGION V (Bicol Region)")
-
-# Get provinces by region
-region.provinces
-```
-## Acknowledgement
-
 The data used in this gem is from `gem pinas`. Kudos!
 
-## TODO
-
-* Add a form helper
-
 ## 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.

data/lib/pilipinas/db/concerns/static_record.rb

@@ -25,10 +25,14 @@ module Pilipinas
       #
       # == Optimizations applied
       #
-      # * +readonly?+ returns +true+ for persisted records only — accidental
+      # * +readonly?+ returns +true+ for persisted records when
+      #   +enforce_readonly+ is +true+ (the default) — accidental
       #   +update!/save!/destroy+ on fetched rows raise
       #   +ActiveRecord::ReadOnlyRecord+; new records stay writable so the
       #   Loader and test fixtures can still call +create!+.
+      # * +enforce_readonly+ class attribute: opt a subclass out of the
+      #   read-only guard without touching production models — useful in test
+      #   environments where factories need to write to pilipinas tables.
       # * +self.inheritance_column = :_sti_disabled+: removes STI type-column
       #   look-up from every query.
       # * +.lite+ scope: selects only +id+, +location_id+, +code+, +name+ —
@@ -50,6 +54,11 @@ module Pilipinas
       #   province.cities    # SELECT id, location_id, parent_id, code, name …
       #   city.barangays     # SELECT id, location_id, parent_id, code, name …
       #
+      # @example Opting a subclass out of read-only enforcement (e.g. in tests)
+      #   class Locations::Barangay < Pilipinas::Db::Barangay
+      #     self.enforce_readonly = false
+      #   end
+      #
       module StaticRecord
         extend ActiveSupport::Concern
 
@@ -64,6 +73,16 @@ module Pilipinas
           # Removes the hidden "type" column check AR performs on every query.
           self.inheritance_column = :_sti_disabled
 
+          # ── Read-only enforcement ─────────────────────────────────────────
+          # Defaults to +true+.  Set to +false+ on a subclass (e.g. in a test
+          # environment or for a model that legitimately needs write access)
+          # without touching production behaviour:
+          #
+          #   class Locations::Barangay < Pilipinas::Db::Barangay
+          #     self.enforce_readonly = false
+          #   end
+          class_attribute :enforce_readonly, instance_writer: false, default: true
+
           # ── Memory-efficient query scopes ─────────────────────────────────
 
           # Select only the four columns needed for display and look-up.
@@ -97,19 +116,25 @@ module Pilipinas
           scope :find_lite_by_name, ->(name) { lite.by_name(name).first }
         end
 
-        # Persisted instances loaded from a pilipinas_* table are permanently
-        # read-only: +update!+, +save+, and +destroy+ all raise
-        # +ActiveRecord::ReadOnlyRecord+.  New (unsaved) objects are writable
-        # so that the Loader can still call +create!+ on the fallback path and
-        # so that specs can build fixtures with +create!+.
+        # Guards against accidental writes to static reference data.
+        #
+        # Returns +true+ (making the record read-only) when both conditions hold:
+        # 1. The record is persisted (+new_record?+ is +false+).
+        # 2. The class-level +enforce_readonly+ flag is +true+ (the default).
+        #
+        # New (unsaved) objects are always writable so the Loader and test
+        # factories can call +create!+.  To allow writes on a subclass — for
+        # example in a test environment — set:
+        #
+        #   self.enforce_readonly = false
         #
         # Overriding +readonly?+ is more efficient than an +after_initialize+
-        # callback because it is only called when AR is about to perform a
-        # write operation — it adds zero per-record overhead on reads.
+        # callback: it is only invoked when AR is about to perform a write
+        # operation, so it adds zero overhead on read paths.
         #
-        # @return [Boolean] +true+ for persisted records, +false+ for new ones
+        # @return [Boolean]
         def readonly?
-          !new_record?
+          self.class.enforce_readonly && !new_record?
         end
       end
     end

data/lib/pilipinas/testing/rspec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'pilipinas'
+
+# Pilipinas::Testing::RSpec
+#
+# Optional RSpec helper that disables the read-only guard on all Pilipinas DB
+# models for the duration of the test suite.  Require this file once (e.g. in
+# +rails_helper.rb+ or +spec/support/pilipinas.rb+) and FactoryBot factories,
+# fixtures, or any spec that needs to write to pilipinas_* tables will work
+# without stubbing or subclass overrides.
+#
+# == Usage
+#
+#   # spec/rails_helper.rb  (or spec/support/pilipinas.rb)
+#   require 'pilipinas/testing/rspec'
+#
+# == What it does
+#
+# Calls +enforce_readonly = false+ on every Pilipinas DB model inside a
+# +before(:suite)+ hook so the flag is set once, before any example runs.
+# The models remain writable for the entire test process, which is the correct
+# behaviour for a test environment where factories seed the pilipinas_* tables.
+#
+# If you need write access only in a specific context, set the flag manually
+# with an +around+ hook instead of requiring this file globally.
+#
+# == Models affected
+#
+# * Pilipinas::Db::Region
+# * Pilipinas::Db::Province
+# * Pilipinas::Db::City
+# * Pilipinas::Db::Barangay
+
+require 'rspec/core'
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    [
+      Pilipinas::Db::Region,
+      Pilipinas::Db::Province,
+      Pilipinas::Db::City,
+      Pilipinas::Db::Barangay
+    ].each { |model| model.enforce_readonly = false }
+  end
+end

data/lib/pilipinas/version.rb

@@ -4,5 +4,5 @@ module Pilipinas
   # Semantic version of the gem.
   #
   # Follows {https://semver.org Semantic Versioning}: MAJOR.MINOR.PATCH.
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pilipinas
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Nujian Den Mark Meralpis
@@ -143,6 +143,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -1924,6 +1925,7 @@ files:
 - lib/pilipinas/province.rb
 - lib/pilipinas/railtie.rb
 - lib/pilipinas/region.rb
+- lib/pilipinas/testing/rspec.rb
 - lib/pilipinas/version.rb
 - lib/tasks/pilipinas_tasks.rake
 - pilipinas.gemspec