model_timeline 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7406b06646ef46c0b8d2541835ebeaa5e0f71638c600d0b7de45903bb36b2c81
-  data.tar.gz: dad655ebda19102a5e09eb3a51d07ac15cfbca051527ee3c3a71d979ab2a4543
+  metadata.gz: 9d1c5aacdbe6970e7724f4f40d81c2e67b0f7739b7efe4784adb773a88d142a4
+  data.tar.gz: 38fc7b5502adf1a18809f8fd7aa54d3f5906888a9e37ed3f6b8fa9ef232e893c
 SHA512:
-  metadata.gz: 4f618bea0cc20328d5d2a61352c753ec39fbe04f90b7f909ba93df236ab28a4e239515c3b0b70913381149e99996c189ebb41afe5e2a2d6649e3fdb0fabf24b4
-  data.tar.gz: d145d2798077f4bbb13191f966d8b73433330e5360b808862f14ddc3f1e4d7e6d97d231ad9e0828a5f63f4f759453550eb5cb132781a9a5dfa15b21b816ec36b
+  metadata.gz: 5710fbe04cd8871236b90891e2298098b4d986b9d63e4f0c5943af5592b0e4ee47bf248490f2f508992a3a39ea50f20839f11d5b043196cbb8e6a527925d6d1c
+  data.tar.gz: 584e6aeb8875bffd927d86532e0b05cb2989027df80b6b5cf0ed15d587bfdce1f65f9f5cb6a92b8a88dc7e416ac56c653604d6f9635a6dc91a53ab4f97046192

data/README.md

@@ -127,7 +127,6 @@ end
 
 ### Using Metadata
 
-<!-- ! THIS IS WRONG, NEEDS TO BE UPDATED.  -->
 ModelTimeline allows you to include custom metadata with your timeline entries, which is especially useful for tracking changes across related entities or adding domain-specific context.
 
 #### Adding Metadata Through Configuration
@@ -147,8 +146,7 @@ end
 ```
 
 If your timeline table has columns that match the keys in your `meta` hash, these values will be stored in
-those dedicated columns. Otherwise they will be ignored. (This might change in the future and a metadata column might be
-added to put additional metadata that doesn't have a dedicated column.)
+those dedicated columns. Otherwise, they will be stored inside `metadata` column.
 
 #### Adding Metadata at Runtime
 
@@ -172,13 +170,16 @@ For tracking related entities more effectively, you can create a custom timeline
 class CreatePostTimelineEntries < ActiveRecord::Migration[6.1]
   def change
     create_table :post_timeline_entries do |t|
-      # Standard ModelTimeline columns
-      t.string   :timelineable_type
-      t.integer  :timelineable_id
-      t.string   :action
-      t.jsonb    :object_changes
-      t.integer  :user_id
-      t.string   :ip_address
+      # Default Columns - All of them are required.
+      t.string :timelineable_type
+      t.bigint :timelineable_id
+      t.string :action, null: false
+      t.jsonb :object_changes, default: {}, null: false
+      t.jsonb :metadata, default: {}, null: false
+      t.string :user_type
+      t.bigint :user_id
+      t.string :username
+      t.inet :ip_address
 
       # Custom columns that can be populated via the meta option
       t.integer  :post_id
@@ -186,9 +187,12 @@ class CreatePostTimelineEntries < ActiveRecord::Migration[6.1]
       t.timestamps
     end
 
-    add_index :post_timeline_entries, [:timelineable_type, :timelineable_id]
-    add_index :post_timeline_entries, :post_id
-    add_index :post_timeline_entries, :user_id
+    add_index :post_timeline_entries, [:timelineable_type, :timelineable_id], name: 'idx_timeline_on_timelineable'
+    add_index :post_timeline_entries, [:user_type, :user_id], name: 'idx_timeline_on_user'
+    add_index :post_timeline_entries, :object_changes, using: :gin, name: 'idx_timeline_on_changes'
+    add_index :post_timeline_entries, :metadata, using: :gin, name: 'idx_timeline_on_meta'
+    add_index :post_timeline_entries, :ip_address, name: 'idx_timeline_on_ip'
+    add_index :post_timeline_entries, :post_id, name: 'idx_timeline_on_post_id'
   end
 end
 ```
