active_record_properties 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c559ee1c0fcde4e5d30fcf9c2886c92a83b05d9b64acec12befd19620f452ba
+  data.tar.gz: 19da1cdd203d63c27fc96ad3079dd41716a35ebfc2547f5b39171f016f70a774
+SHA512:
+  metadata.gz: 378acd7972f525dc79897ab68e5b831e834697b942545ec1e66d4eca8c4d613b1333431d1c857f4fca2b638ec4c7a961a7b7dc56b26ff51c55248005811dbb2b
+  data.tar.gz: b05440aea8f698538a48fb8a72a1c8519afdbc42ecf2572c313ec0efd2bdbbf3b846f11ed688b925c5e4c97f5e1ff9150c66c5456c0beb6460c55019737035cd

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-08
+
+### Added
+- Initial release
+- `ActiveRecordProperties::Settable` concern for adding properties to ActiveRecord models
+- `has_properties` DSL for defining properties stored in JSONB columns
+- Support for types: string, integer, float, boolean, hash, array
+- Static and dynamic (proc) default values
+- Automatic initialization of defaults via `after_initialize` callback
+- Full test coverage with RSpec (28 examples, 0 failures)
+- Support for Rails 7.0+, 7.1+, 7.2+, 8.0+, 8.1+
+- Appraisal configuration for testing against multiple Rails versions
+- Lefthook configuration for pre-commit hooks (rubocop, rspec, appraisal)
+- Comprehensive README with usage examples and comparison table

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexey Poimtsev
+
+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,270 @@
+# ActiveRecordProperties
+
+Type-safe properties stored in JSONB for ActiveRecord models. A modern, lightweight alternative to separate settings tables.
+
+## Why ActiveRecordProperties?
+
+Store model settings and properties in a JSONB column with:
+
+- **Clean DSL** - Simple, readable property definitions
+- **Type Safety** - Built-in type casting for common types
+- **Default Values** - Static or dynamic (proc) defaults
+- **Performance** - No JOINs, everything in one table
+- **Flexibility** - Use any JSONB column name
+- **Rails-native** - Built on `store_accessor` and `attribute` APIs
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "active_record_properties"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Add JSONB column to your model
+
+```ruby
+class AddPropertiesToUsers < ActiveRecord::Migration[7.0]
+  def change
+    add_column :users, :properties, :jsonb, default: {}, null: false
+  end
+end
+```
+
+### 2. Include the module and define properties
+
+```ruby
+class User < ApplicationRecord
+  include ActiveRecordProperties::Settable
+
+  has_properties do  # Uses :properties column by default
+    property :theme, type: :string, default: "light"
+    property :language, type: :string, default: "en"
+    property :notifications_enabled, type: :boolean, default: true
+    property :email_frequency, type: :string, default: "daily"
+    property :preferences, type: :hash, default: -> { {} }
+  end
+end
+```
+
+### 3. Use like normal attributes
+
+```ruby
+user = User.new
+user.theme                   # => "light"
+user.theme = "dark"
+user.notifications_enabled   # => true
+user.preferences             # => {}
+user.save!
+
+# All stored in JSONB
+user.properties
+# => {"theme"=>"dark", "language"=>"en", "notifications_enabled"=>true, ...}
+```
+
+## Usage
+
+### Supported Types
+
+```ruby
+has_properties do
+  property :name, type: :string, default: "default"
+  property :count, type: :integer, default: 0
+  property :rate, type: :float, default: 1.5
+  property :enabled, type: :boolean, default: true
+  property :config, type: :hash, default: -> { {} }
+  property :tags, type: :array, default: -> { [] }
+end
+```
+
+### Static vs Dynamic Defaults
+
+**Static defaults** (for immutable values):
+
+```ruby
+property :tax_rate, type: :float, default: 13.0
+property :enabled, type: :boolean, default: true
+```
+
+**Dynamic defaults** (for mutable values - use proc):
+
+```ruby
+property :settings, type: :hash, default: -> { {} }
+property :tags, type: :array, default: -> { [] }
+```
+
+⚠️ **Important**: Always use proc for Hash and Array defaults to avoid sharing the same object between instances!
+
+### Custom Column Name
+
+By default, `has_properties` uses the `:properties` column. You can specify a different column name:
+
+```ruby
+has_properties column: :settings do
+  property :foo, type: :string
+end
+
+# Defaults to :properties if column is not specified
+has_properties do
+  property :bar, type: :string
+end
+```
+
+### Multiple Property Groups
+
+You can use multiple JSONB columns for different purposes:
+
+```ruby
+class Organization < ApplicationRecord
+  include ActiveRecordProperties::Settable
+
+  has_properties column: :settings do
+    property :income_tax_rate, type: :float, default: 13.0
+  end
+
+  has_properties column: :preferences do
+    property :theme, type: :string, default: "light"
+  end
+end
+```
+
+## Querying
+
+Use PostgreSQL JSONB operators:
+
+```ruby
+# Find organizations with specific tax rate
+Organization.where("settings->>'income_tax_rate' = ?", "13.0")
+
+# Find organizations with auto-calculation enabled
+Organization.where("settings->>'auto_calculate_net_salary' = ?", "true")
+
+# Use JSONB containment
+Organization.where("settings @> ?", {enabled: true}.to_json)
+```
+
+## Examples
+
+### User Preferences
+
+```ruby
+class User < ApplicationRecord
+  include ActiveRecordProperties::Settable
+
+  has_properties do  # Uses :properties column by default
+    property :theme, type: :string, default: "light"
+    property :language, type: :string, default: "en"
+    property :notifications_enabled, type: :boolean, default: true
+    property :email_frequency, type: :string, default: "daily"
+    property :timezone, type: :string, default: "UTC"
+    property :ui_preferences, type: :hash, default: -> { {} }
+  end
+
+  def notification_time
+    Time.current.in_time_zone(timezone)
+  end
+end
+
+# Usage
+user = User.create(theme: "dark", language: "ru")
+user.theme              # => "dark"
+user.timezone = "Europe/Moscow"
+user.notification_time  # => Time in Moscow timezone
+```
+
+### Organization Settings
+
+```ruby
+class Organization < ApplicationRecord
+  include ActiveRecordProperties::Settable
+
+  has_properties column: :settings do
+    property :income_tax_rate, type: :float, default: 13.0
+    property :auto_calculate_net_salary, type: :boolean, default: true
+    property :requires_manager_approval, type: :boolean, default: true
+    property :requires_hrd_approval, type: :boolean, default: true
+    property :probation_period_months, type: :integer, default: 3
+    property :dashboard_period, type: :integer, default: 30
+    property :notification_settings, type: :hash, default: -> { {} }
+    property :kpi_targets, type: :hash, default: -> { {} }
+  end
+
+  def calculate_net_from_gross(gross_amount)
+    return nil unless gross_amount && auto_calculate_net_salary
+
+    tax_multiplier = (100 - income_tax_rate) / 100.0
+    (gross_amount * tax_multiplier).round(2)
+  end
+end
+
+# Usage
+org = Organization.create(income_tax_rate: 15.0)
+org.calculate_net_from_gross(100_000)  # => 85000.0
+```
+
+## Comparison with Alternatives
+
+| Feature     | ActiveRecordProperties | rails-settings-cached | ledermann/rails-settings |
+| ----------- | ---------------------- | --------------------- | ------------------------ |
+| Storage     | JSONB column           | Separate table        | Separate table           |
+| Performance | Fast (no JOIN)         | Slower (JOIN)         | Slower (JOIN)            |
+| Setup       | Include module         | Global model          | Polymorphic model        |
+| API         | `org.setting`          | `Setting.foo`         | `org.settings(:key).foo` |
+| Per-model   | ✅ Yes                 | ❌ No (global)        | ✅ Yes                   |
+| Type safety | ✅ Yes                 | ✅ Yes                | ⚠️ Limited               |
+| Defaults    | ✅ Static + Dynamic    | ✅ Yes                | ✅ Yes                   |
+
+## Rails Compatibility
+
+Tested with:
+
+- Rails 7.0
+- Rails 7.1
+- Rails 7.2
+- Rails 8.0
+- Rails 8.1
+
+Ruby 3.2+ required.
+
+## Development
+
+After checking out the repo:
+
+```bash
+bin/setup              # Install dependencies
+rake spec              # Run tests
+bin/console            # Interactive prompt
+bundle exec appraisal install  # Install for all Rails versions
+bundle exec appraisal rake spec # Test all Rails versions
+```
+
+### Running Tests
+
+```bash
+rake spec                          # Run all tests
+bundle exec appraisal rake spec    # Test against all Rails versions
+bundle exec lefthook install       # Install git hooks
+```
+
+### Code Quality
+
+```bash
+bundle exec rubocop               # Check code style
+bundle exec rubocop -A            # Auto-fix issues
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alec-c4/active_record_properties.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/active_record_properties/dsl.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveRecordProperties
+  # DSL for defining properties
+  class DSL
+    attr_reader :properties, :column
+
+    def initialize(column)
+      @column = column
+      @properties = []
+    end
+
+    # Define a property
+    #
+    # @param name [Symbol, String] Property name
+    # @param type [Symbol] Property type (:string, :integer, :float, :boolean, :hash, :array)
+    # @param default [Object, Proc] Default value or proc
+    #
+    # @example
+    #   property :income_tax_rate, type: :float, default: 13.0
+    #   property :settings, type: :hash, default: -> { {} }
+    def property(name, type: :string, default: nil)
+      prop = Property.new(name, type: type, default: default, column: column)
+      @properties << prop
+    end
+  end
+end

data/lib/active_record_properties/property.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActiveRecordProperties
+  # Represents a single property definition
+  class Property
+    attr_reader :name, :type, :default, :column
+
+    SUPPORTED_TYPES = %i[string integer float boolean hash array].freeze
+
+    def initialize(name, type: :string, default: nil, column: :properties)
+      @name = name.to_sym
+      @type = type.to_sym
+      @default = default
+      @column = column.to_sym
+
+      validate_type!
+    end
+
+    def default_value
+      return default.call if default.respond_to?(:call)
+      default
+    end
+
+    private
+
+    def validate_type!
+      return if SUPPORTED_TYPES.include?(type)
+
+      raise ArgumentError, "Unsupported type: #{type}. " \
+                           "Supported types: #{SUPPORTED_TYPES.join(", ")}"
+    end
+  end
+end

data/lib/active_record_properties/settable.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ActiveRecordProperties
+  # Main concern for adding properties to ActiveRecord models
+  module Settable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Define properties stored in JSONB column
+      #
+      # @param column [Symbol] Name of JSONB column (default: :properties)
+      # @param block [Proc] Block with property definitions
+      #
+      # @example
+      #   class Organization < ApplicationRecord
+      #     include ActiveRecordProperties::Settable
+      #
+      #     has_properties column: :settings do
+      #       property :income_tax_rate, type: :float, default: 13.0
+      #       property :auto_calculate_net_salary, type: :boolean, default: true
+      #       property :probation_period_months, type: :integer, default: 3
+      #       property :notification_settings, type: :hash, default: -> { {} }
+      #     end
+      #   end
+      #
+      #   org = Organization.new
+      #   org.income_tax_rate # => 13.0
+      #   org.income_tax_rate = 15.0
+      def has_properties(column: :properties, &block)
+        dsl = DSL.new(column)
+        dsl.instance_eval(&block)
+
+        setup_properties(column, dsl.properties)
+      end
+
+      private
+
+      def setup_properties(column, properties)
+        # Setup store_accessor for JSONB column
+        accessor_names = properties.map(&:name)
+        store_accessor column, *accessor_names
+
+        # Store properties metadata for introspection
+        class_variable_set(:@@_properties, properties)
+        class_variable_set(:@@_properties_column, column)
+
+        # Initialize defaults via callback
+        after_initialize do
+          column_data = send(column) || {}
+
+          properties.each do |property|
+            # Only set default if value is not already set
+            next if column_data.key?(property.name.to_s)
+
+            default_val = property.default_value
+            send("#{property.name}=", default_val) unless default_val.nil?
+          end
+        end
+      end
+    end
+
+    # Get all defined properties
+    #
+    # @return [Array<Property>] Array of property definitions
+    def self.properties
+      return [] unless class_variable_defined?(:@@_properties)
+
+      class_variable_get(:@@_properties)
+    end
+
+    # Get properties column name
+    #
+    # @return [Symbol] Column name
+    def self.properties_column
+      return :properties unless class_variable_defined?(:@@_properties_column)
+
+      class_variable_get(:@@_properties_column)
+    end
+  end
+end

data/lib/active_record_properties/version.rb

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

data/lib/active_record_properties.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "active_record_properties/version"
+require_relative "active_record_properties/property"
+require_relative "active_record_properties/dsl"
+require_relative "active_record_properties/settable"
+
+module ActiveRecordProperties
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,222 @@
+--- !ruby/object:Gem::Specification
+name: active_record_properties
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexey Poimtsev
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.35.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.35.1
+description: Store model settings and properties in JSONB columns with a clean DSL,
+  type casting, default values, and validations. A modern alternative to separate
+  settings tables.
+email:
+- alexey.poimtsev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/active_record_properties.rb
+- lib/active_record_properties/dsl.rb
+- lib/active_record_properties/property.rb
+- lib/active_record_properties/settable.rb
+- lib/active_record_properties/version.rb
+homepage: https://github.com/alec-c4/active_record_properties
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alec-c4/active_record_properties
+  source_code_uri: https://github.com/alec-c4/active_record_properties
+  changelog_uri: https://github.com/alec-c4/active_record_properties/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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: Type-safe properties stored in JSONB for ActiveRecord models
+test_files: []