cache_box 0.0.1.pre.preview2 → 0.0.1.pre.preview7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffc75a2d7008957a8c53dabf66772390d5eca8e964f6ab92f35fe57c063d5e52
-  data.tar.gz: 28c08be79e3a089f14897a42805a3a3b0b12f44a49c8fda8bc81884763aacc72
+  metadata.gz: e95404d4c91af3089b9d7d5628a3449010007df8784043b3668bc028b3b54c44
+  data.tar.gz: f8fd2afe635ceab0504a2c2aef6b4a27417ad5bdde6564a7a39fd8af9b22840d
 SHA512:
-  metadata.gz: 948602c9c4a3aac655c6a2c13a8284d92f9da2246a7b901133c050adb2119ceadb4936fe750cb27ab5d5afe383326e2e02cf623fb5c3d5145acb6a9dce289aa2
-  data.tar.gz: c8f3529d877814c4007d31699dabbd4fc375714b52184f36ec6660f3c126463f90afbe522c5e7eee42f62c0495ea9483753f02de66f533297dd855ec0b20f88e
+  metadata.gz: 5c5a41a763a413cef9e294c01e94c18808f3e817bdd4baff7ac4b936225b19f3b7785a43981b9167066123d3fd0d5673e81f5b54c71586a83e64fa39c2907a99
+  data.tar.gz: b2029aca5aa9a5a36a82e7010cb5959787ee214d7a0b1739b8575e95e5c3cfb7a842fde3c9264449d1dcb45dc926180d9eb3bbfd18edcb4b30d0ba2d04a50206

data/cache_box.gemspec

@@ -2,25 +2,33 @@
 
 Gem::Specification.new do |spec|
   spec.name    = 'cache_box'
-  spec.version = '0.0.1-preview2'
+  spec.version = '0.0.1-preview7'
   spec.authors = ['Codruț Constantin Gușoi']
-  spec.email   = ['codrut.gusoi+git-commit@gmail.com']
+  spec.email   = ['codrut.gusoi+rubygems.org@gmail.com']
 
-  spec.summary  = 'A simple, fast, and easy to use file backed cache.'
+  spec.summary  = 'A simple, fast, and easy to use local cache.'
   spec.homepage = 'https://gitlab.com/sdwolfz/cache_box_rb'
-  spec.license  = 'BSD 3-clause'
+  spec.license  = 'BSD-3-Clause'
+
+  spec.metadata = {
+    'homepage_uri'    => 'https://gitlab.com/sdwolfz/cache_box_rb',
+    'source_code_uri' => 'https://gitlab.com/sdwolfz/cache_box_rb'
+  }
 
   spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
 
   spec.files = [
     'lib/cache_box.rb',
-    'lib/cache_box_chain.rb',
+    'lib/cache_box/chain.rb',
+    'lib/cache_box/file_storage.rb',
+    'lib/cache_box/memory_storage.rb',
     'LICENSE',
     'cache_box.gemspec'
   ]
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'rake',     '~> 12.0'
-  spec.add_development_dependency 'rubocop',  '~> 0.88'
+  spec.add_development_dependency 'minitest',   '~> 5.14'
+  spec.add_development_dependency 'pry-byebug', '~> 3.9'
+  spec.add_development_dependency 'rake',       '~> 13.0'
+  spec.add_development_dependency 'rubocop',    '~> 0.88'
 end

data/lib/cache_box.rb

@@ -1,80 +1,123 @@
 # frozen_string_literal: true
 
 require 'fileutils'
-require_relative 'cache_box_chain'
+require 'logger'
 
-class CacheBox
-  def initialize(namespace = :namespace)
-    validate!(namespace, 'namespace')
-
-    @namespace = namespace
-    @state     = {}
-    @root      = File.join(Dir.pwd, '.cache')
-    @directory = File.join(@root, @namespace.to_s)
-  end
-
-  def reset!(namespace = :namespace)
-    initialize(namespace)
+require_relative 'cache_box/chain'
+require_relative 'cache_box/file_storage'
+require_relative 'cache_box/memory_storage'
 
-    self
+class CacheBox
+  # Input:
+  #
+  # namespace = String | Symbol # Default: 'namespace'
+  #
+  # Output: N/A
+  def initialize(namespace = nil, logger: nil, storage: nil)
+    validate_symbol_or_string!(namespace, 'namespace')
+
+    @namespace = namespace&.to_s || 'namespace'
+    @logger    = logger  || Logger.new(STDOUT, level: Logger::INFO)
+    @storage   = storage || FileStorage.new(namespace: @namespace)
+    @state     = { result: {}, stash: {} }
   end
 
