togglefy 1.2.0 → 1.2.1

data/lib/togglefy/engine.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The Engine class integrates the Togglefy gem with a Rails application.
+  # It isolates the namespace to avoid conflicts with other parts of the application.
   class Engine < ::Rails::Engine
     isolate_namespace Togglefy
   end

data/lib/togglefy/errors/assignables_not_found.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The AssignablesNotFound class represents an error raised when no assignables
+  # match the provided features and filters.
   class AssignablesNotFound < Togglefy::Error
+    # Initializes a new AssignablesNotFound error.
+    #
+    # @param klass [Class] The class of the assignable.
     def initialize(klass)
       super("No #{klass.name} found matching features and filters sent")
     end

data/lib/togglefy/errors/bulk_toggle_failed.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The BulkToggleFailed error is raised when a bulk toggle operation fails.
+  # This error provides additional context by allowing an optional cause to be specified.
   class BulkToggleFailed < Togglefy::Error
+    # Initializes a new BulkToggleFailed error.
+    #
+    # @param message [String] The error message (default: "Bulk toggle operation failed").
+    # @param cause [Exception, nil] The underlying cause of the error, if any.
+    # @return [BulkToggleFailed] A new instance of the error.
     def initialize(message = "Bulk toggle operation failed", cause = nil)
       super(message)
       set_backtrace(cause.backtrace) if cause
       @cause = cause
     end
 
+    # @!attribute [r] cause
+    #   @return [Exception, nil] The underlying cause of the error, if any.
     attr_reader :cause
   end
 end

data/lib/togglefy/errors/dependency_missing.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The DependencyMissing class represents an error raised when a feature
+  # is missing a required dependency.
   class DependencyMissing < Togglefy::Error
+    # Initializes a new DependencyMissing error.
+    #
+    # @param feature [String] The name of the feature.
+    # @param required [String] The name of the missing dependency.
     def initialize(feature, required)
       super("Feature '#{feature}' is missing dependency: '#{required}'")
     end

data/lib/togglefy/errors/error.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The Error class is the base class for all custom exceptions in the Togglefy gem.
+  # It inherits from StandardError to provide a consistent error hierarchy.
   class Error < StandardError; end
 end

data/lib/togglefy/errors/feature_not_found.rb

@@ -1,9 +1,18 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The FeatureNotFound class represents an error raised when no features
+  # match the provided criteria or filters.
   class FeatureNotFound < Togglefy::Error
-    def initialize
-      super("No features found matching features and/or filters sent")
+    # Initializes a new FeatureNotFound error.
+    def initialize(message = "No features found matching features, identifiers and/or filters sent", cause = nil)
+      super(message)
+      set_backtrace(cause.backtrace) if cause
+      @cause = cause
     end
+
+    # @!attribute [r] cause
+    #   @return [Exception, nil] The underlying cause of the error, if any.
+    attr_reader :cause
   end
 end

data/lib/togglefy/errors/invalid_feature_attribute.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The InvalidFeatureAttribute class represents an error raised when an
+  # invalid attribute is provided for a Togglefy::Feature.
   class InvalidFeatureAttribute < Togglefy::Error
+    # Initializes a new InvalidFeatureAttribute error.
+    #
+    # @param attr [String] The name of the invalid attribute.
     def initialize(attr)
       super("The attribute '#{attr}' is not valid for Togglefy::Feature.")
     end

data/lib/togglefy/errors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# This file loads all custom exception classes used in the Togglefy gem.
+require "togglefy/errors/error"
+
+require "togglefy/errors/feature_not_found"
+require "togglefy/errors/assignables_not_found"
+require "togglefy/errors/bulk_toggle_failed"
+
+module Togglefy
+  # Custom error class for Togglefy-specific errors.
+  class Error < ::StandardError; end
+
+  # Overwrites the default StandardError class to provide a custom error class for Togglefy.
+  StandardError = Class.new(Error)
+end

data/lib/togglefy/feature_assignable_manager.rb

