flipside 0.3.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 658bbe055472e1a880352ecd5af0cbeacc9c0988274dc798610baadaeae7d33b
-  data.tar.gz: 55dcb7671784fee2bdcef7fdd6f26390aa7cd1e7ebc9c443199eadd18bfaf614
+  metadata.gz: d4ecf5b08df6bcc2ac0bd7a9f2e4396d361fefb53b497323725ab543ed3d60a8
+  data.tar.gz: a64de96569181f04e4e7f50f9c7122299ee79581115c0abfbdf24aceef706f03
 SHA512:
-  metadata.gz: 3170999fd42dcecf0232142f55430a9812e0926714f3ed543637ca5ce2b44dd932357e86b5c091b7c5e861de848ff4095eb9cc778e04311f84ecc9e4e8140796
-  data.tar.gz: 57ee735a9edfed83fc66283d7747a5e75614a6dc2de56628b4671796ee7e9dad03c07c82cf844aff9d59cab6bb635cd3fdd694d44345b7e55f0594135b31b46a
+  metadata.gz: 6b8b659ad364668c26e19e2666f78e5c354034c61b68b1c3b54f63a07f310749cc6295fe3cd77b36c61bfefa41f3266cb9c047ce459d688fed5951f4ee00d8ef
+  data.tar.gz: d61860274364b069a96b7547bc4f0c66b0de08b8eae4205f520084afa5b9fd1bb2e8b2d1e0022b05c47a8a8b47ef0421dafef87cb126152b3d7d70c39bb03d80

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [0.5.0] - 2026-10-08
+- Add `flipside_search_by`, `flipside_display_as` and `flipside_identified_by` to `Flipside::Flippable`. Each one registers the class as an entity, so `flipside_entity` is only needed for the defaults
+- A block given to `flipside_search_by` runs in the context of the class, so it can call `where` directly
+- An STI subclass inherits its parent's entity settings, and is registered as an entity of its own when it calls one of the macros itself
+- Test against Ruby 3.4 and 4.0
+
+### Deprecated
+- The `search_by`, `display_as` and `identified_by` options of `flipside_entity`, in favour of `flipside_search_by`, `flipside_display_as` and `flipside_identified_by`. They will be removed in 1.0.
+
+## [0.4.0] - 2026-09-25
+- Show entities whose record has been deleted instead of raising in the UI
+- Add `Flipside::Flippable` with `flipside_entity` and `flipside_role`, so models can register themselves (listed in `Flipside.flippables`); entities of a destroyed record are removed
+- Add `Flipside.prune_orphaned_entities`
+- Registering the same role twice no longer lists it twice
+- Display STI subclass entities through their own or their base class's registration
+- Verify `Flipside.flippables` at boot when a Rails app eager loads
+
+### Deprecated
+- `Flipside.register_entity` and `Flipside.register_role`, in favour of `flipside_entity` and `flipside_role` from `Flipside::Flippable`. They will be removed in 1.0.
+
 ## [0.3.4] - 2026-03-04
 - Support an array of default objects
 

data/README.md

@@ -87,7 +87,7 @@ We can also check multiple records. `.enabled?` will return `true` if any of the
 Flipside.enabled? "MyFeature", user, company, location
 ```
 
-### Enabling features for specific records
+#### Enabling features for specific records
 
 Features can be enabled for a certain record, typically a certain user or organization. These records are called entities. To enable a feature for a given record use `.add_entity`:
 ```ruby
@@ -97,6 +97,13 @@ Flipside.add_entity(name: "MyFeature", entity: user)
 Flipside.enabled? "MyFeature", user # => true
 ```
 
+Entities reference their record polymorphically, so there is no foreign key to clean them up when the record is deleted. A model registered as an entity (see [Registering from the model](#registering-from-the-model)) removes its entities when a record is destroyed.
+
+Entities left behind by records deleted without callbacks (or before the concern was added) can be removed with:
+```ruby
+Flipside.prune_orphaned_entities # => number of entities deleted
+```
+
 Features can be enabled for records responding true to a certain method. This is called a "role". Given that User records have an admin? method. A feature can then be enabled
 for all users who are admins, using the `.add_role` method:
 ```ruby