-  def with(name = :name, *args)
-    validate!(name, 'name')
-
-    file   = File.join(@directory, name.to_s)
-    result = find(name, file)
-    return result unless result.nil?
+  # Input:
+  #
+  # name   = String | Symbol # Default: 'name'
+  # args   = Array[...Object]
+  # &block = Proc(Hash{...Object => Object}, *args)
+  #
+  # Output: Object # Anything the &block returns.
+  def with(name = nil, *args)
+    validate_symbol_or_string!(name, 'name')
+    unless block_given?
+      raise(ArgumentError, 'The `:with` method requires a block')
+    end
 
-    store(yield(*args), name, file)
-  end
+    name = name&.to_s || 'name'
+    return @state[:result][name] if @state[:result].key?(name)
 
-  def with_many(name = :name, *args)
-    validate!(name, 'name')
+    data = @storage.read!(name)
+    if data&.key?(:result)
+      @state[:result][name] = data[:result]
 
-    file   = File.join(@directory, name.to_s)
-    result = find(name, file)
-    return result unless result.nil?
+      return data[:result]
+    elsif data&.key?(:stash)
+      @state[:stash][name] = data[:stash]
+    end
 
-    storage = {}
+    stash = @state[:stash][name] || {}
     begin
-      yield(storage, *args)
+      @state[:result][name] = yield(stash, *args)
     ensure
-      store(storage, name, file)
+      if @state[:result].key?(name)
+        @state[:stash].delete(name)
+        @storage.write!(name, { result: @state[:result][name] })
+      else
+        @state[:stash][name] = stash
+        @storage.write!(name, { stash: stash })
+      end
     end
-    storage
   end
 
-  def has?(name = :name)
-    validate!(name, 'name')
+  # Input:
+  #
+  # name = String | Symbol # Default: 'name'
+  #
+  # Output: true | false
+  def has?(name = nil)
+    validate_symbol_or_string!(name, 'name')
 
-    file = File.join(@directory, name.to_s)
-    load!(name, file)
+    name = name&.to_s || 'name'
+    return true if @state[:result].key?(name)
 
-    @state.key?(name)
-  end
+    data = @storage.read!(name)
 
-  def expire!
-    @state = {}
-    FileUtils.remove_entry_secure(@directory, true)
+    if data&.key?(:result)
+      @state[:result][name] = data[:result]
+    elsif data&.key?(:stash)
+      @state[:stash][name] = data[:stash]
+    end
 
-    self
+    @state[:result].key?(name)
   end
 
-  def expire(name = :name)
-    validate!(name, 'name')
-
-    @state.delete(name)
-    file = File.join(@directory, name.to_s)
-    FileUtils.remove_entry_secure(file, true)
+  # Input:
+  #
+  # name = Array[String | Symbol] # Default: []
+  #
+  # Output: self
+  def expire!(*names)
+    validate_array_of_symbol_or_string!(names, 'names')
+
+    if names.empty?
+      @state = { result: {}, stash: {} }
+
+      @storage.reset!
+    else
+      names.each do |name|
+        name = name.to_s
+        @state[:result].delete(name)
+        @state[:stash].delete(name)
+
+        @storage.delete!(name)
+      end
+    end
 
     self
   end
 
   private
 
-  def validate!(arg, name)
-    return if arg.is_a?(Symbol) || arg.is_a?(String)
+  # Input:
+  #
+  # arg  = String | Symbol
+  # name = String
+  #
+  # Output: N/A
+  def validate_symbol_or_string!(arg, name)
+    return if arg.nil? || arg.is_a?(Symbol) || arg.is_a?(String)
 
     klass = arg.class
     value = arg.inspect
@@ -82,28 +125,23 @@ class CacheBox
     raise(ArgumentError, "#{name} must be a Symbol or String, got #{klass}: #{value}")
   end
 
-  def load!(name, file)
-    return unless @state[name].nil? && File.exist?(file)
-
-    content      = File.read(file)
-    @state[name] = Marshal.load(content)
-  end
-
-  def find(name, file)
-    load!(name, file)
-
-    @state[name]
-  end
-
-  def store(value, name, file)
-    @state[name] = value
-
-    content = Marshal.dump(value)
-
-    directory = File.dirname(file)
-    FileUtils.mkdir_p(directory) unless Dir.exist?(directory)
-    File.write(file, content)
-
-    value
+  # Input:
+  #
+  # arg  = Array[String | Symbol]
+  # name = String
+  #
+  # Output: N/A
+  def validate_array_of_symbol_or_string!(args, name)
+    args.each do |arg|
+      next if arg.is_a?(Symbol) || arg.is_a?(String)
+
+      klass = arg.class
+      value = arg.inspect
+
+      raise(
+        ArgumentError,
+        "#{name} must each be Symbol or String, got #{klass}: #{value} in #{args}"
+      )
+    end
   end
 end

