simple_feature_flags 1.2.0 → 1.3.0

data/lib/simple_feature_flags/redis_storage.rb

@@ -1,11 +1,21 @@
+# typed: true
 # frozen_string_literal: true
 
 require 'yaml'
 
 module SimpleFeatureFlags
-  class RedisStorage
-    attr_reader :file, :redis, :mandatory_flags
+  # Stores feature flags in Redis.
+  class RedisStorage < BaseStorage
+    sig { override.returns(String) }
+    attr_reader :file
 
+    sig { override.returns(T::Array[String]) }
+    attr_reader :mandatory_flags
+
+    sig { returns(T.any(::Redis, ::Redis::Namespace)) }
+    attr_reader :redis
+
+    sig { params(redis: T.any(::Redis, ::Redis::Namespace), file: String).void }
     def initialize(redis, file)
       @file = file
       @redis = redis
@@ -14,46 +24,70 @@ module SimpleFeatureFlags
       import_flags_from_file
     end
 
+    # Checks whether the flag is active. Returns `true`, `false`, `:globally` or `:partially`
+    sig { override.params(feature: T.any(Symbol, String)).returns(T.any(Symbol, T::Boolean)) }
     def active(feature)
       case redis.hget(feature.to_s, 'active')
       when 'globally'
         :globally
       when 'partially'
         :partially
-      when 'true'
+      when 'true', true
         true
-      when 'false'
+      else
         false
       end
     end
 
+    # Checks whether the flag is active.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def active?(feature)
       return true if active(feature)
 
       false
     end
 
+    # Checks whether the flag is inactive.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def inactive?(feature)
       !active?(feature)
     end
 
+    # Checks whether the flag is active globally, for every object.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def active_globally?(feature)
       ACTIVE_GLOBALLY.include? redis.hget(feature.to_s, 'active')
     end
 
+    # Checks whether the flag is inactive globally, for every object.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def inactive_globally?(feature)
       !active_globally?(feature)
     end
 
+    # Checks whether the flag is active partially, only for certain objects.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def active_partially?(feature)
       ACTIVE_PARTIALLY.include? redis.hget(feature.to_s, 'active')
     end
 
+    # Checks whether the flag is inactive partially, only for certain objects.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def inactive_partially?(feature)
       !active_partially?(feature)
     end
 
-    def active_for?(feature, object, object_id_method = CONFIG.default_id_method)
+    # Checks whether the flag is active for the given object.
+    sig do
+      override
+        .params(
+          feature:          T.any(Symbol, String),
+          object:           Object,
+          object_id_method: Symbol,
+        )
+        .returns(T::Boolean)
+    end
+    def active_for?(feature, object, object_id_method: CONFIG.default_id_method)
       return false unless active?(feature)
       return true if active_globally?(feature)
 
@@ -65,68 +99,152 @@ module SimpleFeatureFlags
       active_ids.include? object.public_send(object_id_method)
     end
 
-    def inactive_for?(feature, object, object_id_method = CONFIG.default_id_method)
-      !active_for?(feature, object, object_id_method)
+    # Checks whether the flag is inactive for the given object.
+    sig do
+      override
+        .params(
+          feature:          T.any(Symbol, String),
+          object:           Object,
+          object_id_method: Symbol,
+        )
+        .returns(T::Boolean)
+    end
+    def inactive_for?(feature, object, object_id_method: CONFIG.default_id_method)
+      !active_for?(feature, object, object_id_method: object_id_method)
     end
 
+    # Checks whether the flag exists.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def exists?(feature)
       return false if [nil, ''].include? redis.hget(feature.to_s, 'name')
 
       true
     end
 
+    # Returns the description of the flag if it exists.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T.nilable(String)) }
     def description(feature)
       redis.hget(feature.to_s, 'description')
     end
 
-    def when_active(feature)
+    # Calls the given block if the flag is active.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_active(feature, &block)
       return unless active?(feature)
 
-      yield
+      block.call
     end
 
-    def when_inactive(feature)
+    # Calls the given block if the flag is inactive.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_inactive(feature, &block)
       return unless inactive?(feature)
 
-      yield
+      block.call
     end
 
-    def when_active_globally(feature)
+    # Calls the given block if the flag is active globally.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_active_globally(feature, &block)
       return unless active_globally?(feature)
 
-      yield
+      block.call
     end
 
-    def when_inactive_globally(feature)
+    # Calls the given block if the flag is inactive globally.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_inactive_globally(feature, &block)
       return unless inactive_globally?(feature)
 
-      yield
+      block.call
     end
 
-    def when_active_partially(feature)
+    # Calls the given block if the flag is active partially.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_active_partially(feature, &block)
       return unless active_partially?(feature)
 