@@ -381,11 +385,6 @@ Configure RSpec to work with ModelTimeline:
 require 'model_timeline/rspec'
 
 RSpec.configure do |config|
-  # This disables ModelTimeline by default in tests for better performance
-  config.before(:suite) do
-    ModelTimeline.disable!
-  end
-
   # Include the RSpec helpers and matchers
   config.include ModelTimeline::RSpec
 end
@@ -436,17 +435,65 @@ expect(user).to have_timeline_entries
 expect(user).to have_timeline_entries(3)
 
 # Check for entries with a specific action
-expect(user).to have_timelined_action(:update)
+expect(user).to have_timeline_entry_action(:update)
 
 # Check if a specific attribute was changed
-expect(user).to have_timelined_change(:email)
+expect(user).to have_timeline_entry_change(:email)
 
 # Check if an attribute was changed to a specific value
-expect(user).to have_timelined_entry(:status, 'active')
+expect(user).to have_timeline_entry(:status, 'active')
+
+# Check if an entry was created with expected metadata
+expect(user).to have_timeline_entry_metadata(foo: 'bar', baz: 'biz')
 ```
 
 These matchers make it easy to test that your application is correctly tracking model changes.
 
+##### Matchers for custom models/tables
+
+You can add a configuration in your support file to create matchers for your association.
+Given a model like this:
+
+```ruby
+class User < ApplicationRecord
+  has_timeline :security_events, class_name: 'SecurityTimelineEntry'
+end
+```
+
+You should set a configuration in your RSpec support file with:
+```ruby
+# spec/support/model_timeline.rb
+require 'model_timeline/rspec'
+
+RSpec.configure do |config|
+  # Include the RSpec helpers and matchers
+  config.include ModelTimeline::RSpec
+  config.include ModelTimeline::RSpec::Matchers.define_timeline_matchers_for(:security_events)
+end
+```
+
+Then you have those new matchers:
+
+```ruby
+# Check for any timeline entries
+expect(user).to have_security_events
+
+# Check for a specific number of entries
+expect(user).to have_security_events(3)
+
+# Check for entries with a specific action
+expect(user).to have_security_event_action(:update)
+
+# Check if a specific attribute was changed
+expect(user).to have_security_event_change(:email)
+
+# Check if an attribute was changed to a specific value
+expect(user).to have_security_event(:status, 'active')
+
+# Check if an entry was created with expected metadata
+expect(user).to have_security_event_metadata(foo: 'bar', baz: 'biz')
+```
+
 
 ## License
 

data/lib/model_timeline/generators/templates/migration.rb.tt

@@ -7,6 +7,7 @@ class CreateModelTimelineTables < ActiveRecord::Migration[<%= ActiveRecord::Migr
 
       # Use PostgreSQL's JSONB type for better performance
       t.jsonb :object_changes, default: {}, null: false
+      t.jsonb :metadata, default: {}, null: false
 
       # Polymorphic user association
       t.string :user_type
@@ -22,6 +23,7 @@ class CreateModelTimelineTables < ActiveRecord::Migration[<%= ActiveRecord::Migr
     add_index :<%= @table_name %>, [:timelineable_type, :timelineable_id], name: 'idx_timeline_on_timelineable'
     add_index :<%= @table_name %>, [:user_type, :user_id], name: 'idx_timeline_on_user'
     add_index :<%= @table_name %>, :object_changes, using: :gin, name: 'idx_timeline_on_changes'
+    add_index :<%= @table_name %>, :metadata, using: :gin, name: 'idx_timeline_on_meta'
     add_index :<%= @table_name %>, :ip_address, name: 'idx_timeline_on_ip'
   end
 end

data/lib/model_timeline/rspec/matchers.rb

@@ -2,7 +2,6 @@
 
 module ModelTimeline
   module RSpec
-    # rubocop:disable Naming/PredicateName
     # Custom RSpec matchers for testing model timeline entries
     #
     # These matchers help you test the timeline entries created by the ModelTimeline gem.
@@ -16,58 +15,78 @@ module ModelTimeline
     #   expect(user).to have_timeline_entries(3)
     #
     #   # Check for specific action
-    #   expect(user).to have_timelined_action(:update)
+    #   expect(user).to have_timeline_entry_action(:update)
     #
     #   # Check for changes to a specific attribute
-    #   expect(user).to have_timelined_change(:email)
+    #   expect(user).to have_timeline_entry_change(:email)
     #
     #   # Check for specific value change
-    #   expect(user).to have_timelined_entry(:status, "active")
+    #   expect(user).to have_timeline_entry(:status, "active")
     module Matchers
-      # Check if a model has timeline entries
-      #
-      # @param count [Integer, nil] The expected number of timeline entries (optional)
-      # @return [HaveTimelineEntriesMatcher] A matcher that checks for timeline entries
-      # @example Without count parameter
-      #   expect(user).to have_timeline_entries
-      # @example With count parameter
-      #   expect(user).to have_timeline_entries(3)
-      def have_timeline_entries(count = nil)
-        HaveTimelineEntriesMatcher.new(count)
+      def self.included(base)
+        base.include define_timeline_matchers_for(:timeline_entries)
       end
 
-      # Check if a specific action was recorded in the timeline
-      #
-      # @param action [String, Symbol] The action name to look for
-      # @return [HaveTimelinedAction] A matcher that checks for a specific action
-      # @example
-      #   expect(user).to have_timelined_action(:create)
-      #   expect(user).to have_timelined_action("update")
-      def have_timelined_action(action)
-        HaveTimelinedAction.new(action)
-      end
+      def self.define_timeline_matchers_for(association_name)
+        association_name_singularized = association_name.to_s.singularize
 
-      # Check if a specific attribute change was recorded in the timeline
-      #
-      # @param attribute [String, Symbol] The attribute name to check for changes
-      # @return [HaveTimelinedChange] A matcher that checks if an attribute was changed
-      # @example
-      #   expect(user).to have_timelined_change(:email)
-      #   expect(user).to have_timelined_change("status")
-      def have_timelined_change(attribute)
-        HaveTimelinedChange.new(attribute)
-      end
+        Module.new do
+          # Check if a model has timeline entries
+          #
+          # @param count [Integer, nil] The expected number of timeline entries (optional)
+          # @return [HaveTimelineEntriesMatcher] A matcher that checks for timeline entries
+          # @example Without count parameter
+          #   expect(user).to have_timeline_entries
+          # @example With count parameter
+          #   expect(user).to have_timeline_entries(3)
+          define_method(:"have_#{association_name}") do |count = nil|
+            HaveTimelineEntriesMatcher.new(count, association_name)
+          end
 
-      # Check if an attribute was changed to a specific value in the timeline
-      #
-      # @param attribute [String, Symbol] The attribute name to check
-      # @param value [Object] The value to check for
-      # @return [HaveTimelinedEntry] A matcher that checks for specific attribute values
-      # @example
-      #   expect(user).to have_timelined_entry(:status, "active")
-      #   expect(user).to have_timelined_entry(:role, :admin)
-      def have_timelined_entry(attribute, value)
-        HaveTimelinedEntry.new(attribute, value)
+          # Check if a specific action was recorded in the timeline
+          #
+          # @param action [String, Symbol] The action name to look for
+          # @return [HaveTimelineAction] A matcher that checks for a specific action
+          # @example
+          #   expect(user).to have_timeline_entry_action(:create)
+          #   expect(user).to have_timeline_entry_action("update")
+          define_method(:"have_#{association_name_singularized}_action") do |action|
+            HaveTimelineAction.new(action, association_name)
+          end
+
+          # Check if a specific attribute change was recorded in the timeline
+          #
+          # @param attribute [String, Symbol] The attribute name to check for changes
+          # @return [HaveTimelineChange] A matcher that checks if an attribute was changed
+          # @example
+          #   expect(user).to have_timeline_entry_change(:email)
+          #   expect(user).to have_timeline_entry_change("status")
+          define_method(:"have_#{association_name_singularized}_change") do |attribute|
+            HaveTimelineChange.new(attribute, association_name)
+          end
+
+          # Check if an attribute was changed to a specific value in the timeline
+          #
+          # @param attribute [String, Symbol] The attribute name to check
+          # @param value [Object] The value to check for
+          # @return [HaveTimelineEntry] A matcher that checks for specific attribute values
+          # @example
+          #   expect(user).to have_timeline_entry(:status, "active")
+          #   expect(user).to have_timeline_entry(:role, :admin)
+          define_method(:"have_#{association_name_singularized}") do |attribute, value|
+            HaveTimelineEntry.new(attribute, value, association_name)
+          end
+
+          # Check if a model has timeline entries with specific metadata
+          #
+          # @param expected_metadata [Hash] The metadata key-value pairs to check for
+          # @return [HaveTimelineEntryMetadata] A matcher that checks for specific metadata
+          # @example
+          #   expect(user).to have_timeline_entry_metadata(foo: 'bar', baz: 'biz')
+          define_method(:"have_#{association_name_singularized}_metadata") do |expected_metadata|
+            HaveTimelineEntryMetadata.new(expected_metadata, association_name)
+          end
+        end
       end
 
       # RSpec matcher to check if a model has timeline entries
@@ -77,8 +96,9 @@ module ModelTimeline
         # Initialize the matcher
         #
         # @param expected_count [Integer, nil] The expected number of timeline entries
-        def initialize(expected_count)
+        def initialize(expected_count, association_name)
           @expected_count = expected_count
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -88,9 +108,9 @@ module ModelTimeline
         def matches?(subject)
           @subject = subject
           if @expected_count.nil?
-            subject.timeline_entries.any?
+            subject.public_send(@association_name).any?
           else
-            subject.timeline_entries.count == @expected_count
+            subject.public_send(@association_name).count == @expected_count
           end
         end
 
@@ -102,7 +122,7 @@ module ModelTimeline
             "expected #{@subject} to have timeline entries, but found none"
           else
             "expected #{@subject} to have #{@expected_count} timeline entries, " \
-              "but found #{@subject.timeline_entries.count}"
+              "but found #{@subject.public_send(@association_name).count}"
           end
         end
 
@@ -111,7 +131,7 @@ module ModelTimeline
         # @return [String] A descriptive failure message for negated expectations
         def failure_message_when_negated
           if @expected_count.nil?
-            "expected #{@subject} not to have any timeline entries, but found #{@subject.timeline_entries.count}"
+            "expected #{@subject} not to have any timeline entries, but found #{@subject.public_send(@association_name).count}"
           else
             "expected #{@subject} not to have #{@expected_count} timeline entries, but found exactly that many"
           end
@@ -121,12 +141,13 @@ module ModelTimeline
       # RSpec matcher to check if a model has timeline entries with a specific action
       #
       # @api private
-      class HaveTimelinedAction
+      class HaveTimelineAction
         # Initialize the matcher
         #
         # @param action [String, Symbol] The action to look for
-        def initialize(action)
+        def initialize(action, association_name)
           @action = action.to_s
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -135,7 +156,7 @@ module ModelTimeline
         # @return [Boolean] True if the model has timeline entries with the specified action
         def matches?(subject)
           @subject = subject
-          subject.timeline_entries.where(action: @action).exists?
+          @subject.public_send(@association_name).where(action: @action).exists?
         end
 
         # Message displayed when the expectation fails
@@ -156,12 +177,13 @@ module ModelTimeline
       # RSpec matcher to check if a model has timeline entries with changes to a specific attribute
       #
       # @api private
-      class HaveTimelinedChange
+      class HaveTimelineChange
         # Initialize the matcher
         #
         # @param attribute [String, Symbol] The attribute to check for changes
-        def initialize(attribute)
+        def initialize(attribute, association_name)
           @attribute = attribute.to_s
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -170,7 +192,7 @@ module ModelTimeline
         # @return [Boolean] True if the model has timeline entries with changes to the specified attribute
         def matches?(subject)
           @subject = subject
-          subject.timeline_entries.with_changed_attribute(@attribute).exists?
+          @subject.public_send(@association_name).with_changed_attribute(@attribute).exists?
         end
 
         # Message displayed when the expectation fails
@@ -191,14 +213,15 @@ module ModelTimeline
       # RSpec matcher to check if a model has timeline entries where an attribute changed to a specific value
       #
       # @api private
-      class HaveTimelinedEntry
+      class HaveTimelineEntry
         # Initialize the matcher
         #
         # @param attribute [String, Symbol] The attribute to check
         # @param value [Object] The value the attribute should have changed to
-        def initialize(attribute, value)
+        def initialize(attribute, value, association_name)
           @attribute = attribute.to_s
           @value = value
+          @association_name = association_name
         end
 
         # Check if the subject matches the expectations
@@ -207,7 +230,7 @@ module ModelTimeline
         # @return [Boolean] True if the model has timeline entries where the attribute changed to the specified value
         def matches?(subject)
           @subject = subject
-          subject.timeline_entries.with_changed_value(@attribute, @value).exists?
+          @subject.public_send(@association_name).with_changed_value(@attribute, @value).exists?
         end
 
         # Message displayed when the expectation fails
@@ -224,7 +247,52 @@ module ModelTimeline
           "expected #{@subject} not to have tracked '#{@attribute}' changing to '#{@value}', but such a change was found"
         end
       end
+
+      # RSpec matcher to check if a model has timeline entries with specific metadata
+      #
+      # @api private
+      class HaveTimelineEntryMetadata
+        # Initialize the matcher
+        #
+        # @param expected_metadata [Hash] The metadata key-value pairs to check for
+        # @param association_name [Symbol] The name of the timeline association
+        def initialize(expected_metadata, association_name)
+          @expected_metadata = expected_metadata
+          @association_name = association_name
+        end
+
+        # Check if the subject matches the expectations
+        #
+        # @param subject [Object] The model to check for timeline entries
+        # @return [Boolean] True if the model has timeline entries with the specified metadata
+        def matches?(subject)
+          @subject = subject
+
+          # Build a query that checks for each key-value pair in the metadata
+          entries = subject.public_send(@association_name)
+
+          # Construct queries for each metadata key-value pair
+          @expected_metadata.all? do |key, value|
+            # Use a JSON containment query to check if the metadata contains the key-value pair
+            # This syntax works with PostgreSQL's JSONB containment operator @>
+            entries.where('metadata @> ?', { key.to_s => value }.to_json).exists?
+          end
+        end
+
+        # Message displayed when the expectation fails
+        #
+        # @return [String] A descriptive failure message
+        def failure_message
+          "expected #{@subject} to have timeline entries with metadata #{@expected_metadata.inspect}, but none was found"
+        end
+
+        # Message displayed when the negated expectation fails
+        #
+        # @return [String] A descriptive failure message for negated expectations
+        def failure_message_when_negated
+          "expected #{@subject} not to have timeline entries with metadata #{@expected_metadata.inspect}, but such entries were found"
+        end
+      end
     end
-    # rubocop:enable Naming/PredicateName
   end
 end

data/lib/model_timeline/rspec.rb

@@ -20,7 +20,7 @@ module ModelTimeline
   #   describe User, :with_timeline do
   #     it "records timeline entries when updated" do
   #       user.update(name: "New Name")
-  #       expect(user).to have_timelined_change(:name)
+  #       expect(user).to have_timeline_entry_change(:name)
   #     end
   #   end
   module RSpec

data/lib/model_timeline/timelineable.rb

@@ -107,9 +107,10 @@ module ModelTimeline
           timelineable_id: id,
           action: action,
           object_changes: object_changes,
+          metadata: object_metadata(config),
           ip_address: current_ip_address,
           **current_user_attributes,
-          **collect_metadata(config[:meta], config_key)
+          **column_metadata(config)
         )
       end
 
@@ -128,9 +129,10 @@ module ModelTimeline
           timelineable_id: id,
           action: 'destroy',
           object_changes: {},
+          metadata: object_metadata(config),
           ip_address: current_ip_address,
           **current_user_attributes,
-          **collect_metadata(config[:meta], config_key)
+          **column_metadata(config)
         )
       end
 
@@ -183,32 +185,64 @@ module ModelTimeline
 
       # Collects metadata for the timeline entry
       #
-      # @param meta_config [Hash] The metadata configuration
-      # @param config_key [String] The configuration key for this model
+      # @param meta_config [Hash, Proc] The metadata configuration
       # @return [Hash] Collected metadata
-      def collect_metadata(meta_config, config_key)
-        config = self.class.loggers[config_key]
+      def collect_metadata(meta_config)
         metadata = {}
 
         # First, add any thread-level metadata
         metadata.merge!(ModelTimeline.metadata)
 
-        # Then, add any model-specific metadata defined in config
-        meta_config.each do |key, value|
-          resolved_value = case value
-                           when Proc
-                             instance_exec(self, &value)
-                           when Symbol
-                             respond_to?(value) ? send(value) : value
-                           else
-                             value
-                           end
-          metadata[key] = resolved_value
+        # Then, add any model-specific metadata from config
+        metadata.merge!(resolve_metadata_value(meta_config))
+
+        metadata
+      end
+
+      # Recursively resolves metadata values
+      #
+      # @param value [Hash, Proc, Symbol, Object] The value to resolve
+      # @return [Hash, Object] The resolved value
+      def resolve_metadata_value(value)
+        case value
+        when Proc
+          # If it's a Proc, execute it and process the result recursively
+          proc_result = instance_exec(self, &value)
+          proc_result.is_a?(Hash) ? process_metadata_hash(proc_result) : proc_result
+        when Hash
+          # If it's a Hash, process each key-value pair
+          process_metadata_hash(value)
+        when Symbol
+          # If it's a Symbol, try to call the method
+          respond_to?(value) ? send(value) : value
+        else
+          # Any other value, return as-is
+          value
         end
+      end
 
-        # Only include keys that exist as columns in the timeline entry table
+      # Processes a metadata hash by resolving each value
+      #
+      # @param hash [Hash] The hash to process
+      # @return [Hash] The processed hash
+      def process_metadata_hash(hash)
+        result = {}
+        hash.each do |key, val|
+          result[key] = resolve_metadata_value(val)
+        end
+        result
+      end
+
+      def column_metadata(config)
+        metadata = collect_metadata(config[:meta])
         column_names = config[:klass].column_names.map(&:to_sym)
         metadata.slice(*column_names)
       end
+
+      def object_metadata(config)
+        metadata = collect_metadata(config[:meta])
+        column_names = config[:klass].column_names.map(&:to_sym)
+        metadata.except(*column_names)
+      end
   end
 end

data/lib/model_timeline/version.rb

@@ -5,5 +5,5 @@ module ModelTimeline
   # Follows semantic versioning (https://semver.org/).
   #
   # @return [String] The current version in the format "MAJOR.MINOR.PATCH"
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: model_timeline
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Alexandre Stapenhorst
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-03 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg