locatable 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b00bd3e85ad8ba1435a8368b0ba2c3ca71d15d1e2e288e4a9d36068b51ef6e91
+  data.tar.gz: 45bb56e4b676f1cc7411e6a42d2788a205ae092271924201320f60649b2497fd
+SHA512:
+  metadata.gz: b3318c653b4e4f07e842e9352c5a01264d0bf38ed27f4542d719ddf58d573c4ab6e1a5cae4e5367abe12209095ba3af83381c76c36527e08cc8d79b08c4390e8
+  data.tar.gz: dbf11ce695414d9daed6cf5791dff0e7a2f86b2c9f787bdd79f63009781734af049dded028a9563bbca76c4b4fe8338b0324f78675003d4dc5f2f9cb3ec12af9

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-20
+
+- Initial release

data/README.md

@@ -0,0 +1,108 @@
+# Locatable
+
+Simple, fast, Geocoder-compatible PostGIS-backed location scopes for Active Record models.
+
+## Requirements
+
+- Ruby 3.2+
+- Active Record
+- PostgreSQL with PostGIS
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "locatable"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+## Setup
+
+Add latitude and longitude columns, then call `make_locatable` in the migration.
+
+```ruby
+class CreatePlaces < ActiveRecord::Migration[8.1]
+  def change
+    create_table :places do |t|
+      t.float :latitude
+      t.float :longitude
+      t.timestamps
+    end
+
+    make_locatable :places, latitude: :latitude, longitude: :longitude
+  end
+end
+```
+
+`make_locatable` adds generated PostGIS geography and geometry columns, plus GiST indexes.
+
+In the model, call `locatable`:
+
+```ruby
+class Place < ApplicationRecord
+  locatable
+end
+```
+
+## Usage
+
+Coordinates are passed as `[latitude, longitude]`.
+
+```ruby
+origin = [40.7128, -74.0060]
+
+Place.within_bounding_box([[40.70, -74.02], [40.73, -73.99]]) # Geocoder-compatible
+Place.near(origin, 5) # Geocoder-compatible
+Place.within_radius(origin, 5)
+Place.order_by_closest_to(origin)
+Place.select_distance_to(origin)
+```
+
+These 2 calls are equivalent:
+
+```ruby
+Place.near(origin, 2)
+Place.within_radius(origin, 2).order_by_closest_to(origin)
+```
+
+Distances use miles by default. Supported units are `:km`, `:mi`, and `:nm`.
+
+Set the units directly on a scope call:
+
+```ruby
+Place.near(origin, 10, units: :km)
+Place.within_radius(origin, 5, units: :nm)
+```
+
+Or set the default once in an initializer:
+
+```ruby
+# config/initializers/locatable.rb
+Locatable.default_units = :km
+```
+
+## Development
+
+Install dependencies:
+
+```sh
+bin/setup
+```
+
+Run tests with a PostGIS database URL:
+
+```sh
+LOCATABLE_DATABASE_URL=postgis://user:password@localhost/locatable_test bundle exec rake test
+```
+
+Run formatting:
+
+```sh
+bundle exec rake standard
+```

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/locatable/helpers.rb

@@ -0,0 +1,33 @@
+module Locatable::Helpers
+  module_function
+
+  def extract_lat_lng(origin)
+    lat, lng = case origin
+    when Array
+      [origin[0], origin[1]]
+    when Hash
+      [origin[:lat] || origin["lat"], origin[:lng] || origin["lng"]]
+    else
+      [origin.try(:lat), origin.try(:lng)]
+    end
+
+    [parse_float(lat), parse_float(lng)]
+  end
+
+  def parse_float(value)
+    Float(value)
+  rescue ArgumentError, TypeError
+    nil
+  end
+
+  def meters_per_units(units)
+    Locatable::METERS_PER_UNIT.fetch(Locatable.normalize_units(units))
+  end
+
+  def convert_to_meters(distance, units)
+    distance = parse_float(distance)
+    return nil if distance.nil?
+
+    distance * meters_per_units(units)
+  end
+end

data/lib/locatable/migration_helpers.rb