-      yield
+      block.call
     end
 
-    def when_inactive_partially(feature)
+    # Calls the given block if the flag is inactive partially.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_inactive_partially(feature, &block)
       return unless inactive_partially?(feature)
 
-      yield
+      block.call
     end
 
-    def when_active_for(feature, object, object_id_method = CONFIG.default_id_method)
-      return unless active_for?(feature, object, object_id_method)
+    # Calls the given block if the flag is active for the given object.
+    sig do
+      override
+        .params(
+          feature:          T.any(Symbol, String),
+          object:           Object,
+          object_id_method: Symbol,
+          block:            T.proc.void,
+        ).void
+    end
+    def when_active_for(feature, object, object_id_method: CONFIG.default_id_method, &block)
+      return unless active_for?(feature, object, object_id_method: object_id_method)
 
-      yield
+      block.call
     end
 
-    def when_inactive_for(feature, object, object_id_method = CONFIG.default_id_method)
-      return unless inactive_for?(feature, object, object_id_method)
+    # Calls the given block if the flag is inactive for the given object.
+    sig do
+      override
+        .params(
+          feature:          T.any(Symbol, String),
+          object:           Object,
+          object_id_method: Symbol,
+          block:            T.proc.void,
+        ).void
+    end
+    def when_inactive_for(feature, object, object_id_method: CONFIG.default_id_method, &block)
+      return unless inactive_for?(feature, object, object_id_method: object_id_method)
 
-      yield
+      block.call
     end
 
+    # Activates the given flag. Returns `false` if it does not exist.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def activate(feature)
       return false unless exists?(feature)
 
@@ -137,6 +255,8 @@ module SimpleFeatureFlags
 
     alias activate_globally activate
 
+    # Activates the given flag partially. Returns `false` if it does not exist.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def activate_partially(feature)
       return false unless exists?(feature)
 
@@ -145,17 +265,25 @@ module SimpleFeatureFlags
       true
     end
 
-    def activate_for(feature, objects, object_id_method = CONFIG.default_id_method)
+    # Activates the given flag for the given objects. Returns `false` if it does not exist.
+    sig do
+      override
+        .params(
+          feature:          T.any(Symbol, String),
+          objects:          Object,
+          object_id_method: Symbol,
+        ).void
+    end
+    def activate_for(feature, *objects, object_id_method: CONFIG.default_id_method)
       return false unless exists?(feature)
 
-      objects = [objects] unless objects.is_a? ::Array
-      to_activate_hash = objects_to_hash(objects, object_id_method)
+      to_activate_hash = objects_to_hash(objects, object_id_method: object_id_method)
       active_objects_hash = active_objects(feature)
 
       to_activate_hash.each do |klass, ids|
         (active_objects_hash[klass] = ids) && next unless active_objects_hash[klass]
 
-        active_objects_hash[klass].concat(ids).uniq!.sort!
+        active_objects_hash[klass]&.concat(ids)&.uniq!&.sort! # rubocop:disable Style/SafeNavigationChainLength
       end
 
       redis.hset(feature.to_s, 'active_for_objects', active_objects_hash.to_json)
@@ -163,12 +291,26 @@ module SimpleFeatureFlags
       true
     end
 
-    def activate_for!(feature, objects, object_id_method = CONFIG.default_id_method)
-      return false unless activate_for(feature, objects, object_id_method)
+    # Activates the given flag for the given objects and sets the flag as partially active.
+    # Returns `false` if it does not exist.
+    sig do
+      override
+        .params(
+          feature:          T.any(Symbol, String),
+          objects:          Object,
+          object_id_method: Symbol,
+        ).void
+    end
+    def activate_for!(feature, *objects, object_id_method: CONFIG.default_id_method)
+      return false unless T.unsafe(self).activate_for(feature, *objects, object_id_method: object_id_method)
 
       activate_partially(feature)
     end
 
+    # Deactivates the given flag for all objects.
+    # Resets the list of objects that this flag has been turned on for.
+    # Returns `false` if it does not exist.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def deactivate!(feature)
       return false unless exists?(feature)
 
@@ -178,6 +320,10 @@ module SimpleFeatureFlags
       true
     end
 
+    # Deactivates the given flag globally.
+    # Does not reset the list of objects that this flag has been turned on for.
+    # Returns `false` if it does not exist.
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def deactivate(feature)
       return false unless exists?(feature)
 
@@ -186,18 +332,39 @@ module SimpleFeatureFlags
       true
     end
 
