featuring 1.0.0

data/lib/featuring/declarable.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require_relative "delegatable"
+require_relative "flaggable"
+
+module Featuring
+  # [public] Adds the ability to declare feature flags on a module or class.
+  #
+  #   module Features
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature
+  #   end
+  #
+  #   class User < ActiveRecord::Base
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature
+  #   end
+  #
+  # Each feature flag has a corresponding method to check its value:
+  #
+  #   module Features
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature
+  #   end
+  #
+  #   Features.some_feature?
+  #   => false
+  #
+  # When using feature flags on an object, checks are available through the `features` instance method:
+  #
+  #   class ObjectWithFeatures
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature
+  #   end
+  #
+  #   instance = ObjectWithFeatures.new
+  #   instance.features.some_feature?
+  #   => false
+  #
+  # When using feature flag blocks, values can be passed through the check method:
+  #
+  #   module Features
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature do |value|
+  #       value == :some_value
+  #     end
+  #   end
+  #
+  #   Features.some_feature?(:some_value)
+  #   => true
+  #
+  #   Features.some_feature?(:some_other_value)
+  #   => false
+  #
+  # Check methods are guaranteed to only return `true` or `false`:
+  #
+  #   module Features
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature do
+  #       :foo
+  #     end
+  #   end
+  #
+  #   Features.some_feature?
+  #   => true
+  #
+  # Check methods have access to their context:
+  #
+  #   class ObjectWithFeatures
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature do
+  #       enabled?
+  #     end
+  #
+  #     def enabled?
+  #       true
+  #     end
+  #   end
+  #
+  #   instance = ObjectWithFeatures.new
+  #   instance.features.some_feature?
+  #   => true
+  #
+  # Note that this happens through delegators, which means that instance variables are not accessible
+  # to the feature flag. For cases like this, define an `attr_accessor`.
+  #
+  # Feature flags can be defined in various modules and composed together:
+  #
+  #   module Features
+  #     extend Featuring::Declarable
+  #     feature :some_feature, true
+  #   end
+  #
+  #   module AllTheFeatures
+  #     extend Features
+  #
+  #     extend Featuring::Declarable
+  #     feature :another_feature, true
+  #   end
+  #
+  #   class User < ActiveRecord::Base
+  #     include AllTheFeatures
+  #   end
+  #
+  #   instance = ObjectWithFeatures.new
+  #
+  #   instance.some_feature?
+  #   => true
+  #
+  #   instance.another_feature?
+  #   => true
+  #
+  # Super is fully supported! Here's an example of how it can be useful:
+  #
+  #   module Features
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_feature do
+  #       [true, false].sample
+  #     end
+  #   end
+  #
+  #   class User < ActiveRecord::Base
+  #     include Features
+  #
+  #     extend Featuring::Declarable
+  #     feature :some_feature do
+  #       persisted?(:some_feature) || super()
+  #     end
+  #   end
+  #
+  #   User.find(1).features.some_feature?
+  #   => true/false at random
+  #
+  #   User.find(1).features.enable :some_feature
+  #
+  #   User.find(1).features.some_feature?
+  #   => true (always)
+  #
+  module Declarable
+    # [public] Define a named feature with a default value, or a block that returns the default value.
+    #
+    # By default, a feature flag is disabled. It can be enabled by specifying a value:
+    #
+    #   module Features
+    #     extend Featuring::Declarable
+    #
+    #     feature :some_feature, true
+    #   end
+    #
+    # Feature flags can also compute a value using a block:
+    #
+    #   module Features
+    #     extend Featuring::Declarable
+    #
+    #     feature :some_feature do
+    #       # perform some complex logic
+    #     end
+    #   end
+    #
+    # The truthiness of the block's return value determines if the feature is enabled or disabled.
+    #
+    def feature(name, default = false, &block)
+      define_feature_flag(name, default, &block)
+    end
+
+    # Called when an object is extended by `Featuring::Declarable`.
+    #
+    def self.extended(object)
+      super
+
+      Flaggable.setup_flaggable_object(object)
+    end
+
+    # Called when an object is extended by a module that is extended by `Featuring::Declarable`.
+    #
+    def extended(object)
+      super
+
+      case object
+      when Class
+        raise "extending classes with feature flags is not currently supported"
+      when Module
+        Flaggable.setup_flaggable_object(object)
+
+        # Add the feature check methods to the module that was extended.
+        #
+        object.internal_feature_checks_module.include internal_feature_checks_module
+
+        # Because we added feature check methods above, extend again to make them available.
+        #
+        object.extend internal_feature_checks_module
+
+        # Add the feature methods to the module's internal feature module.
+        #
+        object.internal_feature_module.include internal_feature_module
+
+        # Add our feature flags to the object's feature flags.
+        #
+        object.feature_flags.concat(feature_flags)
+      end
+    end
+
+    # Called when a module extended by `Featuring::Declarable` is included into an object.
+    #
+    def included(object)
+      super
+
+      Flaggable.setup_flaggable_object(object)
+
+      # Add the feature check methods to the object's internal feature class.
+      #
+      object.instance_feature_class.internal_feature_checks_module.include internal_feature_checks_module
+
+      # Because we added feature check methods above, include again to make them available.
+      #
+      object.instance_feature_class.include object.instance_feature_class.internal_feature_checks_module
+
+      # Add the feature methods to the object's internal feature class.
+      #
+      object.instance_feature_class.internal_feature_module.include internal_feature_module
+
+      # Add our feature flags to the object's feature flags.
+      #
+      object.instance_feature_class.feature_flags.concat(feature_flags)
+    end
+  end
+end

