intellihash 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 17ac847b242baeffdc96ca1bb5b53c352b151834f69982221d30d73048b0ae35
+  data.tar.gz: e1f386d85a69f2af333b1c2c85bba7f66e7d2977bfd0fab69aa19174a8e22cd7
+SHA512:
+  metadata.gz: 2dcc030b8a4013d1ed190eafb7ce8ef0c075db1ab77dc254524f7594addcbfad5c717ff8af198fdaa09a07b90548719ffefc40ae1e206d4601f4995215238e26
+  data.tar.gz: 8145467934645236a1819456705cc45e1d08d2be75518af8db5a0027849699b94965735b5ab9b1158744ff03de99a1ca9374deeb889280dc2bb848ee660d24f2

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# byebug history 
+.byebug_history

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,17 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.6.5
+
+Metrics/BlockLength:
+  Exclude: 
+    - spec/*
+
+Metrics/MethodLength:
+  Max: 15
+
+Naming/PredicateName:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in intellihash.gemspec
+gemspec
+
+gem 'rake', '~> 12.0'
+gem 'rspec', '~> 3.0'

data/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: .
+  specs:
+    intellihash (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    benchmark-malloc (0.1.0)
+    benchmark-perf (0.5.0)
+    benchmark-trend (0.3.0)
+    byebug (11.1.3)
+    diff-lcs (1.4.4)
+    parallel (1.20.1)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-benchmark (0.5.1)
+      benchmark-malloc (~> 0.1.0)
+      benchmark-perf (~> 0.5.0)
+      benchmark-trend (~> 0.3.0)
+      rspec (>= 3.0.0, < 4.0.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.18.4)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.8.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.8.0)
+      parser (>= 3.0.1.1)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  byebug
+  intellihash!
+  rake (~> 12.0)
+  rspec (~> 3.0)
+  rspec-benchmark (~> 0.5.0)
+  rubocop (~> 1.18)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Tyler Porter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,274 @@
+# Intellihash
+
+A fast implementation of hashes as objects, benchmarked against OpenStruct. It allows chaining hash attributes as method calls instead of standard hash syntax.
+
+Since an Intellihash extends the native Ruby `Hash`, this means instantiating a new smart hash is just as fast as a normal hash, _and_ you retain the ability to call all the normal instance methods on it.
+
+```ruby
+intellihash = {
+    foo: {
+        bar: {
+            baz: {
+                bat: :bam
+            }
+        }
+    }
+}
+
+intellihash.foo.bar.baz.bat
+
+#=> :bam
+```
+
+You can achieve similar results by converting your hash to an OpenStruct:
+
+```ruby
+hash = {
+    foo: {
+        bar: {
+            baz: {
+                bat: :bam
+            }
+        }
+    }
+}
+
+open_struct = OpenStruct.new(hash)
+open_struct.foo.bar.baz.bat
+
+#=> :bam
+```
+
+But you lose access to your instance methods, and pay a performance penalty to instantiate it!
+
+```ruby
+intellihash.size
+#=> 1
+
+open_struct.size
+#=> nil
+```
+
+## Performance vs. OpenStruct
+
+Creating an Intellihash is approximately 5x faster than instantiating an OpenStruct.
+
+```              
+                  user     system      total        real                
+OpenStruct:   4.046875   0.906250   4.953125 (  4.979611)
+Intellihash:    0.828125   0.125000   0.953125 (  0.956110)
+```
+
+See [Testing Performance](#testing-performance) for details on running benchmarks.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'intellihash'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install intellihash
+
+## Configuration
+
+If you need to customize Intellihash, you may create a configuration:
+
+```ruby
+Intellihash.configure do |config|
+    config.enabled          = true     # (Boolean) Default: false 
+    config.default_format   = :symbol  # (Symbol)  Default: :symbol
+    config.smart_by_default = false    # (Boolean) Default: false
+end
+```
+
+### Options
+
+- **enabled**
+  - Whether Intellihash is enabled or not
+  - You may wish to set this conditionally, such as enabling it only in a test environment
+    - i.e. `config.enabled = Rails.env.test?`
+  - **NOTE**: Once Intellihash is enabled, it cannot easily be disabled. Enable Intellihash with caution.
+- **default_format**
+  - Valid values: `:sym, :symbol, :str, :string, :any`
+  - This determines the default storage and retrieval options
+- **smart_by_default**
+  - Whether newly created hashes are smart
+  - When `false`, new hashes can still be converted to smart hashes via `hash.is_smart = true` or `hash.to_intellihash!`
+
+### Rails
+
+Place the above configuration in an initializer (such as `config/initializers/intellihash.rb`)
+
+## Usage
+
+### Instantiating an Intellihash
+
+If you've configured Intellihash `smart_by_default = true`, you need to do nothing else as _all_ new hashes are Intellihashes.
+
+However, if you prefer not to use this configuration, you can create an Intellihash from any existing hash:
+
+```ruby
+hash = { foo: :bar }
+
+hash.is_smart?
+#=> false
+
+hash.is_smart = true
+# or
+hash.to_intellihash!
+
+hash.is_smart? 
+#=> true
+```
+
+### Methods
+
+Intellihash-powered hashes can access values via method chaining:
+
+```ruby
+intellihash = { foo: :bar }
+
+intellihash.foo
+
+#=> :bar
+```
+
+They can also store values in a similar way:
+
+```ruby
+intellihash.baz = :bat
+intellihash
+
+#=> { foo: :bar, baz: :bat }
+```
+
+When configured correctly, they work even when the object contains arrays and other classes:
+
+```ruby
+Intellihash.configure do |config|
+    config.enabled          = true
+    config.smart_by_default = true
+    config.default_format   = :any
+end
+
+intellihash = {
+    a: {
+        complicated: [
+            {
+                object: {
+                    "containing_many" => {
+                        types_of_things: Also::Works       
+                    }
+                }
+            }
+        ]
+    }
+}
+
+intellihash.a.complicated.first.object.containing_many.types_of_things
+
+#=> Also::Works
+```
+
+### Ambiguous Keys
+
+When using an Intellihash that has an ambiguous key (i.e. the key exists both as a symbol and a string in the same hash), you can define which you would like to return at runtime:
+
+```ruby
+intellihash ={
+    foo: :bar
+    'foo' => 'bar'
+}
+
+intellihash.foo(from: :symbol) # or from: :sym
+#=> :bar
+
+intellihash.foo(from: :string) # or from: :str
+#=> 'bar'
+```
+
+If you prefer, you can use the original hash syntax:
+
+```ruby
+intellihash[:foo]
+#=> :bar
+
+intellihash['foo']
+#=> 'bar'
+```
+
+**NOTE**: Intellihashes always **store** values as the configured `default_format`, which defaults to `:symbol`. Override this in the config as needed, or use hash syntax: `intellihash['bar'] = 'bat'`.
+
+### Collisions with Hash Methods
+
+A powerful feature of Intellihash is the ability to use Ruby Hash instance methods on Intellihash. This also means that it's possible for some of the keys in the hash to collide with the names of the instance method you're trying to call. 
+
+For instance, consider `Hash#size`, which returns the number of keys in the hash:
+
+```ruby
+intellihash = { size: 2 }
+
+intellihash.size
+#=> 1
+```
+
+For this reason, it's better to use hash syntax to fetch these keys:
+
+```ruby
+# Bad
+intellihash.size
+
+# Good
+intellihash[:size]
+intellihash.fetch(:size)
+```
+
+You _can_, however, **set** keys in the hash using these instance methods. This is not recommended as the syntax leads to confusion when attempting to access the key.
+
+```ruby
+intellihash.size = 3
+intellihash
+
+#=> { size: 3 }
+
+intellihash.size
+#=> 1
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Testing
+
+### Unit Tests
+
+Run unit tests:
+
+```
+bundle exec rspec
+```
+
+### Testing Performance
+
+Run performance benchmarks:
+
+```
+bundle exec rspec --tag performance:true
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ty-porter/intellihash.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'intellihash'
+require 'byebug'
+
+Intellihash.configure do |config|
+  config.enabled          = true
+  config.smart_by_default = true
+end
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/intellihash.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'lib/intellihash/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'intellihash'
+  spec.version       = Intellihash::VERSION
+  spec.authors       = ['Tyler Porter']
+  spec.email         = ['tyler.b.porter@gmail.com']
+
+  spec.summary       = 'A fast implementation of hashes as objects'
+  spec.description   = <<~DESC
+    A fast implementation of hashes as objects, benchmarked against OpenStruct.
+    It allows chaining hash attributes as method calls instead of standard hash syntax.
+  DESC
+  spec.homepage      = 'https://github.com/ty-porter/intellihash'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.5')
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/ty-porter/intellihash'
+
+  # 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)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency('byebug', ['>= 0'])
+  spec.add_development_dependency('rspec-benchmark', ['~> 0.5.0'])
+  spec.add_development_dependency('rubocop', ['~> 1.18'])
+end

data/lib/intellihash.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'intellihash/callbacks'
+require 'intellihash/configuration'
+require 'intellihash/mixins'
+require 'intellihash/version'
+
+module Intellihash
+  def self.enabled?
+    Intellihash.configuration.enabled
+  end
+end

data/lib/intellihash/callbacks.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Intellihash
+  module Callbacks
+    # https://ruby-doc.org/core-3.0.1/Hash.html
+    #
+    # Methods that return a copy of :self: need this callback to populate :smart: from :self:
+    AFTER_CALLBACK_TARGETS = %i[
+      compact
+      invert
+      merge
+      reject
+      select
+      slice
+      to_h
+      transform_keys
+      transform_values
+    ].freeze
+
+    # Callback registration happens as soon as Intellihash::Callbacks is prepended
+    AFTER_CALLBACK_TARGETS.each do |instance_method|
+      define_method(instance_method) do |*args, &block|
+        # Call original method
+        result = super(*args, &block)
+
+        # Register :after: callbacks
+        result.is_smart = smart if result.respond_to?(:is_smart=) && !result.frozen?
+
+        result
+      end
+    end
+  end
+end

data/lib/intellihash/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Intellihash
+  class << self
+    attr_reader :configuration
+
+    def configure
+      yield(@configuration)
+
+      inject_dependencies! if Intellihash.enabled?
+    end
+
+    def configuration=(config)
+      raise InvalidConfiguration, config.class unless config.is_a?(Intellihash::Configuration)
+
+      @configuration = config
+    end
+
+    private
+
+    def inject_dependencies!
+      Hash.include Intellihash::Mixins
+      Hash.prepend Intellihash::Callbacks
+    end
+  end
+
+  class Configuration
+    attr_accessor :enabled, :smart_by_default
+    attr_reader   :default_format
+
+    def initialize
+      @default_format    = :symbol
+      @enabled           = false
+      @smart_by_default  = false
+    end
+
+    def default_format=(other)
+      @default_format = Intellihash::Mixins::FORMATTER.member?(other) ? other : :symbol
+    end
+  end
+
+  class InvalidConfiguration < StandardError; end
+
+  @configuration = Intellihash::Configuration.new
+end

data/lib/intellihash/mixins.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Intellihash
+  module Mixins
+    def smart
+      @smart = @smart.nil? ? Intellihash.configuration.smart_by_default : @smart
+    end
+
+    def is_smart=(value)
+      # Ensure this is a boolean
+      @smart = value == true
+    end
+
+    def to_intellihash
+      @smart = true
+      self
+    end
+
+    def is_smart?
+      smart
+    end
+
+    def default_format
+      @default_format ||= Intellihash.configuration.default_format
+    end
+
+    def default_format=(other)
+      @default_format = FORMATTER.member?(other) ? other : FORMATTER[:symbol]
+    end
+
+    private
+
+    FORMATTER = {
+      str: :to_s,
+      string: :to_s,
+      sym: :to_sym,
+      symbol: :to_sym,
+      any: :any
+    }.freeze
+
+    def method_missing(method_name, *args, **kwargs, &block)
+      super unless respond_to?(:is_smart?) && is_smart?
+
+      if method_name[-1] == '='
+        send(:store, method_name[0, method_name.size - 1].send(key_store_as), args.first)
+      else
+        format_method = key_retrieve_from(kwargs)
+        case format_method
+        when :any then fetch_where_present(method_name)
+        else send(:[], method_name.send(format_method))
+        end
+      end
+    end
+
+    def respond_to_missing?(*)
+      is_smart? ? true : super
+    end
+
+    def key_store_as
+      key_format = default_format == :any ? FORMATTER[:symbol] : FORMATTER[default_format]
+      key_format || FORMATTER[:symbol]
+    end
+
+    def key_retrieve_from(options)
+      from_option = options.fetch(:from) { default_format }
+      format(from_option)
+    end
+
+    def format(value)
+      FORMATTER.include?(value) ? FORMATTER[value] : FORMATTER[:symbol]
+    end
+
+    def fetch_where_present(method_name)
+      return send(:[], method_name.to_sym) if member?(method_name.to_sym)
+      return send(:[], method_name.to_s) if member?(method_name.to_s)
+    end
+  end
+end

data/lib/intellihash/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Intellihash
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: intellihash
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Porter
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-08-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
+description: |
+  A fast implementation of hashes as objects, benchmarked against OpenStruct.
+  It allows chaining hash attributes as method calls instead of standard hash syntax.
+email:
+- tyler.b.porter@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- intellihash.gemspec
+- lib/intellihash.rb
+- lib/intellihash/callbacks.rb
+- lib/intellihash/configuration.rb
+- lib/intellihash/mixins.rb
+- lib/intellihash/version.rb
+homepage: https://github.com/ty-porter/intellihash
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ty-porter/intellihash
+  source_code_uri: https://github.com/ty-porter/intellihash
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.5
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A fast implementation of hashes as objects
+test_files: []