npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@sandsoftwaresolutions/atomic-file

v0.1.1

Published

Write files atomically so a crash or power cut never leaves half a file. JSON helpers that never mistake a corrupt file for a missing one.

Readme

@sandsoftwaresolutions/atomic-file

CI

Write files so that nobody ever sees half of one, even if the power goes out in the middle. For settings, state files and anything on a Raspberry Pi that gets switched off by the plug. No dependencies.

Install

npm install @sandsoftwaresolutions/atomic-file

Works with import and require(), and ships TypeScript types for both.

Usage

import { writeFileAtomic, writeJsonAtomic, readJson } from "@sandsoftwaresolutions/atomic-file";

await writeFileAtomic("/var/lib/app/state.json", text);

await writeJsonAtomic("state.json", { lastRun: Date.now() });
const state = await readJson("state.json", { fallback: { lastRun: 0 } });

Why not just fs.writeFile?

writeFile first empties the file, then fills it. If the process stops in between (crash, kill, power loss), you are left with an empty or half-written file. This package writes the data to a temporary file in the same folder, flushes it to disk, and renames it over the old one in a single step. After that the folder entry is flushed too. At any moment the file is either the complete old content or the complete new content.

Details

  • writeFileAtomic(path, data) takes a string or bytes. writeFileAtomicSync is the synchronous twin.
  • The permissions of the file you replace are kept exactly (the umask does not reduce them), or pass { mode }. A new file without mode gets 0o644 minus the umask. The owner of the file is not carried over.
  • A symbolic link is written through: the link stays and the file it points to is replaced.
  • On failure the old file is untouched and the temporary file is removed.
  • fsync: false skips the flushing when speed matters more than surviving a power cut.
  • readJson ignores a byte order mark. readJson with fallback only covers a missing file. A file that exists but is not valid JSON always throws, with its path in the message, so a damaged state file is never silently replaced by defaults.
  • On Windows the rename is retried for about a second when a virus scanner or a busy reader holds the file (a reader that opens the file in a tight loop made the 0.3 s of the first version run out with EPERM).
  • The temporary file lives in the same folder (it has to be on the same disk for the rename to be atomic), so that folder must be writable.

It makes a single file write safe. It does not make a read-modify-write cycle safe against another process doing the same: combine it with @sandsoftwaresolutions/file-lock for that.