simple_feature_flags 1.2.0 → 1.4.0

data/lib/simple_feature_flags/base_storage.rb

@@ -0,0 +1,332 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'yaml'
+
+module SimpleFeatureFlags
+  # Abstract class for all storage adapters.
+  class BaseStorage
+    extend T::Sig
+    extend T::Helpers
+
+    abstract!
+
+    # Path to the file with feature flags
+    sig { abstract.returns(String) }
+    def file; end
+
+    sig { abstract.returns(T::Array[String]) }
+    def mandatory_flags; end
+
+    # Checks whether the flag is active. Returns `true`, `false`, `:globally` or `:partially`
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T.any(Symbol, T::Boolean)) }
+    def active(feature); end
+
+    # Checks whether the flag is active.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def active?(feature); end
+
+    # Checks whether the flag is inactive.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def inactive?(feature); end
+
+    # Checks whether the flag is active globally, for every object.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def active_globally?(feature); end
+
+    # Checks whether the flag is inactive globally, for every object.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def inactive_globally?(feature); end
+
+    # Checks whether the flag is active partially, only for certain objects.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def active_partially?(feature); end
+
+    # Checks whether the flag is inactive partially, only for certain objects.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def inactive_partially?(feature); end
+
+    # Checks whether the flag is active for the given object.
+    sig do
+      abstract
+        .params(
+          feature:          T.any(Symbol, String),
+          object:           Object,
+          object_id_method: Symbol,
+        )
+        .returns(T::Boolean)
+    end
+    def active_for?(feature, object, object_id_method: :id); end
+
+    # Checks whether the flag is inactive for the given object.
+    sig do
+      abstract
+        .params(
+          feature:          T.any(Symbol, String),
+          object:           Object,
+          object_id_method: Symbol,
+        )
+        .returns(T::Boolean)
+    end
+    def inactive_for?(feature, object, object_id_method: :id); end
+
+    # Checks whether the flag exists.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def exists?(feature); end
+
+    # Returns the description of the flag if it exists.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T.nilable(String)) }
+    def description(feature); end
+
+    # Calls the given block if the flag is active.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_active(feature, &block); end
+
+    # Calls the given block if the flag is inactive.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_inactive(feature, &block); end
+
+    # Calls the given block if the flag is active globally.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_active_globally(feature, &block); end
+
+    # Calls the given block if the flag is inactive globally.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_inactive_globally(feature, &block); end
+
+    # Calls the given block if the flag is active partially.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_active_partially(feature, &block); end
+
+    # Calls the given block if the flag is inactive partially.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.void,
+        ).void
+    end
+    def when_inactive_partially(feature, &block); end
+
+    # Calls the given block if the flag is active for the given object.
+    sig do
+      abstract
+        .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); end
+
+    # Calls the given block if the flag is inactive for the given object.
+    sig do
+      abstract
+        .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); end
+
+    # Activates the given flag. Returns `false` if it does not exist.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def activate(feature); end
+
+    # Activates the flag, calls the block and restores the previous state of the flag.
+    sig do
+      abstract
+        .type_parameters(:R)
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.returns(T.type_parameter(:R)),
+        )
+        .returns(T.type_parameter(:R))
+    end
+    def do_activate(feature, &block); end
+
+    # Activates the given flag globally. Returns `false` if it does not exist.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def activate_globally(feature); end
+
+    # Activates the flag globally, calls the block and restores the previous state of the flag.
+    sig do
+      abstract
+        .type_parameters(:R)
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.returns(T.type_parameter(:R)),
+        )
+        .returns(T.type_parameter(:R))
+    end
+    def do_activate_globally(feature, &block); end
+
+    # Activates the given flag partially. Returns `false` if it does not exist.
+    sig { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def activate_partially(feature); end
+
+    # Activates the flag partially, calls the block and restores the previous state of the flag.
+    sig do
+      abstract
+        .type_parameters(:R)
+        .params(
+          feature: T.any(Symbol, String),
+          block:   T.proc.returns(T.type_parameter(:R)),
+        )
+        .returns(T.type_parameter(:R))
+    end
+    def do_activate_partially(feature, &block); end
+
+    # Activates the given flag for the given objects. Returns `false` if it does not exist.
+    sig do
+      abstract
+        .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); end
+
+    # Activates the given flag for the given objects and sets the flag as partially active.
+    # Returns `false` if it does not exist.
+    sig do
+      abstract
+        .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); 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 { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def deactivate!(feature); 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 { abstract.params(feature: T.any(Symbol, String)).returns(T::Boolean) }
+    def deactivate(feature); 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
+      abstract
+        .params(feature: T.any(Symbol, String))
+        .returns(T::Hash[String, T::Array[Object]])
+    end
+    def active_objects(feature); end
+
+    # Deactivates the given flag for the given objects. Returns `false` if it does not exist.
+    sig do
+      abstract
+        .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); end
+
+    # Returns the data of the flag in a hash.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+        ).returns(T.nilable(T::Hash[String, T.anything]))
+    end
+    def get(feature); end
+
+    # Adds the given feature flag.
+    sig do
+      abstract
+        .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'); end
+
+    # Removes the given feature flag.
+    # Returns its data or nil if it does not exist.
+    sig do
+      abstract
+        .params(
+          feature: T.any(Symbol, String),
+        ).returns(T.nilable(T::Hash[String, T.anything]))
+    end
+    def remove(feature); end
+
+    # Returns the data of all feature flags.
+    sig do
+      abstract.returns(T::Array[T::Hash[String, T.anything]])
+    end
+    def all; end
+
+    private
+
+    sig { params(objects: T::Array[Object], object_id_method: Symbol).returns(T::Hash[String, T::Array[Object]]) }
+    def objects_to_hash(objects, object_id_method: CONFIG.default_id_method)
+      objects.group_by { |ob| ob.class.to_s }
+             .transform_values { |arr| arr.map(&object_id_method) }
+    end
+
+    sig { void }
+    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
+    end
+  end
+end

