hashsum v0.0.1

hashsum

Calculate the hashsum of various things.

installation

npm install hashsum

usage

var hashsum = require('hashsum');

hash an arbitrary value

hashsum(value, function (err, hashOrHashes) {
  console.log(hashOrHashes);
});

hash a file's contents

hashsum.file('/path/to/file', function (err, hash) {
  console.log(hash);
});

hash the contents of each file in a directory

hashsum.directory('/path/to/dir', function (err, hashes) {
  for (var path in hashes) {
    console.log(path, hashes[path]);
  }
});

hash a stream

// Create or obtain a stream of some kind...
var src = fs.createReadStream('/path/to/file');

hashsum.stream(src, function (err, hash) {
  console.log(hash);
});

api

Callbacks receive two arguments (err, hash), unless otherwise noted.

All methods accept an optional options object with the following properties:

• algorithm - hashing algorithm supported by crypto.createHash. Default: sha1

Directory-related methods accept additional properties:

• filterFn - function used to filter files or directories out of the results. Receives the file or directory path as an argument. Filter functions should return true to retain the path, or false to skip it. Default: undefined

• recursive - whether to descend into child directories. Default: false

• relativePaths - whether to use relative paths in the hashes object. Default: false

Example filterFn:

// Skip paths containing an underscore.
function filter(path) {
  return path.indexOf('_') === -1;
}

var options = { recursive: true, filterFn: filter };

hashsum.directory('/path', options, function (err, hashes) {
  console.log(hashes);
});

hashsum(src, options, cb)

Calculate the hashsum for the given src. Internally, hashsum will decide the best hashsum API method to use based on the value of src.

If src is a stream, hashsum.stream will be used.

If src is a string, and it is also a path, and a file or directory exists at that location, hashsum.file or hashsum.directory will be used.

If it is not a path, or nothing exists at that location, hashsum.string will be used.

If it is any other type, it will be coerced to string via '' + src and hashsum.string will be used.

When hashing an object, consider implementing a custom toString method on the object, or prepare the source data ahead of time and use hashsum.string directly.

hashsumSync(src, options)

Synchronous version of hashsum. Returns the calculated hash or hashes.

Note: Streams cannot be hashed synchronously. Use hashsum or hashsum.stream instead.

hashsum.file(path, options, cb)

Calculate the hashsum for the given file.

hashsum.fileSync(path, options)

Synchronous version of hashsum.file. Returns the calculated hash.

hashsum.directory(path, options, cb)

Calculate the hashsum for each file in a given directory.

The callback receives two arguments (err, hashes). Hashes are collected as an object that maps filename to hashsum.

This example:

hashsum.directory('/path/to/dir', function (err, hashes) {
  console.log(hashes);
});

Might produce this hashes object:

{
  '/path/to/dir/index.html': 'de59a86eea5cc70b3d3c8c27d210eb23d5e34873',
  '/path/to/dir/public/css/reset.css': '82bed1345e375f93cadd5494cac046e8ff80ece3',
  ...
}

If the relativePaths option is true, the hashes object might look like the following (when run from the /path/to/dir directory):

{
  'index.html': 'de59a86eea5cc70b3d3c8c27d210eb23d5e34873',
  'public/css/reset.css': '82bed1345e375f93cadd5494cac046e8ff80ece3',
  ...
}

hashsum.directorySync(path, options)

Synchonrous version of hashsum.directory. Returns the calculated hashes.

hashsum.string(str, options, cb)

Calculate the hashsum for the given string.

hashsum.stringSync(str, options)

Synchronous version of hashsum.string. Returns the calculated hash.

hashsum.stream(src, options, cb)

Calculate the hashsum for the given stream.

cli

npm install -g hashsum

hashsum [options] <src-1> [...<src-N>]

Options:
  -a, --algorithm      Hashing algorithm to use                [default: "sha1"]
  -e, --filter         RegExp for filtering out unwanted paths
  -f, --format         Output format: text|json                [default: "text"]
  -p, --path           Treat all inputs as paths first, strings second
  -r, --recursive      Recurse into sub-directories
  -t, --relativePaths  Use relative paths in directory output
  -h, --help           Print this help message
  -v, --version        Print version information

notes

On the command line, hashsum's filter option is a bit different than the filterFn option of the module. The hashsum module's filterFn option takes a function, whereas the CLI filter option is the pattern of a RegExp. That is, the string pattern you would pass to new RegExp(pattern).

When specifying --format json, source keys are mapped to hash values. This is slightly different than --format text, which prints hashes before sources.

examples

$ hashsum foo
0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33 foo

$ hashsum foo bar baz
0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33 foo
62cdb7020ff920e5aa642c3d4066950dd1f01f4d bar
bbe960a25ea311d21d40669e93df2003ba9b90a2 baz

$ hashsum /path/to/dir -p
de59a86eea5cc70b3d3c8c27d210eb23d5e34873 /path/to/dir/index.js

$ cd /path/to/dir
$ hashsum /path/to/dir -pt
de59a86eea5cc70b3d3c8c27d210eb23d5e34873 index.js

$ hashsum /path/to/dir -pr
de59a86eea5cc70b3d3c8c27d210eb23d5e34873 /path/to/dir/index.js
82bed1345e375f93cadd5494cac046e8ff80ece3 /path/to/dir/node_modules/.bin/jshint
...

$ hashsum /path/to/dir -pr -e node_modules
de59a86eea5cc70b3d3c8c27d210eb23d5e34873 /path/to/dir/index.js

$ cs /path/to/dir
$ hashsum /path/to/dir -prt -f json
{
  "index.js": "de59a86eea5cc70b3d3c8c27d210eb23d5e34873",
  "node_modules/.bin/jshint": "82bed1345e375f93cadd5494cac046e8ff80ece3",
  ...
}

$ hashsum /path/to/dir -pt -a md5
a1b8790319d43ac420fb25f2b6563887 index.js

stdin

$ echo -n foo | hashsum
0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33

$ hashsum < /path/to/dir/index.js
de59a86eea5cc70b3d3c8c27d210eb23d5e34873