binxtils 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6939fd30bf94c85805b8f5cbc55b0a5e4ea0b3938093c84b986e5d94571a9efb
+  data.tar.gz: 8cf7bcc61f2d001b6b4c67358b99505b528c5bfd40d9ac919c5a8b17a3efa64d
+SHA512:
+  metadata.gz: bc96e2f7f245112cfa3f70b1a224884c320b5cf27d17ce321d71e959935bf80127a113a9f96dfe762eebbb9122ed543589482cd8bc7e0a5f19c7f143f632d3b1
+  data.tar.gz: 0a1d915fb2ce58a04353421c0aed7ec6c41a56b0bdf56d07a146edad73ed26ead20548ca24eb6e6ccd01de9fdbd88ec0f63974b9f7bf4f6342e0eb2435ff9bfb

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bike Index
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,23 @@
+# Binxtils
+
+Bike Index utility modules. Install it by adding the following line to your Gemfile
+
+```ruby
+gem "binxtils"
+```
+
+## Modules
+
+- **Binxtils::InputNormalizer** - Sanitize and normalize user input strings
+- **Binxtils::TimeParser** - Parse fuzzy time/date strings into `Time` objects
+- **Binxtils::TimeZoneParser** - Parse and resolve time zone strings
+
+## Usage
+
+All modules use [Functionable](https://github.com/sethherr/functionable) and are called as class methods:
+
+```ruby
+Binxtils::TimeParser.parse("next thursday")
+Binxtils::InputNormalizer.string("  Some Input  ")
+Binxtils::TimeZoneParser.parse("Eastern Time")
+```

data/lib/binxtils/input_normalizer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Binxtils
+  module InputNormalizer
+    extend Functionable
+
+    def boolean(param = nil)
+      return false if param.blank?
+
+      ActiveRecord::Type::Boolean.new.cast(param.to_s.strip)
+    end
+
+    def string(val)
+      return nil if val.blank?
+
+      val.strip.gsub(/\s+/, " ")
+    end
+
+    def present_or_false?(val)
+      val.to_s.present?
+    end
+
+    def sanitize(str = nil)
+      Rails::Html::Sanitizer.full_sanitizer.new.sanitize(str.to_s, encode_special_chars: true)
+        .strip
+        .gsub("&", "&") # ampersands are commonly used - keep them normal
+        .gsub(/\s+/, " ") # remove extra whitespace
+    end
+
+    def regex_escape(val)
+      # Lazy hack, good enough for current purposes. Improve if required!
+      string(val)&.gsub(/\W/, ".")
+    end
+  end
+end

data/lib/binxtils/time_parser.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Binxtils
+  module TimeParser
+    extend Functionable
+
+    EARLIEST_YEAR = 1900
+    LATEST_YEAR = Time.current.year + 100
+
+    def default_time_zone
+      @default_time_zone ||= ActiveSupport::TimeZone[Rails.application.class.config.time_zone].freeze
+    end
+
+    def parse(time_str = nil, time_zone_str = nil, in_time_zone: false)
+      return nil unless time_str.present?
+      return time_str if time_str.is_a?(Time)
+
+      if looks_like_timestamp?(time_str)
+        return parse("#{time_str}-01-01") if time_str.to_s.length == 4 # Looks like year, valid 8601 format
+
+        # otherwise it's a timestamp
+        time = Time.at(time_str.to_i)
+      else
+        time_zone = Binxtils::TimeZoneParser.parse(time_zone_str)
+        Time.zone = time_zone
+        time = Time.zone.parse(time_str.to_s) # Assign in time zone
+        Time.zone = default_time_zone
+      end
+      # Return in time_zone or not
+      in_time_zone ? time_in_zone(time, time_str:, time_zone:, time_zone_str:) : time
+    rescue ArgumentError => e
+      # Try to parse some other, unexpected formats -
+      paychex_formatted = %r{(?<month>\d+)/(?<day>\d+)/(?<year>\d+) (?<hour>\d\d):(?<minute>\d\d) (?<ampm>\w\w)}.match(time_str)
+      ie11_formatted = %r{(?<month>\d+)/(?<day>\d+)/(?<year>\d+)}.match(time_str)
+      just_date = %r{(?<year>\d{4})[^\d|\w](?<month>\d\d?)}.match(time_str)
+      just_date_backward = %r{(?<month>\d\d?)[^\d|\w](?<year>\d{4})}.match(time_str)
+
+      # Get the successful matching regex group, and then reformat it in an expected way
+      regex_match = [paychex_formatted, ie11_formatted, just_date, just_date_backward].compact.first
+      raise e unless regex_match.present?
+
+      new_str = %w[year month day]
+        .map { |component| regex_match[component] if regex_match.names.include?(component) }
+        .compact
+        .join("-")
+
+      # If we end up with an unreasonable year, throw an error
+      raise e unless new_str.split("-").first.to_i.between?(EARLIEST_YEAR, LATEST_YEAR)
+
+      # Add the day, if there isn't one
+      new_str += "-01" unless regex_match.names.include?("day")
+      # If it's paychex_formatted there is an hour and minute
+      if paychex_formatted.present?
+        new_str += " #{regex_match["hour"]}:#{regex_match["minute"]}#{regex_match["ampm"]}"
+      end
+      # Run it through Binxtils::TimeParser again
+      parse(new_str, time_zone_str, in_time_zone:)
+    end
+
+    def looks_like_timestamp?(time_str)
+      time_str.is_a?(Integer) || time_str.is_a?(Float) || time_str.to_s.strip.match(/^\d+\z/) # it's only numbers
+    end
+
+    # Accepts a time object, rounds to minutes
+    def round(time, unit = "minute")
+      if unit == "second"
+        time.change(usec: 0, sec: 0)
+      else # Default is minute, nothing is built to manage anything else
+        time.change(min: 0, usec: 0, sec: 0)
+      end
+    end
+
+    #
+    # private below here
+    #
+
+    def time_in_zone(time, time_zone_str:, time_str: nil, time_zone: nil)
+      time_zone ||= if time_zone_str.present?
+        Binxtils::TimeZoneParser.parse(time_zone_str)
+      elsif time_str.present?
+        # If no time_zone_str was passed, try to parse it out of the time string
+        Binxtils::TimeZoneParser.parse_from_time_string(time_str.to_s)
+      end
+
+      time.in_time_zone(time_zone || ActiveSupport::TimeZone["UTC"])
+    end
+
+    conceal :time_in_zone
+  end
+end

data/lib/binxtils/time_zone_parser.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Binxtils
+  module TimeZoneParser
+    extend Functionable
+
+    def parse(time_zone_str)
+      return nil if time_zone_str.blank?
+      return time_zone_str if time_zone_str.is_a?(ActiveSupport::TimeZone) # in case we were given a time_zone obj
+
+      # tzinfo requires non-whitespaced strings.
+      # if the normal lookup fails, remove parens, then remove spaces and convert to underscores
+      ActiveSupport::TimeZone[time_zone_str] ||
+        ActiveSupport::TimeZone[time_zone_str.to_s.gsub(/\(.*?\)/, "").strip.tr("\s", "_")]
+    end
+
+    def parse_from_time_string(time_str)
+      return unless time_str.present? && time_string_has_zone_info?(time_str)
+
+      at = Time.parse(time_str.to_s)
+      offset_seconds = at.utc_offset
+      # Otherwise this returns casablanca. Guess UTC over London
+      return ActiveSupport::TimeZone["UTC"] if offset_seconds == 0
+
+      prioritized_zones_matching_offset(at, offset_seconds).first
+    end
+
+    def parse_from_time_and_offset(time:, offset:)
+      offset_seconds = offset.is_a?(String) ? Time.zone_offset(offset) : offset
+      offset_seconds ||= offset.to_i # Fallback parsing of seconds in a string
+
+      prioritized_zones_matching_offset(time, offset_seconds).first
+    end
+
+    def full_name(time_zone)
+      # TODO: figure out an easier way to get this
+      ActiveSupport::TimeZone::MAPPING.key(time_zone.tzinfo.name) || time_zone.name
+    end
+
+    #
+    # private below here
+    #
+
+    # TODO: This might be overly complicated garbage
+    def time_string_has_zone_info?(time_str)
+      return false if Binxtils::TimeParser.looks_like_timestamp?(time_str)
+
+      timezone_patterns = [
+        /[+-]\d{2}:?\d{2}\b/,          # +0900, +09:00, -0500, etc
+        /\b(?:UTC|GMT)\b/i,            # UTC or GMT
+        /\b[A-Z]{3,4}\b/,              # EST, PDT, AEST, etc
+        /[+-]\d{4}\b/,                 # +0900, -0500 without colon
+        /Z\b/,                         # UTC (Zulu time)
+        /\[[-+A-Za-z0-9\/]+\]/         # Time zone in brackets [America/New_York]
+      ]
+
+      # Try parsing to validate it's actually a time string
+      Time.parse(time_str)
+
+      # Check if any timezone pattern matches
+      timezone_patterns.any? { |pattern| time_str.match?(pattern) }
+    rescue ArgumentError
+      false
+    end
+
+    # Guess possible time zones based on UTC offset at a specific time
+    # Returns an array of [timezone_name, city_name] pairs
+    def prioritized_zones_matching_offset(at, offset_seconds)
+      # Convert seconds to hours for comparison
+      offset_hours = offset_seconds / 3600.0
+
+      # Get all time zones
+      possible_zones = ActiveSupport::TimeZone.all.select do |zone|
+        # Calculate the offset at the specific time
+        zone_time = at.in_time_zone(zone)
+        zone_offset = zone_time.utc_offset / 3600.0
+
+        zone_offset == offset_hours
+      end
+
+      # Sort zones by priority/popularity
+      prioritize_zones(possible_zones)
+    end
+
+    def prioritize_zones(zones)
+      zones.sort_by do |zone|
+        priority = case zone.tzinfo.name
+        # Major US zones
+        when /New_York/, /Chicago/, /Los_Angeles/ then 1
+        # Major European zones
+        when /London/, /Paris/, /Berlin/ then 5
+        # Major Asian zones
+        when /Tokyo/, /Shanghai/, /Singapore/ then 5
+
+        # Major cities generally
+        when /Mexico City|Sydney|Hong_Kong|Dubai|Toronto|Vancouver/ then 10
+        # State/Provincial capitals
+        when /Melbourne|Brisbane|Perth|Montreal|Edmonton/ then 20
+        # Smaller cities
+        else 100
+        end
+
+        [priority, zone]
+      end
+    end
+
+    conceal :time_string_has_zone_info?, :prioritized_zones_matching_offset, :prioritize_zones
+  end
+end

data/lib/binxtils.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "functionable"
+require "active_support"
+require "active_support/core_ext"
+require "active_record"
+require "loofah"
+require "rails-html-sanitizer"
+
+require_relative "binxtils/input_normalizer"
+require_relative "binxtils/time_zone_parser"
+require_relative "binxtils/time_parser"

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: binxtils
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bike Index
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: functionable
+  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: activesupport
+  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: activerecord
+  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: loofah
+  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: rails-html-sanitizer
+  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'
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- LICENSE
+- README.md
+- lib/binxtils.rb
+- lib/binxtils/input_normalizer.rb
+- lib/binxtils/time_parser.rb
+- lib/binxtils/time_zone_parser.rb
+homepage: https://github.com/bikeindex/binxtils
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/bikeindex/binxtils/issues
+  homepage_uri: https://github.com/bikeindex/binxtils
+  funding_uri: https://github.com/sponsors/bikeindex
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Bike Index utility modules
+test_files: []