{"id":17771410,"url":"https://github.com/rootslab/shashi","last_synced_at":"2025-04-01T15:18:25.786Z","repository":{"id":25609368,"uuid":"29044457","full_name":"rootslab/shashi","owner":"rootslab","description":"Shashi, a simple module to generate, using pseudo-randomness, a universal family/set of hash functions, which produce integer values within the selected range.","archived":false,"fork":false,"pushed_at":"2015-02-22T16:12:51.000Z","size":2848,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-08T02:46:10.243Z","etag":null,"topics":["hash-functions","pseudo-random","universal"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/rootslab.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":"2015-01-10T02:32:07.000Z","updated_at":"2017-11-08T23:52:34.000Z","dependencies_parsed_at":"2022-07-27T05:16:20.021Z","dependency_job_id":null,"html_url":"https://github.com/rootslab/shashi","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fshashi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fshashi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fshashi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rootslab%2Fshashi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rootslab","download_url":"https://codeload.github.com/rootslab/shashi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246660075,"owners_count":20813338,"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":["hash-functions","pseudo-random","universal"],"created_at":"2024-10-26T21:32:47.136Z","updated_at":"2025-04-01T15:18:25.754Z","avatar_url":"https://github.com/rootslab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"### Shashi\n\n[![NPM VERSION](http://img.shields.io/npm/v/shashi.svg?style=flat)](https://www.npmjs.org/package/shashi)\n[![CODACY BADGE](https://img.shields.io/codacy/b18ed7d95b0a4707a0ff7b88b30d3def.svg?style=flat)](https://www.codacy.com/public/44gatti/shashi)\n[![CODECLIMATE](http://img.shields.io/codeclimate/github/rootslab/shashi.svg?style=flat)](https://codeclimate.com/github/rootslab/shashi)\n[![CODECLIMATE-TEST-COVERAGE](https://img.shields.io/codeclimate/coverage/github/rootslab/shashi.svg?style=flat)](https://codeclimate.com/github/rootslab/shashi)\n[![LICENSE](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://github.com/rootslab/shashi#mit-license)\n\n[![TRAVIS CI BUILD](http://img.shields.io/travis/rootslab/shashi.svg?style=flat)](http://travis-ci.org/rootslab/shashi)\n[![BUILD STATUS](http://img.shields.io/david/rootslab/shashi.svg?style=flat)](https://david-dm.org/rootslab/shashi)\n[![DEVDEPENDENCY STATUS](http://img.shields.io/david/dev/rootslab/shashi.svg?style=flat)](https://david-dm.org/rootslab/shashi#info=devDependencies)\n[![NPM DOWNLOADS](http://img.shields.io/npm/dm/shashi.svg?style=flat)](http://npm-stat.com/charts.html?package=shashi)\n\n[![NPM GRAPH1](https://nodei.co/npm-dl/shashi.png)](https://nodei.co/npm/shashi/)\n\n[![NPM GRAPH2](https://nodei.co/npm/shashi.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/shashi/)\n\n[![status](https://sourcegraph.com/api/repos/github.com/rootslab/shashi/.badges/status.png)](https://sourcegraph.com/github.com/rootslab/shashi)\n[![views](https://sourcegraph.com/api/repos/github.com/rootslab/shashi/.counters/views.png)](https://sourcegraph.com/github.com/rootslab/shashi)\n[![views 24h](https://sourcegraph.com/api/repos/github.com/rootslab/shashi/.counters/views-24h.png)](https://sourcegraph.com/github.com/rootslab/shashi)\n\n\u003e __Shashi__, a simple module to generate, using __pseudo-randomness__, a __universal family/set of hash functions__, which produce __integer values__ within the selected range (a __prime__ number).\n\n###A random bit of theory\n\n\u003e A family __H__ of hash functions is __universal__ if, for any two items in the universe, the __probability of collision__ is as small as possible.\n\n\u003e Briefly, assumed that for every input key k ∈ K and for every hash function h ∈ H:\n\n\u003e - h(k) map to { 0, 1, .., m−1 }\n\n\u003e then, __H is universal__ when, for any two items x != y:\n\n\u003e - Prob( h(x) == h(y) ) = __1/m__\n\n\u003e In other words, chosen __h__ uniformly at random, from a __universal set H__ of hash functions, if h is\n\u003e used to hash __n__ arbitrary keys into __m__ slots, then, for a given key __k__, we expect that the total\n\u003e number of __collisions__ with k is \u003c __n/m__.\n\n\u003e Universal hash functions could also be used to compute __perfect hashing__, for a determined set of keys.\n\n\u003e __Choosing properly a prime p and a constant c__:\n\u003e - p \u003e c*|set of keys| (c \u003e= ~2.09)\n\n\u003e We expect to find a perfect hash mapping for values, in a __finite time__ (with __high probability__), interpreting lists of resulting hashed values as edges to insert in a __bipartite__ or __tripartite__ (hyper) __graph G__ = {V,E}:\n\u003e - |E| = n (keys)\n\u003e - |V| = p\n\n\u003e we set:\n\u003e - |V| = c * |E|\n\n\u003e then we choose a prime \u003e= 2*n:\n\u003e - |V| = p = c * |E| = c * n \u003e n * 2\n\n\u003e Algo example; we choose |H| = 2, then H = { h0, h1 }:\n\u003e\n\u003e - while ( true ) :\n\u003e  - pick-up at random 2 hash functions from H\n\u003e\n\u003e  - for every key k ∈ K, add resulting edge and vertices to the 2-graph:\n\u003e    - edge = (v0, v1), with v0 = h0(k), v1 = h1(k)\n\u003e\n\u003e  - now testing the 2-graph acyclicity (it could be performed in linear time).\n\u003e  - if 2-graph is acyclic:\n\u003e    - break the loop, well done!\n\u003e      - from now on, you can build a perfect hashing function for your set of keys,\n\u003e        in a deterministic way.\n\u003e    - otherwise let's gamble!!\n\u003e      - continue loop, picking-up 2 others random hash functions\n\n\u003e See also:\n\u003e - __[Universal Hashing](http://en.wikipedia.org/wiki/Universal_hashing)__\n\u003e - __[Perfect Hash Function](http://en.wikipedia.org/wiki/Perfect_hash_function)__\n\u003e - __[Brando](https://github.com/rootslab/brando)__\n\u003e - __[Nprime](https://github.com/rootslab/nprime)__\n\n###Install\n\n```bash\n$ npm install shashi [-g]\n```\n\u003e __require__:\n\n```javascript\nvar Shashi = require( 'shashi' );\n```\n###Run Tests\n\n\u003e __to run all test files, install devDependecies:__\n\n```bash\n $ cd shashi/\n # install or update devDependecies\n $ npm install\n # run tests\n $ npm test\n```\n\u003e __to execute a single test file simply do__:\n\n```bash\n $ node test/file-name.js\n```\n###Run Benchmarks\n\n\u003e run miscellaneous benchmarks for Shashi:\n\n```bash\n $ cd shashi/\n $ npm run bench\n # or to run a single file\n $ node bench/file-name-bench.js\n```\n----------------------------------------------------------------------------------------------\n\n###Method\n\n\u003e Arguments within [ ] are optional.\n\n#####Generate seed sequence using Math.random.\n\n\u003e get a method to use a family of hash functions.\n\n```javascript\n/*\n * A trivial example, Shashi( 2, 16, 257 ) generates:\n * - 2 hash functions, h0 and h1 (indexes 0, 1)\n * - every hash fn, expects/accepts at most 16 items to encode\n * - the range of items should be: [0,255], then using 1 byte\n *   per item in the seed sequence.\n *\n * NOTE:\n * - if the p number is not a prime, the next greater prime number will be calculated.\n * - if the p number is out of range (\u003e 2^53), you'll get an Error.\n */\nShashi( Number hash_fn, Number items_to_hash, Number prime_for_seed_range ) : Array\n```\n\n\u003e It returns an Array composed by:\n\u003e - a method used to retrieve and execute a particular hash function, using an index (0-k).\n\u003e - the underlying seed __[Sequence](https://github.com/rootslab/brando)__, used for generating the hashed value (an integer).\n\n```javascript\n/*\n * When you only need to regenerate random data for seeding your hash functions,\n * you can simply refresh the seed sequence using Sequence#fill or Sequence#parse.\n *\n * See also https://github.com/rootslab/brando.\n */\nArray : [ Function uhash, Sequence seed ]\n\n// universal set of hash functions\nuhash : function ( Number fn_index, Buffer input_data [, Number bytes_per_item ] )\n```\n\n#####Generate seed sequence using a random sample.\n\n\u003e When a data Buffer is used to fill the seed sequence, the method automatically switches to the callback mode.\n\n```javascript\nShashi( Number h, Number i, Number p [, Buffer src [, Function cback ] ] ) : undefined\n```\n\u003e the callback gets 3 arguments:\n\n```javascript\n/*\n * NOTE: an error was returned when:\n * - the number supplied for the seed sequence range is not a prime.\n * - the sample data are not enough to fill the random seed Sequence.\n */\ncback : function ( Error e, Function uhash, Sequence seed ) { .. }\n```\n\u003e See also __[examples](example/)__.\n\n### MIT License\n\n\u003e Copyright (c) 2015 \u0026lt; Guglielmo Ferri : 44gatti@gmail.com \u0026gt;\n\n\u003e Permission is hereby granted, free of charge, to any person obtaining\n\u003e a copy of this software and associated documentation files (the\n\u003e 'Software'), to deal in the Software without restriction, including\n\u003e without limitation the rights to use, copy, modify, merge, publish,\n\u003e distribute, sublicense, and/or sell copies of the Software, and to\n\u003e permit persons to whom the Software is furnished to do so, subject to\n\u003e the following conditions:\n\n\u003e __The above copyright notice and this permission notice shall be\n\u003e included in all copies or substantial portions of the Software.__\n\n\u003e THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\n\u003e EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n\u003e MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\n\u003e IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\n\u003e CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\n\u003e TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\n\u003e SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n[![GA](https://ga-beacon.appspot.com/UA-53998692-1/shashi/Readme?pixel)](https://github.com/igrigorik/ga-beacon)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fshashi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frootslab%2Fshashi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootslab%2Fshashi/lists"}