@@ -123,7 +130,7 @@ Note: you probably want to wrap this inside a constraints block to provide some
 ![UI](/features.png)
 
 
-### Configuration
+## Configuration
 
 Flipside can be configured by calling some class methods on `Flipside` (see below).
 
@@ -154,7 +161,7 @@ Flipside.enabled? :some_feature, Current.user
 Flipside.default_object = -> { [Current.user, Current.organization] }
 ```
 
-# Note: if we do pass in an argument, then `default_object ` will not be used:
+#### Note: if we do pass in an argument, then `default_object ` will not be used:
 Flipside.enabled? :some_feature, Current.company # check current company instead of user.
 ```
 
@@ -170,75 +177,148 @@ Flipside.create_missing_features = true
 Flipside.default_object = -> { Current.user }
 ```
 
-#### Entities
+### Registering from the model
+
+Entities and roles are searched for in the UI, so Flipside needs to know which classes can be used. A model registers itself by including `Flipside::Flippable` and calling the entity macros (`flipside_entity`, `flipside_search_by`, `flipside_display_as`, `flipside_identified_by`) and/or `flipside_role`:
+```ruby
+class User < ApplicationRecord
+  include Flipside::Flippable
+
+  flipside_search_by :name
+  flipside_display_as :name
+  flipside_role :admin?
+  flipside_role :awesome?, display_as: "Awesome users"
+end
+```
+
+List the class names in an initializer, so that Flipside can load them when the UI needs them (also when the app does not eager load):
+```ruby
+# config/initializers/flipside.rb
+Flipside.flippables = %w[User]
+```
+
+A class using these macros must be listed in `Flipside.flippables`, and a listed class must call at least one of them, otherwise Flipside raises.
+
+### Entities
 
 Entities can be added to a feature by searching for records.
 
 ![Add an entity](/add_entity.png)
 
-To make this work, some configuration is required. Use the class method `Flipside.register_entity` for this.
+Each class that may be used as a feature enabler is registered as an entity by calling `flipside_entity`, `flipside_search_by`, `flipside_display_as` or `flipside_identified_by` (any combination of them, in any order). `flipside_entity` is only needed to register with the defaults. A registered entity class also removes the entities of a record when it is destroyed. Note that this includes soft deletion that runs destroy callbacks (e.g. paranoia), so a restored record comes back without its features. Soft deletion that skips them (e.g. discard) keeps the entities.
 ```ruby
-Flipside.register_entity(
-  class_name: "User",
-  search_by: :name,
-  display_as: :name,
-  identified_by: :id
-)
+class User < ApplicationRecord
+  include Flipside::Flippable
+
+  flipside_entity
+end
 ```
 
-The `.register_entity` method should be called once for each class that may be used as a feature enabler.
-The `search_by` keyword argument, which may be a `Symbol` or a `Proc`, dictates how records are found from searching in the ui.
-When a `Symbol` is given, e.g. `:name`, then entities with an exact match on the corresponding attribute are returned. I.e. `User.where(name: query)`.
-When a `Proc` is given, then this `Proc` is called with the search string and is expected to return an object responding to `to_a` (e.g. an AR collection).
+`flipside_identified_by` sets the column Flipside uses to identify records. This defaults to `:id` and typically does not need to be changed.
+Currently composite keys are not supported.
+```ruby
+flipside_identified_by :uuid
+```
+
+`flipside_search_by` dictates how records are found from searching in the ui. It takes a block, which is called with the search string in the context of the class and is expected to return an object responding to `to_a` (e.g. an AR collection).
 This gives us the flexibility to decide how to search for entities. For example, to search for users with matching first name or last name or an email
 starting with _query_, something like this could be used.
 ```ruby