data/lib/simple_feature_flags/cli/command/generate.rb

@@ -1,3 +1,4 @@
+# typed: true
 # frozen_string_literal: true
 
 require 'fileutils'
@@ -5,15 +6,21 @@ require 'fileutils'
 module SimpleFeatureFlags
   module Cli
     module Command
+      # Implements the `generate` CLI command
       class Generate
-        CONFIG_FILE = 'simple_feature_flags.yml'
+        extend T::Sig
 
+        CONFIG_FILE = T.let('simple_feature_flags.yml', String)
+
+        sig { returns(Options) }
         attr_reader :options
 
+        sig { params(options: Options).void }
         def initialize(options)
           @options = options
         end
 
+        sig { void }
         def run
           if options.rails
             generate_for_rails
@@ -29,10 +36,11 @@ module SimpleFeatureFlags
 
         private
 
+        sig { void }
         def generate_for_rails
           ::FileUtils.cp_r example_config_dir, destination_dir
 
-          puts "Generated:"
+          puts 'Generated:'
           puts '----------'
           puts "- #{::File.join(destination_dir, 'config')}"
           print_dir_tree(example_config_dir, 1)
@@ -62,21 +70,30 @@ module SimpleFeatureFlags
           system 'bundle'
         end
 
+        sig do
+          params(
+            file_path: String,
+            regexp:    Regexp,
+            block:     T.proc.params(arg0: String).returns(String),
+          ).void
+        end
         def file_gsub(file_path, regexp, &block)
           new_content = File.read(file_path).gsub(regexp, &block)
-          File.open(file_path, 'wb') { |file| file.write(new_content) }
+          File.binwrite(file_path, new_content)
         end
 
+        sig { params(file_path: String, line: String).void }
         def file_append(file_path, line)
           new_content = File.read(file_path)
           new_content = "#{new_content}\n#{line}\n"
-          File.open(file_path, 'wb') { |file| file.write(new_content) }
+          File.binwrite(file_path, new_content)
         end
 
+        sig { params(dir: String, embed_level: Integer).void }
         def print_dir_tree(dir, embed_level = 0)
           padding = ' ' * (embed_level * 2)
 
-          children = ::Dir.new(dir).entries.reject { |el| /^\.{1,2}$/ =~ el }
+          children = ::Dir.new(dir).entries.grep_v(/^\.{1,2}$/)
 
           children.each do |child|
             child_dir = ::File.join(dir, child)
@@ -88,32 +105,42 @@ module SimpleFeatureFlags
           end
         end
 
+        sig { returns String }
         def initializer_file
           ::File.join(destination_dir, 'config', 'initializers', 'simple_feature_flags.rb')
         end
 