@@ -1,32 +1,53 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The FeatureAssignableManager class provides methods to manage features
+  # for an assignable object, such as enabling, disabling, and clearing features.
   class FeatureAssignableManager
+    # Initializes a new FeatureAssignableManager.
+    #
+    # @param assignable [Object] The assignable object to manage features for.
     def initialize(assignable)
       @assignable = assignable
     end
 
+    # Enables a feature for the assignable.
+    #
+    # @param feature [Togglefy::Feature, Symbol, String] The feature or its identifier.
+    # @return [FeatureAssignableManager] Returns self for method chaining.
     def enable(feature)
       assignable.add_feature(feature)
       self
     end
 
+    # Disables a feature for the assignable.
+    #
+    # @param feature [Togglefy::Feature, Symbol, String] The feature or its identifier.
+    # @return [FeatureAssignableManager] Returns self for method chaining.
     def disable(feature)
       assignable.remove_feature(feature)
       self
     end
 
+    # Clears all features from the assignable.
+    #
+    # @return [FeatureAssignableManager] Returns self for method chaining.
     def clear
       assignable.clear_features
       self
     end
 
+    # Checks if the assignable has a specific feature.
+    #
+    # @param feature [Togglefy::Feature, Symbol, String] The feature or its identifier.
+    # @return [Boolean] True if the feature exists, false otherwise.
     def has?(feature)
       assignable.has_feature?(feature)
     end
 
     private
 
+    # @return [Object] The assignable object being managed.
     attr_reader :assignable
   end
 end

data/lib/togglefy/feature_manager.rb

@@ -1,43 +1,74 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The FeatureManager class provides methods to manage features, including
+  # creating, updating, toggling, and destroying them.
   class FeatureManager
+    # Initializes a new FeatureManager.
+    #
+    # nil only applies when creating a new feature.
+    #
+    # @param identifier [String, nil] The identifier of the feature to manage.
     def initialize(identifier = nil)
       @identifier = identifier unless identifier.nil?
     end
 
+    # Creates a new feature with the given parameters.
+    #
+    # @param params [Hash] The attributes for the new feature.
+    # @return [Togglefy::Feature] The created feature.
     def create(**params)
       Togglefy::Feature.create!(**params)
     end
 
+    # Updates the feature with the given parameters.
+    #
+    # @param params [Hash] The attributes to update the feature with.
+    # @return [Togglefy::Feature] The updated feature.
     def update(**params)
       feature.update!(**params)
     end
 
+    # Destroys the feature.
+    #
+    # @return [Togglefy::Feature] The destroyed feature.
     def destroy
       feature.destroy
     end
 
+    # Toggles the feature's status between active and inactive.
+    #
+    # @return [Togglefy::Feature] The toggled feature.
     def toggle
       return feature.inactive! if feature.active?
 
       feature.active!
     end
 
+    # Activates the feature.
+    #
+    # @return [Togglefy::Feature] The activated feature.
     def active!
       feature.active!
     end
 
+    # Deactivates the feature.
+    #
+    # @return [Togglefy::Feature] The deactivated feature.
     def inactive!
       feature.inactive!
     end
 
     private
 
+    # @return [String, nil] The identifier of the feature being managed.
     attr_reader :identifier
 
+    # Finds the feature by its identifier.
+    #
+    # @return [Togglefy::Feature] The found feature.
     def feature
-      Togglefy::Feature.find_by!(identifier:)
+      Togglefy::Feature.find_by!(identifier: identifier)
     end
   end
 end

data/lib/togglefy/feature_query.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The FeatureQuery class provides methods to query features based on various filters.
   class FeatureQuery
+    # A mapping of filter keys to their corresponding query scopes.
     FILTERS = {
       identifier: :identifier,
       group: :for_group,
@@ -12,48 +14,88 @@ module Togglefy
       status: :with_status
     }.freeze
 
+    # Retrieves all features.
+    #
+    # @return [ActiveRecord::Relation] A relation of all features.
     def features
       Togglefy::Feature.all
     end
 