+    # Returns a hash of Objects that the given flag is turned on for.
+    # The keys are class/model names, values are arrays of IDs of instances/records.
+    #
+    # looks like this:
+    #
+    #      { "Page" => [25, 89], "Book" => [152] }
+    #
+    sig do
+      override
+        .params(feature: T.any(Symbol, String))
+        .returns(T::Hash[String, T::Array[Object]])
+    end
     def active_objects(feature)
       ::JSON.parse(redis.hget(feature.to_s, 'active_for_objects').to_s)
     rescue ::JSON::ParserError
       {}
     end
 
-    def deactivate_for(feature, objects, object_id_method = CONFIG.default_id_method)
+    # Deactivates the given flag for the given objects. Returns `false` if it does not exist.
+    sig do
+      override
+        .params(
+          feature:          T.any(Symbol, String),
+          objects:          Object,
+          object_id_method: Symbol,
+        ).void
+    end
+    def deactivate_for(feature, *objects, object_id_method: CONFIG.default_id_method)
       return false unless exists?(feature)
 
       active_objects_hash = active_objects(feature)
 
-      objects_to_deactivate_hash = objects_to_hash(objects, object_id_method)
+      objects_to_deactivate_hash = objects_to_hash(objects, object_id_method: object_id_method)
 
       objects_to_deactivate_hash.each do |klass, ids_to_remove|
         active_ids = active_objects_hash[klass]
@@ -211,18 +378,38 @@ module SimpleFeatureFlags
       true
     end
 
+    # Returns the data of the flag in a hash.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+        ).returns(T.nilable(T::Hash[String, T.anything]))
+    end
     def get(feature)
       return unless exists?(feature)
 
       hash = redis.hgetall(feature.to_s)
       hash['mandatory'] = mandatory_flags.include?(feature.to_s)
-      hash['active_for_objects'] = ::JSON.parse(hash['active_for_objects']) rescue {}
+      hash['active_for_objects'] = begin
+        ::JSON.parse(hash['active_for_objects'])
+      rescue StandardError
+        {}
+      end
 
       hash
     end
 
+    # Adds the given feature flag.
+    sig do
+      override
+        .params(
+          feature:     T.any(Symbol, String),
+          description: String,
+          active:      T.any(String, Symbol, T::Boolean, NilClass),
+        ).returns(T.nilable(T::Hash[String, T.anything]))
+    end
     def add(feature, description, active = 'false')
-      return false if exists?(feature)
+      return if exists?(feature)
 
       active = if ACTIVE_GLOBALLY.include?(active)
                  'globally'
@@ -233,17 +420,25 @@ module SimpleFeatureFlags
                end
 
       hash = {
-        'name' => feature.to_s,
-        'active' => active,
-        'description' => description
+        'name'        => feature.to_s,
+        'active'      => active,
+        'description' => description,
       }
 
       redis.hset(feature.to_s, hash)
       hash
     end
 
+    # Removes the given feature flag.
+    # Returns its data or nil if it does not exist.
+    sig do
+      override
+        .params(
+          feature: T.any(Symbol, String),
+        ).returns(T.nilable(T::Hash[String, T.anything]))
+    end
     def remove(feature)
-      return false unless exists?(feature)
+      return unless exists?(feature)
 
       removed = get(feature)
       redis.del(feature.to_s)
@@ -251,10 +446,14 @@ module SimpleFeatureFlags
       removed
     end
 
+    # Returns the data of all feature flags.
+    sig do
+      override.returns(T::Array[T::Hash[String, T.anything]])
+    end
     def all
       keys = []
       hashes = []
-      redis.scan_each(match: "*") do |key|
+      redis.scan_each(match: '*') do |key|
         next if keys.include?(key)
 
         keys << key
@@ -264,30 +463,12 @@ module SimpleFeatureFlags
       hashes
     end
 
+    sig { returns(T.nilable(Redis::Namespace)) }
     def namespaced_redis
-      redis
-    end
+      r = redis
+      return unless r.is_a?(Redis::Namespace)
 
-    private
-
-    def objects_to_hash(objects, object_id_method = CONFIG.default_id_method)
-      objects = [objects] unless objects.is_a? ::Array
-
-      objects.group_by { |ob| ob.class.to_s }.transform_values { |arr| arr.map(&object_id_method) }
-    end
-
-    def import_flags_from_file
-      changes = ::YAML.load_file(file)
-      changes = { mandatory: [], remove: [] } unless changes.is_a? ::Hash
-
-      changes[:mandatory].each do |el|
-        mandatory_flags << el['name']
-        add(el['name'], el['description'], el['active'])
-      end
-
-      changes[:remove].each do |el|
-        remove(el)
-      end
+      r
     end
   end
 end

data/lib/simple_feature_flags/test_ram_storage.rb

@@ -1,9 +1,15 @@
+# typed: true
 # frozen_string_literal: true
 
 module SimpleFeatureFlags
