npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

folder-hash

v4.0.4

Published

Create a hash checksum over a folder and its content - its children and their content

Downloads

751,134

Readme

Create a hash checksum over a folder or a file.
The hashes are propagated upwards, the hash that is returned for a folder is generated over all the hashes of its children.
The hashes are generated with the sha1 algorithm and returned in base64 encoding by default.

Each file returns a name and a hash, and each folder returns additionally an array of children (file or folder elements).

Usage

First, install folder-hash with npm install --save folder-hash or yarn add folder-hash.

Simple example

To see differences to the last version of this package, I would create hashes over all .js and .json files. But ignore everything inside folders starting with a dot, and also from the folders node_modules, test_coverage. The structure of the options object is documented below.
This example is also stored in ./examples/readme-example1.js.

const { hashElement } = require('folder-hash');

const options = {
  folders: { exclude: ['.*', 'node_modules', 'test_coverage'] },
  files: { include: ['*.js', '*.json'] },
};

console.log('Creating a hash over the current folder:');
hashElement('.', options)
  .then(hash => {
    console.log(hash.toString());
  })
  .catch(error => {
    return console.error('hashing failed:', error);
  });

The returned information looks for example like this:

Creating a hash over the current folder:
{ name: '.', hash: 'YZOrKDx9LCLd8X39PoFTflXGpRU=,'
  children: [
    { name: 'examples', hash: 'aG8wg8np5SGddTnw1ex74PC9EnM=,'
      children: [
        { name: 'readme-example1.js', hash: 'Xlw8S2iomJWbxOJmmDBnKcauyQ8=' }
        { name: 'readme-with-callbacks.js', hash: 'ybvTHLCQBvWHeKZtGYZK7+6VPUw=' }
        { name: 'readme-with-promises.js', hash: '43i9tE0kSFyJYd9J2O0nkKC+tmI=' }
        { name: 'sample.js', hash: 'PRTD9nsZw3l73O/w5B2FH2qniFk=' }
      ]}
    { name: 'index.js', hash: 'kQQWXdgKuGfBf7ND3rxjThTLVNA=' }
    { name: 'package.json', hash: 'w7F0S11l6VefDknvmIy8jmKx+Ng=' }
    { name: 'test', hash: 'H5x0JDoV7dEGxI65e8IsencDZ1A=,'
      children: [
        { name: 'parameters.js', hash: '3gCEobqzHGzQiHmCDe5yX8weq7M=' }
        { name: 'test.js', hash: 'kg7p8lbaVf1CPtWLAIvkHkdu1oo=' }
      ]}
  ]}

And the structure may be traversed to e.g. create incremental backups.

It is also possible to only match the full path and not the basename. The same configuration could look like this:
You should be aware that *nix and Windows behave differently, so please use caution.

const options = {
  folders: {
    exclude: ['.*', '**.*', '**node_modules', '**test_coverage'],
    matchBasename: false,
    matchPath: true,
  },
  files: {
    //include: ['**.js', '**.json' ], // Windows
    include: ['*.js', '**/*.js', '*.json', '**/*.json'], // *nix
    matchBasename: false,
    matchPath: true,
  },
};

Parameters for the hashElement function

Options

Default values

{
    algo: 'sha1',       // see crypto.getHashes() for options in your node.js REPL
    encoding: 'base64', // 'base64', 'base64url', 'hex' or 'binary'
    files: {
        exclude: [],
        include: [],
        matchBasename: true,
        matchPath: false,
        ignoreBasename: false,
        ignoreRootName: false
    },
    folders: {
        exclude: [],
        include: [],
        matchBasename: true,
        matchPath: false,
        ignoreRootName: false
    },
    symbolicLinks: {
        include: true,
        ignoreBasename: false,
        ignoreTargetPath: true,
        ignoreTargetContent: false,
        ignoreTargetContentAfterError: false,
    }
}

Rules object properties

Symlink options

Configure, how symbolic links should be hashed.
To understand how the options can be combined to create a specific behavior, look into test/symbolic-links.js.

Command line usage

After installing it globally via

$ npm install -g folder-hash

You can use it like this:

# local folder
$ folder-hash -c config.json .
# local folder
$ folder-hash
# global folder
$ folder-hash /user/bin

It also allows to pass an optional JSON configuration file with the -c or --config flag, which should contain the same configuration as when using the JavaScript API.

You can also use a local version of folder-hash like this:

$ npx folder-hash --help
Use folder-hash on cli like this:
  folder-hash [--config <json-file>] <file-or-folder>

Examples

Other examples using promises

See file ./examples/readme-with-promises.js

const path = require('path');
const { hashElement } = require('folder-hash');

// pass element name and folder path separately
hashElement('test', path.join(__dirname, '..'))
  .then(hash => {
    console.log('Result for folder "../test":', hash.toString(), '\n');
  })
  .catch(error => {
    return console.error('hashing failed:', error);
  });

// pass element path directly
hashElement(__dirname)
  .then(hash => {
    console.log(`Result for folder "${__dirname}":`);
    console.log(hash.toString(), '\n');
  })
  .catch(error => {
    return console.error('hashing failed:', error);
  });

// pass options (example: exclude dotFolders)
const options = { encoding: 'hex', folders: { exclude: ['.*'] } };
hashElement(__dirname, options)
  .then(hash => {
    console.log('Result for folder "' + __dirname + '" (with options):');
    console.log(hash.toString(), '\n');
  })
  .catch(error => {
    return console.error('hashing failed:', error);
  });

Other examples using error-first callbacks

See ./examples/readme-with-callbacks.js

const path = require('path');
const { hashElement } = require('folder-hash');

// pass element name and folder path separately
hashElement('test', path.join(__dirname, '..'), (error, hash) => {
  if (error) {
    return console.error('hashing failed:', error);
  } else {
    console.log('Result for folder "../test":', hash.toString(), '\n');
  }
});

// pass element path directly
hashElement(__dirname, (error, hash) => {
  if (error) {
    return console.error('hashing failed:', error);
  } else {
    console.log('Result for folder "' + __dirname + '":');
    console.log(hash.toString(), '\n');
  }
});

// pass options (example: exclude dotFiles)
const options = { algo: 'md5', files: { exclude: ['.*'], matchBasename: true } };
hashElement(__dirname, options, (error, hash) => {
  if (error) {
    return console.error('hashing failed:', error);
  } else {
    console.log('Result for folder "' + __dirname + '":');
    console.log(hash.toString());
  }
});

Behavior

The behavior is documented and verified in the unit tests. Execute npm test or mocha test, and have a look at the test subfolder.
You can also have a look at the CircleCI report. CircleCI

Creating hashes over files (with default options)

The hashes are the same if:

  • A file is checked again
  • Two files have the same name and content (but exist in different folders)

The hashes are different if:

  • A file was renamed or its content was changed
  • Two files have the same name but different content
  • Two files have the same content but different names

Creating hashes over folders (with default options)

Content means in this case a folder's children - both the files and the subfolders with their children.

The hashes are the same if:

  • A folder is checked again
  • Two folders have the same name and content (but have different parent folders)

The hashes are different if:

  • A file somewhere in the directory structure was renamed or its content was changed
  • Two folders have the same name but different content
  • Two folders have the same content but different names

License

MIT, see LICENSE.txt