+    # Finds a feature by its identifier.
+    #
+    # @param identifier [Symbol, Array<Symbol>, String, Array<String>] The identifier(s) of the feature(s).
+    # @return [Togglefy::Feature, ActiveRecord::Relation] The feature or features matching the identifier(s).
     def feature(identifier)
       return Togglefy::Feature.identifier(identifier) if identifier.is_a?(Array)
 
-      Togglefy::Feature.find_by!(identifier:)
+      Togglefy::Feature.find_by!(identifier: identifier)
     end
 
+    # Retrieves feature assignments for a specific type.
+    #
+    # @param klass [Class] The class type to filter by.
+    # @return [ActiveRecord::Relation] A relation of feature assignments for the given type.
     def for_type(klass)
       Togglefy::FeatureAssignment.for_type(klass)
     end
 
+    # Retrieves features for a specific group.
+    #
+    # @param group [Symbol, String] The group to filter by.
+    # @return [ActiveRecord::Relation] A relation of features for the given group.
     def for_group(group)
       Togglefy::Feature.for_group(group)
     end
 
+    # Retrieves features without a group.
+    #
+    # @return [ActiveRecord::Relation] A relation of features without a group.
     def without_group
       Togglefy::Feature.without_group
     end
 
+    # Retrieves features for a specific environment.
+    #
+    # @param environment [Symbol, String] The environment to filter by.
+    # @return [ActiveRecord::Relation] A relation of features for the given environment.
     def for_environment(environment)
       Togglefy::Feature.for_environment(environment)
     end
 
+    # Retrieves features without an environment.
+    #
+    # @return [ActiveRecord::Relation] A relation of features without an environment.
     def without_environment
       Togglefy::Feature.without_environment
     end
 
+    # Retrieves features for a specific tenant.
+    #
+    # @param tenant_id [String] The tenant_id to filter by.
+    # @return [ActiveRecord::Relation] A relation of features for the given tenant.
     def for_tenant(tenant_id)
       Togglefy::Feature.for_tenant(tenant_id)
     end
 
+    # Retrieves features without a tenant.
+    #
+    # @return [ActiveRecord::Relation] A relation of features without a tenant.
     def without_tenant
       Togglefy::Feature.without_tenant
     end
 
+    # Retrieves features with a specific status.
+    #
+    # @param status [Symbol, String, Integer] The status to filter by.
+    # @return [ActiveRecord::Relation] A relation of features with the given status.
     def with_status(status)
       Togglefy::Feature.with_status(status)
     end
 
+    # Applies filters to retrieve features.
+    #
+    # @param filters [Hash] The filters to apply.
+    # @return [ActiveRecord::Relation] A relation of features matching the filters.
     def for_filters(filters)
       FILTERS.reduce(Togglefy::Feature) do |query, (key, scope)|
         value = filters[key]
@@ -65,10 +107,10 @@ module Togglefy
 
     private
 
-    def safe_chain(query, method, value, apply_if: true)
-      apply_if && nil_or_not_blank?(value) ? query.public_send(method, value) : query
-    end
-
+    # Checks if a value is nil or not blank.
+    #
+    # @param value [Symbol, String, Integer] The value to check.
+    # @return [Boolean] True if the value is nil or not blank, false otherwise.
     def nil_or_not_blank?(value)
       value.nil? || !value.blank?
     end

data/lib/togglefy/featureable.rb

@@ -3,6 +3,9 @@
 require "togglefy/assignable"
 
 module Togglefy
+  # `Featureable` is an alias for `Assignable`.
+  #
+  # @deprecated Use `Togglefy::Assignable` instead.
   Featureable = Assignable
   warn "[DEPRECATION] `Togglefy::Featureable` is deprecated. Use `Togglefy::Assignable` instead."
 end

data/lib/togglefy/scoped_bulk_wrapper.rb

@@ -3,11 +3,19 @@
 require "togglefy/services/bulk_toggler"
 
 module Togglefy
+  # The ScopedBulkWrapper class provides a wrapper for performing bulk operations
+  # on a specific class using the BulkToggler service.
   class ScopedBulkWrapper
