hashids - npm Package Compare versions

Comparing version 0.1.1 to 0.1.2

examples/encrypting_decrypting_several_numbers.js

examples/encrypting_one_number.js

examples/encrypting_several_numbers.js

examples/encrypting_with_custom_alphabet.js

examples/encrypting_with_custom_hash_length.js

hashids.js

tests/collisions.js

tests/speed.js

index.js

		@@ -1,1 +0,1 @@
		module.exports = require('./lib/hashids');
		module.exports = require('./hashids');

package.json

		{
		"author": "Ivan Akimov <ivan@grather.com> (http://hashids.org)",
		"author": "Ivan Akimov <ivan@grather.com> (https://twitter.com/ivanakimov)",
		"name": "hashids",
		"description": "A tiny Node.js module to generate YouTube-like hashes from one or many ids.",
		"version": "0.1.1",
		"description": "A small Node.js class to generate YouTube-like hashes from one or many numbers. Use hashids when you do not want to expose your database ids to the user. ",
		"version": "0.1.2",
		"preferGlobal": true,
		"homepage": "http://hashids.org",
		"homepage": "http://www.hashids.org/node-js/",
		"repository": {
		"type": "git",
		"url": "https://github.com/ivanakimov/hashids.js"
		"url": "https://github.com/ivanakimov/hashids.node.js"
		},
		"main": "index.js",
		"dependencies": {
		"crypto": ""
		},
		"dependencies": {},
		"devDependencies": {},
		@@ -17,0 +15,0 @@ "optionalDependencies": {},

272

README.md


		# hashids

		A tiny Node.js JavaScript class to generate YouTube-like hashes from one or many ids.
		A small Node.js class to generate YouTube-like hashes from one or many numbers. Use hashids when you do not want to expose your database ids to the user.

		## Contents
		[http://www.hashids.org/node-js/](http://www.hashids.org/node-js/)

		* README.md - documentation and examples
		* LICENSE
		* package.json
		* index.js
		* src/
		* hashids.coffee - hashids class written in CoffeeScript
		* lib/
		* hashids.js - compiled hashids in JavaScript
		## What is it?

		## What's it for?
		hashids (Hash ID's) creates short, unique, decryptable hashes from unsigned integers.

		Generating unique hashes is beneficial when you do not want to expose your database ids in the URL. It's even more helpful when you do not have to look up in the database what record belongs to what hash.
		It was designed for websites to use in URL shortening, tracking stuff, or making pages private (or at least unguessable).

		Instead of storing these hashes in the database and selecting by them, you could encode primary ids and select by those - which is faster. Providing a unique `salt` value to the constructor will make your hashes unique also.
		This algorithm tries to satisfy the following requirements:

		Hashes look similar to what YouTube, Bitly, and other popular websites have: `p9`, `pZsCB`, `qKuBQuxc`. They are case-sensitive, include alphanumeric characters and a dash by default.
		1. Hashes must be unique and decryptable.
		2. They should be able to contain more than one integer (so you can use them in complex or clustered systems).
		3. You should be able to specify minimum hash length.
		4. Hashes should not contain basic English curse words (since they are meant to appear in public places - like the URL).

		(You can customize the alphabet from which your hashes are created.)
		Instead of showing items as `1`, `2`, or `3`, you could show them as `U6dc`, `u87U`, and `HMou`.
		You don't have to store these hashes in the database, but can encrypt + decrypt on the fly.

		## What's different?
		All integers need to be greater than or equal to zero.

		With this class you could encode several ids into one hash. If you have several objects to keep track of, you could use for example `userId`, `univesityId` and `classId` -- passing all three ids at the same time and getting back one hash.
		## Installation

		This is really useful for complex or clustered systems where you need to remember more than one id.
		1. Grab Node.js and install if you haven't already: [http://nodejs.org/download/](http://nodejs.org/download/)
		2. Install using npm:

		`npm install hashids`

		## Usage

		There is no limit to how many ids you can encode into one hash. The more ids you provide and the bigger the numbers, the longer your hash will be.
		#### Encrypting one number

		## Installation
		You can pass a unique salt value so your hashes differ from everyone else's. I use "this is my salt" as an example.

		1. Grab [Node.js](http://nodejs.org/) and install if you haven't already: [http://nodejs.org/#download](http://nodejs.org/#download)
		2. Same with [npm](http://npmjs.org/) (package manager for Node).
		3. Install [hashids](http://hashids.org/):
		```javascript

		var hashids = require("hashids"),
		hashes = new hashids("this is my salt");

		var hash = hashes.encrypt(12345);
		```

		`hash` is now going to be:

		`npm install -g hashids`
		ryKo

		#### Decrypting

		Notice during decryption, same salt value is used:

		```javascript

		var hashids = require("hashids"),
		hashes = new hashids("this is my salt");

		var numbers = hashes.decrypt("ryKo");
		```

		`numbers` is now going to be:

		## Sample Usage
		[ 12345 ]

		All integers are expected to be positive.
		#### Decrypting with different salt

		### Encoding:
		Decryption will not work if salt is changed:

		To encode a single number:

		```javascript
		var hashids = require('hashids');
		hashids = new hashids('this is my salt');

		var hash = hashids.encode(12345);
		var hashids = require("hashids"),
		hashes = new hashids("this is my pepper");

		var numbers = hashes.decrypt("ryKo");
		```

		var `hash` is now going to be:
		`numbers` is now going to be:

		[]

		#### Encrypting several numbers

		7OR
		```javascript

		To encode multiple numbers into one hash:
		var hashids = require("hashids"),
		hashes = new hashids("this is my salt");

		var hash = hashes.encrypt(683, 94108, 123, 5);
		```

		`hash` is now going to be:

		zKphM54nuAyu5

		#### Decrypting is done the same way

		```javascript
		var hashids = require('hashids');
		hashids = new hashids('this is my salt');

		var hash = hashids.encode(683, 94108, 123, 5);
		var hashids = require("hashids"),
		hashes = new hashids("this is my salt");

		var numbers = hashes.decrypt("zKphM54nuAyu5");
		```

		var `hash` is now going to be:
		`numbers` is now going to be:

		nEfOM6s2oIz
		[ 683, 94108, 123, 5 ]

		### Decoding:
		#### Encrypting and specifying minimum hash length

		Hash decoding is done using the same salt value that you have used during encoding:
		Here we encrypt integer 1, and set the minimum hash length to 8 (by default it's 0 -- meaning hashes will be the shortest possible length).

		```javascript
		var hashids = require('hashids');
		hashids = new hashids('this is my salt');

		var hash1 = hashids.decode('7OR');
		console.log(hash1);
		var hashids = require("hashids"),
		hashes = new hashids("this is my salt", 8);

		var hash2 = hashids.decode('nEfOM6s2oIz');
		console.log(hash2);
		var hash = hashes.encrypt(1);
		```

		Output will be:
		`hash` is now going to be:

		rjiMRirL

		#### Decrypting

		```javascript
		[ 12345 ]
		[ 683, 94108, 123, 5 ]
		```

		## Security
		var hashids = require("hashids"),
		hashes = new hashids("this is my salt", 8);

		The primary purpose of hashids is to make ids look different. It's not meant or tested to be used as a security algorithm.
		var numbers = hashes.decrypt("rjiMRirL");
		```

		Having said that, this class does try to make these hashes un-guessable and unique.
		`numbers` is now going to be:

		[ 1 ]

		#### Specifying custom hash alphabet

		Let's look at the following example:
		Here we set the alphabet to consist of only four letters: "abcd"

		```javascript
		var hashids = require('hashids');
		hashids = new hashids('this is my salt');

		var hash = hashids.encode(5, 5, 5, 5);
		var hashids = require("hashids"),
		hashes = new hashids("this is my salt", 0, "abcd");

		var hash = hashes.encrypt(1, 2, 3, 4, 5);
		```

		var `hash` will be:
		`hash` is now going to be:

		jie1ws6
		adcdacddcdaacdad

		You don't see any repeating patterns that might show there's 4 identical numbers in the hash.
		## Randomness

		The primary purpose of hashids is to obfuscate ids. It's not meant or tested to be used for security purposes or compression.
		Having said that, this algorithm does try to make these hashes unguessable and unpredictable:

		#### Repeating numbers

		```javascript

		var hashids = require("hashids"),
		hashes = new hashids("this is my salt");

		var hash = hashes.encrypt(5, 5, 5, 5);
		```

		You don't see any repeating patterns that might show there's 4 identical numbers in the hash:

		GMh5SAt9

		Same with incremented numbers:

		```javascript
		var hashids = require('hashids');
		hashids = new hashids('this is my salt');

		var hash = hashids.encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
		var hashids = require("hashids"),
		hashes = new hashids("this is my salt");

		var hash = hashes.encrypt(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
		```

		var `hash` will be :
		`hash` will be :

		6utsaI616snh0SdFthj
		zEUzHySGIpuyhpF6Tasj

		## Bonus
		### Incrementing number hashes:

		Since these hashes are most likely to be used in user-visible places, like the url -- no matter the salt value, they should not make up basic curse words by design, like the f-bomb or "#2".
		```javascript

		var hashids = require("hashids"),
		hashes = new hashids("this is my salt");

		var hash1 = hashes.encrypt(1), /* MR */
		hash2 = hashes.encrypt(2), /* ed */
		hash3 = hashes.encrypt(3), /* o9 */
		hash4 = hashes.encrypt(4), /* 4n */
		hash5 = hashes.encrypt(5); /* a5 */
		```

		## Speed

		Even though speed is an important factor of every hashing algorithm, primary goal here was encoding several numbers at once and making the hash unique and random.

		With Node 0.8.8, on a 2.7 GHz Intel Core i7 with 16GB of RAM, it takes roughly 0.08 seconds to:

		1. Encrypt 1000 hashes consisting of 1 integer `hashids.encrypt(12);`
		2. And decrypt these 1000 hashes back into integers `hashids.decrypt(hash);` while ensuring they are valid

		If we do the same with 3 integers, for example: `hashids.encrypt(10, 11, 12);`
		-- the number jumps up to 0.13 seconds on the same machine.

		Sidenote: The numbers tested with were relatively small -- if you increase them, the speed will obviously decrease.

		#### What you could do to speed it up

		Usually people either encrypt or decrypt one hash per request, so the algorithm should already be fast enough for that.
		However, there are still several things you could do:

		1. If you are generating a lot of hashes at once, wrap this class in your own so you can cache hashes.
		2. Use [MongoDB](http://www.mongodb.org/) or [Redis](http://redis.io/).
		3. You could also decrease the length of your alphabet. Your hashes will become longer, but calculating them will be faster.

		## Bad hashes

		I wrote this class with the intent of placing these hashes in visible places - like the URL. If I create a unique hash for each user, it would be unfortunate if the hash ended up accidentally being a bad word. Imagine auto-creating a URL with hash for your user that looks like this - `http://example.com/user/a**hole`

		Therefore, this algorithm tries to avoid generating most common English curse words with the default alphabet. This is done by never placing the following letters next to each other:

		c, C, s, S, f, F, h, H, u, U, i, I, t, T

		## Changelog

		0.1.2 - Current Stable

		Warning: If you are using 0.1.1 or below, updating to this version will change your hashes.

		- Minimum hash length can now be specified
		- Added more randomness to hashes
		- Added unit tests
		- Added example files
		- Changed warnings that can be thrown
		- Renamed `encode/decode` to `encrypt/decrypt`
		- Consistent shuffle does not depend on md5 anymore
		- Speed improvements

		0.1.1

		- Speed improvements
		- Bug fixes

		0.1.0

		- First commit

		## Contact

		Follow me [@IvanAkimov](http://twitter.com/ivanakimov)

		Or [http://ivanakimov.com](http://ivanakimov.com)

		## License

		MIT License. See the `LICENSE` file.

lib/hashids.js

src/hashids.coffee

hashids - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics

Worsened metrics

Dependency changes