+        sig { returns String }
         def gemfile
           ::File.join(destination_dir, 'Gemfile')
         end
 
+        sig { returns String }
         def routes_rb
           ::File.join(destination_dir, 'config', 'routes.rb')
         end
 
+        sig { returns String }
         def example_config_dir
           ::File.join(::File.expand_path(__dir__), '..', '..', '..', 'example_files', 'config')
         end
 
+        sig { returns String }
         def example_config_file
           ::File.join(example_config_dir, CONFIG_FILE)
         end
 
+        sig { returns String }
         def destination_dir
-          raise IncorrectWorkingDirectoryError, "You should enter the main directory of your Rails project!" if options.rails && !::Dir.new(::Dir.pwd).entries.include?('config')
+          if options.rails && !::Dir.new(::Dir.pwd).entries.include?('config')
+            raise IncorrectWorkingDirectoryError,
+                  'You should enter the main directory of your Rails project!'
+          end
 
           ::Dir.pwd
         end
 
+        sig { returns String }
         def destination_file
           @destination_file ||= ::File.join(destination_dir, CONFIG_FILE)
         end

data/lib/simple_feature_flags/cli/command.rb

@@ -1,9 +1,11 @@
+# typed: true
 # frozen_string_literal: true
 
 module SimpleFeatureFlags
   module Cli
+    # Contains CLI commands
     module Command; end
   end
 end
 
-Dir[File.expand_path('command/*.rb', __dir__)].sort.each { |file| require file }
+Dir[File.expand_path('command/*.rb', __dir__)].each { |file| require file }

data/lib/simple_feature_flags/cli/options.rb

@@ -1,15 +1,31 @@
+# typed: true
 # frozen_string_literal: true
 
 require 'optparse'
 
 module SimpleFeatureFlags
   module Cli
+    # Parses CLI options.
     class Options
-      attr_reader :opt_parser, :generate, :help, :rails, :ui
+      extend T::Sig
 
+      sig { returns(OptionParser) }
+      attr_reader :opt_parser
+
+      sig { returns(T::Boolean) }
+      attr_reader :generate
+
+      sig { returns(T::Boolean) }
+      attr_reader :rails
+
+      sig { returns(T::Boolean) }
+      attr_reader :ui
+
+      sig { params(args: T::Array[String]).void }
       def initialize(args)
-        @rails = true
-        @ui = false
+        @rails = T.let(true, T::Boolean)
+        @ui = T.let(false, T::Boolean)
+        @generate = T.let(false, T::Boolean)
 
         @opt_parser = ::OptionParser.new do |opts|
           opts.banner = 'Usage: simple_feature_flags [options]'

data/lib/simple_feature_flags/cli/runner.rb

@@ -1,20 +1,28 @@
+# typed: true
 # frozen_string_literal: true
 
 module SimpleFeatureFlags
   module Cli
+    # Runs CLI commands
     class Runner
+      extend T::Sig
+
+      sig { returns(Options) }
       attr_reader :options
 
+      sig { params(args: T::Array[String]).void }
       def initialize(args = ARGV)
         @options = Options.new(args)
       end
 
+      sig { void }
       def run
-        command_class = if @options.generate
-                          ::SimpleFeatureFlags::Cli::Command::Generate
-                        else
-                          raise NoSuchCommandError, 'No such command!'
-                        end
+        command_class =
+          if @options.generate
+            ::SimpleFeatureFlags::Cli::Command::Generate
+          else
+            raise NoSuchCommandError, 'No such command!'
+          end
 
         command_class.new(options).run
       end

data/lib/simple_feature_flags/cli.rb

@@ -1,7 +1,9 @@
+# typed: true
 # frozen_string_literal: true
 
 module SimpleFeatureFlags
+  # Handles the CLI
   module Cli; end
 end
 
-Dir[File.expand_path('cli/*.rb', __dir__)].sort.each { |file| require file }
+Dir[File.expand_path('cli/*.rb', __dir__)].each { |file| require file }

data/lib/simple_feature_flags/configuration.rb

@@ -1,9 +1,15 @@
+# typed: true
 # frozen_string_literal: true
 
 module SimpleFeatureFlags
+  # The main configuration object of the library.
   class Configuration
+    extend T::Sig
+
+    sig { returns(Symbol) }
     attr_accessor :default_id_method
 
+    sig { void }
     def initialize
       @default_id_method = :id
     end