featuring 1.0.0

data/lib/featuring/persistence/adapter.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "featuring/persistence"
+require "featuring/persistence/transaction"
+
+module Featuring
+  module Persistence
+    # [public] Defines the behavior for feature flag adapters.
+    #
+    # Adapters are modules that are extended by {Adapter}. They must define three methods:
+    #
+    #   1. `fetch`: Returns persisted feature flag values for a given object.
+    #
+    #   2. `create`: Creates feature flags for a given object.
+    #
+    #   3. `update`: Updates feature flags for a given object.
+    #
+    #   4. `replace`: Replaces feature flags for a given object.
+    #
+    # See `Featuring::Persistence::ActiveRecord` for a complete example.
+    #
+    module Adapter
+      def included(object)
+        object.instance_feature_class.prepend Methods
+
+        object.instance_feature_class.module_exec(self) do |adapter|
+          define_method :feature_flag_adapter do
+            adapter
+          end
+        end
+
+        # Give adapters the ability to extend the object with persistent flags.
+        #
+        if const_defined?("Flaggable", false)
+          object.prepend(const_get("Flaggable"))
+        end
+      end
+
+      module Methods
+        # [public] Persist the default or computed value for a feature flag.
+        #
+        #   class User < ActiveRecord::Base
+        #     extend Featuring::Persistence::ActiveRecord
+        #
+        #     extend Featuring::Declarable
+        #     feature :feature_1, true
+        #   end
+        #
+        #   User.find(1).features.persist :feature_1
+        #   User.find(1).features.feature_1?
+        #   => true
+        #
+        # Passing arguments to a feature flag block:
+        #
+        #   class User < ActiveRecord::Base
+        #     extend Featuring::Persistence::ActiveRecord
+        #
+        #     extend Featuring::Declarable
+        #     feature :feature_1 do |value|
+        #       value == :foo
+        #     end
+        #   end
+        #
+        #   User.find(1).features.persist :feature_1, :bar
+        #   User.find(1).features.feature_1?
+        #   => false
+        #
+        def persist(feature, *args)
+          create_or_update_feature_flags(feature => fetch_feature_flag_value(feature, *args, raw: true))
+        end
+
+        # [public] Ensure that a feature flag is *not* persisted, falling back to its default value.
+        #
+        #   class User < ActiveRecord::Base
+        #     extend Featuring::Persistence::ActiveRecord
+        #
+        #     extend Featuring::Declarable
+        #     feature :feature_1, true
+        #   end
+        #
+        #   User.find(1).features.disable :feature_1
+        #   User.find(1).features.feature_1?
+        #   => false
+        #
+        #   User.find(1).features.reset :feature_1
+        #   User.find(1).features.feature_1?
+        #   => true
+        #
+        def reset(feature)
+          if persisted?(feature)
+            features = persisted_flags
+            features.delete(feature)
+            feature_flag_adapter.replace(@parent, **features.symbolize_keys)
+          end
+        end
+
+        # [public] Set the value for a feature flag.
+        #
+        #   class User < ActiveRecord::Base
+        #     extend Featuring::Persistence::ActiveRecord
+        #
+        #     extend Featuring::Declarable
+        #     feature :feature_1
+        #   end
+        #
+        #   User.find(1).features.set :feature_1, true
+        #   User.find(1).features.feature_1?
+        #   => true
+        #
+        def set(feature, value)
+          create_or_update_feature_flags(feature.to_sym => !!value)
+        end
+
+        # [public] Enable a feature flag.
+        #
+        #   class User < ActiveRecord::Base
+        #     extend Featuring::Persistence::ActiveRecord
+        #
+        #     extend Featuring::Declarable
+        #     feature :feature_1
+        #   end
+        #
+        #   User.find(1).features.enable :feature_1
+        #   User.find(1).features.feature_1?
+        #   => true
+        #
+        def enable(feature)
+          create_or_update_feature_flags(feature.to_sym => true)
+        end
+
+        # [public] Disable a feature flag.
+        #
+        #   class User < ActiveRecord::Base
+        #     extend Featuring::Persistence::ActiveRecord
+        #
+        #     extend Featuring::Declarable
+        #     feature :feature_1
+        #   end
+        #
+        #   User.find(1).features.disable :feature_1
+        #   User.find(1).features.feature_1?
+        #   => false
+        #
+        def disable(feature)
+          create_or_update_feature_flags(feature.to_sym => false)
+        end
+
+        # [public] Reload feature flag values for the object.
+        #
+        def reload
+          @_persisted_flags = nil
+        end
+
+        # [public] Start a transaction in which multiple feature flags values can be persisted at once.
+        #
+        # See `Featuring::Persistence::Transaction`.
+        #
+        def transaction
+          transaction = Transaction.new(self)
+          yield transaction
+          create_or_update_feature_flags(__perform: :replace, **transaction.values)
+        end
+
+        # [public] Returns `true` if the feature flag is persisted, optionally with the specified value.
+        #
+        #   class User < ActiveRecord::Base
+        #     extend Featuring::Persistence::ActiveRecord
+        #
+        #     extend Featuring::Declarable
+        #     feature :feature_1
+        #   end
+        #
+        #   User.find(1).features.persisted?(:feature_1)
+        #   => false
+        #
+        #   User.find(1).features.enable :feature_1
+        #
+        #   User.find(1).features.persisted?(:feature_1)
+        #   => true
+        #   User.find(1).features.persisted?(:feature_1, true)
+        #   => true
+        #   User.find(1).features.persisted?(:feature_1, false)
+        #   => false
+        #
+        def persisted?(name = nil, value = value_omitted = true)
+          if name && persisted_flags
+            persisted_flags.key?(name.to_sym) && (value_omitted || persisted(name) == value)
+          else
+            !persisted_flags.nil?
+          end
+        end
+
+        private def persisted(name)
+          persisted_flags[name.to_sym]
+        end
+
+        private def persisted_flags
+          @_persisted_flags ||= fetch_flags
+        end
+
+        private def fetch_flags
+          if (flags = feature_flag_adapter.fetch(@parent))
+            ActiveSupport::HashWithIndifferentAccess.new(flags)
+          end
+        end
+
+        private def create_or_update_feature_flags(__perform: :update, **features)
+          if persisted?
+            feature_flag_adapter.public_send(__perform, @parent, **features)
+
+            # Update the local persisted values to match.
+            #
+            features.each do |feature, value|
+              persisted_flags[feature] = value
+            end
+
+            # Remove local feature flags if no longer present.
+            #
+            persisted_flags.each_key do |feature|
+              unless features.include?(feature.to_sym)
+                persisted_flags.delete(feature)
+              end
+            end
+          else
+            feature_flag_adapter.create(@parent, **features)
+          end
+        end
+
+        def fetch_feature_flag_value(name, *args, raw: false)
+          if !raw && persisted?(name)
+            if feature_flag_has_block?(name)
+              persisted(name) && super(name, *args)
+            else
+              persisted(name)
+            end
+          else
+            super(name, *args)
+          end
+        end
+
+        private def feature_flag_has_block?(name)
+          internal_feature_delegator.method(name).arity > 0
+        end
+      end
+    end
+  end
+end