data/lib/cache_box/chain.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+class CacheBox
+  class Chain
+    # Input:
+    #
+    # namespace = String | Symbol # Default: 'namespace'
+    #
+    # Output: N/A
+    def initialize(namespace = nil, logger: nil, storage: nil)
+      namespace ||= 'namespace'
+      logger    ||= Logger.new(STDOUT, level: Logger::INFO)
+      storage   ||= FileStorage.new(namespace: namespace)
+
+      @cache = ::CacheBox.new(namespace, logger: logger, storage: storage)
+      @chain = []
+      @set   = Set.new
+    end
+
+    # Input:
+    #
+    # name   = String | Symbol
+    # args   = Array[...Object]
+    # &block = Proc(Hash{...Object => Object}, *args)
+    #
+    # Output: self
+    def add(name, *args, &block)
+      validate_add!(name, &block)
+
+      string_name = name.to_s
+      if @set.include?(string_name)
+        raise(
+          ArgumentError,
+          "Chain already contains a step named #{name.inspect}"
+        )
+      else
+        @set << string_name
+      end
+
+      @chain.push(
+        [name, args, proc { |*all| @cache.with(string_name, *all, &block) }]
+      )
+
+      self
+    end
+
+    # Output: Object # Anything the last block in the chain returns.
+    def run!
+      work = []
+
+      @chain.reverse_each do |name, args, callable|
+        work.push([name, args, callable])
+
+        break if @cache.has?(name)
+      end
+
+      result = nil
+      work.reverse_each do |_name, args, callable|
+        input = []
+        input << result if result
+        input += args   if args
+
+        result = callable.call(*input)
+      end
+
+      result
+    end
+
+    # Input:
+    #
+    # name = Array[String | Symbol] # Default: []
+    #
+    # Output: self
+    def expire!(*names)
+      @cache.expire!(*names)
+
+      self
+    end
+
+    private
+
+    # Input:
+    #
+    # name   = String | Symbol
+    # &block = Proc
+    #
+    # Output: N/A
+    def validate_add!(name, &block)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        klass = name.class
+        value = name.inspect
+
+        raise(
+          ArgumentError,
+          "name must be a Symbol or String, got #{klass}: #{value}"
+        )
+      end
+
+      return unless block.nil?
+
+      raise(ArgumentError, 'The `:add` method requires a block')
+    end
+  end
+end

data/lib/cache_box/file_storage.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+class CacheBox
+  # A storage backed by files.
+  class FileStorage
+    # Input:
+    #
+    # namespace = Symbol | String # Default: 'namespace'
+    # path      = String # Path; Default: nil
+    #
+    # Output: N/A
+    def initialize(namespace: nil, path: nil)
+      validate_symbol_or_string!(namespace, 'namespace')
+      validate_string!(path, 'path')
+
+      @namespace = namespace.to_s || 'namespace'
+
+      root  = path || File.join(Dir.pwd, '.cache')
+      @path = File.join(root, @namespace)
+    end
+
+    # Output: self
+    def reset!
+      FileUtils.remove_entry_secure(@path, true)
+
+      self
+    end
+
+    # Reads the content.
+    #
+    # Input:
+    #
+    # name = String
+    #
+    # Output: Object # Anything
+    def read!(name)
+      validate_string!(name, 'name')
+
+      file = File.join(@path, name)
+      return unless File.exist?(file)
+
+      Marshal.load(File.read(file))
+    end
+
+    # Input:
+    #
+    # name = String
+    # data = Object # Anything
+    #
+    # Output: self
+    def write!(name, data)
+      validate_string!(name, 'name')
+
+      FileUtils.mkdir_p(@path) unless Dir.exist?(@path)
+
+      content = Marshal.dump(data)
+      file    = File.join(@path, name)
+
+      File.write(file, content)
+
+      self
+    end
+
+    # Input:
+    #
+    # name = String
+    #
+    # Output: self
+    def delete!(name)
+      validate_string!(name, 'name')
+
+      file = File.join(@path, name)
+      FileUtils.remove_entry_secure(file, true)
+
+      self
+    end
+
+    # Input:
+    #
+    # name = String
+    #
+    # Output: true | false
+    def has?(name)
+      validate_string!(name, 'name')
+
+      file = File.join(@path, name)
+      File.file?(file)
+    end
+
+    private
+
+    def validate_symbol_or_string!(arg, name)
+      return if arg.nil? || arg.is_a?(Symbol) || arg.is_a?(String)
+
+      klass = arg.class
+      value = arg.inspect
+
+      raise(
+        ArgumentError,
+        "#{name} must be a Symbol or String, got #{klass}: #{value}"
+      )
+    end
+
+    def validate_string!(arg, name)
+      return if arg.nil? || arg.is_a?(String)
+
+      klass = arg.class
+      value = arg.inspect
+
+      raise(
+        ArgumentError,
+        "#{name} must be a String, got #{klass}: #{value}"
+      )
+    end
+  end
+end