-Flipside.register_entity(
-  class_name: "User",
-  search_by: ->(str) { User.where("lower(first_name) = :name OR lower(last_name) = :name or email LIKE :str", name: str.downcase, str: "#{str}%") },
-)
+flipside_search_by do |str|
+  where(
+    "lower(first_name) = :name OR lower(last_name) = :name OR email LIKE :str",
+    name: str.downcase,
+    str: "#{str}%"
+  )
+end
+```
 
+Instead of a block, it may be given the name of a column, e.g. `:name`. Then records with an exact match on that column are returned, i.e. `User.where(name: query)`:
+```ruby
+flipside_search_by :name
 ```
 
-The `identified_by` keyword argument, sets the column used as primary key for the corresponding table. This defaults to `:id` and typically does need to be change.
-Currently composite keys are not supported.
+Without `flipside_search_by`, records are found by an exact match on `identified_by`.
 
-The `display_as` keyword argument, is used to configure how these entities show up in the combobox. When set to a `Symbol`, then this value is sent to the corresponding entity.
+`flipside_display_as` configures how these entities show up in the combobox. When given the name of an instance method, that method is called on the entity.
 For example, given the following setup. Users will be displayed with first name and last name:
 ```ruby
 class User < ApplicationRecord
+  include Flipside::Flippable
+
+  flipside_display_as :name
+
   def name
     [first_name, last_name].compact.map(&:capitalize).join(" ")
   end
 end
-
-Flipside.register_entity(
-  class_name: "User",
-  display_as: :name,
-)
 ```
 
-When a `Proc` is given, then it is expected to take an entity as input and return a string used for displaying the entity. The config above could then instead be done using:
+When given a block, it is called with the entity and is expected to return a string used for displaying the entity. The config above could then instead be done using:
 ```ruby
-Flipside.register_entity(
-  class_name: "User",
-  display_as: ->(user) { [user.first_name, user.last_name].compact.map(&:capitalize).join(" ") }
-)
+flipside_display_as do |user|
+  [user.first_name, user.last_name].compact.map(&:capitalize).join(" ")
+end
 ```
 
-#### Roles
+Without `flipside_display_as`, entities are displayed by their `identified_by` value.
+
+An STI subclass inherits these settings. When a subclass calls one of the macros itself, it is registered as an entity of its own, so it must also be listed in `Flipside.flippables` and shows up separately in the UI.
+
+The `search_by`, `display_as` and `identified_by` keyword arguments of `flipside_entity` from Flipside 0.4.0 are deprecated in favour of these macros, and will be removed in 1.0.
+
+### Roles
 
 Features can be enabled for certain roles, by searching for roles (by method name).
 
 ![Add a role](/add_role.png)
 
-This is configured by calling the class method `Flipside.register_role` for each role to be added.
-Note a role consists of a class and a corresponding instance method.
+This is configured by calling `flipside_role` for each role to be added. A role consists of a class and a corresponding instance method, and `display_as` optionally sets how it shows up in the UI.
 ```ruby
+class User < ApplicationRecord
+  include Flipside::Flippable
+
+  flipside_role :admin?
+  flipside_role :awesome?, display_as: "Awesome users"
+end
+```
+
+### Classes you cannot edit
+
+A class from another gem can be registered by including the concern from `to_prepare`, which runs at boot and again after every reload. It must still be listed in `Flipside.flippables`:
+```ruby
+# config/initializers/flipside.rb
+Flipside.flippables = %w[User OtherGem::Account]
+
+Rails.application.config.to_prepare do
+  OtherGem::Account.include(Flipside::Flippable)
+  OtherGem::Account.flipside_display_as(:name)
+end
+```
+
+### Upgrading from `register_entity` and `register_role`
+
+`Flipside.register_entity` and `Flipside.register_role` are deprecated and will be removed in Flipside 1.0. Move each call into its model:
+```ruby
+# Before, in config/initializers/flipside.rb
+Flipside.register_entity(class_name: "User", search_by: :name, display_as: :name)
 Flipside.register_role(class_name: "User", method_name: :admin?)
