node-fs: Legacy FS Extension

Common errors

• TypeError: fs.createDirectory is not a function

  cause Attempting to use `fs.createDirectory` (or other `node-fs` methods) after requiring the native Node.js 'fs' module, or after `node-fs` failed to load/patch 'fs'.
  fix Ensure you are requiring `node-fs` correctly (`const fs = require('node-fs');`). However, the real fix is to stop using this abandoned package and migrate to native Node.js `fs` methods like `fs.mkdir(path, { recursive: true })`.

• Error: Cannot find module 'node-fs'

  cause The `node-fs` package is not installed in `node_modules` or Node.js cannot resolve the module path.
  fix Install the package via `npm install node-fs`. However, it's strongly recommended NOT to use this abandoned package. Instead, refactor your code to use the native `fs` module.

• Error: EACCES: permission denied, mkdir 'some/path'

  cause The Node.js process does not have sufficient permissions to create a directory or file at the specified path, which is a common operating system permission error.
  fix Ensure the Node.js process has write permissions to the target directory. On Linux/macOS, check file permissions with `ls -l` and use `chmod` if necessary. On Windows, verify folder security settings. This error is not specific to `node-fs` but common for any file system operation.

Warnings

• breaking This package is entirely incompatible with modern Node.js versions (v10+). Its functionalities are either natively implemented or have different, incompatible APIs in current Node.js releases. Attempting to use it will lead to runtime errors or unexpected behavior.
  Fix: Do not use this package. Migrate to native Node.js `fs` module functionalities. For recursive directory creation, use `fs.mkdir(path, { recursive: true })`. For recursive directory removal, use `fs.rm(path, { recursive: true, force: true })`.
• breaking The package is abandoned, with its last commit in 2011. It receives no maintenance, security updates, or bug fixes, making it a significant security risk for any application still using it.
  Fix: Immediately remove this package from your dependencies and refactor code to use modern Node.js `fs` features or well-maintained third-party alternatives like `fs-extra` if additional utility functions are required.
• deprecated Many functionalities provided by `node-fs`, such as recursive `mkdir` and `rmdir`, were eventually integrated into the native Node.js `fs` module with a different API signature and improved behavior. The `node-fs` API is effectively deprecated by native `fs` advancements.
  Fix: Rewrite code to use Node.js's native `fs.mkdir(path, { recursive: true })` (since v10.12.0) and `fs.rm(path, { recursive: true })` (since v14.14.0 for `fs.rmdir` or preferred `fs.rm` for file/directory).
• gotcha The `fs.watchTree` method provided by this package is an inefficient and unreliable pattern for file system watching. Modern Node.js provides `fs.watch` which is more performant and robust, though still has platform-specific caveats.
  Fix: Replace `fs.watchTree` with `fs.watch` from the native Node.js `fs` module, or use a robust third-party watcher library that handles complexities (e.g., `chokidar`).
• gotcha This package explicitly extends the Node.js `fs` module in a way that can lead to conflicts or unexpected behavior if other libraries also try to extend `fs` or if Node.js updates introduce new `fs` methods with the same names.
  Fix: Avoid using packages that monkey-patch or globally extend core Node.js modules. Prefer modular libraries that export their functionalities clearly or use native Node.js features.

Install

• npm install node-fs npm
• yarn add node-fs yarn
• pnpm add node-fs pnpm

Imports

• fs
  wrong:

  import { fs } from 'node-fs';

  correct:

  const fs = require('node-fs');

  This package exclusively uses CommonJS `require()` due to its age (Node.js 0.1.x era) and is incompatible with ESM `import` statements. The module exports an extended `fs` object.
• createDirectory
  wrong:

  const { createDirectory } = require('node-fs');

  correct:

  const fs = require('node-fs');
  fs.createDirectory('./path/to/dir', 0o777, (err) => { /* ... */ });

  The module extends the global `fs` object or returns an object with extended methods; individual functions are not typically destructured from the `require` call in this old CommonJS pattern. The `createDirectory` method has been superseded by `fs.mkdir(path, { recursive: true })` in modern Node.js.
• remove
  wrong:

  require('node-fs').remove('./path');

  correct:

  const fs = require('node-fs');
  fs.remove('./path/to/remove', (err) => { /* ... */ });

  This method for recursive deletion has been superseded by `fs.rm(path, { recursive: true, force: true })` in modern Node.js, with `fs.rmdir({ recursive: true })` being deprecated.

Quickstart

Demonstrates `node-fs`'s recursive directory creation and file copying features, then cleans up using modern Node.js `fs` methods.

const fs = require('node-fs');
const path = require('path');

const dirToCreate = path.join(__dirname, 'test-dir-legacy/sub-dir');
const fileToCopy = path.join(__dirname, 'test-file.txt');
const copiedFile = path.join(__dirname, 'test-dir-legacy/copied-file.txt');

// Create a dummy file for copying
require('fs').writeFileSync(fileToCopy, 'Hello from the past!');

console.log('Attempting to create directory recursively with node-fs...');
fs.createDirectory(dirToCreate, 0o777, true, (err) => {
  if (err) {
    console.error('Error creating directory:', err);
    return;
  }
  console.log(`Directory created: ${dirToCreate}`);

  console.log('Attempting to copy file with node-fs...');
  fs.copy(fileToCopy, copiedFile, (err) => {
    if (err) {
      console.error('Error copying file:', err);
      return;
    }
    console.log(`File copied from ${fileToCopy} to ${copiedFile}`);

    // Clean up (using modern fs for robust cleanup)
    console.log('Cleaning up...');
    require('fs').unlinkSync(fileToCopy);
    require('fs').unlinkSync(copiedFile);
    require('fs').rmdirSync(path.dirname(dirToCreate), { recursive: true });
    console.log('Cleanup complete.');
  });
});