data/lib/cache_box/memory_storage.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+class CacheBox
+  # A storage backed by an in memory Hash.
+  class MemoryStorage
+    # Accepts a Hash or any Hash-like object as argument. Will use a plain Hash
+    # if none provided.
+    #
+    # Input:
+    #
+    # state = Hash{...Object => Object} # Default: nil
+    #
+    # Output: N/A
+    def initialize(state = nil)
+      validate!(state)
+
+      @state = state || {}
+    end
+
+    # Accepts a Hash or any Hash-like object as argument. Will use a plain Hash
+    # if none provided.
+    #
+    # Input:
+    #
+    # state = Hash{...Object => Object}
+    #
+    # Output: self
+    def reset!(state = nil)
+      initialize(state)
+
+      self
+    end
+
+    # Input:
+    #
+    # name = String
+    #
+    # Output: Object # Anything
+    def read!(name)
+      validate_string!(name, 'name')
+
+      @state[name]
+    end
+
+    # Input:
+    #
+    # name = String
+    # data = Object # Anything
+    #
+    # Output: self
+    def write!(name, data)
+      validate_string!(name, 'name')
+
+      @state[name] = data
+
+      self
+    end
+
+    # Input:
+    #
+    # name = String
+    #
+    # Output: self
+    def delete!(name)
+      validate_string!(name, 'name')
+
+      @state.delete(name)
+
+      self
+    end
+
+    # Input:
+    #
+    # name = String
+    #
+    # Output: true | false
+    def has?(name)
+      validate_string!(name, 'name')
+
+      @state.key?(name)
+    end
+
+    private
+
+    # Input:
+    #
+    # state = Object # Anything
+    #
+    # Output: N/A
+    def validate!(state)
+      return if state.nil? || state.is_a?(Hash)
+
+      validate_get!(state)
+      validate_set!(state)
+      validate_delete!(state)
+      validate_key!(state)
+    end
+
+    # Input:
+    #
+    # state = Object # Anything
+    #
+    # Output: N/A
+    def validate_get!(state)
+      unless state.respond_to?(:[])
+        raise(ArgumentError, 'Given state object does not respond to `:[]`')
+      end
+
+      arity = state.method(:[]).arity
+      unless arity == 1
+        raise(
+          ArgumentError,
+          "Given state object's `:[]` method arity must be 1, got: #{arity}"
+        )
+      end
+    end
+
+    # Input:
+    #
+    # state = Object # Anything
+    #
+    # Output: N/A
+    def validate_set!(state)
+      unless state.respond_to?(:[]=)
+        raise(ArgumentError, 'Given state object does not respond to `:[]=`')
+      end
+
+      arity = state.method(:[]=).arity
+      unless arity == 2
+        raise(
+          ArgumentError,
+          "Given state object's `:[]=` method arity must be 2, got: #{arity}"
+        )
+      end
+    end
+
+    # Input:
+    #
+    # state = Object # Anything
+    #
+    # Output: N/A
+    def validate_delete!(state)
+      unless state.respond_to?(:delete)
+        raise(ArgumentError, 'Given state object does not respond to `delete`')
+      end
+
+      arity = state.method(:delete).arity
+      unless arity == 1
+        raise(
+          ArgumentError,
+          "Given state object's `:delete` method arity must be 1, got: #{arity}"
+        )
+      end
+    end
+
+    # Input:
+    #
+    # state = Object # Anything
+    #
+    # Output: N/A
+    def validate_key!(state)
+      unless state.respond_to?(:key?)
+        raise(ArgumentError, 'Given state object does not respond to `:key?`')
+      end
+
+      arity = state.method(:key?).arity
+      unless arity == 1
+        raise(
+          ArgumentError,
+          "Given state object's `:key?` method arity must be 1, got: #{arity}"
+        )
+      end
+    end
+
+    # Input:
+    #
+    # arg  = String
+    # name = String
+    #
+    # Output: N/A
+    def validate_string!(arg, name)
+      return if arg.nil? || arg.is_a?(String)
+
+      klass = arg.class
+      value = arg.inspect
+
+      raise(
+        ArgumentError,
+        "#{name} must be a String, got #{klass}: #{value}"
+      )
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cache_box
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre.preview2
+  version: 0.0.1.pre.preview7
 platform: ruby
 authors:
 - Codruț Constantin Gușoi
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-18 00:00:00.000000000 Z
+date: 2020-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -16,28 +16,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.14'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -52,9 +66,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.88'
-description:
+description: 
 email:
