togglefy 1.1.1 → 1.2.1

data/lib/togglefy/services/bulk_toggler.rb

@@ -1,108 +1,200 @@
+# 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 = Togglefy.for_filters(
-        filters: {identifier: identifiers}.merge(build_scope_filters(filters))
-      ).to_a
-
-      raise Togglefy::FeatureNotFound if features.empty?
+      features = get_features(identifiers, filters)
 
       feature_ids = features.map(&:id)
 
-      assignables = if action == :enable
-        klass.without_features(feature_ids)
-      else
-        klass.with_features(feature_ids)
-      end
+      assignables = get_assignables(action, feature_ids)
 
-      raise Togglefy::AssignablesNotFound.new(klass, identifiers, filters) if assignables.empty?
-      
       assignables = sample_assignables(assignables, filters[:percentage]) if filters[:percentage]
 
-      existing_assignments = Togglefy::FeatureAssignment.where(
-        assignable_id: assignables.map(&:id),
-        assignable_type: klass.name,
-        feature_id: features.map(&:id)
-      ).pluck(:assignable_id, :feature_id)
-
-      existing_lookup = Set.new(existing_assignments)
-      
-      if action == :enable
-        rows = []
-
-        assignables.each do |assignable|
-          features.each do |feature|
-            key = [assignable.id, feature.id]
-            next if existing_lookup.include?(key)
-
-            rows << {
-              assignable_id: assignable.id,
-              assignable_type: assignable.class.name,
-              feature_id: feature.id
-            }
-          end
-        end
+      enable_flow(assignables, features, identifiers) if action == :enable
+      disable_flow(assignables, features, identifiers) if action == :disable
+    end
 
-        begin
-          Togglefy::FeatureAssignment.insert_all(rows) if rows.any?
-        rescue => error
-          raise Togglefy::BulkToggleFailed.new(
-            "Bulk toggle enable failed for #{klass.name} with identifiers #{identifiers.inspect}",
-            error
-          )
-        end
-      elsif action == :disable
-        ids_to_remove = []
-        assignables.each do |assignable|
-          features.each do |feature|
-            key = [assignable.id, feature.id]
-            ids_to_remove << key if existing_lookup.include?(key)
-          end
-        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
 
