{"id":10511,"library":"archiver-utils","title":"Archiver Utilities","description":"archiver-utils provides essential utility functions designed to support the `archiver` package, primarily focusing on file system and stream operations. As of its current stable version, 5.0.2, it offers robust capabilities for tasks such as directory traversal (`fs.walkdir`) and stream interface detection (`stream.detect`). The package maintains a relatively frequent release cadence, often aligning major version updates with Node.js EOL cycles and significant dependency upgrades. Key differentiators include its tight integration with the `archiver` ecosystem, providing specialized helpers that enhance the core archiving functionality, ensuring efficient and reliable handling of file and stream inputs. It is not intended as a standalone archiving solution but as a foundational helper for `archiver` itself.","status":"active","version":"5.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/archiverjs/archiver-utils","tags":["javascript","archiver","utils"],"install":[{"cmd":"npm install archiver-utils","lang":"bash","label":"npm"},{"cmd":"yarn add archiver-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add archiver-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal stream handling and compatibility. Updated to v4 in 5.0.2.","package":"readable-stream","optional":false},{"reason":"Internal file matching and path resolution. Updated to v9/v10 in 5.0.1.","package":"glob","optional":false}],"imports":[{"note":"The `fs` object contains utilities like `walkdir`. Named import is preferred for ESM, but CommonJS `require` is also supported for Node.js environments.","wrong":"const fs = require('archiver-utils').fs;","symbol":"fs","correct":"import { fs } from 'archiver-utils';"},{"note":"The `stream` object includes utilities such as `detect` for identifying stream-like interfaces. Named import is standard.","wrong":"const stream = require('archiver-utils').stream;","symbol":"stream","correct":"import { stream } from 'archiver-utils';"},{"note":"The `buffer` object provides buffer-related utilities, such as `isBuffer`. Named import is standard.","wrong":"const buffer = require('archiver-utils').buffer;","symbol":"buffer","correct":"import { buffer } from 'archiver-utils';"}],"quickstart":{"code":"import { fs } from 'archiver-utils';\nimport { fileURLToPath } from 'url';\nimport { dirname, join } from 'path';\nimport * as nodeFs from 'node:fs';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\n// Create a dummy directory structure for demonstration\nconst tempDir = join(__dirname, 'temp_walkdir_test');\nconst subDir = join(tempDir, 'subfolder');\nnodeFs.mkdirSync(subDir, { recursive: true });\nnodeFs.writeFileSync(join(tempDir, 'file1.txt'), 'Content 1');\nnodeFs.writeFileSync(join(subDir, 'file2.txt'), 'Content 2');\nnodeFs.writeFileSync(join(tempDir, 'another-file.js'), 'console.log(\"hello\");');\n\nconsole.log(`Walking directory: ${tempDir}`);\n\nfs.walkdir(tempDir, (filepath, stats) => {\n  if (stats.isDirectory()) {\n    console.log(`[DIR] ${filepath}`);\n  } else {\n    console.log(`[FILE] ${filepath} (size: ${stats.size} bytes)`);\n  }\n}, (err) => {\n  if (err) {\n    console.error('Error during walkdir:', err);\n  } else {\n    console.log('Walkdir complete.');\n  }\n\n  // Clean up the dummy directory\n  nodeFs.rmSync(tempDir, { recursive: true, force: true });\n  console.log('Cleaned up temp directory.');\n});","lang":"javascript","description":"Demonstrates how to use `fs.walkdir` to recursively traverse a directory and log file/directory information, then cleans up."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14 or higher. The current recommended minimum is Node.js 14.","message":"Version 5.0.1 and above dropped support for Node.js v12. Ensure your environment uses Node.js v14 or newer to avoid compatibility issues.","severity":"breaking","affected_versions":">=5.0.1"},{"fix":"Upgrade your Node.js runtime to version 12 or higher. For current releases, Node.js 14+ is required.","message":"Version 4.0.0 dropped support for Node.js v10. This was a significant breaking change requiring environments to upgrade to Node.js v12 or newer.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review any custom stream detection logic in your application to ensure it aligns with the improved detection mechanism in 5.0.2. Test thoroughly if using custom stream implementations.","message":"The `stream.detect` function was improved in v5.0.2 to allow for more general Stream-like interfaces. If you were relying on specific, stricter detection logic from older versions that might have excluded certain interfaces, this change could alter behavior.","severity":"gotcha","affected_versions":">=5.0.2"},{"fix":"Check the changelogs for `readable-stream` v4 and `glob` v9/v10 if unexpected issues related to stream handling or file globbing arise after upgrading `archiver-utils`.","message":"Dependency updates in v5.0.1, specifically `readable-stream` to v4 and `glob` to v9/v10, could introduce subtle behavioral changes or require different polyfills/usage patterns in specific environments.","severity":"gotcha","affected_versions":">=5.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using the correct import syntax for your module environment. For ESM, use `import { fs } from 'archiver-utils';`. For CommonJS, use `const { fs } = require('archiver-utils');` or `const archiverUtils = require('archiver-utils'); const fs = archiverUtils.fs;`.","cause":"This error typically occurs when trying to destructure `fs` (or `stream`, `buffer`) from a CommonJS `require` call in an environment that expects named exports, or vice-versa with default imports.","error":"TypeError: (0, _archiverUtils.fs) is not a function"},{"fix":"Verify that the path variable passed to `fs.walkdir` is a valid string. Log the path before the call to debug its value.","cause":"`fs.walkdir` (or similar path-based utilities) received an `undefined` or null path argument, likely due to an uninitialized variable or incorrect concatenation.","error":"Error: The 'path' argument must be of type string. Received undefined"},{"fix":"If your project is an ES Module, switch to `import { fs } from 'archiver-utils';`. If the issue persists with other dependencies, ensure consistent module type usage across your project or use dynamic `import()` for CJS-only modules within an ESM context if absolutely necessary.","cause":"Attempting to use `require()` to load `archiver-utils` in a context where Node.js has determined it should be an ES Module (e.g., in a package with `\"type\": \"module\"` or when importing a dependency that is ESM-only). While `archiver-utils` primarily supports CJS, conflicts can arise.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module"}],"ecosystem":"npm"}