@@ -0,0 +1,27 @@
+module Locatable::MigrationHelpers
+  def make_locatable(table, latitude:, longitude:)
+    reversible do |dir|
+      dir.up do
+        execute <<~SQL
+          ALTER TABLE #{table}
+          ADD COLUMN location_geography geography(Point, 4326)
+          GENERATED ALWAYS AS (
+            ST_Point(#{longitude}, #{latitude}, 4326)::geography
+          ) STORED,
+          ADD COLUMN location_geometry geometry(Point, 4326)
+          GENERATED ALWAYS AS (
+            ST_Point(#{longitude}, #{latitude}, 4326)
+          ) STORED;
+        SQL
+      end
+
+      dir.down do
+        remove_column table, :location_geometry
+        remove_column table, :location_geography
+      end
+    end
+
+    add_index table, :location_geography, using: :gist
+    add_index table, :location_geometry, using: :gist
+  end
+end

data/lib/locatable/model.rb

@@ -0,0 +1,10 @@
+require "locatable/scopes"
+module Locatable::Model
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def locatable
+      include Locatable::Scopes
+    end
+  end
+end

data/lib/locatable/railtie.rb

@@ -0,0 +1,19 @@
+require "rails/railtie"
+require "locatable/migration_helpers"
+require "locatable/model"
+
+module Locatable
+  class Railtie < Rails::Railtie
+    initializer "locatable.migration_helpers" do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Migration.include Locatable::MigrationHelpers
+      end
+    end
+
+    initializer "locatable.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include Locatable::Model
+      end
+    end
+  end
+end

data/lib/locatable/scopes.rb

@@ -0,0 +1,80 @@
+require "active_support/concern"
+require "active_record"
+require "locatable/helpers"
+
+module Locatable::Scopes
+  extend ActiveSupport::Concern
+
+  SRID = 4326
+
+  included do
+    scope :within_bounding_box, ->(sw_ne_corners) do
+      next none if sw_ne_corners.nil?
+
+      sw_corner = sw_ne_corners.flatten[0..1]
+      ne_corner = sw_ne_corners.flatten[2..3]
+
+      sw_lat, sw_lng = Locatable::Helpers.extract_lat_lng(sw_corner)
+      ne_lat, ne_lng = Locatable::Helpers.extract_lat_lng(ne_corner)
+
+      next none if [sw_lat, sw_lng, ne_lat, ne_lng].any?(&:nil?)
+
+      location_column = :location_geometry
+
+      within_bbox_sql = if ne_lng > sw_lng
+        <<~SQL.squish
+          #{location_column} && ST_MakeEnvelope(#{sw_lng}, #{sw_lat}, #{ne_lng}, #{ne_lat}, #{SRID})
+        SQL
+      else
+        <<~SQL.squish
+          #{location_column} && ST_MakeEnvelope(#{sw_lng}, #{sw_lat}, 180, #{ne_lat}, #{SRID}) OR
+          #{location_column} && ST_MakeEnvelope(-180, #{sw_lat}, #{ne_lng}, #{ne_lat}, #{SRID})
+        SQL
+      end
+
+      where(Arel.sql(within_bbox_sql))
+    end
+
+    scope :order_by_closest_to, ->(origin) do
+      lat, lng = Locatable::Helpers.extract_lat_lng(origin)
+
+      next all if lat.nil? || lng.nil?
+
+      order(Arel.sql("location_geography <-> ST_Point(#{lng}, #{lat}, #{SRID})::geography"))
+    end
+
+    scope :select_distance_to, ->(origin, units: nil) do
+      units ||= Locatable.default_units
+      lat, lng = Locatable::Helpers.extract_lat_lng(origin)
+      meters_per_units = Locatable::Helpers.meters_per_units(units)
+
+      distance_sql = if lat.nil? || lng.nil?
+        "NULL"
+      else
+        "ST_Distance(location_geography, ST_Point(#{lng}, #{lat}, #{SRID})::geography) / #{meters_per_units}"
+      end
+
+      select("#{distance_sql} AS distance")
+    end
+
+    scope :within_radius, ->(origin, radius, units: nil) do
+      units ||= Locatable.default_units
+      lat, lng = Locatable::Helpers.extract_lat_lng(origin)
+      radius = Locatable::Helpers.convert_to_meters(radius, units)
+
+      next none if lat.nil? || lng.nil?
+      next all if radius.nil?
+
+      where(Arel.sql("ST_DWithin(location_geography, ST_Point(#{lng}, #{lat}, #{SRID})::geography, #{radius})"))
+    end
+
+    scope :near, ->(origin, radius = 20, units: nil, order_by_closest: true, select_distance: false) do
+      units ||= Locatable.default_units
+      scope = all
+      scope = scope.within_radius(origin, radius, units: units) if radius.present?
+      scope = scope.order_by_closest_to(origin) if order_by_closest
+      scope = scope.select_distance_to(origin, units: units) if select_distance
+      scope
+    end
+  end
+end

data/lib/locatable/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Locatable
+  VERSION = "0.1.1"
+end

data/lib/locatable.rb

@@ -0,0 +1,35 @@
+require_relative "locatable/version"
+require_relative "locatable/migration_helpers"
+require_relative "locatable/scopes"
+
+require "activerecord-postgis-adapter"
+
+require "locatable/railtie" if defined?(Rails::Railtie)
+
+module Locatable
+  VALID_UNITS = %i[km mi nm].freeze
+  METERS_PER_UNIT = {
+    km: 1_000.0,
+    mi: 1_609.344,
+    nm: 1_852.0
+  }.freeze
+
+  class << self
+    def default_units
+      @default_units ||= :mi
+    end
+
+    def default_units=(units)
+      @default_units = normalize_units(units)
+    end
+
+    def normalize_units(units)
+      units = units.to_sym
+      return units if VALID_UNITS.include?(units)
+
+      raise ArgumentError, "units must be one of: #{VALID_UNITS.join(", ")}"
+    rescue NoMethodError
+      raise ArgumentError, "units must be one of: #{VALID_UNITS.join(", ")}"
+    end
+  end
+end

data/sig/locatable.rbs

@@ -0,0 +1,4 @@
+module Locatable
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: locatable
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- simon
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord-postgis-adapter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Location scopes for Active Record models backed by PostGIS.
+email:
+- simonrmurcia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/locatable.rb
+- lib/locatable/helpers.rb
+- lib/locatable/migration_helpers.rb
+- lib/locatable/model.rb
+- lib/locatable/railtie.rb
+- lib/locatable/scopes.rb
+- lib/locatable/version.rb
+- sig/locatable.rbs
+homepage: https://github.com/simon/locatable
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/simon/locatable
+  source_code_uri: https://github.com/simon/locatable
+  changelog_uri: https://github.com/simon/locatable/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Location scopes for Active Record models.
+test_files: []