{"id":12181,"library":"ts-md5","title":"TypeScript MD5 Hashing Library","description":"ts-md5 is a TypeScript-first implementation of the MD5 hashing algorithm, designed for both Node.js (>=18) and browser environments. It provides functionalities for hashing Unicode and ASCII strings, supporting incremental hashing, and directly processing Files and Blobs. The library also includes advanced features like a `ParallelHasher` that leverages web workers for asynchronous file/blob hashing, improving performance in browser contexts. Its current stable version is 2.0.1, with releases showing active maintenance, including a recent major update to v2.0.0 in July 2025 that shifted to Vite for bundling. Key differentiators include its strong TypeScript typing, robust handling of various input types (strings, byte arrays, files), and built-in web worker support for computationally intensive tasks, making it a versatile choice for applications requiring MD5 checksums. It builds upon established MD5 implementations by Joseph Myers, André Cruz (SparkMD5), and Raymond Hill (yamd5.js).","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/cotag/ts-md5","tags":["javascript","placeos","cotag","md5","typescript","ts"],"install":[{"cmd":"npm install ts-md5","lang":"bash","label":"npm"},{"cmd":"yarn add ts-md5","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-md5","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for synchronous MD5 hashing. Since v2.0.0, the package is ESM-first, so CommonJS `require` is discouraged and may lead to errors without proper bundler configuration.","wrong":"const Md5 = require('ts-md5').Md5;\nimport Md5 from 'ts-md5';","symbol":"Md5","correct":"import { Md5 } from 'ts-md5';"},{"note":"Used for hashing large files or blobs in a web worker to avoid blocking the main thread. Requires the `md5_worker.js` script to be served publicly, as it's loaded as a separate file by the browser.","wrong":"const { ParallelHasher } = require('ts-md5');","symbol":"ParallelHasher","correct":"import { ParallelHasher } from 'ts-md5';"},{"note":"A static utility method on the `Md5` class for quick string hashing. Ensure `Md5` is imported as a named export and called directly on the class, not an instance.","wrong":"import Md5 from 'ts-md5';\nMd5.hashStr('some string');\nnew Md5().hashStr('some string');","symbol":"Md5.hashStr","correct":"import { Md5 } from 'ts-md5';\nMd5.hashStr('some string');"}],"quickstart":{"code":"import { Md5, ParallelHasher } from 'ts-md5';\n\n// Basic synchronous hashing\nconsole.log('--- Basic Hashing ---');\nconst hexHash1 = Md5.hashStr('hello world');\nconsole.log(`'hello world' (hex): ${hexHash1}`);\n\nconst rawHash1 = Md5.hashStr('hello world', true);\nconsole.log(`'hello world' (raw Int32Array): ${rawHash1}`);\n\nconst asciiHash = Md5.hashAsciiStr('simple ascii');\nconsole.log(`'simple ascii' (ascii hex): ${asciiHash}`);\n\n// Incremental hashing\nconsole.log('\\n--- Incremental Hashing ---');\nconst md5Instance = new Md5();\nmd5Instance\n    .appendStr('first part of the string ')\n    .appendAsciiStr('second part')\n    .appendStr(' and a final piece');\nconst incrementalHash = md5Instance.end();\nconsole.log(`Incremental hash: ${incrementalHash}`);\n\n// Example for hashing a Blob (requires a Blob instance, mocking for quickstart)\n// In a real scenario, 'fileBlob' would come from an <input type=\"file\"> event or similar.\nasync function hashBlobExample() {\n    console.log('\\n--- Hashing a Blob (ParallelHasher) ---');\n    if (typeof Worker === 'undefined') {\n        console.warn('Web Workers not available in this environment. Skipping ParallelHasher example.');\n        return;\n    }\n\n    // Mocking a Blob\n    const mockBlob = new Blob(['This is some content for the blob to be hashed.'], { type: 'text/plain' });\n    \n    // NOTE: Replace '/path/to/ts-md5/dist/md5_worker.js' with the actual URL where your worker script is served.\n    // This typically means configuring your build tool (e.g., Vite, Webpack) to copy this file to your public directory.\n    const workerPath = '/ts-md5/dist/md5_worker.js'; // Example relative path in a public folder\n    let hasher: ParallelHasher | undefined;\n    try {\n        hasher = new ParallelHasher(workerPath);\n        const result = await hasher.hash(mockBlob);\n        console.log(`MD5 of mockBlob is: ${result}`);\n    } catch (error) {\n        console.error(`Error hashing blob with ParallelHasher: ${error}. Make sure '${workerPath}' is accessible.`);\n    } finally {\n        // Important: Terminate the worker to release resources\n        hasher?.terminate();\n    }\n}\n\nhashBlobExample();","lang":"typescript","description":"Demonstrates basic synchronous string hashing, incremental hashing with the Md5 class, and asynchronous blob hashing using ParallelHasher with a mocked Blob and worker path."},"warnings":[{"fix":"Migrate your project to use ECMAScript Modules (ESM) `import` syntax. If using Node.js, ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) or use a bundler that transpiles ESM for CJS consumption.","message":"Version 2.0.0 introduced a significant change by updating the project to use Vite for bundling. This likely shifts the package to an ESM-first or ESM-only distribution, which can break existing CommonJS (`require()`) imports in older Node.js environments or projects without proper bundler configuration.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Configure your build tool (e.g., Webpack, Rollup, Vite) to copy `node_modules/ts-md5/dist/md5_worker.js` to your public directory (e.g., `dist/public/ts-md5/md5_worker.js`) and pass the corresponding public URL (e.g., `/public/ts-md5/md5_worker.js`) to the `ParallelHasher` constructor.","message":"When using `ParallelHasher` in a browser environment, the `md5_worker.js` file (located in `ts-md5/dist/`) must be publicly accessible via a URL. Your build process needs to copy this file to your public assets, and the path provided to the `ParallelHasher` constructor must reflect this public URL.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For security-critical hashing, use modern and robust cryptographic hash functions like SHA-256, SHA-3, or Argon2 (for password hashing).","message":"MD5 is a cryptographically broken hash function and should NOT be used for security-sensitive applications such as password storage, digital signatures, or generating secure tokens. It is vulnerable to collision attacks.","severity":"gotcha","affected_versions":"*"},{"fix":"Always check the return type when using the second argument. If you consistently need a hexadecimal string, omit the second argument or explicitly convert the raw array to your desired format.","message":"The static methods `Md5.hashStr()` and `Md5.hashAsciiStr()` accept an optional second argument. If `true` is passed, the method returns a raw `Int32Array(4)` instead of the default hexadecimal string. This can lead to unexpected type mismatches if not explicitly handled or if a hex string is always expected.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statements to use ESM `import { Md5 } from 'ts-md5';`. If your project is CommonJS, consider setting `\"type\": \"module\"` in your `package.json` or configuring your bundler to transpile ESM for CJS consumption.","cause":"Attempting to import `ts-md5` using CommonJS `require()` syntax in a Node.js environment or bundler that strictly enforces ESM for `ts-md5` v2.0.0 and above.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...ts-md5/dist/md5.js not supported. Instead change the require of ...md5.js to a dynamic import() call."},{"fix":"Ensure `md5_worker.js` (from `node_modules/ts-md5/dist/`) is copied to your public assets directory by your build system. Then, provide the correct, publicly accessible URL to the `ParallelHasher` constructor (e.g., `new ParallelHasher('/assets/md5_worker.js')`).","cause":"The web worker script (`md5_worker.js`) required by `ParallelHasher` is not found at the specified URL, or there's a CORS issue preventing its loading.","error":"Uncaught DOMException: Failed to construct 'Worker': Script at 'http://localhost:3000/md5_worker.js' cannot be accessed from origin 'http://localhost:3000'."},{"fix":"Verify that you are importing `Md5` as a named export: `import { Md5 } from 'ts-md5';`. Then, call `Md5.hashStr()` directly on the class name, as it is a static method.","cause":"This error typically occurs if `Md5` is imported incorrectly (e.g., as a default import instead of a named export) or if you are trying to call `hashStr` on an instance of `Md5` instead of the static class itself.","error":"TypeError: Md5.hashStr is not a function"}],"ecosystem":"npm"}