+    # Initializes a new ScopedBulkWrapper.
+    #
+    # @param klass [Class] The class to perform bulk operations on.
     def initialize(klass)
       @klass = klass
     end
 
+    # Returns a BulkToggler instance for the specified class.
+    #
+    # @return [BulkToggler] The BulkToggler instance.
     def bulk
       BulkToggler.new(@klass)
     end

data/lib/togglefy/services/bulk_toggler.rb

@@ -1,25 +1,58 @@
 # frozen_string_literal: true
 
 module Togglefy
+  # The BulkToggler class provides functionality to enable or disable features
+  # in bulk for assignables, such as users or accounts.
   class BulkToggler
+    # List of allowed filters for assignables.
     ALLOWED_ASSIGNABLE_FILTERS = %i[group role environment env tenant_id].freeze
 
+    # Initializes a new BulkToggler instance.
+    #
+    # @param klass [Class] The assignable class (e.g., User, Account).
     def initialize(klass)
       @klass = klass
     end
 
+    # Enables features for assignables based on filters.
+    # @note All parameters but the first (identifiers) should be passed as keyword arguments.
+    #
+    # @param identifiers [Array<String>, String] The feature identifiers to enable.
+    # @param group [String] The group name to filter assignables by.
+    # @param role [String] The role name to filter assignables by.
+    # @param environment [String] The environment name to filter assignables by.
+    # @param env [String] The environment name to filter assignables by.
+    # @param tenant_id [String] The tenant_id to filter assignables by.
+    # @param percentage [Integer] The percentage of assignables to include.
     def enable(identifiers, **filters)
       toggle(:enable, identifiers, filters)
+      true
     end
 
+    # Disables features for assignables based on filters.
+    # @note All parameters but the first (identifiers) should be passed as keyword arguments.
+    #
+    # @param identifiers [Array<String>, String] The feature identifiers to disable.
+    # @param group [String] The group name to filter assignables by.
+    # @param role [String] The role name to filter assignables by.
+    # @param environment [String] The environment name to filter assignables by.
+    # @param env [String] The environment name to filter assignables by.
+    # @param tenant_id [String] The tenant_id to filter assignables by.
+    # @param percentage [Integer] The percentage of assignables to include.
     def disable(identifiers, **filters)
       toggle(:disable, identifiers, filters)
+      true
     end
 
     private
 
     attr_reader :klass
 
+    # Toggles features for assignables based on the action.
+    #
+    # @param action [Symbol] The action to perform (:enable or :disable).
+    # @param identifiers [Array<String>, String] The feature identifiers.
+    # @param filters [Hash] Additional filters for assignables.
     def toggle(action, identifiers, filters)
       identifiers = Array(identifiers)
       features = get_features(identifiers, filters)
@@ -34,6 +67,12 @@ module Togglefy
       disable_flow(assignables, features, identifiers) if action == :disable
     end
 
+    # Retrieves features based on identifiers and filters.
+    #
+    # @param identifiers [Array<String>] The feature identifiers.
+    # @param filters [Hash] Additional filters for features.
+    # @return [Array<Togglefy::Feature>] The matching features.
+    # @raise [Togglefy::FeatureNotFound] If no features are found.
     def get_features(identifiers, filters)
       features = Togglefy.for_filters(filters: { identifier: identifiers }.merge(build_scope_filters(filters))).to_a
 
@@ -42,6 +81,12 @@ module Togglefy
       features
     end
 
+    # Retrieves assignables based on the action and feature IDs.
+    #
+    # @param action [Symbol] The action to perform (:enable or :disable).
+    # @param feature_ids [Array<Integer>] The feature IDs.
+    # @return [Array<Assignable>] The matching assignables.
+    # @raise [Togglefy::AssignablesNotFound] If no assignables are found.
     def get_assignables(action, feature_ids)
       assignables = klass.without_features(feature_ids) if action == :enable
       assignables = klass.with_features(feature_ids) if action == :disable
@@ -51,15 +96,29 @@ module Togglefy
       assignables
     end
 
