togglefy 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f78d7324689b7cacb720114af6d9ef3a8f472f8da8a572860855a77b32cdea7
-  data.tar.gz: a1861e9b87081fdce869358ad64d7bf9b653296d79363fe3765aab1947929a09
+  metadata.gz: 48668b30d043e271706d2264cba4c2ff6917bd36bc11aed4e8aee24aa9431917
+  data.tar.gz: f1d0543de69758fb5ef769b5b509901d4b9d1ae263d5f362489c7e099b0bc840
 SHA512:
-  metadata.gz: 2cf79e274cea2c678f2b1719f7a570b1ed428dca4570dac9d30c7207396c71bd38fd45a77111c04a3f6b66e7845a1f9d4b61b72607e6713920024117a547592d
-  data.tar.gz: c383ec661ba05a10a9dbb9c0fd8b4ac46c27aeb71fa0371193674bf26a4fcaee43ea8684ffe73cac1ed1e92300b3c5f7c55b6949d1160de3a2b73c06a5610eec
+  metadata.gz: e9ef4ce6770dc88b80b9a4a27b3ce4b43cfa8484b4115f6c6e1451065721e248f0fd0464b881c6edfacfa57f93dae213e10157910b4fc44bc93aa06f4aa3a724
+  data.tar.gz: 8181535e9663feb971707ac2d6806020c13e15745fc647508da0d0f578f57cb298fdd98927b90e525837c37b7f7ec5249d1eaab0eb5be580dd068d39e7a19f23

data/README.md

@@ -1,5 +1,8 @@
 # Togglefy
 
