Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/elitemastereric/object_hash_rb

Generate cryptographic hashes from Ruby objects.
https://github.com/elitemastereric/object_hash_rb

Last synced: about 1 month ago
JSON representation

Generate cryptographic hashes from Ruby objects.

Awesome Lists containing this project

README 

        
# object_hash_rb



Generate cryptographic hashes from objects and values in Ruby. Supports SHA1 and many others.



The library aims to support hashing of objects such as circular object structures, allowing for simplified deep equality checks.



Built to generate cryptographic hashes which are compatible with [object-hash](https://github.com/puleos/object-hash) for NodeJS.



[![Travis CI](https://img.shields.io/travis/com/mastereric/object_hash_rb/master)](https://travis-ci.com/github/MasterEric/object_hash_rb)

[![RubyGems](https://img.shields.io/gem/dv/object_hash_rb/stable)](https://rubygems.org/gems/object_hash_rb)

[![Coverage Status](https://img.shields.io/coveralls/github/MasterEric/object_hash_rb/master)](https://coveralls.io/github/MasterEric/object_hash_rb)



## Installation



Add this line to your application's Gemfile:



```ruby

gem 'object_hash_rb'

```



And then execute:



    $ bundle install



Or install it yourself as:



    $ gem install object_hash_rb



## Usage



WARNING: For `object_hash_rb` values to be compatible with NodeJS `object-hash` values, you must disable the `respectTypes` option when hashing in JavaScript.



```ruby

require "object_hash_rb"



# Encode and hash the given input.

ObjectHash.hash("Hello World")

=> "3415EF7FD82C1A04DEA35838ED84A6CECB03C790"



# The input can be any object.

ObjectHash.hash({ a: 1, b: 2, c: 3 })

=> "86BFBAADC95B656DCA2BF2393EF310A1983D59CB"



# The same input has the same output, regardless of key order.

# Great for deep equality checks.

ObjectHash.hash({ c: 3, a: 1, b: 2 })

=> "86BFBAADC95B656DCA2BF2393EF310A1983D59CB"



# There's even a handler for circular references.

test = {a: "b"}

test[:b] = test

ObjectHash.hash(test)

=> "B28AFE82FB41FE5E3CAF60E2045E46E5F5431C04"



# You can use one of several different hashing algorithms...

ObjectHash.hash("foobar", algorithm: "md5")

=> "EB920AE43AF94B25AE057837D80129EC"



# ...or you can select "passthrough" to preview how the library builds hashes.

ObjectHash.hash(test, algorithm: "passthrough")

=> "object:2:symbol:a:string:1:b,symbol:b:string:12:[CIRCULAR:0],"



# If there's a non-standard type you want to hash, you can specify a replacer

# to substitute the value before it gets hashed.

class TestStuff

  def generate_name

    "foobar"

  end

end

ObjectHash.hash({ a: TestStuff.new }, algorithm: "passthrough",

  replacer: lambda do |x|

    # Replace our type.

    return x.generate_name if x.instance_of? TestStuff

    # Else return the original.

    x

  end)

=> "object:1:symbol:a:string:6:foobar,"



# You can also make key order matter.

ObjectHash.hash({ c: 3, a: 1, b: 2 })

=> "86BFBAADC95B656DCA2BF2393EF310A1983D59CB"

ObjectHash.hash({ c: 3, a: 1, b: 2 }, unordered_objects: false)

=> "A3566EE29CFE62438C36C72BDA4C21621445E7D0"



```



## Comparisons



How does this compare with other libraries?



- JS: [puleos/object-hash](https://github.com/puleos/object-hash): `object_hash_rb` is intended to be a compatible port of puelos/object-hash, which has wide adoption. As long as `respectType` is set to false, the JavaScript version will produce identical hashes to this library.

- Ruby: [benlaurie/objecthash](https://github.com/benlaurie/objecthash/tree/master/ruby): `object_hash_rb` competes with, and has the following improvements over, `benlaurie/objecthash`:

  - Direct compatibility with the JavaScript library.

  - Recent maintenance (at time of writing, `benlaurie/objecthash` has not received any fixes in 3 years, for any of its libraries).

  - Higher performance (`benlaurie/objecthash` cryptographically hashes each value individually, whereas `object_hash_rb` produces a single encoding of the object before hashing.)

  - Support for circular references (`benlaurie/objecthash` has no handler to prevent issues with circular references)



## 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.



To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).



## Contributing



Bug reports and pull requests are welcome on GitHub at https://github.com/MasterEric/object_hash_rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/MasterEric/object_hash_rb/blob/master/CODE_OF_CONDUCT.md).



## License



The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).



## Code of Conduct



Everyone interacting in the ObjectHash project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/MasterEric/object_hash_rb/blob/master/CODE_OF_CONDUCT.md).