+    # Builds scope filters for assignables.
+    #
+    # @param filters [Hash] The filters to process.
+    # @return [Hash] The processed filters.
     def build_scope_filters(filters)
       filters.slice(*ALLOWED_ASSIGNABLE_FILTERS).compact
     end
 
+    # Samples assignables based on a percentage.
+    #
+    # @param assignables [Array<Assignable>] The assignables to sample.
+    # @param percentage [Float] The percentage of assignables to include.
+    # @return [Array<Assignable>] The sampled assignables.
     def sample_assignables(assignables, percentage)
       count = (assignables.size * percentage.to_f / 100).round
       assignables.sample(count)
     end
 
+    # Enables features for assignables.
+    #
+    # @param assignables [Array<Assignable>] The assignables to update.
+    # @param features [Array<Togglefy::Feature>] The features to enable.
+    # @param identifiers [Array<String>] The feature identifiers.
     def enable_flow(assignables, features, identifiers)
       rows = []
 
@@ -72,8 +131,17 @@ module Togglefy
       mass_insert(rows, identifiers)
     end
 
+    # Inserts feature assignments in bulk.
+    #
+    # @param rows [Array<Hash>] The rows to insert.
+    # @param identifiers [Array<String>] The feature identifiers.
+    # @raise [Togglefy::BulkToggleFailed] If the bulk insert fails.
     def mass_insert(rows, identifiers)
-      Togglefy::FeatureAssignment.insert_all(rows) if rows.any?
+      return unless rows.any?
+
+      ActiveRecord::Base.transaction do
+        Togglefy::FeatureAssignment.insert_all(rows)
+      end
     rescue Togglefy::Error => e
       raise Togglefy::BulkToggleFailed.new(
         "Bulk toggle enable failed for #{klass.name} with identifiers #{identifiers.inspect}",
@@ -81,6 +149,11 @@ module Togglefy
       )
     end
 
+    # Disables features for assignables.
+    #
+    # @param assignables [Array<Assignable>] The assignables to update.
+    # @param features [Array<Togglefy::Feature>] The features to disable.
+    # @param identifiers [Array<String>] The feature identifiers.
     def disable_flow(assignables, features, identifiers)
       ids_to_remove = []
 
@@ -93,11 +166,16 @@ module Togglefy
       mass_delete(ids_to_remove, identifiers)
     end
 
+    # Deletes feature assignments in bulk.
+    #
+    # @param ids_to_remove [Array<Array>] The IDs to remove.
+    # @param identifiers [Array<String>] The feature identifiers.
+    # @raise [Togglefy::BulkToggleFailed] If the bulk delete fails.
     def mass_delete(ids_to_remove, identifiers)
-      if ids_to_remove.any?
-        Togglefy::FeatureAssignment.where(
-          assignable_id: ids_to_remove.map(&:first), assignable_type: klass.name, feature_id: ids_to_remove.map(&:last)
-        ).delete_all
+      return unless ids_to_remove.any?
+
+      ActiveRecord::Base.transaction do
+        Togglefy::FeatureAssignment.where(mass_delete_scope(ids_to_remove, klass.name)).delete_all
       end
     rescue Togglefy::Error => e
       raise Togglefy::BulkToggleFailed.new(
@@ -105,5 +183,18 @@ module Togglefy
         e
       )
     end
+
+    # Builds the scope for mass deletion.
+    #
+    # @param ids [Array<Array>] The IDs of features to delete from the assignables.
+    # @param klass_name [String] The class name of the assignable.
+    # @return [Hash] The scope for mass deletion to be used in the query.
+    def mass_delete_scope(ids, klass_name)
+      {
+        assignable_id: ids.map(&:first),
+        assignable_type: klass_name,
+        feature_id: ids.map(&:last)
+      }
+    end
   end
 end

data/lib/togglefy/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Togglefy
-  VERSION = "1.2.0"
+  # The VERSION constant defines the current version of the Togglefy gem.
+  VERSION = "1.2.1"
 end