+  # Used in tests
   class TestRamStorage < RamStorage
+    sig { override.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
     def active?(feature)
-      raise(FlagNotDefinedError, "Feature Flag `#{feature}` is not defined as mandatory in #{file}") unless mandatory_flags.include?(feature.to_s)
+      unless mandatory_flags.include?(feature.to_s)
+        raise(FlagNotDefinedError,
+              "Feature Flag `#{feature}` is not defined as mandatory in #{file}",)
+      end
 
       super
     end

data/lib/simple_feature_flags/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleFeatureFlags
-  VERSION = "1.2.0"
+  VERSION = '1.3.0'
 end

data/lib/simple_feature_flags.rb

@@ -1,17 +1,24 @@
+# typed: true
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
+require 'sorbet-runtime'
 
-Dir[File.expand_path('simple_feature_flags/*.rb', __dir__)].sort.each { |file| require file }
+Dir[File.expand_path('simple_feature_flags/*.rb', __dir__)].each { |file| require file }
 
+# Tha main namespace of the `simple_feature_flags` gem.
 module SimpleFeatureFlags
+  extend T::Sig
+
   NOT_PRESENT = ::Object.new.freeze
-  UI_GEM = 'simple_feature_flags-ui'
-  UI_CLASS_NAME = '::SimpleFeatureFlags::Ui'
-  WEB_UI_CLASS_NAME = '::SimpleFeatureFlags::Ui::Web'
+  UI_GEM = T.let('simple_feature_flags-ui', String)
+  UI_CLASS_NAME = T.let('::SimpleFeatureFlags::Ui', String)
+  WEB_UI_CLASS_NAME = T.let('::SimpleFeatureFlags::Ui::Web', String)
 
-  ACTIVE_GLOBALLY = ::Set['globally', :globally, 'true', true].freeze
-  ACTIVE_PARTIALLY = ::Set['partially', :partially].freeze
+  ACTIVE_GLOBALLY = T.let(::Set['globally', :globally, 'true', true].freeze,
+                          T::Set[T.any(String, Symbol, T::Boolean, NilClass)],)
+  ACTIVE_PARTIALLY = T.let(::Set['partially', :partially].freeze, T::Set[T.any(String, Symbol, T::Boolean, NilClass)])
 
   class NoSuchCommandError < StandardError; end
 
@@ -19,9 +26,15 @@ module SimpleFeatureFlags
 
   class FlagNotDefinedError < StandardError; end
 
-  CONFIG = Configuration.new
+  CONFIG = T.let(Configuration.new, Configuration)
+
+  class << self
+    extend T::Sig
 
-  def self.configure(&block)
-    block.call(CONFIG)
+    sig { params(block: T.proc.params(arg0: Configuration).void).returns(Configuration) }
+    def configure(&block)
+      block.call(CONFIG)
+      CONFIG
+    end
   end
 end

data/simple_feature_flags.gemspec

@@ -3,36 +3,31 @@
 require_relative 'lib/simple_feature_flags/version'
 
 ::Gem::Specification.new do |spec|
-  spec.name          = "simple_feature_flags"
+  spec.name          = 'simple_feature_flags'
   spec.version       = ::SimpleFeatureFlags::VERSION
-  spec.authors       = ["Espago", "Mateusz Drewniak"]
-  spec.email         = ["m.drewniak@espago.com"]
+  spec.authors       = ['Espago', 'Mateusz Drewniak']
+  spec.email         = ['m.drewniak@espago.com']
 
-  spec.summary       = "Simple feature flag functionality for your Ruby/Rails/Sinatra app!"
-  spec.description   = "A simple Ruby gem which lets you dynamically enable/disable parts of your code using Redis or your server's RAM!"
-  spec.homepage      = "https://github.com/espago/simple_feature_flags"
-  spec.license       = "MIT"
-  spec.required_ruby_version = ::Gem::Requirement.new(">= 2.5.0")
+  spec.summary       = 'Simple feature flag functionality for your Ruby/Rails/Sinatra app!'
+  spec.description   = <<~DESC
+    A simple Ruby gem which lets you dynamically enable/disable parts of your code using Redis or your server's RAM!
+  DESC
+  spec.homepage      = 'https://github.com/espago/simple_feature_flags'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/espago/simple_feature_flags"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/espago/simple_feature_flags'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = ::Dir.chdir(::File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|sorbet)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = ['simple_feature_flags']
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'bundler-audit'
-  spec.add_development_dependency 'byebug'
-  spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'rake', '~> 12.0'
-  spec.add_development_dependency 'redis'
-  spec.add_development_dependency 'redis-namespace'
-  spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'solargraph'
+  spec.add_dependency 'sorbet-runtime', '> 0.5'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end