togglefy 1.2.0 → 1.2.1

data/lib/togglefy.rb

@@ -8,100 +8,245 @@ 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
+    # Aliases for group-related Features.
     alias for_role for_group
     alias without_role without_group
 
+    # Aliases for environment-related Features.
     alias for_env for_environment
     alias without_env without_environment
 
-    # FeatureManager
+    # Aliases for feature management Features.
     alias create_feature create
     alias update_feature update
     alias toggle_feature toggle

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,6 +19,8 @@ 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.
@@ -26,7 +28,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.glob("lib/**/*") +
                Dir.glob("app/**/*") +
                Dir.glob("config/**/*") +
-               %w[LICENSE.txt README.md Rakefile togglefy.gemspec]
+               %w[LICENSE README.md Rakefile togglefy.gemspec]
 
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
@@ -37,4 +39,6 @@ Gem::Specification.new do |spec|
   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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: togglefy
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Gabriel Azevedo
 bindir: exe
 cert_chain: []
-date: 2025-04-29 00:00:00.000000000 Z
+date: 2025-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bootsnap
@@ -79,15 +79,43 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
 description: Togglefy is a feature management Rails gem to help you control which
   features an user or a group has access to.
 email:
-- gazeveco@gmail.com
+- gabriel@azeveco.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
 - app/models/togglefy/feature.rb
@@ -95,16 +123,18 @@ files:
 - lib/generators/togglefy/install_generator.rb
 - lib/generators/togglefy/templates/create_feature_assignments.rb
 - lib/generators/togglefy/templates/create_features.rb
+- lib/generators/togglefy/templates/older_rails_create_feature_assignments.rb
+- lib/generators/togglefy/templates/older_rails_create_features.rb
 - lib/togglefy.rb
 - lib/togglefy/assignable.rb
 - lib/togglefy/engine.rb
+- lib/togglefy/errors.rb
 - lib/togglefy/errors/assignables_not_found.rb
 - lib/togglefy/errors/bulk_toggle_failed.rb
 - lib/togglefy/errors/dependency_missing.rb
 - lib/togglefy/errors/error.rb
 - lib/togglefy/errors/feature_not_found.rb
 - lib/togglefy/errors/invalid_feature_attribute.rb
-- lib/togglefy/exceptions.rb
 - lib/togglefy/feature_assignable_manager.rb
 - lib/togglefy/feature_manager.rb
 - lib/togglefy/feature_query.rb
@@ -120,6 +150,8 @@ metadata:
   homepage_uri: https://github.com/azeveco/Togglefy
   source_code_uri: https://github.com/azeveco/Togglefy
   changelog_uri: https://github.com/azeveco/Togglefy/releases
+  bug_tracker_uri: https://github.com/azeveco/Togglefy/issues
+  documentation_uri: https://rubydoc.info/github/azeveco/Togglefy
 rdoc_options: []
 require_paths:
 - lib

data/lib/togglefy/exceptions.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-require "togglefy/errors/error"
-
-require "togglefy/errors/feature_not_found"
-require "togglefy/errors/assignables_not_found"
-require "togglefy/errors/bulk_toggle_failed"