The File System

// One operation, three styles
import { readFile as readFileCb, readFileSync } from 'node:fs';
import { readFile } from 'node:fs/promises';

const catalog = new URL('./catalog.json', import.meta.url);

// 1. Promises: the default choice in application code
const viaPromise = JSON.parse(await readFile(catalog, 'utf8'));

// 2. Callback: error first, runs later
readFileCb(catalog, 'utf8', (err, text) => {
  if (err) throw err;
  console.log('callback  :', JSON.parse(text).length, 'books');
});

// 3. Sync: blocks the thread until the data is there
const viaSync = JSON.parse(readFileSync(catalog, 'utf8'));

console.log('promise   :', viaPromise.length, 'books');
console.log('sync      :', viaSync.length, 'books');

promise   : 3 books
sync      : 3 books
callback  : 3 books

// Three ways to name the same file
import { readFile } from 'node:fs/promises';
import { basename, join } from 'node:path';
import { fileURLToPath } from 'node:url';

// Relative paths are resolved against the working directory (where node was started)...
console.log('relative  :', await readFile('catalog.json').then(() => 'found', (err) => err.code));

// ...so anchor files to the module instead
const viaJoin = join(import.meta.dirname, 'catalog.json');       // a string path
const viaUrl = new URL('./catalog.json', import.meta.url);       // a file: URL
console.log('url       :', viaUrl.protocol, basename(fileURLToPath(viaUrl)));

const [fromPath, fromUrl, fromBuffer] = await Promise.all([
  readFile(viaJoin),
  readFile(viaUrl),
  readFile(Buffer.from(viaJoin)),                                 // a Buffer path: raw bytes on POSIX
]);
console.log('same bytes:', fromPath.equals(fromUrl) && fromPath.equals(fromBuffer), fromPath.length, 'bytes');

relative  : ENOENT
url       : file: catalog.json
same bytes: true 247 bytes
relative  : found
url       : file: catalog.json
same bytes: true 247 bytes

// readFile options: encoding, signal, a caller-supplied buffer (Node.js 26.4+), and a directory
import { readFile } from 'node:fs/promises';
import { Buffer } from 'node:buffer';

const file = new URL('./catalog.json', import.meta.url);

const bytes = await readFile(file);               // no encoding: a Buffer
const text = await readFile(file, 'utf8');        // a string (same as { encoding: 'utf8' })
console.log(Buffer.isBuffer(bytes), typeof text);

// Cancellation: the promise rejects with an AbortError
const controller = new AbortController();
const pending = readFile(file, { signal: controller.signal });
controller.abort();
try { await pending; } catch (err) { console.log('aborted    :', err.name, err.code); }

// Reading into memory you already own (v26.4.0 and later)
try {
  const scratch = Buffer.alloc(16 * 1024);
  const view = await readFile(file, { buffer: scratch });
  console.log('buffer opt :', view.length, 'bytes, shares memory:', view.buffer === scratch.buffer);
} catch (err) {
  console.log('buffer opt :', err.code ?? err.name);
}

// A directory is not a file
try { await readFile(new URL('.', import.meta.url)); } catch (err) { console.log('directory  :', err.code, err.syscall); }

true string
aborted    : AbortError ABORT_ERR
buffer opt : 247 bytes, shares memory: true
directory  : EISDIR read

true string
aborted    : AbortError ABORT_ERR
buffer opt : 247 bytes, shares memory: false
directory  : EISDIR read

