memosa 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f32b1b800bfdaf62015183e444f5ad4ecdf49584bb04ee31f85b5c7747a8aaa1
+  data.tar.gz: 3b4107c3d7c801b0fc9015ec41bb43743e8a5ddf424b6c4710b180c0e0b78356
+SHA512:
+  metadata.gz: 62d00474986ac1d1a691454b07e97d33879ac7846af0edb39b77847c6e5928beee2788b45a3555acb3c2bd89980f14ff26477074d2cf7db8a5fe333b8ee03ccb
+  data.tar.gz: 967d8646d2fff68b257e7058570690d3e2df89c3d806982483a4bebb6e9524cfde5971bf0d55321408796cae56cb56d51aa57ead071e99f24e6d22f642741776

data/config/rubocop.yml

@@ -0,0 +1,10 @@
+require:
+  - rubocop/cop/memosa
+
+Memosa/MethodDefinition:
+  Description: "Disallows the use of `memoize` without a method definition"
+  Enabled: true
+
+Memosa/MethodSignature:
+  Description: "Disallows the use of `memoize` for methods that accept arguments"
+  Enabled: true

data/lib/memosa/cache.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Memosa
+  # This class is used to interact with the memoization cache.
+  # @api public
+  class Cache
+    # Create a new instance of {Cache}
+    #
+    # @api private
+    # @param cache [Hash<Symbol, BasicObject>] the memoization cache
+    def initialize(cache)
+      @cache = cache
+    end
+
+    # Add values to the cache
+    #
+    # @api public
+    # @param values [Hash<Symbol, BasicObject>] the values to add to the cache.
+    # @return [self]
+    # @example
+    #   memosa.merge!(foo: "bar")
+    def merge!(values)
+      @cache.merge!(values)
+      self
+    end
+
+    # Reset the cache
+    #
+    # @api public
+    # @return [self]
+    # @example
+    #   memosa.clear
+    def clear
+      @cache.clear
+      self
+    end
+
+    # Delete a key from the cache
+    #
+    # @api public
+    # @param key [Symbol]
+    # @return [self]
+    # @example
+    #   memosa.delete(:foo)
+    def delete(key)
+      @cache.delete(key)
+      self
+    end
+  end
+end

data/lib/memosa/internal.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Memosa
+  # These methods are use internally by Memosa and are not intended for public use.
+  # @!visibility private
+  module Internal
+    # Determine the visibility of a method
+    #
+    # @param owner [Module]
+    # @param method_name [Symbol]
+    # @return [Symbol]
+    def self.visibility(owner, method_name)
+      if owner.private_method_defined?(method_name)
+        :private
+      elsif owner.protected_method_defined?(method_name)
+        :protected
+      elsif owner.public_method_defined?(method_name)
+        :public
+      else
+        raise ArgumentError, "`#{method_name.inspect}` is not defined"
+      end
+    end
+
+    # Determine if a method is defined (including private methods)
+    #
+    # @param owner [Module]
+    # @param method_name [Symbol]
+    # @return [Boolean]
+    def self.method_defined?(owner, method_name)
+      owner.method_defined?(method_name) || owner.private_method_defined?(method_name)
+    end
+  end
+end

data/lib/memosa/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Memosa
+  # The current Memosa version
+  # @return [String]
+  VERSION = "0.8.0"
+end