-- codrut.gusoi+git-commit@gmail.com
+- codrut.gusoi+rubygems.org@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -62,12 +76,16 @@ files:
 - LICENSE
 - cache_box.gemspec
 - lib/cache_box.rb
-- lib/cache_box_chain.rb
+- lib/cache_box/chain.rb
+- lib/cache_box/file_storage.rb
+- lib/cache_box/memory_storage.rb
 homepage: https://gitlab.com/sdwolfz/cache_box_rb
 licenses:
-- BSD 3-clause
-metadata: {}
-post_install_message:
+- BSD-3-Clause
+metadata:
+  homepage_uri: https://gitlab.com/sdwolfz/cache_box_rb
+  source_code_uri: https://gitlab.com/sdwolfz/cache_box_rb
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -82,8 +100,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.1.3
-signing_key:
+rubygems_version: 3.1.2
+signing_key: 
 specification_version: 4
-summary: A simple, fast, and easy to use file backed cache.
+summary: A simple, fast, and easy to use local cache.
 test_files: []

data/lib/cache_box_chain.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-class CacheBox
-  class Chain
-    def initialize(namespace = :namespace)
-      @cache = ::CacheBox.new(namespace)
-      @chain = []
-    end
-
-    def reset!(namespace = :namespace)
-      @cache.reset!(namespace)
-      @chain = []
-
-      self
-    end
-
-    def chain(name, *args, &block)
-      validate_chain!(name, &block)
-
-      @chain.push(
-        [name, args, proc { |*all| @cache.with(name, *all, &block) }]
-      )
-
-      self
-    end
-
-    def chain_many(name, *args, &block)
-      validate_chain!(name, &block)
-
-      @chain.push(
-        [name, args, proc { |*all| @cache.with_many(name, *all, &block) }]
-      )
-
-      self
-    end
-
-    def run!(all = nil)
-      validate_run!(all)
-
-      if all
-        run_all
-      else
-        run_chain
-      end
-    end
-
-    def expire!
-      @cache.expire!
-
-      self
-    end
-
-    def expire(*names)
-      names.each do |name|
-        @cache.expire(name)
-      end
-
-      self
-    end
-
-    private
-
-    def validate_chain!(name, &block)
-      unless name.is_a?(Symbol) || name.is_a?(String)
-        klass = name.class
-        value = name.inspect
-
-        raise(
-          ArgumentError,
-          "name must be a Symbol or a String, got #{klass}: #{value}"
-        )
-      end
-
-      return unless block.nil?
-
-      raise(
-        ArgumentError,
-        'The `#chain/2` method needs to be called with a block'
-      )
-    end
-
-    def validate_run!(arg)
-      return if arg.nil? || arg == :all
-
-      klass = arg.class
-      value = arg.inspect
-
-      raise(
-        ArgumentError,
-        'The `run!` method only accepts `nil` or the Symbol `:all` as an ' \
-        "argument, got #{klass}: #{value}"
-      )
-    end
-
-    def run_all
-      result = nil
-      @chain.each do |_name, args, callable|
-        input = []
-        input << result if result
-        input += args if args
-
-        result = callable.call(*input)
-      end
-
-      result
-    end
-
-    def run_chain
-      work = []
-
-      @chain.reverse_each do |name, args, callable|
-        work.push([name, args, callable])
-
-        break if @cache.has?(name)
-      end
-
-      result = nil
-      work.reverse_each do |_name, args, callable|
-        input = []
-        input << result if result
-        input += args if args
-
-        result = callable.call(*input)
-      end
-
-      result
-    end
-  end
-end