# @stackline/fs-write-stream-atomic 1.0.0

Canonical documentation: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/
Repository: https://github.com/alexandroit/stackline-fs-write-stream-atomic
Registry: https://www.npmjs.com/package/@stackline/fs-write-stream-atomic
License: ISC
Runtime: Node.js >=14.15.1
Browser support: none
Compatibility baseline: fs-write-stream-atomic@1.0.10
Production dependencies: graceful-fs@4.2.11 only

## Purpose

@stackline/fs-write-stream-atomic creates a Node.js Writable that stages bytes
in an adjacent temporary file and renames the complete value over a target
after the physical file closes.

## Install and alias

Scoped dependency: npm install @stackline/fs-write-stream-atomic
Compatibility alias:
"fs-write-stream-atomic": "npm:@stackline/fs-write-stream-atomic@1.0.0"

The alias preserves existing require('fs-write-stream-atomic') calls. Commit
the manifest and lockfile, install cleanly, and run real filesystem tests.

## Module API

The CommonJS root is createWriteStreamAtomic(filename[, options]). It remains
callable with or without new and returns a core Writable subclass. Its
non-enumerable WriteStreamAtomic property is the constructor.

ESM exposes the same callable factory as default and WriteStreamAtomic as a
named export. CommonJS declarations support TypeScript 3.9; modern ESM
declarations supply the default and named constructor forms.

Supported package entries are ., ./index, ./index.js, and ./package.json. There
are no supported lib/* historical deep modules.

## Inputs and options

The documented filename is a string. Supported options include ordinary
WritableOptions plus encoding, highWaterMark, mode, flags, and
chown: { uid, gid }. A custom temporary directory is intentionally unsupported.
File descriptors, URL or Buffer paths, and disabling physical auto-close are
outside the supported contract.

## Writable and events

write(chunk[, encoding][, callback]) preserves callbacks and backpressure. If
write returns false, wait for drain before producing more. cork, uncork, end,
destroy, and standard Writable observations remain available.

open forwards the adjacent temporary file descriptor. On success the relevant
sequence is open; writes, callbacks, and possible drain; physical temporary
close; optional chown; rename; finish; close. Successful finish and close mean
the complete accepted value is visible at the target.

Use pipeline() for a source stream. Bare source.pipe(destination) does not
forward source errors; explicitly destroy the destination if the source is
managed separately.

## Preserved behavior

- The previous target remains visible until one adjacent rename.
- encoding, mode, flags, highWaterMark, callbacks, drain, cork, uncork, and
  chown remain supported.
- Concurrent writers produce one whole winning value, never interleaved bytes.
- flags:'a' writes to a new empty temporary file and replaces the target; it
  does not append to old target bytes.
- On Windows a rename EPERM counts as success only when target and temporary
  SHA-512 content match.

## Intentional corrections

- Temporary names combine process, worker-thread, invocation, and
  cryptographic random identity.
- Temporary files are opened exclusively.
- Explicit destroy, physical stream errors, chown/rename failures, and errors
  forwarded through pipeline clean up the sibling temporary file.
- The production graph uses core Writable and exact graceful-fs@4.2.11,
  removing iferr, imurmurhash, and readable-stream.

## Atomicity and trust boundary

Adjacent same-filesystem rename provides atomic visibility only where the
filesystem supplies it. No file or directory fsync is performed. The package
does not promise power-loss durability, serialize contending writers, or
provide a transaction across files.

The caller chooses the target path and must enforce an allowed root,
permissions, ownership policy, disk limits, cancellation, and trust boundary.
Abrupt process termination can leave a temporary file because JavaScript
cleanup cannot run reliably after termination.

No official advisory affecting upstream 1.0.10 was identified during intake.
Exclusive naming is defense-in-depth, not an assigned vulnerability or CVE.

## References

README: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/README.md
API: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/API.md
Changelog: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/CHANGELOG.md
Compatibility: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/COMPATIBILITY_CONTRACT.md
Migration: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/MIGRATION.md
Security: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/SECURITY.md
Licenses: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/THIRD_PARTY_LICENSES.md
CommonJS example: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/examples/commonjs.cjs
ESM example: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/examples/esm.mjs
Metadata: https://alexandro.net/docs/vanilla/fs-write-stream-atomic/package-meta.json