@stackline/fs-write-stream-atomic
Compatibility-first atomic filesystem Writable streams with maintained lifecycle handling and first-party types.
Documentation | npm | Issues | Repository
Current package version: 1.0.4
Why this package?
A compatibility-first maintained continuation of
fs-write-stream-atomic@1.0.10. It exposes a Node.js Writable stream that
writes to an adjacent temporary file and replaces the target only after the
temporary stream has closed successfully.
Compatibility
| Item | Value |
|---|---|
| Package | @stackline/fs-write-stream-atomic@1.0.4 |
| Node.js runtime | >=14.15.1 |
| CommonJS / primary entry | ./index.js |
| ES module entry | ./index.mjs |
| Type declarations | ./index.d.ts |
Installation
npm install @stackline/fs-write-stream-atomic
Usage
npm install @stackline/fs-write-stream-atomic
Existing dependency keys can migrate with an npm alias:
npm install fs-write-stream-atomic@npm:@stackline/fs-write-stream-atomic
CommonJS
const createWriteStreamAtomic = require('@stackline/fs-write-stream-atomic')
const output = createWriteStreamAtomic('output.txt', { mode: 0o600 })
output.on('error', console.error)
output.on('close', () => console.log('replacement visible'))
output.end('complete value')
The factory remains callable with or without new.
ESM
import createWriteStreamAtomic, { WriteStreamAtomic } from '@stackline/fs-write-stream-atomic'
const output = new WriteStreamAtomic('output.txt')
output.end('complete value')
Features and Integrations
Error and cancellation cleanup
Use stream.pipeline() when connecting a source so a source error destroys the
destination and removes its temporary file:
const { pipeline } = require('stream')
pipeline(input, createWriteStreamAtomic('output.txt'), callback)
Bare .pipe() does not forward source errors. Call destination.destroy(error)
yourself if the source is managed separately. Explicit destroy and ordinary
write/chown/rename failures are cleaned up. Abrupt process termination can
still leave a temporary file.
Security
Atomicity boundary
The adjacent rename supplies atomic visibility on filesystems that provide it. This package does not fsync the file or parent directory and does not claim power-loss durability. It is not a transaction across multiple files.
See COMPATIBILITY_CONTRACT.md and MIGRATION.md before replacing the historical package.
API Surface
Options and events
The documented filename is a string. Writable and file-stream options such as
encoding, mode, flags, and highWaterMark are supported. An additional
chown: { uid, gid } option applies ownership before rename.
open reflects the temporary file descriptor. On success, finish occurs
only after the physical file closes and rename succeeds; close follows it.
The existing target remains visible until then. Contending writers publish one
complete winner.
Append flags preserve upstream behavior: because every operation starts with
a new temporary file, flags: 'a' replaces the target with newly streamed
content rather than appending to its old content.
Local Development
git clone https://github.com/alexandroit/stackline-fs-write-stream-atomic.git
cd stackline-fs-write-stream-atomic
npm ci
npm run verify
Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.
Consumer Smoke Test
Run the repository's existing consumer/package check after installing development dependencies:
npm run test:smoke
Release Checklist
Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.
License
ISC. See the license for the complete terms.
Original authorship and third-party attribution are preserved in NOTICE.
Credits and original authors
- Stackline Maintainers.
- Copyright (c) 2026 Stackline Maintainers.
- Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.
Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.
Community and Links
Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.