{"id":19780458,"url":"https://github.com/cbetta/json-bloomfilter","last_synced_at":"2025-04-30T21:33:23.661Z","repository":{"id":56879518,"uuid":"7657739","full_name":"cbetta/json-bloomfilter","owner":"cbetta","description":"🗜 A bloom filter implementation in Ruby and Javascript that is serialisable to JSON and compatible between both languages.","archived":false,"fork":false,"pushed_at":"2013-01-28T01:19:33.000Z","size":2956,"stargazers_count":15,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-29T14:44:23.048Z","etag":null,"topics":["bitarray","bloom-filter","javascript","json","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cbetta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-01-17T01:44:43.000Z","updated_at":"2019-12-31T07:10:32.000Z","dependencies_parsed_at":"2022-08-20T23:10:58.946Z","dependency_job_id":null,"html_url":"https://github.com/cbetta/json-bloomfilter","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbetta%2Fjson-bloomfilter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbetta%2Fjson-bloomfilter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbetta%2Fjson-bloomfilter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbetta%2Fjson-bloomfilter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbetta","download_url":"https://codeload.github.com/cbetta/json-bloomfilter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224225352,"owners_count":17276435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitarray","bloom-filter","javascript","json","ruby"],"created_at":"2024-11-12T05:39:51.403Z","updated_at":"2024-11-12T05:39:52.025Z","avatar_url":"https://github.com/cbetta.png","language":"Ruby","readme":"# Serialisable (JSON) Bloom Filter\n\n[![Build Status](https://travis-ci.org/cbetta/json-bloomfilter.png?branch=master)](https://travis-ci.org/cbetta/json-bloomfilter) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/cbetta/json-bloomfilter)\n\nA bloom filter implementation that is serialisable to JSON and compatible between both Ruby and Javascript. Very useful when needing to train a bloom filter in one language and using it in the other.\n\n## Why?\n\nBloom filters allow for space efficient lookups in a list, without having to store all the items in the list. This is useful for looking up tags, domain names, links, or anything else that you might want to do client side.\n\nWhat this Gem allows you to do is build a bloom filter server side, add all your entries to it, and then serialise the filter to JSON. On the client side you can then load up the serialised data into the Javascript version and use the bloom filter as is.\n\nAll of this while not sending the entire list to the client, which is something you might not want to do for either security or efficiency reasons.\n\n## Installation\n\n### Ruby\n\n```\ngem install json-bloomfilter\n```\n\n### Javascript\n\nWith the gem installed run\n\n```\njson-bloomfilter install\n```\n\nand the `json-bloomfilter.min.js` will be copied to your local directory. If you are in a Rails project it will be copied to your `app/assets/javascripts` folder.\n\n## Usage\n\n### Ruby\n\n```ruby\nrequire \"json-bloomfilter\"\n\n# use the factory to configure the filter\nfilter =  JsonBloomFilter.build 10000, 0.01 # number of expected items, desired error rate\n\n# or create a define the BloomFilter manually\nfilter = JsonBloomFilter.new size: 100\n\n# and add entries\nfilter.add \"foo\"\nfilter.add \"bar\"\n# alternatively\nfilter.add [\"foo\", \"bar\"]\n# test the entries\nfilter.test \"foo\" #=\u003e true\nfilter.test \"bar\" #=\u003e true\nfilter.test \"doh\" #=\u003e probably false\n\n# export the filter to a hash or json\nfilter.to_json #=\u003e hash as JSON\nconfig = filter.to_hash #=\u003e { \"size\" =\u003e 100, \"hashes\" =\u003e 4, \"seed\" =\u003e 1234567890, \"bits\" =\u003e [...] }\n\n# use the hash to generate a new filter with the same config\nfilter2 = JsonBloomFilter.new config\nfilter2.test \"foo\" #=\u003e true\nfilter2.test \"bar\" #=\u003e true\nfilter2.test \"doh\" #=\u003e probably false\n```\n\n### Javascript\n\n```javascript\n// use the factory to configure the filter\nfilter =  JsonBloomFilter.build(10000, 0.01); // number of expected items, desired error rate\n\n// or create a define the filter manually\nfilter = new JsonBloomFilter({ size: 100 });\n\n// and add entries\nfilter.add(\"foo\");\nfilter.add(\"bar\");\n// alternatively\nfilter.add([\"foo\", \"bar\"]);\n// test the entries\nfilter.test(\"foo\"); //=\u003e true\nfilter.test(\"bar\"); //=\u003e true\nfilter.test(\"doh\"); //=\u003e probably false\n\n// export the filter to a hash or json\nfilter.toJson();  //=\u003e hash as JSON\nconfig = filter.toHash(); //=\u003e { \"size\" =\u003e 100, \"hashes\" =\u003e 4, \"seed\" =\u003e 1234567890, \"bits\" =\u003e [...] }\n\n// use the hash to generate a new BloomFilter with the same config\nfilter2 = new JsonBloomFilter(config);\nfilter2.test(\"foo\"); //=\u003e true\nfilter2.test(\"bar\"); //=\u003e true\nfilter2.test(\"doh\") //=\u003e probably false\n```\n\n### Options\n\nValid options for constructor are:\n\n* `size` (default: 100), the bit size of the bit array used\n* `hashes` (default: 4), the number of hashes used to calculate the bit positions in the bit field\n* `seed` (default: current UNIX time), the seed for the hashing method\n\nAdditionally you can pass along:\n\n* `bits` (default: null), an array with the bitfield in non-bit format. Use `#to_hash` to create these for your active BloomFilter.\n\n## Credits\n\n* [bitarray.rb](https://github.com/cbetta/json-bloomfilter/blob/master/lib/json/bloomfilter/bitarray.rb) and [bitarray.coffee](https://github.com/cbetta/json-bloomfilter/blob/master/coffee/bitarray.coffee) based on [version by Peter Cooper](https://github.com/peterc/bitarray).\n* [bloomfilter.rb](https://github.com/cbetta/json-bloomfilter/blob/master/lib/json/bloomfilter.rb) and [bloomfilter.coffee](https://github.com/cbetta/json-bloomfilter/blob/master/coffee/bloomfilter.coffee) inspired by [Ilya Grigorik's Redis Bloomfilter](https://github.com/igrigorik/bloomfilter-rb/blob/master/lib/bloomfilter/redis.rb)\n* [zlib.coffee](https://github.com/cbetta/json-bloomfilter/blob/master/coffee/zlib.coffee) crc32 method based on the [node-crc32](https://github.com/mikepulaski/node-crc32) library and [this snippet](http://stackoverflow.com/questions/6226189/how-to-convert-a-string-to-bytearray/10132540#10132540)\n\n## Compatibilities\n\n### Confirmed:\n\n* Ruby 1.8.7\n* Ruby 1.8.2\n* Ruby 1.9.3\n* Rubinius (1.8 mode)\n* Rubinius (1.9 mode)\n* REE\n\n### Probably will work:\n\n* jRuby\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create new Pull Request\n\n## Release notes\n\n* **0.1.5** Changes namespacing\n* **0.1.4** Changes .build function to take a list of items\n* **0.1.3** Adds a check for non positive capacity values on build\n* **0.1.2** Adds Zlib dependency\n* **0.1.1** Fixes a JS integer overflow issue and makes Ruby 1.8.7 compatible\n* **0.1.0** Adds travis-ci. Bumped minor release version\n* **0.0.6** Adds a factory that takes a size + error rate\n* **0.0.5** Adds installer of JS file\n* **0.0.4** Adds JS tests\n* **0.0.3** Adds Ruby tests\n* **0.0.2** Adds implementation of Ruby and JS filters\n* **0.0.1** Gem skeleton\n\n## License\n\nSee [LICENSE](https://github.com/cbetta/json-bloomfilter/blob/master/LICENSE)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbetta%2Fjson-bloomfilter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbetta%2Fjson-bloomfilter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbetta%2Fjson-bloomfilter/lists"}