activerecord-deepstore 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a8e192500276489b18a179c56d5e0878a1ca8b4600b85cd2c4f587403f2dc01
+  data.tar.gz: d40765f8d041804eb22d02036f7cb458e8540d7a75a7bfc82c5176af189ccfe2
+SHA512:
+  metadata.gz: 31153e6a0a5e32e49cd5cc8667cb79681b21d8c296d1521a7cdbf8b264b681552953ca5ee4c9061435cc880044fbf86f530f99ef6d795ef3a7ea7c1db1b3188b
+  data.tar.gz: a8e5052ee7ff97e8ac527c693019cad85a32430248984adb841e2be1ac49ae2279c060732fd0858620bc4c3ba3748b4c6622079bef7ba860eeccab8168d88f40

data/.rubocop.yml

@@ -0,0 +1,26 @@
+AllCops:
+  SuggestExtensions: false
+  TargetRubyVersion: 2.6
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-03-30
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Emmanuel Cousin
+
+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,129 @@
+# ActiveRecord-Deepstore
+
+ActiveRecord-Deepstore is a Ruby gem that extends ActiveRecord models with additional functionality for handling deeply nested data structures within a database column. It simplifies storing, accessing, and managing complex nested data in your Rails applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activerecord-deepstore'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install activerecord-deepstore
+```
+
+## Usage
+
+To use ActiveRecord-Deepstore in your Rails application, include it in your ActiveRecord models:
+
+```ruby
+class MyModel < ActiveRecord::Base
+  extend ActiveRecord::Deepstore
+end
+```
+
+Once included, your models gain access to methods for storing and accessing deeply nested data within database columns.
+
+### Example
+
+```ruby
+class User < ActiveRecord::Base
+  extend ActiveRecord::Deepstore
+
+  deep_store :settings, {
+    notifications: {
+      posts: { push: true, email: true },
+      comments: { push: true, email: false }
+    }
+  }
+end
+```
+
+This implementation provides with an accessor for every level of the provider hash:
+
+```ruby
+user.notifications_settings # => { posts: { push: true, email: true }, comments: { push: true, email: false } }
+user.posts_notifications_settings # => { push: true, email: true }
+user.push_posts_notifications_settings # => true
+user.email_posts_notifications_settings # => true
+user.comments_notifications_settings # => { push: true, email: false }
+user.push_comments_notifications_settings # => true
+user.email_comments_notifications_settings # => false
+```
+
+You can list all the generated accessors by calling `deep_stored_accessors` on the model `User`:
+
+```ruby
+User.deep_stored_accessors
+# => ["notifications_settings", "posts_notifications_settings", "push_posts_notifications_settings", [...], "email_comments_notifications_settings"]
+```
+
+#### Automatic typecasting
+
+Writer methods automatically cast the value to the type the default values belong to. For example:
+
+```ruby
+user.push_comments_notifications_settings = "1" # => "1"
+user.push_comments_notifications_settings # => true
+user.push_comments_notifications_settings = "0" # => "0"
+user.push_comments_notifications_settings # => false
+```
+
+#### Tracking value changes
+
+Dirty attributes are implemented for every accessor. For example:
+
+```ruby
+user.push_comments_notifications_settings # => false
+user.push_comments_notifications_settings = true # => true
+user.push_comments_notifications_settings_was # => false
+user.push_comments_notifications_settings_changes # => { false => true }
+user.push_comments_notifications_settings_changed? # => true
+```
+
+#### Accessing default values
+
+You can access the default value of every accessor at anytime by calling the associated `default_#{accessor_name}` method:
+
+```ruby
+user.push_comments_notifications_settings # => false
+user.update! push_comments_notifications_settings: true
+user.push_comments_notifications_settings # => true
+user.default_push_comments_notifications_settings #=> false
+```
+
+#### Resetting to default values
+
+You can reset every accessor to its default value  at anytime by calling the associated `reset_#{accessor_name}` method:
+
+```ruby
+# When the changes are not persisted
+user.push_comments_notifications_settings # => false
+user.push_comments_notifications_settings = true
+user.reset_push_comments_notifications_settings
+user.push_comments_notifications_settings # => false
+
+# When the changes are persisted
+user.update! push_comments_notifications_settings: true
+user.push_comments_notifications_settings # => true
+user.reset_push_comments_notifications_settings!
+user.reload.push_comments_notifications_settings # => false
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/EmCousin/activerecord-deepstore](https://github.com/EmCousin/activerecord-deepstore).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/activerecord-deepstore.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/active_record/deepstore/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "activerecord-deepstore"
+  spec.version = ActiveRecord::Deepstore::VERSION
+  spec.authors = ["Emmanuel Cousin"]
+  spec.email = ["emmanuel@hey.com"]
+
+  spec.summary = "ActiveRecord-Deepstore adds powerful functionality to ActiveRecord models for handling deeply nested data structures within database columns. Simplify storing, accessing, and managing complex nested data in your Rails applications with ease."
+  spec.description = "ActiveRecord-Deepstore enhances ActiveRecord models with powerful functionality for handling deeply nested data structures within a database column. It provides methods for storing, accessing, and managing deeply nested data, making it easier to work with complex data structures in your Rails applications. With ActiveRecord-Deepstore, you can seamlessly store nested hashes in database columns, access nested data with simple method calls, track changes to nested attributes, and much more. This gem simplifies the handling of complex data structures, improving the maintainability and readability of your Rails codebase."
+  spec.homepage = "https://github.com/EmCousin/activerecord-deepstore"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", "~> 7.0"
+  spec.add_dependency "activesupport", "~> 7.0"
+end

data/config/database.yml

@@ -0,0 +1,17 @@
+sqlite:
+  adapter: sqlite3
+  database: ":memory:"
+
+mysql:
+  adapter: mysql2
+  database: active_record_deepstore_test
+  username: root
+  password:
+
+postgresql:
+  adapter: postgresql
+  database: active_record_deepstore_test
+  username: postgres
+  password:
+  host: localhost
+  port: 5432

data/lib/active_record/deepstore/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Deepstore
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_record/deepstore.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require_relative "deepstore/version"
+
+module ActiveRecord
+  # The ActiveRecord::Deepstore module extends ActiveRecord models with additional
+  # functionality for handling deeply nested data structures within a database column.
+  module Deepstore
+    # Raised when an error occurs in the ActiveRecord::Deepstore module.
+    class Error < StandardError; end
+
+    attr_reader :deep_stored_accessors
+
+    # Retrieves or initializes the array containing names of attributes declared as deep stores.
+    #
+    # @return [Array<String>] The array containing names of deep stores.
+    def deep_stores
+      @deep_stores ||= []
+    end
+
+    # Recursively traverses a nested hash and returns a flattened representation of leaf nodes along with their paths.
+    #
+    # @param hash [Hash] The nested hash to traverse.
+    # @param path [Array] The current path in the hash.
+    # @param current_depth [Integer] The current depth in the hash traversal.
+    # @param max_depth [Integer, nil] The maximum depth to traverse. If nil, traverses the entire hash.
+    # @return [Hash] The flattened representation of leaf nodes along with their paths.
+    def leaves(hash, path: [], current_depth: 0, max_depth: nil)
+      hash.each_with_object({}) do |(key, value), result|
+        current_path = path + [key]
+
+        if value.is_a?(Hash) && (max_depth.nil? || current_depth < max_depth)
+          result.merge!(leaves(value, path: current_path, current_depth: current_depth + 1, max_depth: max_depth))
+        else
+          result[current_path] = value
+        end
+      end
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/PerceivedComplexity
+
+    # Defines behavior for storing deeply nested data in a database column.
+    #
+    # @param accessor_name [Symbol, String] The name of the accessor for the deep store.
+    # @param payload [Hash] The hash representing the deeply nested data.
+    # @param suffix [Boolean] Whether to include a suffix in the accessor name.
+    # @param column_required [Boolean] Whether the corresponding column is required in the database table.
+    # @raise [ActiveRecord::Deepstore::Error] If the deep store is already declared.
+    # @raise [NotImplementedError] If the required column is not found in the database table.
+    # @return [void]
+    def deep_store(accessor_name, payload, suffix: true, column_required: true)
+      accessor_name = accessor_name.to_s.parameterize.underscore
+
+      raise Error, "Deep store '#{accessor_name}' is already declared" if deep_stores.include?(accessor_name)
+
+      @deep_stores << accessor_name
+
+      if column_required && (columns.find do |c|
+                               c.name == accessor_name.to_s
+                             end).blank?
+        raise NotImplementedError,
+              "Column #{accessor_name} not found for table #{table_name}"
+      end
+
+      serialize accessor_name, type: Hash, default: payload, yaml: { unsafe_load: true } if payload.is_a?(Hash)
+
+      define_method(:"default_#{accessor_name}") { payload.try(:with_indifferent_access) || payload }
+
+      define_method(:"reset_#{accessor_name}") { assign_attributes(accessor_name => send(:"default_#{accessor_name}")) }
+
+      define_method(:"reset_#{accessor_name}!") { update(accessor_name => send(:"default_#{accessor_name}")) }
+
+      define_method(:"#{accessor_name}_changes") do
+        old_value = send(:"#{accessor_name}_was")
+        current_value = send(accessor_name)
+        old_value == current_value ? {} : { old_value => current_value }
+      end
+
+      define_method(:"#{accessor_name}=") do |value|
+        old_value = send(:"#{accessor_name}_was")
+
+        if value.is_a?(Hash)
+          value = {}.with_indifferent_access if value.blank?
+          self.class.leaves(value).each do |leaf_path, leaf_value|
+            default_value = leaf_path.inject(payload.with_indifferent_access) do |h, key|
+              h.is_a?(Hash) ? h.fetch(key, h) : h
+            end
+            cast_type = self.class.cast_type_from_name(self.class.cast_type_name_from_value(default_value))
+
+            # Traverse the hash using the leaf path and update the leaf value.
+            leaf_key = leaf_path.pop
+            parent_hash = leaf_path.inject(value, :[])
+            #  old_leaf_value = parent_hash[leaf_key]
+            new_leaf_value = cast_type.cast(leaf_value)
+            old_parent_hash = parent_hash.dup
+            parent_hash[leaf_key] = new_leaf_value
+
+            instance_variable_set(:"@#{leaf_path.join("_")}_#{accessor_name}_was",
+                                  old_parent_hash.with_indifferent_access)
+          end
+
+          formatted_value = payload.with_indifferent_access.deep_merge(value)
+        else
+          default_value = send(:"default_#{accessor_name}")
+          cast_type = self.class.cast_type_from_name(self.class.cast_type_name_from_value(default_value))
+          formatted_value = cast_type.cast(value)
+        end
+
+        instance_variable_set(:"@#{accessor_name}_was", old_value)
+
+        super(formatted_value)
+      end
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      return unless payload.is_a?(Hash)
+
+      payload.each do |key, value|
+        deep_store_accessor(accessor_name, payload, key, value, suffix)
+      end
+    end
+
+    # Reloads the model instance and clears deep store changes information.
+    #
+    # @param args [Array] Arguments to pass to the reload method.
+    # @return [void]
+    define_method(:reload) do |*args|
+      clear_deep_store_changes_information
+      super(*args)
+    end
+
+    # Clears deep store changes information.
+    #
+    # @return [void]
+    define_method(:clear_deep_store_changes_information) do
+      self.class.deep_stored_accessors.each do |accessor|
+        formatted_accessor = accessor.to_s.parameterize.underscore
+        instance_variable_set(:"@#{formatted_accessor}_was", send(formatted_accessor))
+      end
+    end
+
+    # Defines accessor methods for nested keys within the deep store hash.
+    #
+    # @param accessor_name [Symbol, String] The name of the deep store accessor.
+    # @param payload [Hash] The hash representing the deeply nested data.
+    # @param key [Symbol, String] The key within the hash.
+    # @param value [Object] The value associated with the key.
+    # @param suffix [Boolean] Whether to include a suffix in the accessor name.
+    # @return [void]
+    def deep_store_accessor(accessor_name, payload, key, value, suffix)
+      store_json_accessor(accessor_name, payload, key, suffix)
+
+      deep_store(deep_accessor_name(accessor_name, key), value, column_required: false)
+
+      return if value.is_a?(Hash)
+
+      define_method(deep_accessor_name(accessor_name, key)) do
+        return value unless (hash = public_send(accessor_name)).is_a?(Hash) && hash.key?(key)
+
+        hash[key]
+      end
+    end
+
+    # rubocop:disable Metrics/MethodLength
+
+    # Defines accessor methods for individual keys within the nested hash.
+    #
+    # @param accessor_name [Symbol, String] The name of the deep store accessor.
+    # @param hash [Hash] The hash representing the deeply nested data.
+    # @param key [Symbol, String] The key within the hash.
+    # @param suffix [Boolean] Whether to include a suffix in the accessor name.
+    # @return [void]
+    def store_json_accessor(accessor_name, hash, key, suffix)
+      store_accessor(accessor_name.to_sym, key, suffix: suffix)
+      base_method_name = deep_accessor_name(accessor_name, key)
+      @deep_stored_accessors ||= []
+      @deep_stored_accessors << base_method_name
+      attribute base_method_name, cast_type_name_from_value(hash[key])
+
+      define_method(:"#{base_method_name}_was") do
+        method_name = :"#{base_method_name}_was"
+        return instance_variable_get("@#{method_name}") if instance_variable_defined?("@#{method_name}")
+
+        instance_variable_set("@#{method_name}", send(base_method_name))
+      end
+
+      define_method(:"#{base_method_name}_changed?") do
+        send(:"#{base_method_name}_changes").any?
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # Generates a unique name for accessor methods based on the accessor name and key.
+    #
+    # @param accessor_name [Symbol, String] The name of the deep store accessor.
+    # @param key [Symbol, String] The key within the hash.
+    # @return [String] The generated accessor name.
+    def deep_accessor_name(accessor_name, key)
+      "#{key.to_s.parameterize.underscore}_#{accessor_name.to_s.parameterize.underscore}"
+    end
+
+    # Determines the data type for serialization based on the value type.
+    #
+    # @param name [Symbol, String] The name of the data type.
+    # @return [ActiveRecord::Type::Value] The corresponding data type.
+    def cast_type_from_name(name)
+      ActiveRecord::Type.lookup name.to_sym, adapter: ActiveRecord::Type.adapter_name_from(self)
+    end
+
+    # Determines the data type name based on the value.
+    #
+    # @param value [Object] The value for which to determine the data type name.
+    # @return [Symbol] The name of the data type.
+    def cast_type_name_from_value(value)
+      type_mappings = {
+        TrueClass => :boolean,
+        FalseClass => :boolean,
+        NilClass => :string,
+        Hash => :text
+      }
+
+      type_mappings.fetch(value.class, value.class.name.underscore.to_sym)
+    end
+  end
+end

data/sig/activerecord/deepstore.rbs

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

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-deepstore
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Emmanuel Cousin
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-04-20 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'
+description: ActiveRecord-Deepstore enhances ActiveRecord models with powerful functionality
+  for handling deeply nested data structures within a database column. It provides
+  methods for storing, accessing, and managing deeply nested data, making it easier
+  to work with complex data structures in your Rails applications. With ActiveRecord-Deepstore,
+  you can seamlessly store nested hashes in database columns, access nested data with
+  simple method calls, track changes to nested attributes, and much more. This gem
+  simplifies the handling of complex data structures, improving the maintainability
+  and readability of your Rails codebase.
+email:
+- emmanuel@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- activerecord-deepstore.gemspec
+- activerecord-deepstore.sqlite3
+- config/database.yml
+- db/activerecord-deepstore.sqlite3
+- lib/active_record/deepstore.rb
+- lib/active_record/deepstore/version.rb
+- sig/activerecord/deepstore.rbs
+homepage: https://github.com/EmCousin/activerecord-deepstore
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/EmCousin/activerecord-deepstore
+  source_code_uri: https://github.com/EmCousin/activerecord-deepstore
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.21
+signing_key:
+specification_version: 4
+summary: ActiveRecord-Deepstore adds powerful functionality to ActiveRecord models
+  for handling deeply nested data structures within database columns. Simplify storing,
+  accessing, and managing complex nested data in your Rails applications with ease.
+test_files: []