SparkMD5

Common errors

• TypeError: SparkMD5.hash is not a function

  cause This error occurs when you attempt to call `hash()` on an *instance* of SparkMD5 (e.g., `new SparkMD5().hash()`) instead of using it as a static method on the main `SparkMD5` object.
  fix For direct, non-incremental hashing of a single string, call `SparkMD5.hash('your string')`. For incremental hashing, create an instance: `const spark = new SparkMD5(); spark.append('...'); spark.end();`

• TypeError: SparkMD5 is not a constructor

  cause This typically indicates an issue with how the `spark-md5` module is being imported or required in your environment, especially when mixing CommonJS (`require()`) and ES Modules (`import`) or incorrect bundler configurations.
  fix Ensure your import statement matches your module system: `import SparkMD5 from 'spark-md5';` for ES Modules (often with `esModuleInterop: true` in TypeScript) or `const SparkMD5 = require('spark-md5');` for CommonJS. If using TypeScript, check your `tsconfig.json` for `allowSyntheticDefaultImports` and `esModuleInterop` options.

• Uncaught DOMException: The operation is not supported.

  cause This error often arises when `File.prototype.slice` or related Blob/File API methods are invoked in an environment that lacks support for these features, such as very old web browsers or specific non-browser JavaScript runtimes.
  fix Ensure your target web browser or runtime environment supports the necessary File and Blob APIs. For extremely old browsers, consider using polyfills for these APIs if available, or specify a more modern browser as a minimum requirement for your application.

Warnings

• breaking Earlier versions of SparkMD5 (prior to internal fixes) could yield incorrect MD5 hashes for extremely large data inputs due to internal overflow issues. If upgrading from a very old version (e.g., pre-2.x), verify hash consistency for large files after the upgrade.
  Fix: Upgrade to SparkMD5 version 3.x or later to ensure correct computations for large data sets. Always test hash consistency after major version upgrades, especially when dealing with critical data integrity.
• gotcha The `SparkMD5#appendBinary(str)` method is designed to accept 'binary strings' which were historically generated by deprecated browser APIs like `FileReader.readAsBinaryString()`. Using this method with standard JavaScript strings may lead to incorrect hash results if the strings contain non-ASCII characters, as `appendBinary` does not perform UTF-8 encoding.
  Fix: For general string input, always use `SparkMD5#append(str)` which correctly handles UTF-8 encoding. Only use `appendBinary(str)` if you are absolutely certain the input `str` is a true binary string and not a standard UTF-8 encoded string.
• gotcha When testing file hashing in a local browser environment using the `file://` protocol, browsers like Chrome often impose security restrictions that prevent `FileReader` from accessing local files. This can result in `DOMException` or `SecurityError` during file operations.
  Fix: For Chrome, launch the browser with the `--allow-file-access-from-files` flag. Alternatively, serve your HTML file via a local web server (e.g., `http-server`, `serve`, or a simple Python web server) to avoid these browser-level security restrictions.

Install

• npm install spark-md5 npm
• yarn add spark-md5 yarn
• pnpm add spark-md5 pnpm

Imports

• SparkMD5
  wrong:

  const SparkMD5 = require('spark-md5');

  correct:

  import SparkMD5 from 'spark-md5';

  SparkMD5 is typically consumed as a default export in modern ESM projects. It exposes both static methods (e.g., SparkMD5.hash) and a constructor for incremental hashing (new SparkMD5()). For CommonJS environments, `require()` is appropriate.
• SparkMD5.ArrayBuffer
  wrong:

  import { ArrayBuffer } from 'spark-md5';

  correct:

  import SparkMD5 from 'spark-md5';
  const sparkAB = new SparkMD5.ArrayBuffer();

  The ArrayBuffer-specific hashing utility is exposed as a property on the main SparkMD5 default export, not as a separate named export. Access it via the imported `SparkMD5` object.
• SparkMD5.hash
  wrong:

  const spark = new SparkMD5(); spark.hash('your string');

  correct:

  import SparkMD5 from 'spark-md5';
  const hexHash = SparkMD5.hash('your string');

  The direct hashing method (`.hash()`) is a static utility function on the SparkMD5 class, not an instance method. For incremental hashing, you must create an instance using `new SparkMD5()`.

Quickstart

Demonstrates how to incrementally hash a large file in a web browser using ArrayBuffers and the File API, splitting the file into chunks to manage memory efficiently during the hashing process.

document.getElementById('file').addEventListener('change', function () {
    var blobSlice = File.prototype.slice || File.prototype.mozSlice || File.prototype.webkitSlice,
        file = this.files[0],
        chunkSize = 2097152,                             // Read in chunks of 2MB
        chunks = Math.ceil(file.size / chunkSize),
        currentChunk = 0,
        spark = new SparkMD5.ArrayBuffer(),
        fileReader = new FileReader();

    fileReader.onload = function (e) {
        console.log('read chunk nr', currentChunk + 1, 'of', chunks);
        spark.append(e.target.result);                   // Append array buffer
        currentChunk++;

        if (currentChunk < chunks) {
            loadNext();
        } else {
            console.log('finished loading');
            console.info('computed hash', spark.end());  // Compute hash
        }
    };

    fileReader.onerror = function () {
        console.warn('oops, something went wrong.');
    };

    function loadNext() {
        var start = currentChunk * chunkSize,
            end = ((start + chunkSize) >= file.size) ? file.size : start + chunkSize;

        fileReader.readAsArrayBuffer(blobSlice.call(file, start, end));
    }

    loadNext();
});