Function writeFileDurable

src/fs.ts:34–57

* Crash-durable atomic write: write to tmp → fsync file → rename → fsync parent dir. * On power loss, the target file either has the old content or the full new content — * never zero-byte or partially-written.

(filePath: string, content: string, mode: number)

 * never zero-byte or partially-written.
 */
async function writeFileDurable(filePath: string, content: string, mode: number): Promise<void> {
  const tmp = filePath + '.tmp';
  const handle = await open(tmp, 'w', mode);
  try {
    await handle.writeFile(content, 'utf8');
    await handle.sync();
  } finally {
    await handle.close();
  }
  await rename(tmp, filePath);
  // fsync the parent directory so the rename itself is durable.
  const parent = path.dirname(filePath);
  try {
    const dirHandle = await open(parent, 'r');
    try {
      await dirHandle.sync();
    } finally {
      await dirHandle.close();
    }
  } catch {
    // Some platforms (Windows) can't open a dir for fsync. The file fsync
    // above is still the critical durability guarantee.
  }
}

export async function writeJson(filePath: string, value: unknown, options: WriteOptions = {}): Promise<void> {
  await writeFileDurable(filePath, JSON.stringify(value, null, 2), options.mode ?? 0o600);