data/lib/featuring/persistence/transaction.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "featuring/persistence"
+
+module Featuring
+  module Persistence
+    # [public] Persist multiple feature flag values for an object at once.
+    #
+    #   class User < ActiveRecord::Base
+    #     extend Featuring::Persistence::ActiveRecord
+    #
+    #     extend Featuring::Declarable
+    #     feature :feature_1
+    #     feature :feature_2
+    #   end
+    #
+    #   User.find(1).features.transaction do |features|
+    #     features.enable :feature_1
+    #     features.disable :feature_2
+    #   end
+    #
+    #   User.find(1).features.feature_1?
+    #   => true
+    #
+    #   User.find(1).features.feature_2?
+    #   => false
+    #
+    class Transaction
+      attr_reader :values
+
+      def initialize(features)
+        @features = features
+        @values = {}
+      end
+
+      # [public] Persist the default or computed value for a feature flag within a transaction.
+      #
+      # See `Featuring::Persistence::Adapter::Methods#persist`.
+      #
+      def persist(feature, *args)
+        @values[feature.to_sym] = @features.fetch_feature_flag_value(feature, *args, raw: true)
+      end
+
+      # [public] Set the value for a feature flag within a transaction.
+      #
+      # See `Featuring::Persistence::Adapter::Methods#set`.
+      #
+      def set(feature, value)
+        @values[feature.to_sym] = !!value
+      end
+
+      # [public] Enable a feature flag.
+      #
+      # See `Featuring::Persistence::Adapter::Methods#enable`.
+      #
+      def enable(feature)
+        @values[feature.to_sym] = true
+      end
+
+      # [public] Disable a feature flag.
+      #
+      # See `Featuring::Persistence::Adapter::Methods#disable`.
+      #
+      def disable(feature)
+        @values[feature.to_sym] = false
+      end
+
+      # [public] Reset a feature flag.
+      #
+      # See `Featuring::Persistence::Adapter::Methods#reset`.
+      #
+      def reset(feature)
+        @values.delete(feature.to_sym)
+      end
+    end
+  end
+end