-Flipside.register_role(class_name: "User", method_name: :awesome?)
+
+# After, in config/initializers/flipside.rb
+Flipside.flippables = %w[User]
+
+# and in app/models/user.rb
+class User < ApplicationRecord
+  include Flipside::Flippable
+
+  flipside_search_by :name
+  flipside_display_as :name
+  flipside_role :admin?
+end
 ```
 
+In a Rails 7.1+ app the deprecation warnings follow the app's own deprecation settings (`Rails.application.deprecators[:flipside]`).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests.

data/app/models/flipside/flippable.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "models/flipside/entity"
+
+module Flipside
+  # Lets a model register itself with Flipside. The class must also be listed in
+  # Flipside.flippables, so that Flipside can load it when the UI needs it. The
+  # listing is checked when Flipside loads the classes rather than here, since
+  # a model may be loaded before the initializer that sets Flipside.flippables.
+  module Flippable
+    extend ActiveSupport::Concern
+
+    included do
+      # The class's Flipside::RegisteredEntity. Being a class attribute, it is
+      # inherited by STI subclasses and starts out empty in a reloaded class.
+      class_attribute :_flipside_registration, instance_accessor: false, instance_predicate: false
+    end
+
+    class_methods do
+      # Registers the class as an entity and removes its Flipside::Entity rows
+      # when a record is destroyed. Calling flipside_search_by,
+      # flipside_display_as or flipside_identified_by does the same, so this is
+      # only needed to register with the defaults.
+      def flipside_entity(search_by: nil, display_as: nil, identified_by: nil)
+        flipside_registration
+        deprecated_entity_options(search_by:, display_as:, identified_by:)
+      end
+
+      # Sets how entities are found from a search in the UI, either with a block
+      # or the name of a column. The block is run in the context of the class,
+      # given the search string, and returns the matching records. A column
+      # matches the search string exactly. Registers the class as an entity, as
+      # flipside_entity does.
+      def flipside_search_by(column = nil, &block)
+        flipside_registration.search_by = name_or_block(column, block)
+      end
+
+      # Sets how entities are displayed in the UI, either with a block given the
+      # record or the name of an instance method. Either returns a string.
+      # Registers the class as an entity, as flipside_entity does.
+      def flipside_display_as(method_name = nil, &block)
+        flipside_registration.display_as = name_or_block(method_name, block)
+      end
+
+      # Sets the column that identifies an entity, :id by default. Registers the
+      # class as an entity, as flipside_entity does.
+      def flipside_identified_by(column)
+        flipside_registration.identified_by = column.to_sym
+      end
+
+      def flipside_role(method_name, display_as: nil)
+        register_flippable!
+
+        Flipside.add_registered_role(class_name: name, method_name:, display_as:)
+      end
+
+      private
+
+      def register_flippable!
+        raise Flipside::Error, "Flipside macros need a named class" if name.nil?
+
+        Flipside.register_flippable(name)
+      end
+
+      # The registration this class owns, created on first use. An STI subclass
+      # starts from a copy of the settings it inherits.
+      def flipside_registration
+        return _flipside_registration if _flipside_registration&.class_name == name
+
+        register_flippable!
+
+        has_many :flipside_entities,
+          class_name: "Flipside::Entity",
+          as: :flippable,
+          dependent: :delete_all
+
+        self._flipside_registration = Flipside.add_registered_entity(
+          class_name: name,
+          **(_flipside_registration&.options || {})
+        )
+      end
+
+      def name_or_block(name, block)
+        return name.to_sym if name && !block
+        return block if block && !name
+
+        raise ArgumentError, "pass either a name or a block"
+      end
+
+      def deprecated_entity_options(search_by:, display_as:, identified_by:)
+        return if search_by.nil? && display_as.nil? && identified_by.nil?
+
+        Flipside.deprecator.warn(
+          "The search_by, display_as and identified_by options of flipside_entity are " \
+          "deprecated and will be removed in Flipside #{Flipside.deprecator.deprecation_horizon}. " \
+          "Use flipside_search_by, flipside_display_as and flipside_identified_by in " \
+          "#{name} instead."
+        )
+
+        registration = flipside_registration
+        registration.search_by = search_by if search_by
+        registration.display_as = display_as if display_as
+        registration.identified_by = identified_by if identified_by
+      end
+    end
+  end
+end

data/lib/flipside/config/entities.rb

@@ -4,6 +4,15 @@ module Flipside
   module Config
     module Entities
       def register_entity(class_name:, search_by:, display_as:, identified_by: :id)
+        deprecator.warn(
+          "Flipside.register_entity is deprecated and will be removed in Flipside " \
+          "#{deprecator.deprecation_horizon}. Include Flipside::Flippable in " \
+          "#{class_name}, call flipside_entity there and list it in Flipside.flippables."
+        )
+        add_registered_entity(class_name:, search_by:, display_as:, identified_by:)
+      end
+
+      def add_registered_entity(class_name:, search_by: nil, display_as: nil, identified_by: :id) # :nodoc:
         registered_entities[class_name.to_s] = RegisteredEntity.new(
           class_name:,
           search_by:,
@@ -13,25 +22,61 @@ module Flipside
       end
 
       def entity_classes
+        load_flippables
         registered_entities.keys
       end
 
       def search_entity(class_name:, query:)
+        load_flippables
         registered_entities.fetch(class_name.to_s).search(query)
       end
 
       def find_entity(class_name:, identifier:)
+        load_flippables
         registered_entities.fetch(class_name.to_s).find(identifier)
       end
 
+      # Accepts either a flippable record or a Flipside::Entity join row. Given
+      # a join row, it still renders when the record or its class has been
+      # deleted, or the class is no longer registered, so the UI can list it
+      # for removal.
       def display_entity(entity)
-        registered_entities
-          .fetch(entity.class.to_s)
-          .display(entity)
+        return display_flippable(entity) unless entity.is_a?(Flipside::Entity)
+
+        record = entity.flippable if entity.flippable_type.safe_constantize
+        label = "#{entity.flippable_type} ##{entity.flippable_id}"
+
+        if record.nil?
+          "#{label} (deleted)"
+        elsif (registration = registration_for(record.class))
+          registration.display(record)
+        else
+          label
+        end
       end
 
       private
 
+      def display_flippable(record)
+        registration = registration_for(record.class)
+        raise KeyError, "#{record.class} is not registered with Flipside" unless registration
+
+        registration.display(record)
+      end
+
+      # The registration of the class or its closest registered superclass, so
+      # an STI subclass is displayed through the base class's registration
+      # unless it has one of its own.
+      def registration_for(klass)
+        klass.ancestors.each do |ancestor|
+          next unless ancestor.is_a?(Class)
+
+          registration = registered_entities[ancestor.name]
+          return registration if registration
+        end
+        nil
+      end
+
       def registered_entities
         @registered_entities ||= {}
       end

data/lib/flipside/config/flippables.rb

@@ -0,0 +1,46 @@
+module Flipside
+  module Config
+    # Names of the classes that register themselves through the
+    # Flipside::Flippable macros. Listing them lets Flipside load them on demand,
+    # so the UI finds them whether or not the app eager loads.
+    module Flippables
+      attr_writer :flippables
+
+      def flippables
+        @flippables ||= []
+      end
+
+      def register_flippable(class_name) # :nodoc:
+        registered_flippables << class_name.to_s
+      end
+
+      # Raises unless Flipside.flippables and the classes calling the
+      # Flipside::Flippable macros agree. Runs whenever the UI reads the
+      # registry, and at boot in an app that eager loads (see Railtie).
+      def verify_flippables! # :nodoc:
+        load_flippables
+      end
+
+      private
+
+      def load_flippables
+        flippables.each do |name|
+          name.constantize
+          next if registered_entities.key?(name) || registered_roles.key?(name)
+
+          raise Error, "#{name} is listed in Flipside.flippables but calls neither " \
+            "flipside_entity nor flipside_role"
+        end
+
+        unlisted = registered_flippables.to_a - flippables
+        return if unlisted.empty?
+
+        raise Error, "#{unlisted.join(", ")} must be listed in Flipside.flippables"
+      end
+
+      def registered_flippables
+        @registered_flippables ||= Set.new
+      end
+    end
+  end
+end

data/lib/flipside/config/registered_entity.rb

@@ -2,7 +2,8 @@ require "flipside/search_result"
 
 module Flipside
   class RegisteredEntity
-    attr_reader :class_name, :search_by, :display_as, :identified_by
+    attr_reader :class_name
+    attr_accessor :search_by, :display_as, :identified_by
 
     def initialize(class_name:, identified_by: :id, search_by: nil, display_as: nil)
       @class_name = class_name
@@ -11,8 +12,12 @@ module Flipside
       @identified_by = identified_by
     end
 
+    def options
+      {search_by:, display_as:, identified_by:}
+    end
+
     def search(query)
-      Array(lookup_proc.call(query)).map do |entity|
+      Array(lookup(query)).map do |entity|
         SearchResult.new(
           entity,
           display(entity),
@@ -22,39 +27,32 @@ module Flipside
     end
 
     def find(identifier)
-      class_name.constantize.find_by!("#{identified_by}": identifier)
+      klass.find_by!("#{identified_by}": identifier)
     end
 
     def display(entity)
-      display_proc.call(entity)
+      case display_as
+      when Proc then display_as.call(entity)
+      when Symbol then entity.public_send(display_as)
+      when String then display_as
+      else entity.public_send(identified_by)
+      end
     end
 
     private
 
-    def lookup_proc
-      @lookup_proc ||=
-        case search_by
-        when Proc
-          search_by
-        when Symbol
-          ->(query) { class_name.constantize.where("#{search_by}": query) }
-        else
-          ->(query) { class_name.constantize.where("#{identified_by}": query) }
-        end
+    # A block runs in the context of the class, so it can call where directly.
+    # A Symbol names a column to match exactly.
+    def lookup(query)
+      case search_by
+      when Proc then klass.instance_exec(query, &search_by)
+      when Symbol then klass.where("#{search_by}": query)
+      else klass.where("#{identified_by}": query)
+      end
     end
 
-    def display_proc
-      @display_proc ||=
-        case display_as
-        when Proc
-          display_as
-        when Symbol
-          ->(entity) { entity.public_send(display_as) }
-        when String
-          ->(entity) { display_as }
-        else
-          ->(entity) { entity.public_send(identified_by) }
-        end
+    def klass
+      class_name.constantize
     end
   end
 end

data/lib/flipside/config/roles.rb

@@ -4,8 +4,17 @@ module Flipside
   module Config
     module Roles
       def register_role(class_name:, method_name:, display_as: nil)
-        registered_roles[class_name.to_s] ||= []
-        registered_roles[class_name.to_s] << RegisteredRole.new(
+        deprecator.warn(
+          "Flipside.register_role is deprecated and will be removed in Flipside " \
+          "#{deprecator.deprecation_horizon}. Include Flipside::Flippable in " \
+          "#{class_name}, call flipside_role there and list it in Flipside.flippables."
+        )
+        add_registered_role(class_name:, method_name:, display_as:)
+      end
+
+      def add_registered_role(class_name:, method_name:, display_as: nil) # :nodoc:
+        registered_roles[class_name.to_s] ||= {}
+        registered_roles[class_name.to_s][method_name.to_s] = RegisteredRole.new(
           class_name:,
           method_name:,
           display_as:
@@ -13,11 +22,13 @@ module Flipside
       end
 
       def role_classes
+        load_flippables
         registered_roles.keys
       end
 
       def search_role(class_name:, query:)
-        registered_roles.fetch(class_name.to_s).filter_map do |registered_role|
+        load_flippables
+        registered_roles.fetch(class_name.to_s).values.filter_map do |registered_role|
           next unless registered_role.match? query
           registered_role.to_result
         end

data/lib/flipside/railtie.rb

@@ -0,0 +1,18 @@
+module Flipside
+  # Wires Flipside into a Rails app. Only loaded when Rails is present.
+  class Railtie < ::Rails::Railtie
+    # Hands Flipside's deprecator to the app, so its deprecation settings (log,
+    # raise, silence) apply to Flipside's warnings too.
+    initializer "flipside.deprecator" do |app|
+      app.deprecators[:flipside] = Flipside.deprecator if app.respond_to?(:deprecators)
+    end
+
+    # Eager loading runs before after_initialize, so every class calling the
+    # macros has registered by now. Checking here fails boot, and so CI, for a
+    # misconfigured list instead of the first visit to the UI. Without eager
+    # loading the check would only see whatever happens to be loaded.
+    config.after_initialize do |app|
+      Flipside.verify_flippables! if app.config.eager_load
+    end
+  end
+end

data/lib/flipside/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flipside
-  VERSION = "0.3.4"
+  VERSION = "0.5.0"
 end

data/lib/flipside/views/feature_entities.erb

@@ -51,7 +51,7 @@
           <li class="mt-2 p-2 bg-slate-700 text-slate-300 border border-slate-600 rounded-lg">
             <div class="flex justify-between items-center">
               <div>
-                <%= Flipside.display_entity(entity.flippable) %> (<%= entity.flippable_type %>)
+                <%= Flipside.display_entity(entity) %> (<%= entity.flippable_type %>)
               </div>
               <div>
                 <form action="<%= feature_path(feature, "remove_entity") %>" method="post">

data/lib/flipside.rb

@@ -1,17 +1,22 @@
 # frozen_string_literal: true
 
 require "active_record"
+require "active_support/deprecation"
 require "flipside/version"
 require "flipside/web"
 require "flipside/config/settings"
 require "flipside/config/entities"
 require "flipside/config/roles"
+require "flipside/config/flippables"
 require "models/flipside/feature"
+require "models/flipside/flippable"
+require "flipside/railtie" if defined?(Rails::Railtie)
 
 module Flipside
   extend Config::Settings
   extend Config::Entities
   extend Config::Roles
+  extend Config::Flippables
 
   class Error < StandardError; end
 
@@ -22,6 +27,10 @@ module Flipside
   end
 
   class << self
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("1.0", "Flipside")
+    end
+
     def enabled?(name, *objects)
       feature = find_by(name:)
       return false unless feature
@@ -40,6 +49,11 @@ module Flipside
       feature.update(enabled: true)
     end
 
+    def disable!(name)
+      feature = find_by!(name:)
+      feature.update(enabled: false)
+    end
+
     def add_entity(entity:, feature: nil, name: nil)
       feature ||= find_by!(name:)
       Entity.find_or_create_by(feature:, flippable: entity)
@@ -50,6 +64,22 @@ module Flipside
       feature.entities.find_by(id: entity_id)&.destroy
     end
 
+    # Deletes entities whose record no longer exists, or whose class does not.
+    # Returns the number of entities deleted.
+    def prune_orphaned_entities
+      Entity.distinct.pluck(:flippable_type).sum do |type|
+        entities = Entity.where(flippable_type: type)
+        klass = type.safe_constantize
+        next entities.delete_all unless klass
+
+        existing = klass
+          .unscoped
+          .where(klass.primary_key => entities.pluck(:flippable_id))
+          .pluck(klass.primary_key)
+        entities.where.not(flippable_id: existing).delete_all
+      end
+    end
+
     def add_role(class_name:, method_name:, feature: nil, name: nil)
       feature ||= find_by!(name:)
       Role.find_or_create_by(feature:, class_name:, method: method_name)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: flipside
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Sammy Henningsson
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -136,12 +135,14 @@ files:
 - app/models/flipside/entities.rb
 - app/models/flipside/entity.rb
 - app/models/flipside/feature.rb
+- app/models/flipside/flippable.rb
 - app/models/flipside/key.rb
 - app/models/flipside/keys.rb
 - app/models/flipside/role.rb
 - app/models/flipside/roles.rb
 - lib/flipside.rb
 - lib/flipside/config/entities.rb
+- lib/flipside/config/flippables.rb
 - lib/flipside/config/registered_entity.rb
 - lib/flipside/config/registered_role.rb
 - lib/flipside/config/roles.rb
@@ -152,6 +153,7 @@ files:
 - lib/flipside/public/inline_edit_controller.js
 - lib/flipside/public/modal_controller.js
 - lib/flipside/public/search_controller.js
+- lib/flipside/railtie.rb
 - lib/flipside/search_result.rb
 - lib/flipside/version.rb
 - lib/flipside/views/_datetime_modal.erb
@@ -174,7 +176,6 @@ metadata:
   homepage_uri: https://github.com/apoex/flipside
   source_code_uri: https://github.com/apoex/flipside
   changelog_uri: https://github.com/apoex/flipside/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - app
@@ -190,8 +191,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Feature flags.
 test_files: []