logga 3.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 156b89d500e231c81261932228af86c934bf2a95d57eaeed5016aa98fcd8ce72
-  data.tar.gz: 6662b604701dc7a5422863977d7d2dbef2549af382f1bf7f038afb72c7d032e6
+  metadata.gz: d75ebd3e7aaf71d362a3434cfdf18c443f9a9e2211f493f9263f1297c73f1bca
+  data.tar.gz: 59c3bcfba124a2cff37290d364527bcedd26c9c2ddc9fcd290bdd7b3323f4181
 SHA512:
-  metadata.gz: 7c13d5319ed50c2114252f174c5433b8b67a5c91ce78dca3f22f238f8c62c963e2a5a98ac21e68f5d70b89f95b02d80a94dc3de990f823fa1a100e31a60ca621
-  data.tar.gz: 0bcdbdffe2682e5d21ec90f02b4dc2cdf26fa1fb3ebe0f2893b69573b4bbd903526b983b59783ed3a37a11d4960c0f023ba47562432db8cc600a65522dbfcbe9
+  metadata.gz: 638afbac5bd2330208069a0f4c725090fb88cb7e3785f64e1cf6a1d6c4255c5e7f39a7b92fc7481061e135a0e8765129ec4b12e06a48148e421b5f3cf62e6bc3
+  data.tar.gz: 6d07832218be126bb2328b72d0d2aba1b2640b46d830cf6a087e3b45fd1221d5947869ad892b2db33aff4f024304f94fe79811e4288aaa9a1449ca6084d1470e

data/README.md

@@ -7,7 +7,7 @@ Provides attribute logging functionality to ActiveRecord objects.
 
 ## Requirements
 
-Requires Ruby 2.7.3 or above
+- Ruby >= 3.0
 
 ## Installation
 
@@ -31,27 +31,94 @@ gem install logga
 
 ## Usage
 
-Add this to your model:
+Add the following to your model:
 
 ```ruby
-class Order < ApplicationRecord
-  add_log_entries_for :create, :update
+class Thing < ApplicationRecord
+  # Optional author accessor. See #author
+  attr_accessor :author
+
+  # Association to :log_entries, which the loggable object must response to for logging.
+  has_many :log_entries, as: :loggable, dependent: :destroy
+
+  add_log_entries_for(
+    :create, # Log on object create
+    :delete, # Log on object delete
+    :update, # Log on object update
+    allowed_fields: [], # set an array of fields allowed to be logged
+    exclude_fields: [], # set an array of fields excluded from logging. Ignored if allowed_fields is set
+    fields: {}, # Custom messages for fields. See #fields
+    to: nil
+  )
 end
 ```
 
-So that new LogEntry records attached to a given Order instance will be created whenever a new one is created or
+So that new `LogEntry` records attached to a given `Thing` instance will be created whenever a new one is created or
 modified.
 