data/lib/memosa.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "memosa/cache"
+require_relative "memosa/internal"
+require_relative "memosa/version"
+
+# Memosa provides a simple way to memoize methods in Ruby.
+module Memosa
+  # Convert a method to a memoized method
+  #
+  # Memosa does not support memoizing methods that accept arguments.
+  #
+  # @api public
+  # @param method_name [Symbol] the name of the method to memoize
+  # @return [Symbol] the name of the memoized method
+  # @raise [ArgumentError] when the method is is not defined
+  # @raise [ArgumentError] when the method is already memoized
+  # @example
+  #   class State
+  #     extend Memosa
+  #
+  #     memoize def id
+  #       SecureRandom.uuid
+  #     end
+  #   end
+  #
+  def memoize(method_name)
+    methods = prepend_memosa
+    visibility = Internal.visibility(self, method_name)
+
+    if Internal.method_defined?(methods, method_name)
+      raise ArgumentError, "`#{method_name.inspect}` is already memoized"
+    end
+
+    methods.module_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+      #{visibility} def #{method_name}
+        raise ArgumentError, "unsupported block argument" if block_given?
+
+        cache = (@_memosa_cache ||= {})
+        cache.fetch(:#{method_name}) do
+          cache[:#{method_name}] = super()
+        end
+      end
+    RUBY
+
+    method_name
+  end
+
+  # Define and prepend MemosaMethods
+  #
+  # When {memoize} is called, Memosa will define a module named MemosaMethods. Memoized
+  # methods will be defined on this module and then prepended to the class.
+  #
+  # This method allows you to force that module to be defined and prepended, which is
+  # useful when order matters.
+  #
+  # @api public
+  # @return [Module]
+  # @example
+  #   class Foo
+  #     extend Memosa
+  #     prepend_memosa
+  #   end
+  def prepend_memosa
+    prepend Initializer
+
+    if const_defined?(:MemosaMethods, false)
+      const_get(:MemosaMethods, false)
+    else
+      const_set(:MemosaMethods, Module.new).tap { |mod| prepend(mod) }
+    end
+  end
+
+  # Reset an object's memoization cache
+  #
+  # @api public
+  # @param object [Object]
+  # @return [void]
+  # @example
+  #   Memosa.reset(user)
+  def self.reset(object)
+    cache = object.instance_variable_get(:@_memosa_cache)
+    cache&.clear
+    nil
+  end
+
+  # This module is responsible for initializing the cache
+  #
+  # @!visibility private
+  module Initializer
+    # Eagerly initialize the cache before the object is frozen
+    #
+    # This ensures that frozen objects can still have memoized methods.
+    #
+    # @return [self]
+    def freeze
+      @_memosa_cache ||= {}
+      super
+    end
+  end
+
+  # This module provides a {#memosa} helper that can be used to manipulate the
+  # memoization cache directly.
+  module API
+    # Used to manipulate the memoized cache directly
+    #
+    # @api public
+    # @return [Memosa::Cache]
+    # @example
+    #   class State
+    #     extend Memosa
+    #     include Memosa::API
+    #
+    #     memoize def id
+    #       SecureRandom.uuid
+    #     end
+    #
+    #     def reset!
+    #       memosa.clear
+    #     end
+    #   end
+    def memosa
+      ::Memosa::Cache.new(@_memosa_cache ||= {})
+    end
+  end
+end

data/lib/rubocop/cop/memosa.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    # Memosa includes a set of RuboCop rules that encourage best practices when using
+    # memosa.
+    #
+    # Add the following configuration to your `.rubocop.yml`:
+    #
+    # @example
+    #   inherit_gem:
+    #     memosa: config/rubocop.yml
+    #
+    module Memosa
+      # This cop checks for memoized methods that accept arguments or yield.
+      #
+      # @example
+      #   # bad
+      #   def foo; end
+      #   memoize :foo
+      #
+      #   # good
+      #   memoize def foo; end
+      class MethodDefinition < RuboCop::Cop::Base
+        # @return [String]
+        MSG = "`memoize` should precede a method definition (e.g. `memoize def`)"
+
+        def_node_matcher :invalid_usage?, <<~PATTERN
+          (send nil? :memoize (sym _))
+        PATTERN
+
+        # @!visibility private
+        def on_send(node)
+          add_offense(node.selector) if invalid_usage?(node)
+        end
+      end
+
+      # This cop checks for memoized methods that accept arguments or yield.
+      #
+      # @example
+      #   # bad
+      #   memoize def foo(a); end
+      #
+      #   # good
+      #   memoize def foo; end
+      class MethodSignature < RuboCop::Cop::Base
+        # @return [String]
+        MSG = "Memoized methods should not accept arguments or yield"
+
+        def_node_matcher :invalid_signature?, <<~PATTERN
+          (send nil? :memoize {(def _name (args _+) _body) | (def _name _args `yield)})
+        PATTERN
+
+        # @!visibility private
+        def on_send(node)
+          add_offense(node.selector) if invalid_signature?(node)
+        end
+      end
+    end
+  end
+end

data/rbi/memosa.rbi

@@ -0,0 +1,152 @@
+# typed: strong
+# Memosa provides a simple way to memoize methods in Ruby.
+module Memosa
+  VERSION = T.let("0.8.0", T.untyped)
+
+  # Convert a method to a memoized method
+  # 
+  # Memosa does not support memoizing methods that accept arguments.
+  # 
+  # _@param_ `method_name` — the name of the method to memoize
+  # 
+  # _@return_ — the name of the memoized method
+  # 
+  # ```ruby
+  # class State
+  #   extend Memosa
+  # 
+  #   memoize def id
+  #     SecureRandom.uuid
+  #   end
+  # end
+  # ```
+  sig { params(method_name: Symbol).returns(Symbol) }
+  def memoize(method_name); end
+
+  # Define and prepend MemosaMethods
+  # 
+  # When {memoize} is called, Memosa will define a module named MemosaMethods. Memoized
+  # methods will be defined on this module and then prepended to the class.
+  # 
+  # This method allows you to force that module to be defined and prepended, which is
+  # useful when order matters.
+  # 
+  # ```ruby
+  # class Foo
+  #   extend Memosa
+  #   prepend_memosa
+  # end
+  # ```
+  sig { returns(Module) }
+  def prepend_memosa; end
+
+  # Reset an object's memoization cache
+  # 
+  # _@param_ `object`
+  # 
+  # ```ruby
+  # Memosa.reset(user)
+  # ```
+  sig { params(object: Object).void }
+  def self.reset(object); end
+
+  # This module provides a {#memosa} helper that can be used to manipulate the
+  # memoization cache directly.
+  module API
+    # Used to manipulate the memoized cache directly
+    # 
+    # ```ruby
+    # class State
+    #   extend Memosa
+    #   include Memosa::API
+    # 
+    #   memoize def id
+    #     SecureRandom.uuid
+    #   end
+    # 
+    #   def reset!
+    #     memosa.clear
+    #   end
+    # end
+    # ```
+    sig { returns(Memosa::Cache) }
+    def memosa; end
+  end
+
+  # This class is used to interact with the memoization cache.
+  # @api public
+  class Cache
+    # Create a new instance of {Cache}
+    # 
+    # _@param_ `cache` — the memoization cache
+    sig { params(cache: T::Hash[Symbol, BasicObject]).void }
+    def initialize(cache); end
+
+    # Add values to the cache
+    # 
+    # _@param_ `values` — the values to add to the cache.
+    # 
+    # ```ruby
+    # memosa.merge!(foo: "bar")
+    # ```
+    sig { params(values: T::Hash[Symbol, BasicObject]).returns(T.self_type) }
+    def merge!(values); end
+
+    # Reset the cache
+    # 
+    # ```ruby
+    # memosa.clear
+    # ```
+    sig { returns(T.self_type) }
+    def clear; end
+
+    # Delete a key from the cache
+    # 
+    # _@param_ `key`
+    # 
+    # ```ruby
+    # memosa.delete(:foo)
+    # ```
+    sig { params(key: Symbol).returns(T.self_type) }
+    def delete(key); end
+  end
+end
+
+module RuboCop
+  module Cop
+    # Memosa includes a set of RuboCop rules that encourage best practices when using
+    # memosa.
+    # 
+    # Add the following configuration to your `.rubocop.yml`:
+    # 
+    # @example
+    #   inherit_gem:
+    #     memosa: config/rubocop.yml
+    module Memosa
+      # This cop checks for memoized methods that accept arguments or yield.
+      # 
+      # @example
+      #   # bad
+      #   def foo; end
+      #   memoize :foo
+      # 
+      #   # good
+      #   memoize def foo; end
+      class MethodDefinition < RuboCop::Cop::Base
+        MSG = T.let("`memoize` should precede a method definition (e.g. `memoize def`)", T.untyped)
+      end
+
+      # This cop checks for memoized methods that accept arguments or yield.
+      # 
+      # @example
+      #   # bad
+      #   memoize def foo(a); end
+      # 
+      #   # good
+      #   memoize def foo; end
+      class MethodSignature < RuboCop::Cop::Base
+        MSG = T.let("Memoized methods should not accept arguments or yield", T.untyped)
+      end
+    end
+  end
+end

data/sig/memosa.rbs

@@ -0,0 +1,143 @@
+# Memosa provides a simple way to memoize methods in Ruby.
+module Memosa
+  VERSION: String
+
+  # Convert a method to a memoized method
+  # 
+  # Memosa does not support memoizing methods that accept arguments.
+  # 
+  # _@param_ `method_name` — the name of the method to memoize
+  # 
+  # _@return_ — the name of the memoized method
+  # 
+  # ```ruby
+  # class State
+  #   extend Memosa
+  # 
+  #   memoize def id
+  #     SecureRandom.uuid
+  #   end
+  # end
+  # ```
+  def memoize: (Symbol method_name) -> Symbol
+
+  # Define and prepend MemosaMethods
+  # 
+  # When {memoize} is called, Memosa will define a module named MemosaMethods. Memoized
+  # methods will be defined on this module and then prepended to the class.
+  # 
+  # This method allows you to force that module to be defined and prepended, which is
+  # useful when order matters.
+  # 
+  # ```ruby
+  # class Foo
+  #   extend Memosa
+  #   prepend_memosa
+  # end
+  # ```
+  def prepend_memosa: () -> Module
+
+  # Reset an object's memoization cache
+  # 
+  # _@param_ `object`
+  # 
+  # ```ruby
+  # Memosa.reset(user)
+  # ```
+  def self.reset: (Object object) -> void
+
+  # This module provides a {#memosa} helper that can be used to manipulate the
+  # memoization cache directly.
+  module API
+    # Used to manipulate the memoized cache directly
+    # 
+    # ```ruby
+    # class State
+    #   extend Memosa
+    #   include Memosa::API
+    # 
+    #   memoize def id
+    #     SecureRandom.uuid
+    #   end
+    # 
+    #   def reset!
+    #     memosa.clear
+    #   end
+    # end
+    # ```
+    def memosa: () -> Memosa::Cache
+  end
+
+  # This class is used to interact with the memoization cache.
+  # @api public
+  class Cache
+    # Create a new instance of {Cache}
+    # 
+    # _@param_ `cache` — the memoization cache
+    def initialize: (::Hash[Symbol, BasicObject] cache) -> void
+
+    # Add values to the cache
+    # 
+    # _@param_ `values` — the values to add to the cache.
+    # 
+    # ```ruby
+    # memosa.merge!(foo: "bar")
+    # ```
+    def merge!: (::Hash[Symbol, BasicObject] values) -> self
+
+    # Reset the cache
+    # 
+    # ```ruby
+    # memosa.clear
+    # ```
+    def clear: () -> self
+
+    # Delete a key from the cache
+    # 
+    # _@param_ `key`
+    # 
+    # ```ruby
+    # memosa.delete(:foo)
+    # ```
+    def delete: (Symbol key) -> self
+  end
+end
+
+module RuboCop
+  module Cop
+    # Memosa includes a set of RuboCop rules that encourage best practices when using
+    # memosa.
+    # 
+    # Add the following configuration to your `.rubocop.yml`:
+    # 
+    # @example
+    #   inherit_gem:
+    #     memosa: config/rubocop.yml
+    module Memosa
+      # This cop checks for memoized methods that accept arguments or yield.
+      # 
+      # @example
+      #   # bad
+      #   def foo; end
+      #   memoize :foo
+      # 
+      #   # good
+      #   memoize def foo; end
+      class MethodDefinition < RuboCop::Cop::Base
+        MSG: String
+      end
+
+      # This cop checks for memoized methods that accept arguments or yield.
+      # 
+      # @example
+      #   # bad
+      #   memoize def foo(a); end
+      # 
+      #   # good
+      #   memoize def foo; end
+      class MethodSignature < RuboCop::Cop::Base
+        MSG: String
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: memosa
+version: !ruby/object:Gem::Version
+  version: 0.8.0
+platform: ruby
+authors:
+- Ray Zane
+bindir: exe
+cert_chain: []
+date: 2025-02-14 00:00:00.000000000 Z
+dependencies: []
+email:
+- raymondzane@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- config/rubocop.yml
+- lib/memosa.rb
+- lib/memosa/cache.rb
+- lib/memosa/internal.rb
+- lib/memosa/version.rb
+- lib/rubocop/cop/memosa.rb
+- rbi/memosa.rbi
+- sig/memosa.rbs
+homepage: https://github.com/rzane/memosa
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rzane/memosa
+  source_code_uri: https://github.com/rzane/memosa
+  changelog_uri: https://github.com/rzane/memosa/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A brutally simple macro for memoizing methods.
+test_files: []