+![Gem](https://img.shields.io/gem/v/togglefy)
+![Downloads](https://img.shields.io/gem/dt/togglefy)
+
 Togglefy is a simple feature management solution to help you control which features an user or a group has access to.
 
 Togglefy is free, open source and you are welcome to help build it.
@@ -9,7 +12,7 @@ Togglefy is free, open source and you are welcome to help build it.
 Add the gem manually to your Gemfile:
 
 ```gemfile
-gem 'togglefy', '~> 1.0', '>= 1.0.1'
+gem 'togglefy', '~> 1.0', '>= 1.1.0'
 ```
 
 Or install it and add to the application's Gemfile by executing:
@@ -34,7 +37,37 @@ After adding the gem to your project, you need to run the generate command to ad
 rails generate togglefy:install
 ```
 
-This command will create the migrations to create the tables inside your project. Please, don't remove/change anything that's there or Togglefy may not work as expected.
+This command will create the migrations to create the tables inside your project.
+
+If you use an older version of Rails (< 5), then the migration files don't need you to specify the version.
+
+To fix this, you will have to manually go to the two migration files of Togglefy: `create_feature` and `create_feature_assignments` and do the following:
+
+Change these lines from this:
+
+```ruby
+rails_version = "#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"
+
+class CreateTogglefyFeatures < ActiveRecord::Migration[rails_version]
+```
+
+```ruby
+rails_version = "#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"
+
+class CreateTogglefyFeatureAssignments < ActiveRecord::Migration[rails_version]
+```
+
+To this:
+
+```ruby
+class CreateTogglefyFeatures < ActiveRecord::Migration
+```
+
+```ruby
+class CreateTogglefyFeatureAssignments < ActiveRecord::Migration
+```
+
+Please, don't remove/change anything else that's there or Togglefy may not work as expected.
 
 Run the migration to create these in your datase:
 ```bash
@@ -55,14 +88,18 @@ After that, the next steps are also pretty simple.
 
 Add the following to your model that will have a relation with the features. It can be an `User`, `Account` or something you decide:
 ```ruby
-include Togglefy::Featureable
+include Togglefy::Assignable
 ```
 
-This will add the relationship between Togglefy's models and yours. Yours will be referred to as **assignable** throughout this documentation. If you want to check it in the source code, you can find it here: `lib/togglefy/featureable.rb` inside de `included` block.
+This will add the relationship between Togglefy's models and yours. Yours will be referred to as **assignable** throughout this documentation. If you want to check it in the source code, you can find it here: `lib/togglefy/assignable.rb` inside de `included` block.
+
+Older versions (`<= 1.0.2`) had the `Featureable` instead of the `Assignable`. The `Featureable` is now deprecated. You can still use it and it won't impact old users, but we highly recommend you to use the `Assignable` as it is semantically more accurate about what it does.
 
 With that, everything is ready to use **Togglefy**, welcome!
 
-### Creating Features
+### Managing Features
+
+#### Creating Features
 To create features it's as simple as drinking a nice cold beer after a hard day or drinking the entire bottle of coffee in a span of 1 hour:
 
 ```ruby
@@ -84,6 +121,24 @@ Togglefy::Feature.create(
 )
 ```
 
+You can also use:
+
+```ruby
+Togglefy.create(
+  name: "Teleportation",
+  description: "Allows the assignable to teleport to anywhere",
+  group: :jumper
+)
+
+# Or
+
+Togglefy.create_feature(
+  name: "Teleportation",
+  description: "Allows the assignable to teleport to anywhere",
+  group: :jumper
+)
+```
+
 You don't have to fill all fields, the only one that is mandatory is the name, because is by using the name that we will create the unique identifier, which is the field we'll use to find, delete and more.
 
 The identifier is the name, downcased and snake_cased 🐍
@@ -97,17 +152,60 @@ identifier: "super_powers",
 description: "With great power comes great responsibility",
 created_at: "2025-04-12 01:39:10.176561000 +0000",
 updated_at: "2025-04-12 01:39:46.818928000 +0000",
-tenant: "123abc",
+tenant_id: "123abc",
 group: "admin",
 environment: "production",
 status: "inactive"
 ```
 
+#### Updating a Feature
+
+To update a feature is as simple as riding on a monocycle while balancing a cup of water on the top of a really tall person that's on your shoulders.
+
+Here's how you can do it:
+
+```ruby
+Togglefy.update(:super_powers, tenant_id: "abc123")
+Togglefy.update_feature(:super_powers, tenant_id: "abc123")
+```
+
+Or by finding the feature manually and then updating it like you always do with Rails:
+
+```ruby
+feature = Togglefy::Feature.find_by(identifier: :super_powers)
+# or
+feature = Togglefy.feature(:super_powers) # This is explained more in the "Finding a specific feature" section of this README
+
+feature.update(tenant_id: "123abc")
+```
+
+#### Destroying Features
+
+It looks like you're mean 😈
+
+So here's how you can destroy a feature:
+
+```ruby
+Togglefy.destroy(:super_powers)
+Togglefy.destroy_feature(:super_powers)
+Togglefy::Feature.identifier(:super_powers).destroy
+Togglefy::Feature.find_by(identifier: :super_powers).destroy
+```
+
+#### Toggle Features
+
+You can toggle a feature status to active or inactive by doing this:
+
+```ruby
+Togglefy.toggle(:super_powers)
+Togglefy.toggle_feature(:super_powers)
+```
+
 #### About `Togglefy::Feature` status
 
 As you can see, the `Togglefy::Feature` also has a status and it is default to `inactive`. You can change this during creation.
 
-The status holds the `inactive` or `active` values. This status is not to define if a assignable (any model that has the `include Togglefy::Featureable`) either has ou hasn't a feature, but to decide if this feature is available in the entire system.
+The status holds the `inactive` or `active` values. This status is not to define if a assignable (any model that has the `include Togglefy::Assignable`) either has ou hasn't a feature, but to decide if this feature is available in the entire system.
 
 It's up to you to define how you will implement it.
 
@@ -121,14 +219,21 @@ You can change the status by:
 * Updating the column
 * Doing a:
   ```ruby
-  feature.active! # To activate
-  feature.inactive! # To inactivate
+  Togglefy::Feature.find_by(identifier: :super_powers).active!
+  Togglefy.feature(:super_powers).active!
+  Togglefy.active!(:super_powers)
+  Togglefy.activate_feature(:super_powers)
+
+  Togglefy::Feature.find_by(identifier: :super_powers).inactive!
+  Togglefy.feature(:super_powers).inactive!
+  Togglefy.inactive!(:super_powers)
+  Togglefy.inactivate_feature(:super_powers)
   ```
 
 ### Managing Assignables <-> Features
 Now that we know how to create features, let's check how we can manage them.
 
-An assignable has some direct methods thanks to the `include Togglefy::Featureable`, which are (and let's use an user as an example of an assignable):
+An assignable has some direct methods thanks to the `include Togglefy::Assignable`, which are (and let's use an user as an example of an assignable):
 
 ```ruby
 user.has_feature?(:super_powers) # Checks if user has a single feature
@@ -139,7 +244,7 @@ user.clear_features # Clears all features from an user
 
 The assignable <-> feature relation is held by the `Togglefy::FeatureAssignment` table/model.
 
-But there's another way to manage assignables <-> features by using the `FeatureManager`. It's up to you to decide which one.
+But there's another way to manage assignables <-> features by using the `FeatureAssignableManager`. It's up to you to decide which one.
 
 Here are the examples:
 
@@ -150,8 +255,59 @@ Togglefy.for(assignable).disable(:super_powers) # Disables/removes a feature fro
 Togglefy.for(assignable).clear # Clears all features from an assignable
 ```
 
+You can also supercharge it by chaining methods, like:
+
+```ruby
+# Instead of doing this:
+Togglefy.for(assignable).disable(:alpha_access)
+Togglefy.for(assignable).enable(:beta_access)
+
+# You can go something like this:
+Togglefy.for(assignable).disable(:alpha_access).enable(:beta_access)
+```
+
 This second method may look strange, but it's the default used by the gem and you will see that right now!
 
+#### Mass Enable/Disable of Features to/from Assignables
+You can mass enable/disable features to/from Assignables.
+
+Doing that is simple! Let's assume that your assignable is an User model.
+
+```ruby
+Togglefy.mass_for(User).bulk.enable(:super_powers) # To enable a specific feature to all users
+Togglefy.mass_for(User).bulk.enable([:super_powers, :magic, ...]) # To enable two or more features to all users
+Togglefy.mass_for(User).bulk.enable(:super_powers, percentage: 20) # To enable a feature to 20% of all users
+Togglefy.mass_for(User).bulk.enable([:super_powers, :magic, ...], percentage: 50) # To enable two or more features to 50% of all users
+```
+
+The same applies to the disable:
+
+```ruby
+Togglefy.mass_for(User).bulk.disable(:super_powers) # To disable a specific feature to all users
+Togglefy.mass_for(User).bulk.disable([:super_powers, :magic, ...]) # To disable two or more features to all users
+Togglefy.mass_for(User).bulk.disable(:super_powers, percentage: 5) # To disable a feature to 5% of all users
+Togglefy.mass_for(User).bulk.disable([:super_powers, :magic, ...], percentage: 75) # To disable two or more features to 75% of all users
+```
+
+There are a few things to pay attention:
+* Whenever you do a enable/disable, it will only query for valid assignables, so:
+  * If you do a enable, it will query all assignables that don't have the feature(s) enabled
+  * If you do a disable, it will query all assignables that do already have the feature(s) enabled
+* You can also use filters for:
+  * `group || role`
+  * `environment || env`
+  * `tenant_id`
+  * You can check about filters aliases at [Aliases table](#aliases-table)
+
+These will be applied to query features that match the identifiers + the filters sent.
+
+So it would be something like:
+
+```ruby
+Togglefy.mass_for(User).bulk.enable(:super_powers, group: :admin, percentage: 20)
+Togglefy.mass_for(User).bulk.disable(:magic, group: :dev, env: :production, percentage: 75)
+```
+
 ### Querying Features
 Remember when I told you a looooong time ago that the strange way is the default using by the gem? If you don't, no worries. It was a really loooong time ago, like `1.minute.ago`.
 
@@ -178,12 +334,28 @@ Togglefy.for_filters(filters: {group: :admin, environment: :production})
 
 This will query me all `Togglefy::Feature`s that belongs to group admin and the production environment.
 
+The `Togglefy.for_filters` can have the following filters:
+
+```ruby
+filters: {
+  group:,
+  role:, # Acts as a group, explained in the Aliases section
+  environment:,
+  env:, # Acts as a group, explained in the Aliases section
+  tenant_id:,
+  status:,
+  identifier:
+}
+```
+
+The `Togglefy.for_filters` will only apply the filters sent that are `nil` or `!value.blank?`.
+
 You can send `nil` values too, like:
 
 ```ruby
 Togglefy.for_tenant(nil) # This will query me all Togglefy::Features with tenant_id nil
 
-Togglefy.for_filters(filters: {group: :admin, environment: :nil, tenant_id: nil})
+Togglefy.for_filters(filters: {group: :admin, environment: nil, tenant_id: nil})
 ```
 
 There's also another way to filter for `nil` values:
@@ -210,13 +382,39 @@ Togglefy.with_status(:active)
 #### Finding a specific feature
 ```ruby
 Togglefy.feature(:super_powers)
+Togglefy::Feature.identifier(:super_powers)
 Togglefy::Feature.find_by(identifier: :super_powers)
 ```
 
-#### Finding a specific feature just to destroy it because you're mean 😈
+#### Finding multiple features
 ```ruby
-Togglefy.destroy_feature(:super_powers)
-Togglefy::Feature.find_by(identifier: :super_powers).destroy
+Togglefy.feature([:super_powers, :magic])
+Togglefy::Feature.identifier([:super_powers, :magic])
+Togglefy::Feature.where(identifier: [:super_powers, :magic])
+```
+
+#### List all features of an Assignable
+Let's pretend that your assignable is an User.
+
+```ruby
+user = User.find(1)
+user.features
+```
+
+#### Check all features an Assignable have/doesn't have
+Again, let's pretend that your assignable is an User. This is the only case you need to send the feature id and not the identifier.
+
+```ruby
+User.with_features(1)
+User.with_features([2, 3])
+User.without_features(1)
+User.without_features([2, 3])
+```
+
+#### Querying all features
+```ruby
+Togglefy.features(:super_powers)
+Togglefy::Feature.all
 ```
 
 #### Querying all features enabled to a klass
@@ -225,7 +423,7 @@ Let's assume that you have two different assignables: User and Account.
 You want to list all features being used by assignables of User type:
 
 ```ruby
-Togglefy.for_type(User) # This is return all current FeatureAssignment with a User assignable
+Togglefy.for_type(User) # This returns all current FeatureAssignment with a User assignable
 ```
 
 #### Aliases
@@ -248,17 +446,39 @@ Togglefy.for_filters(filters: {environment: :production})
 Togglefy.for_filters(filter: {env: :production})
 ```
 
+## Aliases table
+
+Here's a table of all aliases available on Togglefy.
+
+You can use either, as long as you respect the rules listed.
+
+| Original              | Alias                | Rules                                               |
+| --------------------- | -------------------- | --------------------------------------------------- |
+| `for_group`           | `for_role`           | Can't be used if doing a direct `Togglefy::Feature` |
+| `without_group`       | `without_role`       | Can't be used if doing a direct `Togglefy::Feature` |
+| `for_environment`     | `for_env`            | Can't be used if doing a direct `Togglefy::Feature` |
+| `without_environment` | `without_env`        | Can't be used if doing a direct `Togglefy::Feature` |
+| `group`         | `role`                | Used inside methods that receives filters |
+| `environment`         | `env`                | Used inside methods that receives filters |
+| `create`              | `create_feature`     | None                                                |
+| `update`              | `update_feature`     | None                                                |
+| `toggle`              | `toggle_feature`     | None                                                |
+| `active!`             | `activate_feature`   | None                                                |
+| `deactive!`           | `inactivate_feature` | None                                                |
+| `destroy`             | `destroy_feature`    | None                                                |
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/azeveco/togglefy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/azeveco/togglefy/blob/master/CODE_OF_CONDUCT.md).
 
-There's a PR Template. Its usa is highly encouraged.
+There's a PR Template. Its use is highly encouraged.
 
 ## License
 

data/app/models/togglefy/feature.rb

@@ -7,6 +7,8 @@ module Togglefy
 
     before_validation :build_identifier
 
+    scope :identifier, ->(identifier) { where(identifier:) }
+
     scope :for_group, ->(group) { where(group:) }
     scope :without_group, -> { where(group: nil) }
 

data/lib/generators/togglefy/templates/create_feature_assignments.rb

@@ -1,4 +1,8 @@
-class CreateTogglefyFeatureAssignments < ActiveRecord::Migration[8.0]
+# frozen_string_literal: true
+
+rails_version = "#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"
+
+class CreateTogglefyFeatureAssignments < ActiveRecord::Migration[rails_version]
   def change
     create_table :togglefy_feature_assignments do |t|
       t.references :feature, null: false, foreign_key: { to_table: :togglefy_features }

data/lib/generators/togglefy/templates/create_features.rb

@@ -1,4 +1,8 @@
-class CreateTogglefyFeatures < ActiveRecord::Migration[8.0]
+# frozen_string_literal: true
+
+rails_version = "#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"
+
+class CreateTogglefyFeatures < ActiveRecord::Migration[rails_version]
   def change
     create_table :togglefy_features do |t|
       t.string :name, null: false

data/lib/togglefy/assignable.rb

@@ -0,0 +1,66 @@
+require "active_support/concern"
+
+module Togglefy
+  module Assignable
+    extend ActiveSupport::Concern
+
+    included do
+      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) {
+        joins(:feature_assignments)
+        .where(feature_assignments: {
+          feature_id: feature_ids
+        })
+        .distinct
+      }
+
+      scope :without_features, ->(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)
+    end
+
+    def add_feature(feature)
+      feature = find_feature!(feature)
+      features << feature unless has_feature?(feature.identifier)
+    end
+
+    def remove_feature(feature)
+      feature = find_feature!(feature)
+      features.destroy(feature) if has_feature?(feature.identifier)
+    end
+
+    def clear_features
+      features.destroy_all
+    end
+
+    private
+
+    def find_feature!(feature)
+      return feature if feature.is_a?(Togglefy::Feature)
+
+      Togglefy::Feature.find_by!(identifier: feature.to_s)
+    end
+
+    class_methods do
+      def left_join_on_features(feature_ids)
+        table = self.table_name
+        type = self.name
+
+        <<~SQL.squish
+          LEFT JOIN togglefy_feature_assignments fa
+            ON fa.assignable_id = #{table}.id
+            AND fa.assignable_type = '#{type}'
+            AND fa.feature_id IN (#{Array(feature_ids).join(",")})
+        SQL
+      end
+    end
+  end
+end

data/lib/togglefy/errors/assignables_not_found.rb

@@ -0,0 +1,7 @@
+module Togglefy
+  class AssignablesNotFound < Togglefy::Error
+    def initialize(klass)
+      super("No #{klass.name} found matching features and filters sent")
+    end
+  end
+end

data/lib/togglefy/errors/bulk_toggle_failed.rb

@@ -0,0 +1,11 @@
+module Togglefy
+  class BulkToggleFailed < Togglefy::Error
+    def initialize(message = "Bulk toggle operation failed", cause = nil)
+      super(message)
+      set_backtrace(cause.backtrace) if cause
+      @cause = cause
+    end
+
+    attr_reader :cause
+  end
+end

data/lib/togglefy/errors/dependency_missing.rb

@@ -0,0 +1,7 @@
+module Togglefy
+  class DependencyMissing < Togglefy::Error
+    def initialize(feature, required)
+      super("Feature '#{feature}' is missing dependency: '#{required}'")
+    end
+  end
+end

data/lib/togglefy/errors/error.rb

@@ -0,0 +1,3 @@
+module Togglefy
+  class Error < StandardError; end
+end

data/lib/togglefy/errors/feature_not_found.rb

@@ -0,0 +1,7 @@
+module Togglefy
+  class FeatureNotFound < Togglefy::Error
+    def initialize
+      super("No features found matching features and/or filters sent")
+    end
+  end
+end

data/lib/togglefy/errors/invalid_feature_attribute.rb

@@ -0,0 +1,7 @@
+module Togglefy
+  class InvalidFeatureAttribute < Togglefy::Error
+    def initialize(attr)
+      super("The attribute '#{attr}' is not valid for Togglefy::Feature.")
+    end
+  end
+end

data/lib/togglefy/exceptions.rb

@@ -0,0 +1,5 @@
+require "togglefy/errors/error"
+
+require "togglefy/errors/feature_not_found"
+require "togglefy/errors/assignables_not_found"
+require "togglefy/errors/bulk_toggle_failed"

data/lib/togglefy/feature_assignable_manager.rb

@@ -0,0 +1,30 @@
+module Togglefy
+  class FeatureAssignableManager
+    def initialize(assignable)
+      @assignable = assignable
+    end
+
+    def enable(feature)
+      assignable.add_feature(feature)
+      self
+    end
+
+    def disable(feature)
+      assignable.remove_feature(feature)
+      self
+    end
+
+    def clear
+      assignable.clear_features
+      self
+    end
+
+    def has?(feature)
+      assignable.has_feature?(feature)
+    end
+
+    private
+
+    attr_reader :assignable
+  end
+end

data/lib/togglefy/feature_manager.rb

@@ -1,27 +1,41 @@
 module Togglefy
   class FeatureManager
-    def initialize(assignable)
-      @assignable = assignable
+    def initialize(identifier = nil)
+      @identifier = identifier unless identifier.nil?
     end
 
-    def enable(feature)
-      assignable.add_feature(feature)
+    def create(**params)
+      Togglefy::Feature.create!(**params)
     end
 
-    def disable(feature)
-      assignable.remove_feature(feature)
+    def update(**params)
+      feature.update!(**params)
     end
 
-    def clear
-      assignable.clear_features
+    def destroy
+      feature.destroy
     end
 
-    def has?(feature)
-      assignable.has_feature?(feature)
+    def toggle
+      return feature.inactive! if feature.active?
+
+      feature.active!
+    end
+
+    def active!
+      feature.active!
+    end
+
+    def inactive!
+      feature.inactive!
     end
 
     private
 
-    attr_reader :assignable
+    attr_reader :identifier
+
+    def feature
+      Togglefy::Feature.find_by!(identifier:)
+    end
   end
-end
+end

data/lib/togglefy/feature_query.rb

@@ -1,12 +1,13 @@
 module Togglefy
   class FeatureQuery
-    def feature(identifier)
-      Togglefy::Feature.find_by!(identifier:)
+    def features
+      Togglefy::Feature.all
     end
 
-    def destroy_feature(identifier)
-      feature = Togglefy::Feature.find_by!(identifier:)
-      feature&.destroy
+    def feature(identifier)
+      return Togglefy::Feature.identifier(identifier) if identifier.is_a?(Array)
+
+      Togglefy::Feature.find_by!(identifier:)
     end
 
     def for_type(klass)
@@ -16,22 +17,18 @@ module Togglefy
     def for_group(group)
       Togglefy::Feature.for_group(group)
     end
-    alias :for_role :for_group
 
     def without_group
       Togglefy::Feature.without_group
     end
-    alias :without_role :without_group
 
     def for_environment(environment)
       Togglefy::Feature.for_environment(environment)
     end
-    alias :for_env :for_environment
 
     def without_environment
       Togglefy::Feature.without_environment
     end
-    alias :without_env :without_environment
 
     def for_tenant(tenant_id)
       Togglefy::Feature.for_tenant(tenant_id)
@@ -41,15 +38,27 @@ module Togglefy
       Togglefy::Feature.without_tenant
     end
 
+    def with_status(status)
+      Togglefy::Feature.with_status(status)
+    end
+
     def for_filters(filters)
       Togglefy::Feature
-        .for_group(filters[:group] || filters[:role])
-        .for_environment(filters[:environment] || filters[:env])
-        .for_tenant(filters[:tenant_id])
+        .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
 
-    def with_status(status)
-      Togglefy::Feature.with_status(status)
+    def safe_chain(query, method, value, apply_if: true)
+      apply_if && nil_or_not_blank?(value) ? query.public_send(method, value) : query
+    end
+
+    def nil_or_not_blank?(value)
+      value.nil? || !value.blank?
     end
   end
 end

data/lib/togglefy/featureable.rb

@@ -1,36 +1,6 @@
-module Togglefy
-  module Featureable
-    extend ActiveSupport::Concern
-
-    included do
-      has_many :feature_assignments, as: :assignable, class_name: "Togglefy::FeatureAssignment"
-      has_many :features, through: :feature_assignments, class_name: "Togglefy::Feature"
-    end
-
-    def has_feature?(identifier)
-      features.exists?(identifier: identifier.to_s)
-    end
-
-    def add_feature(feature)
-      feature = find_feature!(feature)
-      features << feature unless has_feature?(feature.identifier)
-    end
-
-    def remove_feature(feature)
-      feature = find_feature!(feature)
-      features.destroy(feature) if has_feature?(feature.identifier)
-    end
+require "togglefy/assignable"
 
-    def clear_features
-      features.destroy_all
-    end
-
-    private
-
-    def find_feature!(feature)
-      return feature if feature.is_a?(Togglefy::Feature)
-
-      Togglefy::Feature.find_by!(identifier: feature.to_s)
-    end
-  end
+module Togglefy
+  Featureable = Assignable
+  warn "[DEPRECATION] `Togglefy::Featureable` is deprecated. Use `Togglefy::Assignable` instead."
 end

data/lib/togglefy/scoped_bulk_wrapper.rb

@@ -0,0 +1,13 @@
+require "togglefy/services/bulk_toggler"
+
+module Togglefy
+  class ScopedBulkWrapper
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def bulk
+      BulkToggler.new(@klass)
+    end
+  end
+end

data/lib/togglefy/services/bulk_toggler.rb

@@ -0,0 +1,108 @@
+module Togglefy
+  class BulkToggler
+    ALLOWED_ASSIGNABLE_FILTERS = %i[group role environment env tenant_id].freeze
+
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def enable(identifiers, **filters)
+      toggle(:enable, identifiers, filters)
+    end
+
+    def disable(identifiers, **filters)
+      toggle(:disable, identifiers, filters)
+    end
+
+    private
+
+    attr_reader :klass
+
+    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?
+
+      feature_ids = features.map(&:id)
+
+      assignables = if action == :enable
+        klass.without_features(feature_ids)
+      else
+        klass.with_features(feature_ids)
+      end
+
+      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
+
+        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
+
+        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
+    end
+
+    def build_scope_filters(filters)
+      filters.slice(*ALLOWED_ASSIGNABLE_FILTERS).compact
+    end
+
+    def sample_assignables(assignables, percentage)
+      count = (assignables.size * percentage.to_f / 100).round
+      assignables.sample(count)
+    end
+  end
+end

data/lib/togglefy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Togglefy
-  VERSION = "1.0.2"
+  VERSION = "1.1.1"
 end

data/lib/togglefy.rb

@@ -1,24 +1,25 @@
 # frozen_string_literal: true
 
 require "togglefy/version"
-require "togglefy/engine"
+require "togglefy/engine" if defined?(Rails)
 require "togglefy/featureable"
+require "togglefy/assignable"
+require "togglefy/feature_assignable_manager"
 require "togglefy/feature_manager"
 require "togglefy/feature_query"
+require "togglefy/scoped_bulk_wrapper"
+require "togglefy/exceptions"
 
 module Togglefy
   class Error < StandardError; end
 
-  def self.feature(identifier)
-    FeatureQuery.new.feature(identifier)
+  # FeatureQuery
+  def self.features
+    FeatureQuery.new.features
   end
 
-  def self.destroy_feature(identifier)
-    FeatureQuery.new.destroy_feature(identifier)
-  end
-  
-  def self.for(assignable)
-    FeatureManager.new(assignable)
+  def self.feature(identifier)
+    FeatureQuery.new.feature(identifier)
   end
   
   def self.for_type(klass)
@@ -57,11 +58,55 @@ module Togglefy
     FeatureQuery.new.with_status(status)
   end
 
+  # FeatureManager
+  def self.create(**params)
+    FeatureManager.new.create(**params)
+  end
+
+  def self.update(identifier, **params)
+    FeatureManager.new(identifier).update(**params)
+  end
+
+  def self.destroy(identifier)
+    FeatureManager.new(identifier).destroy
+  end
+
+  def self.toggle(identifier)
+    FeatureManager.new(identifier).toggle
+  end
+
+  def self.active!(identifier)
+    FeatureManager.new(identifier).active!
+  end
+
+  def self.inactive!(identifier)
+    FeatureManager.new(identifier).inactive!
+  end
+
+  # FeatureAssignableManager
+  def self.for(assignable)
+    FeatureAssignableManager.new(assignable)
+  end
+
+  # ScopedBulkWrapper
+  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
 
     alias_method :for_env, :for_environment
     alias_method :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
   end
 end

data/togglefy.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ["gazeveco@gmail.com"]
 
   spec.summary = "Simple and open source Feature Management."
-  spec.description = "Togglefy is a feature management solution to help you control which features an user or a group has access to."
+  spec.description = "Togglefy is a feature management Rails gem to help you control which features an user or a group has access to."
   spec.homepage = "https://github.com/azeveco/Togglefy"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.4.0"
@@ -31,10 +31,4 @@ Gem::Specification.new do |spec|
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
 end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: togglefy
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.1
 platform: ruby
 authors:
 - Gabriel Azevedo
 bindir: exe
 cert_chain: []
-date: 2025-04-12 00:00:00.000000000 Z
+date: 2025-04-18 00:00:00.000000000 Z
 dependencies: []
-description: Togglefy is a feature management solution to help you control which features
-  an user or a group has access to.
+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
 executables: []
@@ -25,10 +25,21 @@ files:
 - lib/generators/togglefy/templates/create_feature_assignments.rb
 - lib/generators/togglefy/templates/create_features.rb
 - lib/togglefy.rb
+- lib/togglefy/assignable.rb
 - lib/togglefy/engine.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
 - lib/togglefy/featureable.rb
+- lib/togglefy/scoped_bulk_wrapper.rb
+- lib/togglefy/services/bulk_toggler.rb
 - lib/togglefy/version.rb
 - togglefy.gemspec
 homepage: https://github.com/azeveco/Togglefy