// Writing: replace, append, create-only, and the file mode of a new file
import { writeFile, appendFile, readFile, stat, mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const dir = await mkdtemp(join(tmpdir(), 'bookshelf-'));
const file = join(dir, 'reading-list.txt');

try {
  await writeFile(file, 'Efficient Streams\n');                 // flag 'w': create or truncate
  await writeFile(file, 'Projects in Practice\n');              // replaces, does not append
  console.log(JSON.stringify(await readFile(file, 'utf8')));

  await appendFile(file, 'Event Loops Explained\n');            // flag 'a': create if needed, add at the end
  console.log(JSON.stringify(await readFile(file, 'utf8')));

  try {
    await writeFile(file, 'overwrite?\n', { flag: 'wx' });      // 'x': fail if the path exists
  } catch (err) {
    console.log('wx on existing file ->', err.code);
  }

  const secret = join(dir, 'token.txt');
  await writeFile(secret, 'placeholder\n', { mode: 0o600 });     // mode only applies to a newly created file
  console.log('new file mode  :', ((await stat(secret)).mode & 0o777).toString(8));
  await writeFile(secret, 'again\n', { mode: 0o644 });           // existing file: mode ignored
  console.log('after rewrite  :', ((await stat(secret)).mode & 0o777).toString(8));
} finally {
  await rm(dir, { recursive: true, force: true });
}

"Projects in Practice\n"
"Projects in Practice\nEvent Loops Explained\n"
wx on existing file -> EEXIST
new file mode  : 600
after rewrite  : 600

// Descriptor-based API: numbers instead of FileHandle objects. Every open needs a close.
import { openSync, readSync, closeSync, fstatSync, open, read, close } from 'node:fs';
import { promisify } from 'node:util';

const path = new URL('./catalog.json', import.meta.url);

// Synchronous: try/finally guarantees the close
const fd = openSync(path, 'r');
try {
  const { size } = fstatSync(fd);
  const head = Buffer.alloc(12);
  const n = readSync(fd, head, 0, head.length, 0);         // position 0
  console.log('sync    :', fd > 2, size, n, JSON.stringify(head.toString()));
} finally {
  closeSync(fd);
}

// Callback style, promisified with util.promisify when you need await
const openP = promisify(open);
const readP = promisify(read);
const closeP = promisify(close);
const fd2 = await openP(path, 'r');
try {
  const { bytesRead, buffer } = await readP(fd2, Buffer.alloc(12), 0, 12, 2);
  console.log('promisified:', bytesRead, JSON.stringify(buffer.toString()));
} finally {
  await closeP(fd2);
}

// The descriptor is gone after close: using it again fails
try { readSync(fd, Buffer.alloc(1), 0, 1, 0); } catch (err) { console.log('after close:', err.code); }

sync    : true 247 12 "[\n  { \"isbn\""
promisified: 12 "  { \"isbn\": "
after close: EBADF

// What stat() tells you, and how to ask without an exception
import { stat, lstat, access, constants } from 'node:fs/promises';
import { existsSync } from 'node:fs';

const file = new URL('./catalog.json', import.meta.url);
const s = await stat(file);
console.log({
  isFile: s.isFile(),
  isDirectory: s.isDirectory(),
  isSymbolicLink: s.isSymbolicLink(),
  size: s.size,
  mode: (s.mode & 0o777).toString(8),
  mtimeIsDate: s.mtime instanceof Date,
  mtimeMs: typeof s.mtimeMs,
});

const exact = await stat(file, { bigint: true });
console.log('bigint:', typeof exact.size, typeof exact.mtimeMs, typeof exact.mtimeNs);

// A missing entry: undefined instead of ENOENT (async option since v25.7.0)
const missing = new URL('./nope.txt', import.meta.url);
try {
  console.log('throwIfNoEntry:', await stat(missing, { throwIfNoEntry: false }));
} catch (err) {
  console.log('throwIfNoEntry option not honoured:', err.code);
}

// Existence checks (only for reporting; do not use them before opening)
console.log('existsSync   :', existsSync(file), existsSync(missing));
await access(file, constants.R_OK).then(() => console.log('access R_OK  : ok'));
console.log('Instant props:', 'mtimeInstant' in s, typeof s.mtimeInstant);

{
  isFile: true,
  isDirectory: false,
  isSymbolicLink: false,
  size: 247,
  mode: '644',
  mtimeIsDate: true,
  mtimeMs: 'number'
}
bigint: bigint bigint bigint
throwIfNoEntry: undefined
existsSync   : true false
access R_OK  : ok
Instant props: true object

// Permissions: umask and the mode of a new file, chmod, access(), and what a denied read looks like
import { writeFile, chmod, stat, access, readFile, mkdtemp, rm, constants } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const octal = async (path) => ((await stat(path)).mode & 0o777).toString(8).padStart(3, '0');
const dir = await mkdtemp(join(tmpdir(), 'bookshelf-'));
const file = join(dir, 'report.txt');
try {
  const previous = process.umask(0o077);              // setting a umask returns the old one
  await writeFile(file, 'q3 numbers\n');              // default mode 0o666 minus the umask bits
  console.log('umask 077 ->', await octal(file));
  process.umask(previous);

  await chmod(file, 0o400);                           // owner may read, nobody may write
  console.log('chmod 400  ->', await octal(file));
  await access(file, constants.R_OK).then(() => console.log('R_OK        : allowed'));
  await access(file, constants.W_OK).catch((err) => console.log('W_OK        :', err.code));
  await writeFile(file, 'overwrite\n').catch((err) => console.log('writeFile   :', err.code, err.syscall));

  await chmod(file, 0o000);
  await readFile(file).catch((err) => console.log('readFile    :', err.code, err.syscall));
} finally {
  await rm(dir, { recursive: true, force: true });     // removing needs the directory's permissions, not the file's
}

umask 077 -> 600
chmod 400  -> 400
R_OK        : allowed
W_OK        : EACCES
writeFile   : EACCES open
readFile    : EACCES open

// Symbolic links, hard links, and why stat() and lstat() disagree
import { writeFile, symlink, link, readlink, realpath, stat, lstat, unlink, rm, mkdtemp, readFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const dir = await realpath(await mkdtemp(join(tmpdir(), 'bookshelf-')));   // realpath: /tmp is itself a link on macOS
try {
  const real = join(dir, 'catalog-2025.json');
  const alias = join(dir, 'catalog.json');
  const hard = join(dir, 'catalog-copy.json');
  await writeFile(real, '[]\n');

  await symlink('catalog-2025.json', alias);          // target is stored as given (relative here)
  await link(real, hard);                             // a second name for the same data

  console.log('readlink    :', await readlink(alias));
  console.log('stat  alias :', (await stat(alias)).isSymbolicLink(), '(follows the link)');
  console.log('lstat alias :', (await lstat(alias)).isSymbolicLink(), '(looks at the link itself)');
  console.log('realpath ok :', (await realpath(alias)) === real);
  const a = await stat(real, { bigint: true });
  const b = await stat(hard, { bigint: true });
  console.log('hard link   : same inode', a.ino === b.ino, ', nlink', (await stat(real)).nlink);

  await unlink(real);                                 // remove one name; data stays reachable through the hard link
  console.log('copy still  :', JSON.stringify(await readFile(hard, 'utf8')));
  console.log('alias now   :', await stat(alias).catch((err) => err.code), '(dangling link)');
  console.log('lstat alias :', (await lstat(alias)).isSymbolicLink());

  await symlink('loop-b', join(dir, 'loop-a'));
  await symlink('loop-a', join(dir, 'loop-b'));
  console.log('loop        :', await readFile(join(dir, 'loop-a')).catch((err) => err.code));
} finally {
  await rm(dir, { recursive: true, force: true });
}

readlink    : catalog-2025.json
stat  alias : false (follows the link)
lstat alias : true (looks at the link itself)
realpath ok : true
hard link   : same inode true , nlink 2
copy still  : "[]\n"
alias now   : ENOENT (dangling link)
lstat alias : true
loop        : ELOOP

// rename() is atomic but cannot cross a file system boundary (EXDEV); fall back to copy + delete
import { rename, copyFile, unlink, writeFile, readFile, mkdtemp, rm, constants } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

async function move(from, to) {
  try {
    await rename(from, to);
    return 'rename';
  } catch (err) {
    if (err.code !== 'EXDEV') throw err;
    await copyFile(from, to, constants.COPYFILE_EXCL);   // refuse to overwrite an existing target
    await unlink(from);                                   // only after the copy succeeded
    return 'copy + unlink';
  }
}

// Pass another volume as the first argument to take the fallback path
const sourceDir = await mkdtemp(join(process.argv[2] ?? tmpdir(), 'move-src-'));
const targetDir = await mkdtemp(join(tmpdir(), 'move-dst-'));
try {
  const from = join(sourceDir, 'cover.png');
  const to = join(targetDir, 'cover.png');
  await writeFile(from, 'png bytes');
  console.log('strategy :', await move(from, to));
  console.log('content  :', await readFile(to, 'utf8'));

  await writeFile(from, 'second copy');
  await copyFile(from, to, constants.COPYFILE_EXCL).catch((err) => console.log('no clobber:', err.code));
} finally {
  await rm(sourceDir, { recursive: true, force: true });
  await rm(targetDir, { recursive: true, force: true });
}

strategy : rename
content  : png bytes
no clobber: EEXIST
strategy : copy + unlink
content  : png bytes
no clobber: EEXIST

// Probe the file system you are on instead of guessing from process.platform
import { writeFile, readdir, stat, utimes, mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const dir = await mkdtemp(join(process.argv[2] ?? tmpdir(), 'bookshelf-probe-'));
try {
  // Case sensitivity: create "probe.txt", then ask for "PROBE.TXT"
  await writeFile(join(dir, 'probe.txt'), 'x');
  const caseInsensitive = await stat(join(dir, 'PROBE.TXT')).then(() => true, () => false);

  // Case preservation: what name does the directory listing return?
  await writeFile(join(dir, 'MixedCase.txt'), 'x');
  const listed = (await readdir(dir)).includes('MixedCase.txt');

  // Unicode form: create the NFC name, look for the NFD spelling
  const nfc = 'café.txt';
  const nfd = nfc.normalize('NFD');
  await writeFile(join(dir, nfc), 'x');
  const normalizationInsensitive = await stat(join(dir, nfd)).then(() => true, () => false);
  const names = (await readdir(dir)).filter((n) => n.startsWith('caf'));
  const stored = names[0] === nfc ? 'NFC' : 'NFD';

  // Timestamp resolution: set a mtime with millisecond detail and read it back
  const wanted = new Date(1_444_291_759_414);          // ...414 ms
  await utimes(join(dir, 'probe.txt'), wanted, wanted);
  const mtimeMs = (await stat(join(dir, 'probe.txt'), { bigint: true })).mtimeMs;

  console.log({ caseInsensitive, casePreserved: listed, normalizationInsensitive, storedAs: stored, mtimeMs });
  console.log('NFC length', nfc.length, 'NFD length', nfd.length, 'equal when normalised:', nfc.normalize('NFC') === nfd.normalize('NFC'));
} finally {
  await rm(dir, { recursive: true, force: true });
}

{
  caseInsensitive: true,
  casePreserved: true,
  normalizationInsensitive: true,
  storedAs: 'NFC',
  mtimeMs: 1444291759414n
}
NFC length 8 NFD length 9 equal when normalised: true

// The errors you will meet: always branch on err.code
import { readFile, writeFile, mkdir, rmdir, rm, mkdtemp, chmod, open } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const dir = await mkdtemp(join(tmpdir(), 'bookshelf-'));
const trial = async (label, fn) => {
  try { await fn(); console.log(label.padEnd(26), 'ok'); }
  catch (err) { console.log(label.padEnd(26), err.code.padEnd(10), err.syscall); }
};
try {
  await writeFile(join(dir, 'file.txt'), 'x');
  await mkdir(join(dir, 'sub'));
  await writeFile(join(dir, 'sub', 'inner.txt'), 'x');
  await writeFile(join(dir, 'locked.txt'), 'x', { mode: 0o000 });

  await trial('read missing file', () => readFile(join(dir, 'missing.txt')));
  await trial('read a directory', () => readFile(join(dir, 'sub')));
  await trial('mkdir existing', () => mkdir(join(dir, 'sub')));
  await trial('create with wx', () => writeFile(join(dir, 'file.txt'), 'y', { flag: 'wx' }));
  await trial('path through a file', () => readFile(join(dir, 'file.txt', 'child')));
  await trial('read without permission', () => readFile(join(dir, 'locked.txt')));
  await trial('rmdir non-empty', () => rmdir(join(dir, 'sub')));
  await trial('open missing for reading', () => open(join(dir, 'nope'), 'r'));
} finally {
  await rm(dir, { recursive: true, force: true });
}

read missing file          ENOENT     open
read a directory           EISDIR     read
mkdir existing             EEXIST     mkdir
create with wx             EEXIST     open
path through a file        ENOTDIR    open
read without permission    EACCES     open
rmdir non-empty            ENOTEMPTY  rmdir
open missing for reading   ENOENT     open

// Two file-backed helpers: a Blob that reads lazily from disk, and an experimental fast log writer
import { openAsBlob, Utf8Stream } from 'node:fs';
import { readFile, mkdtemp, rm } from 'node:fs/promises';
import { once } from 'node:events';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const catalog = new URL('./catalog.json', import.meta.url);
const blob = await openAsBlob(catalog, { type: 'application/json' });   // stable since v24.0.0 / v22.17.0
console.log('blob       :', blob.type, blob.size, 'bytes');
console.log('slice      :', JSON.stringify(await blob.slice(0, 8).text()));   // reads only that range

const dir = await mkdtemp(join(tmpdir(), 'bookshelf-'));
try {
  const log = new Utf8Stream({ dest: join(dir, 'app.log'), sync: false, minLength: 4096 });   // Stability 1 - Experimental
  await once(log, 'ready');
  for (let i = 0; i < 3; i++) log.write(`line ${i}\n`);     // buffered, not yet on disk
  log.end();                                                 // flush, then close
  await once(log, 'finish');
  console.log('log file   :', JSON.stringify(await readFile(join(dir, 'app.log'), 'utf8')));
} finally {
  await rm(dir, { recursive: true, force: true });
}

blob       : application/json 247 bytes
slice      : "[\n  { \"i"
log file   : "line 0\nline 1\nline 2\n"