data/lib/featuring/delegatable.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Featuring
+  # Internal concerns related to delegating feature flag checks to parent context, like this:
+  #
+  #   module Features
+  #     extend Featuring::Declarable
+  #
+  #     feature :some_enabled_feature do |value|
+  #       value == internal_value
+  #     end
+  #
+  #     def internal_value
+  #       true
+  #     end
+  #
+  #     module_function :internal_value
+  #   end
+  #
+  module Delegatable
+    def self.extended(object)
+      super
+
+      object.extend ClassMethods
+    end
+
+    def self.included(object)
+      super
+
+      object.extend ClassMethods
+      object.include InstanceMethods
+    end
+
+    private def internal_feature_delegates_to
+      self
+    end
+
+    private def internal_feature_delegator
+      @_internal_feature_delegator ||= internal_feature_delegator_class.new(
+        internal_feature_delegates_to
+      )
+    end
+
+    def fetch_feature_flag_value(name, *args)
+      !!internal_feature_delegator.public_send(name, *args)
+    end
+
+    module ClassMethods
+      # Returns the delegator class that responds to all feature check methods and delegates other
+      # method calls to its wrapped object.
+      #
+      def internal_feature_delegator_class
+        @_internal_feature_delegator_class ||= Class.new(SimpleDelegator).tap { |klass|
+          klass.include internal_feature_module
+        }
+      end
+    end
+
+    module InstanceMethods
+      private def internal_feature_delegator_class
+        self.class.internal_feature_delegator_class
+      end
+    end
+  end
+end

