Archiver Utilities

5.0.2 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: (0, _archiverUtils.fs) is not a function
```
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.

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;`.
```
Error: The 'path' argument must be of type string. Received undefined
```
cause `fs.walkdir` (or similar path-based utilities) received an `undefined` or null path argument, likely due to an uninitialized variable or incorrect concatenation.

fix Verify that the path variable passed to `fs.walkdir` is a valid string. Log the path before the call to debug its value.
```
ERR_REQUIRE_ESM: Must use import to load ES Module
```
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.

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.

Warnings

breaking 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.
Fix: Upgrade your Node.js runtime to version 14 or higher. The current recommended minimum is Node.js 14.
breaking 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.
Fix: Upgrade your Node.js runtime to version 12 or higher. For current releases, Node.js 14+ is required.
gotcha 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.
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.
gotcha 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.
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`.

Install

npm install archiver-utils npm
yarn add archiver-utils yarn
pnpm add archiver-utils pnpm

Imports

fs
wrong:
```
const fs = require('archiver-utils').fs;
```
correct:
```
import { fs } from 'archiver-utils';
```
The `fs` object contains utilities like `walkdir`. Named import is preferred for ESM, but CommonJS `require` is also supported for Node.js environments.
stream
wrong:
```
const stream = require('archiver-utils').stream;
```
correct:
```
import { stream } from 'archiver-utils';
```
The `stream` object includes utilities such as `detect` for identifying stream-like interfaces. Named import is standard.
buffer
wrong:
```
const buffer = require('archiver-utils').buffer;
```
correct:
```
import { buffer } from 'archiver-utils';
```
The `buffer` object provides buffer-related utilities, such as `isBuffer`. Named import is standard.

Quickstart

Demonstrates how to use `fs.walkdir` to recursively traverse a directory and log file/directory information, then cleans up.

import { fs } from 'archiver-utils';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import * as nodeFs from 'node:fs';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Create a dummy directory structure for demonstration
const tempDir = join(__dirname, 'temp_walkdir_test');
const subDir = join(tempDir, 'subfolder');
nodeFs.mkdirSync(subDir, { recursive: true });
nodeFs.writeFileSync(join(tempDir, 'file1.txt'), 'Content 1');
nodeFs.writeFileSync(join(subDir, 'file2.txt'), 'Content 2');
nodeFs.writeFileSync(join(tempDir, 'another-file.js'), 'console.log("hello");');

console.log(`Walking directory: ${tempDir}`);

fs.walkdir(tempDir, (filepath, stats) => {
  if (stats.isDirectory()) {
    console.log(`[DIR] ${filepath}`);
  } else {
    console.log(`[FILE] ${filepath} (size: ${stats.size} bytes)`);
  }
}, (err) => {
  if (err) {
    console.error('Error during walkdir:', err);
  } else {
    console.log('Walkdir complete.');
  }

  // Clean up the dummy directory
  nodeFs.rmSync(tempDir, { recursive: true, force: true });
  console.log('Cleaned up temp directory.');
});

view raw JSON →