+## Author
+
+If you want to log the author of the changes you can do so by setting:
+
+```ruby
+thing.author = { id: "1", name: "Barry", type: "User" }
+```
+
+## Fields
+
+You can override the default messages per field by using:
+
+```ruby
+add_log_entries_for(
+  :update,
+  fields: {
+    name: lambda { |record, field, old_value, new_value|
+      "Name changed from #{old_value} to #{new_value}"
+    }
+  }
+)
+```
+
+This is with the exeception on `:created_at` which only takes the created record.
+
+```ruby
+add_log_entries_for(
+  :create,
+  fields: {
+    created_at: lambda { |record|
+      "Created object with id: #{record.id}"
+    }
+  }
+)
+```
+
+## Configuration
+
+Add an initializer to your project:
+
+```ruby
+Logga.configure do |config|
+  config.enabled = true
+  config.excluded_fields = [] # Default array of excluded fields i.e. [:id] to ignore all :id fields for every object
+  config.excluded_suffixes = [] # Array of excluded suffixes i.e. [:_id] to ignore all fields that end in :_id for every object
+end
+```
+
+For example:
+
+```ruby
+Logga.configure do |config|
+  config.excluded_fields = [:id] # Don't log any id changes
+  config.excluded_suffixes = [_id] # Don't log any column that ends in _id
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
-## Versioning
-
-The version of the gem should be set in the `VERSION` file found in the root of the project. This is then read by the `lib/boxt_aasm_ext/version.rb` file to set in the gem.
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/boxt/logga.
@@ -62,6 +129,5 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## TODOs
 
-- Write some tests
 - Improve the documentation
-- Remove explicit `EXCLUDED_KEYS` and `EXCLUDED_SUFFIXES` for something that can be set in an initializer
+- Add migration generator for `:log_entries`

data/Rakefile

@@ -8,4 +8,5 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.pattern = Dir.glob("spec/**/*_spec.rb")
 end
 
+desc "Map rake test to rake spec"
 task test: :spec

data/VERSION

@@ -1 +1 @@
-3.0.0
+5.0.0

data/lib/logga/active_record.rb

@@ -4,21 +4,18 @@ module Logga
   module ActiveRecord
     extend ActiveSupport::Concern
 
-    EXCLUDED_KEYS = %i[id created_at deleted_at initial updated_at log sent_after_sales_emails].freeze
-    EXCLUDED_SUFFIXES = %i[_id _filenames].freeze
-
     included do
       class_attribute :allowed_fields, instance_writer: false
       class_attribute :excluded_fields, instance_writer: false
-      class_attribute :log_fields, instance_writer: false
+      class_attribute :fields, instance_writer: false
 
       self.allowed_fields = []
       self.excluded_fields = []
-      self.log_fields = {}
+      self.fields = {}
     end
 
     class_methods do
-      def add_log_entries_for(*actions, to: :self, fields: {}, allowed_fields: [], exclude_fields: [])
+      def add_log_entries_for(*actions, allowed_fields: [], exclude_fields: [], fields: {}, to: :self)
         after_create :log_model_creation if actions.include?(:create)
         after_destroy :log_model_deletion if actions.include?(:delete)
         after_update :log_model_changes if actions.include?(:update)
@@ -26,7 +23,7 @@ module Logga
 
         self.allowed_fields = Array(allowed_fields)
         self.excluded_fields = allowed_fields.blank? ? Array(exclude_fields) : []
-        self.log_fields = fields
+        self.fields = fields
       end
     end
 
@@ -34,27 +31,29 @@ module Logga
       return if changes.blank?
 
       body = field_changes_to_message(changes)
-      create_log_entry(author_data.merge(body: body)) if body.present?
+      return if body.blank?
+
+      create_log_entry(author_data.merge(body: body))
     end
 
     def log_model_creation
-      return if should_not_log?
+      return unless should_log?
 
       body_generator = ->(record) { default_creation_log_body(record) }
-      body = log_fields.fetch(:created_at, body_generator).call(self)
+      body = fields.fetch(:created_at, body_generator).call(self)
       create_log_entry(author_data.merge(body: body, created_at: creation_at))
     end
 
     def log_model_deletion
-      return if should_not_log?
+      return unless should_log?
 
       body_generator = ->(record) { default_deletion_log_body(record) }
-      body = log_fields.fetch(:deleted_at, body_generator).call(self)
+      body = fields.fetch(:deleted_at, body_generator).call(self)
       create_log_entry(author_data.merge(body: body))
     end
 
     def log_model_changes
-      return if should_not_log?
+      return unless should_log?
 
       field_changes = previous_changes.reject { |k, _| reject_change?(k) }
       log_field_changes(field_changes)
@@ -64,13 +63,22 @@ module Logga
 
     def author_data
       data = Hash(log_receiver.try(:author) || try(:author)).with_indifferent_access
+
       {
         author_id: data[:id],
-        author_type: data[:type],
-        author_name: data[:name]
+        author_name: data[:name],
+        author_type: data[:type]
       }
     end
 
+    def config_excluded_fields
+      Logga.configuration.excluded_fields
+    end
+
+    def config_excluded_suffixes
+      Logga.configuration.excluded_suffixes
+    end
+
     def create_log_entry(entry)
       log_receiver&.log_entries&.create(entry)
     end
@@ -82,10 +90,7 @@ module Logga
     end
 
     def default_creation_log_body(record)
-      [
-        "#{titleized_model_class_name(record)} created",
-        ("(#{record.state})" if record.try(:state))
-      ].compact.join(" ")
+      "#{titleized_model_class_name(record)} created"
     end
 
     def default_change_log_body(record, field, _old_value, new_value)
@@ -104,7 +109,7 @@ module Logga
         default_change_log_body(record, field, old_value, new_value)
       }
       changes.inject([]) do |result, (field, (old_value, new_value))|
-        result << log_fields.fetch(field.to_sym, body_generator).call(self, field, old_value, new_value)
+        result << fields.fetch(field.to_sym, body_generator).call(self, field, old_value, new_value)
       end.compact.join("\n")
     end
 
@@ -112,14 +117,14 @@ module Logga
       sym_key = key.to_sym
       return allowed_fields.exclude?(sym_key) if allowed_fields.present?
 
-      EXCLUDED_KEYS.include?(sym_key) ||
-        (log_fields.exclude?(sym_key) &&
+      config_excluded_fields.include?(sym_key) ||
+        (fields.exclude?(sym_key) &&
          (excluded_fields.include?(sym_key) ||
-          EXCLUDED_SUFFIXES.any? { |suffix| key.to_s.end_with?(suffix.to_s) }))
+          config_excluded_suffixes.any? { |suffix| key.to_s.end_with?(suffix.to_s) }))
     end
 
-    def should_not_log?
-      !log_receiver.respond_to?(:log_entries)
+    def should_log?
+      Logga.enabled? && log_receiver.respond_to?(:log_entries)
     end
 
     def titleized_model_class_name(record)

data/lib/logga/config.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Logga
+  class Config
+    attr_accessor :enabled, :excluded_fields, :excluded_suffixes
+
+    def initialize(enabled: true, excluded_fields: [], excluded_suffixes: [])
+      @enabled = enabled
+      @excluded_fields = excluded_fields
+      @excluded_suffixes = excluded_suffixes
+    end
+  end
+end

data/lib/logga.rb

@@ -3,11 +3,37 @@
 require "active_support"
 require "active_support/core_ext"
 require "active_support/concern"
-require_relative "logga/version"
+
 require_relative "logga/active_record"
+require_relative "logga/config"
+require_relative "logga/version"
 
 module Logga
   ActiveSupport.on_load(:active_record) do
     include Logga::ActiveRecord
   end
+
+  class << self
+    def configuration
+      @configuration ||= Config.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # Switches Logga on or off
+    def enabled=(value)
+      configuration.enabled = value
+    end
+
+    # Returns `true` if Logga is on, `false` otherwise
+    def enabled?
+      !!configuration.enabled
+    end
+
+    def version
+      Logga::VERSION
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logga
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Boxt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-07 00:00:00.000000000 Z
+date: 2024-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -63,6 +63,7 @@ files:
 - VERSION
 - lib/logga.rb
 - lib/logga/active_record.rb
+- lib/logga/config.rb
 - lib/logga/version.rb
 homepage: https://github.com/boxt/logga
 licenses:
@@ -77,14 +78,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: ActiveRecord log entries on model changes