data/lib/featuring/flaggable.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "serializable"
+
+module Featuring
+  # Internal concerns related to defining feature flags on a module or class.
+  #
+  module Flaggable
+    def self.extended(object)
+      super
+
+      case object
+      when Class
+        object.include object.internal_feature_checks_module
+      when Module
+        object.extend object.internal_feature_checks_module
+      end
+    end
+
+    def self.setup_flaggable_object(object)
+      case object
+      when Class
+        object.extend ClassMethods
+        object.prepend InstanceMethods
+      when Module
+        object.extend Flaggable
+        object.extend Delegatable
+        object.extend Serializable
+      end
+    end
+
+    # Contains methods that return the feature's original default value, or block value.
+    #
+    def internal_feature_module
+      @_internal_feature_module ||= Module.new
+    end
+
+    # Contains methods that wrap the original values to typecast them into true or false values.
+    #
+    def internal_feature_checks_module
+      @_internal_feature_checks_module ||= Module.new
+    end
+
+    def define_feature_flag(name, default, &block)
+      # Define a feature check method that returns the default value or the block's return value.
+      #
+      internal_feature_module.module_eval do
+        if method_defined?(name)
+          undef_method(name)
+        end
+
+        if block
+          define_method name, &block
+        else
+          define_method name do
+            default
+          end
+        end
+      end
+
+      # Define a method that typecasts the value returned from the delegator to true/false. This is
+      # the method that's called when calling code asks if a feature is enabled. It guarantees that
+      # only true or false is returned when checking a feature flag.
+      #
+      internal_feature_checks_module.module_eval do
+        method_name = "#{name}?"
+
+        if method_defined?(method_name)
+          undef_method(method_name)
+        end
+
+        define_method method_name do |*args|
+          fetch_feature_flag_value(name, *args)
+        end
+      end
+
+      # Keep track of the feature flag we just defined.
+      #
+      feature_flags << name
+    end
+
+    def feature_flags
+      @_feature_flags ||= []
+    end
+
+    module ClassMethods
+      extend Forwardable
+
+      # Delegate flaggable methods to the internal `instance_feature_class`. This lets features be
+      # defined through the object, but actually be defined on the internal class.
+      #
+      def_delegators :instance_feature_class, :internal_feature_module, :internal_feature_checks_module, :define_feature_flag
+
+      # The internal class where feature flags for the object are defined. An instance of this class
+      # is returned when calling `object.features`. The object delegates all feature flag definition
+      # concerns to this internal class (see the comment above).
+      #
+      def instance_feature_class
+        @_instance_feature_class ||= Class.new do
+          extend Flaggable
+
+          # The class is `Flaggable`, but *instances* are `Delegatable`. This lets us delegate
+          # dynamically to the parent object (the object `features` is called on).
+          #
+          include Delegatable
+
+          include Serializable
+
+          def initialize(parent)
+            @parent = parent
+          end
+
+          # @api private
+          def feature_flags
+            self.class.feature_flags
+          end
+
+          private def internal_feature_delegates_to
+            @parent
+          end
+        end
+      end
+
+      def inherited(object)
+        # Add the feature check methods to the object's internal feature class.
+        #
+        object.instance_feature_class.internal_feature_checks_module.include instance_feature_class.internal_feature_checks_module
+
+        # Because we added feature check methods above, include again to make them available.
+        #
+        object.instance_feature_class.include object.instance_feature_class.internal_feature_checks_module
+
+        # Add the feature methods to the object's internal feature class.
+        #
+        object.instance_feature_class.internal_feature_module.include instance_feature_class.internal_feature_module
+      end
+    end
+
+    module InstanceMethods
+      # Returns the object's feature context.
+      #
+      def features
+        @_features ||= self.class.instance_feature_class.new(self)
+      end
+    end
+  end
+end

data/lib/featuring/persistence/activerecord.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../persistence"
+require_relative "adapter"
+
+module Featuring
+  module Persistence
+    # [public] Persists feature flag values using an ActiveRecord model. Postgres is currently the only
+    # supported database (see `Featuring::Persistence` for details on how to use persistence).
+    #
+    #   class User < ActiveRecord::Base
+    #     extend Featuring::Persistence::ActiveRecord
+    #
+    #     extend Featuring::Declarable
+    #     feature :some_feature
+    #   end
+    #
+    #   User.find(1).features.enable :some_feature
+    #   User.find(1).features.some_feature?
+    #   => true
+    #
+    module ActiveRecord
+      extend Adapter
+
+      # [public] Methods to be added to the flaggable object.
+      #
+      module Flaggable
+        def reload
+          features.reload
+
+          super
+        end
+      end
+
+      # [public] Returns the ActiveRecord model used to persist feature flag values.
+      #
+      def feature_flag_model
+        ::FeatureFlag
+      end
+
+      class << self
+        def fetch(target)
+          target.feature_flag_model.find_by(flaggable_id: target.id, flaggable_type: target.class.name)&.metadata
+        end
+
+        def create(target, **features)
+          target.feature_flag_model.create(
+            flaggable_id: target.id,
+            flaggable_type: target.class.name,
+            metadata: features
+          )
+        end
+
+        def update(target, **features)
+          scoped_dataset(target).update_all("metadata = metadata || '#{features.to_json}'")
+        end
+
+        def replace(target, **features)
+          scoped_dataset(target).update_all("metadata = '#{features.to_json}'")
+        end
+
+        private def scoped_dataset(target)
+          target.feature_flag_model.where(
+            flaggable_type: target.class.name,
+            flaggable_id: target.id
+          )
+        end
+      end
+    end
+  end
+end