-        begin
-          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
-          end
-        rescue => error
-          raise Togglefy::BulkToggleFailed.new(
-            "Bulk toggle disable failed for #{klass.name} with identifiers #{identifiers.inspect}",
-            error
-          )
-        end
-      end
+      raise Togglefy::FeatureNotFound if features.empty?
+
+      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
+
+      raise Togglefy::AssignablesNotFound, klass if assignables.empty?
+
+      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 = []
+
+      assignables.each do |assignable|
+        features.each do |feature|
+          rows << { assignable_id: assignable.id, assignable_type: assignable.class.name, feature_id: feature.id }
+        end
+      end
+
+      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)
+      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}",
+        e
+      )
+    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 = []
+
+      assignables.each do |assignable|
+        features.each do |feature|
+          ids_to_remove << [assignable.id, feature.id]
+        end
+      end
+
+      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)
+      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(
+        "Bulk toggle disable failed for #{klass.name} with identifiers #{identifiers.inspect}",
+        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.1.1"
+  # The VERSION constant defines the current version of the Togglefy gem.
+  VERSION = "1.2.1"
 end

data/lib/togglefy.rb

@@ -8,105 +8,250 @@ require "togglefy/feature_assignable_manager"
 require "togglefy/feature_manager"
 require "togglefy/feature_query"
 require "togglefy/scoped_bulk_wrapper"
-require "togglefy/exceptions"
+require "togglefy/errors"
 
+# The Togglefy module provides a feature management system.
+# It includes methods for querying, creating, updating, toggling, and managing features.
+# It also provides a way to manage features for assignable objects.
+#
+# == Features
+#
+# The Togglefy module provides a variety of features, including:
+#
+# - Querying features by type, group, environment, tenant, and custom filters
+# - Creating, updating, and deleting features
+# - Managing features for Assignables
+#
+# For more detailed information on each method,
+# please refer to the {file:README.md README}, individual method documentation in this file or the usage documentation.
+#
+# == Usage
+#
+# Main usage for this always starts with the {Togglefy} module.
+#
+# Below are a few examples on how to use Togglefy:
+#
+# === Examples
+#
+# - +Togglefy.feature(:super_powers)+
+# - +Togglefy.for_type(User)+
+# - +Togglefy.for_group(group)+
+# - +Togglefy.for_filters(filters: {group: :admin})+
+# - +Togglefy.with_status(:active)+
+# - +Togglefy.create(name: "Feature Name", identifier: :feature_name, description: "Feature description")+
+# - +Togglefy.update(:feature_name, name: "Updated Feature Name")+
+# - +Togglefy.destroy(:feature_name)+
+# - +Togglefy.toggle(:feature_name)+
+# - +Togglefy.inactive!(:feature_name)+
+# - +Togglefy.for(assignable).enable(:feature_name)+
+# - +Togglefy.for(assignable).has?(:feature_name)+
+# - +Togglefy.mass_for(Assignable).bulk.enable(:feature_name)+
+# - +Togglefy.mass_for(Assignable).bulk.enable(:feature_name, percentage: 35)+
+# - +Togglefy.mass_for(Assignable).bulk.disable([:feature_name, :another_feature])+
+#
+# == Aliases
+#
+# The following aliases are available for convenience:
+#
+# - +for_role+ is an alias for +for_group+
+# - +without_role+ is an alias for +without_group+
+# - +for_env+ is an alias for +for_environment+
+# - +without_env+ is an alias for +without_environment+
+# - +create_feature+ is an alias for +create+
+# - +update_feature+ is an alias for +update+
+# - +toggle_feature+ is an alias for +toggle+
+# - +activate_feature+ is an alias for +active!+
+# - +inactivate_feature+ is an alias for +inactive!+
+# - +destroy_feature+ is an alias for +destroy+
+#
 module Togglefy
-  class Error < StandardError; end
-
-  # FeatureQuery
+  # Returns all features.
+  # @return [Array] List of all features.
   def self.features
     FeatureQuery.new.features
   end
 
+  # Finds a feature by its identifier.
+  # @param identifier [String, Symbol] The unique identifier of the feature.
+  # @return [Feature] The feature object.
+  # @raise [Togglefy::FeatureNotFound] If the feature is not found by the identifier.
   def self.feature(identifier)
     FeatureQuery.new.feature(identifier)
+  rescue ActiveRecord::RecordNotFound
+    raise Togglefy::FeatureNotFound, "Couldn't find Togglefy::Feature with identifier '#{identifier}'"
   end
-  
+
+  # Queries features for a specific type.
+  # @param klass [Class] The class type to filter features by.
+  # @return [Array] List of features for the given type.
   def self.for_type(klass)
     FeatureQuery.new.for_type(klass)
   end
-  
+
+  # Queries features for a specific group.
+  # @param group [String, Symbol] The group name to filter features by.
+  # @return [Array] List of features for the given group.
   def self.for_group(group)
     FeatureQuery.new.for_group(group)
   end
 
+  # Queries features without a group.
+  # @return [Array] List of features without a group.
   def self.without_group
     FeatureQuery.new.without_group
   end
 
+  # Queries features for a specific environment.
+  # @param environment [String, Symbol] The environment name to filter features by.
+  # @return [Array] List of features for the given environment.
   def self.for_environment(environment)
     FeatureQuery.new.for_environment(environment)
   end
 
+  # Queries features without an environment.
+  # @return [Array] List of features without an environment.
   def self.without_environment
     FeatureQuery.new.without_environment
   end
 
+  # Queries features for a specific tenant.
+  # @param tenant_id [String] The tenant ID to filter features by.
+  # @return [Array] List of features for the given tenant.
   def self.for_tenant(tenant_id)
     FeatureQuery.new.for_tenant(tenant_id)
   end
 
+  # Queries features without a tenant.
+  # @return [Array] List of features without a tenant.
   def self.without_tenant
     FeatureQuery.new.without_tenant
   end
 
+  # Queries features based on custom filters.
+  # @param filters [Hash] A hash of filters to apply.
+  # @return [Array] List of features matching the filters.
   def self.for_filters(filters: {})
     FeatureQuery.new.for_filters(filters)
   end
 
+  # Queries features by their status.
+  # @param status [String, Symbol, Integer] The status to filter features by.
+  # @return [Array] List of features with the given status.
   def self.with_status(status)
     FeatureQuery.new.with_status(status)
   end
 
-  # FeatureManager
+  # Creates a new feature.
+  # @note All parameters are optional, except for the name. If sent, it should be a keyword argument.
+  #
+  # @param name [String] The name of the feature.
+  # @param identifier [Symbol, String, nil] The unique identifier for the feature. Optional, it can also be nil or blank
+  # @param description [String] A description of the feature.
+  # @param group [String, Symbol, nil] The group the feature belongs to.
+  # @param environment [String, Symbol, nil] The environment the feature is for.
+  # @param tenant_id [String] The tenant ID the feature is for.
+  # @param status [String, Symbol, Integer] The status of the feature.
+  # @return [Feature] The created feature.
+  # @example
+  #   Togglefy.create(name: "New Feature", identifier: :new_feature, description: "A new feature")
+  #   Togglefy.create(name: "New Feature", identifier: nil, description: "A new feature", group: :admin)
+  #   Togglefy.create(name: "New Feature", description: "A new feature", environment: :production, tenant_id: "123abc")
   def self.create(**params)
     FeatureManager.new.create(**params)
   end
 
+  # Updates an existing feature.
+  # @note All parameters but the first (identifier) should be keyword arguments.
+  #
+  # @param identifier [Symbol, String] The unique identifier of the feature.
+  # @param name [String] The name of the feature.
+  # @param identifier [Symbol, String, nil] The unique identifier for the feature. Optional, it can also be nil or blank
+  # @param description [String] A description of the feature.
+  # @param group [String, Symbol, nil] The group the feature belongs to.
+  # @param environment [String, Symbol, nil] The environment the feature is for.
+  # @param tenant_id [String] The tenant ID the feature is for.
+  # @param status [String, Symbol, Integer] The status of the feature.
+  # @return [Feature] The updated feature.
+  # @raise [Togglefy::FeatureNotFound] If the feature is not found by the identifier.
+  # @example
+  #   Togglefy.update(:new_feature, name: "Updated Feature", description: "Updated feature description")
+  #   Togglefy.update(:new_feature, identifier: :updated_feature, group: :support)
+  #   Togglefy.update(:new_feature, environment: :staging, tenant_id: "abc123")
   def self.update(identifier, **params)
     FeatureManager.new(identifier).update(**params)
+  rescue ActiveRecord::RecordNotFound
+    raise Togglefy::FeatureNotFound, "Couldn't find Togglefy::Feature with identifier '#{identifier}'"
   end
 
+  # Deletes a feature.
+  # @param identifier [Symbol, String] The unique identifier of the feature.
+  # @return [boolean] True if the feature was deleted, false otherwise.
+  # @raise [Togglefy::FeatureNotFound] If the feature is not found by the identifier.
   def self.destroy(identifier)
     FeatureManager.new(identifier).destroy
+  rescue ActiveRecord::RecordNotFound
+    raise Togglefy::FeatureNotFound, "Couldn't find Togglefy::Feature with identifier '#{identifier}'"
   end
 
+  # Toggles the status of a feature.
+  # @param identifier [Symbol, String] The unique identifier of the feature.
+  # @return [boolean] True if the feature was toggled, false otherwise.
+  # @raise [Togglefy::FeatureNotFound] If the feature is not found by the identifier.
   def self.toggle(identifier)
     FeatureManager.new(identifier).toggle
+  rescue ActiveRecord::RecordNotFound
+    raise Togglefy::FeatureNotFound, "Couldn't find Togglefy::Feature with identifier '#{identifier}'"
   end
 
+  # Activates a feature.
+  # @param identifier [Symbol, String] The unique identifier of the feature.
+  # @return [boolean] True if the feature was activated, false otherwise.
+  # @raise [Togglefy::FeatureNotFound] If the feature is not found by the identifier.
   def self.active!(identifier)
     FeatureManager.new(identifier).active!
+  rescue ActiveRecord::RecordNotFound
+    raise Togglefy::FeatureNotFound, "Couldn't find Togglefy::Feature with identifier '#{identifier}'"
   end
 
+  # Deactivates a feature.
+  # @param identifier [Symbol, String] The unique identifier of the feature.
+  # @return [boolean] True if the feature was inactivated, false otherwise.
+  # @raise [Togglefy::FeatureNotFound] If the feature is not found by the identifier.
   def self.inactive!(identifier)
     FeatureManager.new(identifier).inactive!
+  rescue ActiveRecord::RecordNotFound
+    raise Togglefy::FeatureNotFound, "Couldn't find Togglefy::Feature with identifier '#{identifier}'"
   end
 
-  # FeatureAssignableManager
+  # Manages features for a specific assignable object.
+  # @param assignable [Object] The assignable object.
+  # @return [FeatureAssignableManager] The manager for the assignable object.
   def self.for(assignable)
     FeatureAssignableManager.new(assignable)
   end
 
-  # ScopedBulkWrapper
+  # Provides bulk management for a specific class.
+  # @param klass [Class] The class to manage features for.
+  # @return [ScopedBulkWrapper] The bulk wrapper for the class.
   def self.mass_for(klass)
     Togglefy::ScopedBulkWrapper.new(klass)
   end
 
-  class <<self
-    # FeatureQuery
-    alias_method :for_role, :for_group
-    alias_method :without_role, :without_group
+  class << self
+    # Aliases for group-related Features.
+    alias for_role for_group
+    alias without_role without_group
 
-    alias_method :for_env, :for_environment
-    alias_method :without_env, :without_environment
+    # Aliases for environment-related Features.
+    alias for_env for_environment
+    alias without_env without_environment
 
-    # FeatureManager
-    alias_method :create_feature, :create
-    alias_method :update_feature, :update
-    alias_method :toggle_feature, :toggle
-    alias_method :activate_feature, :active!
-    alias_method :inactivate_feature, :inactive!
-    alias_method :destroy_feature, :destroy
+    # Aliases for feature management Features.
+    alias create_feature create
+    alias update_feature update
+    alias toggle_feature toggle
+    alias activate_feature active!
+    alias inactivate_feature inactive!
+    alias destroy_feature destroy
   end
 end

data/togglefy.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.name = "togglefy"
   spec.version = Togglefy::VERSION
   spec.authors = ["Gabriel Azevedo"]
-  spec.email = ["gazeveco@gmail.com"]
+  spec.email = ["gabriel@azeveco.com"]
 
   spec.summary = "Simple and open source Feature Management."
   spec.description = "Togglefy is a feature management Rails gem to help you control which features an user or a group has access to."
@@ -19,16 +19,26 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/azeveco/Togglefy"
   spec.metadata["changelog_uri"] = "https://github.com/azeveco/Togglefy/releases"
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/azeveco/Togglefy/issues'
+  spec.metadata['documentation_uri'] = 'https://rubydoc.info/github/azeveco/Togglefy'
 
   # 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.
-  gemspec = File.basename(__FILE__)
+  File.basename(__FILE__)
   spec.files = Dir.glob("lib/**/*") +
-             Dir.glob("app/**/*") +
-             Dir.glob("config/**/*") +
-             %w[LICENSE.txt README.md togglefy.gemspec]
+               Dir.glob("app/**/*") +
+               Dir.glob("config/**/*") +
+               %w[LICENSE README.md Rakefile togglefy.gemspec]
 
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bootsnap", "~> 1.17"
+  spec.add_development_dependency "database_cleaner-active_record", "~> 2.1"
+  spec.add_development_dependency "rails", "~> 8.0.2"
+  spec.add_development_dependency "rspec-rails", "~> 7.1.1"
+  spec.add_development_dependency "sqlite3", "~> 2.1"
+  spec.add_development_dependency "yard", "~> 0.9.37"
+  spec.add_development_dependency "redcarpet", "~> 3.6"
 end