togglefy 1.1.1 → 1.2.1

data/lib/togglefy/assignable.rb

@@ -1,48 +1,75 @@
+# frozen_string_literal: true
+
 require "active_support/concern"
 
 module Togglefy
+  # The Assignable module provides functionality for models to relate with features.
+  # It includes methods to add, remove, and query features, as well as ActiveRecord scopes.
   module Assignable
     extend ActiveSupport::Concern
 
     included do
+      # Establishes a many-to-many relationship with features through feature assignments.
       has_many :feature_assignments, as: :assignable, class_name: "Togglefy::FeatureAssignment"
       has_many :features, through: :feature_assignments, class_name: "Togglefy::Feature"
 
-      scope :with_features, ->(feature_ids) {
+      # Scope to retrieve assignables with specific features.
+      #
+      # @param feature_ids [Array<Integer>] The IDs of the features to filter by.
+      scope :with_features, lambda { |feature_ids|
         joins(:feature_assignments)
-        .where(feature_assignments: {
-          feature_id: feature_ids
-        })
-        .distinct
+          .where(feature_assignments: {
+                   feature_id: feature_ids
+                 })
+          .distinct
       }
 
-      scope :without_features, ->(feature_ids) {
+      # Scope to retrieve assignables without specific features.
+      #
+      # @param feature_ids [Array<Integer>] The IDs of the features to filter by.
+      scope :without_features, lambda { |feature_ids|
         joins(left_join_on_features(feature_ids))
           .where("fa.id IS NULL")
           .distinct
       }
     end
 
-    def has_feature?(identifier)
-      features.exists?(identifier: identifier.to_s)
+    # Checks if the assignable has a specific feature.
+    #
+    # @param identifier [Symbol, String] The identifier of the feature.
+    # @return [Boolean] True if the feature exists, false otherwise.
+    def feature?(identifier)
+      features.active.exists?(identifier: identifier.to_s)
     end
+    alias has_feature? feature?
 
+    # Adds a feature to the assignable.
+    #
+    # @param feature [Togglefy::Feature, String] The feature or its identifier.
     def add_feature(feature)
       feature = find_feature!(feature)
       features << feature unless has_feature?(feature.identifier)
     end
 
+    # Removes a feature from the assignable.
+    #
+    # @param feature [Togglefy::Feature, String] The feature or its identifier.
     def remove_feature(feature)
       feature = find_feature!(feature)
       features.destroy(feature) if has_feature?(feature.identifier)
     end
 
+    # Clears all features from the assignable.
     def clear_features
       features.destroy_all
     end
 
     private
 
+    # Finds a feature by its identifier or returns the feature if already provided.
+    #
+    # @param feature [Togglefy::Feature, String] The feature or its identifier.
+    # @return [Togglefy::Feature] The found feature.
     def find_feature!(feature)
       return feature if feature.is_a?(Togglefy::Feature)
 
@@ -50,9 +77,13 @@ module Togglefy
     end
 
     class_methods do
+      # Generates a SQL LEFT JOIN clause for features.
+      #
+      # @param feature_ids [Array<Integer>] The IDs of the features to join on.
+      # @return [String] The SQL LEFT JOIN clause.
       def left_join_on_features(feature_ids)
-        table = self.table_name
-        type = self.name
+        table = table_name
+        type = name
 
         <<~SQL.squish
           LEFT JOIN togglefy_feature_assignments fa
@@ -63,4 +94,4 @@ module Togglefy
       end
     end
   end
-end
+end

data/lib/togglefy/engine.rb

@@ -1,5 +1,9 @@
+# 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
-end
+end

data/lib/togglefy/errors/assignables_not_found.rb

@@ -1,7 +1,14 @@
+# 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
   end
-end
+end

data/lib/togglefy/errors/bulk_toggle_failed.rb

@@ -1,11 +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
+end

data/lib/togglefy/errors/dependency_missing.rb

@@ -1,7 +1,15 @@
+# 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
   end
-end
+end

data/lib/togglefy/errors/error.rb

@@ -1,3 +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
+end

data/lib/togglefy/errors/feature_not_found.rb

@@ -1,7 +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
+end

data/lib/togglefy/errors/invalid_feature_attribute.rb

@@ -1,7 +1,14 @@
+# 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
   end
-end
+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,30 +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,41 +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
+end

data/lib/togglefy/feature_query.rb

@@ -1,64 +1,118 @@
+# 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,
+      role: :for_group,
+      environment: :for_environment,
+      env: :for_environment,
+      tenant_id: :for_tenant,
+      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)
-      Togglefy::Feature
-        .then { |q| safe_chain(q, :identifier, filters[:identifier], apply_if: filters.key?(:identifier)) }
-        .then { |q| safe_chain(q, :for_group, filters[:group] || filters[:role], apply_if: filters.key?(:group) || filters.key?(:role)) }
-        .then { |q| safe_chain(q, :for_environment, filters[:environment] || filters[:env], apply_if: filters.key?(:environment) || filters.key?(:env)) }
-        .then { |q| safe_chain(q, :for_tenant, filters[:tenant_id], apply_if: filters.key?(:tenant_id)) }
-        .then { |q| safe_chain(q, :with_status, filters[:status], apply_if: filters.key?(:status)) }
-    end
-    
-    private
+      FILTERS.reduce(Togglefy::Feature) do |query, (key, scope)|
+        value = filters[key]
+        next query unless filters.key?(key) && nil_or_not_blank?(value)
 
-    def safe_chain(query, method, value, apply_if: true)
-      apply_if && nil_or_not_blank?(value) ? query.public_send(method, value) : query
+        query.public_send(scope, value)
+      end
     end
 
+    private
+
+    # 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
   end
-end
+end

data/lib/togglefy/featureable.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
 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
+end

data/lib/togglefy/scoped_bulk_wrapper.rb

@@ -1,13 +1,23 @@
+# frozen_string_literal: true
+
 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
   end
-end
+end