data/lib/featuring/persistence.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Featuring
+  # [public] Concerns related to persisting feature flag values.
+  #
+  #   * See `Featuring::Persistence::ActiveRecord` to learn how to use the ActiveRecord adapter.
+  #   * See `Featuring::Persistence::Adapter::Methods` to learn how to use persistence.
+  #   * See `Featuring::Persistence::Transaction` to learn how to persist multiple flags at once.
+  #   * See `Featuring::Persistence::Adapter` to learn how to build your own adapter.
+  #
+  module Persistence
+  end
+end

data/lib/featuring/serializable.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Featuring
+  # [public] Concerns related to serializing feature flags and their values.
+  #
+  module Serializable
+    # [public] Returns serialized feature flags (see `Featuring::Serializable::Serializer`).
+    #
+    #   module Features
+    #     extend Featuring::Declarable
+    #
+    #     feature :some_feature, true
+    #   end
+    #
+    #   Features.serialize
+    #   => {
+    #     some_feature: true
+    #   }
+    #
+    def serialize
+      serializer = Serializer.new(self)
+      yield serializer if block_given?
+      serializer.to_h
+    end
+
+    # [public] Feature flag serialization context (intended to be used through `Featuring::Serializable#serialize`).
+    #
+    class Serializer
+      def initialize(features)
+        @features = features
+        @included = []
+        @excluded = []
+        @context = {}
+      end
+
+      # Include only specific feature flags in the serialized result.
+      #
+      #   module Features
+      #     extend Featuring::Declarable
+      #
+      #     feature :feature_1, true
+      #     feature :feature_2, true
+      #     feature :feature_3, true
+      #   end
+      #
+      #   Features.serialize do |serializer|
+      #     serializer.include :feature_1, :feature_3
+      #   end
+      #   => {
+      #     feature_1: true,
+      #     feature_2: true
+      #   }
+      #
+      def include(*feature_flags)
+        @included.concat(feature_flags)
+      end
+
+      # [public] Exclude specific feature flags in the serialized result.
+      #
+      # @example
+      #   module Features
+      #     extend Featuring::Declarable
+      #
+      #     feature :feature_1, true
+      #     feature :feature_2, true
+      #     feature :feature_3, true
+      #   end
+      #
+      #   Features.serialize do |serializer|
+      #     serializer.exclude :feature_1, :feature_3
+      #   end
+      #   => {
+      #     feature_2: true
+      #   }
+      #
+      def exclude(*feature_flags)
+        @excluded.concat(feature_flags)
+      end
+
+      # [public] Provide context for serializing complex feature flags.
+      #
+      #   module Features
+      #     extend Featuring::Declarable
+      #
+      #     feature :some_complex_feature do |value|
+      #       value == :some_value
+      #     end
+      #   end
+      #
+      #   Features.serialize do |serializer|
+      #     serializer.context :some_complex_feature, :some_value
+      #   end
+      #   => {
+      #     some_complex_feature: true
+      #   }
+      #
+      def context(feature_flag, *args)
+        @context[feature_flag] = args
+      end
+
+      # [public] Returns a hash representation of feature flags.
+      #
+      def to_h
+        @features.feature_flags.each_with_object({}) { |feature_flag, serialized|
+          if serializable?(feature_flag)
+            serialized[feature_flag] = @features.fetch_feature_flag_value(feature_flag, *@context[feature_flag])
+          end
+        }
+      end
+
+      private def serializable?(feature_flag)
+        included?(feature_flag) && !excluded?(feature_flag)
+      end
+
+      private def included?(feature_flag)
+        @included.empty? || @included.include?(feature_flag)
+      end
+
+      private def excluded?(feature_flag)
+        @excluded.any? && @excluded.include?(feature_flag)
+      end
+    end
+  end
+end

data/lib/featuring/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Featuring
+  VERSION = "1.0.0"
+
+  def self.version
+    VERSION
+  end
+end

data/lib/featuring.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Attach feature flags to your objects.
+#
+#   * See `Featuring::Declarable` for how to define and check feature flags.
+#   * See `Featuring::Persistence` for how to persist feature flag values.
+#
+module Featuring
+  require_relative "featuring/declarable"
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: featuring
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Bryan Powell
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-09-17 00:00:00.000000000 Z
+dependencies: []
+description: Feature flags for Ruby objects.
+email: bryan@metabahn.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/featuring.rb
+- lib/featuring/declarable.rb
+- lib/featuring/delegatable.rb
+- lib/featuring/flaggable.rb
+- lib/featuring/persistence.rb
+- lib/featuring/persistence/activerecord.rb
+- lib/featuring/persistence/adapter.rb
+- lib/featuring/persistence/transaction.rb
+- lib/featuring/serializable.rb
+- lib/featuring/version.rb
+homepage: https://github.com/metabahn/featuring/
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: Feature flags for Ruby objects.
+test_files: []