examples-atomic.js

/**
 * Atomic Writes Examples
 *
 * This file demonstrates the atomic writes feature in filejson,
 * which provides crash safety and prevents data corruption.
 */

const Filejson = require("./app.js");
const fs = require("fs");
const path = require("path");

// Create a test directory
const testDir = path.join(__dirname, "examples-atomic");
if (!fs.existsSync(testDir)) {
  fs.mkdirSync(testDir, { recursive: true });
}

console.log("=".repeat(60));
console.log("Atomic Writes Examples");
console.log("=".repeat(60));

/**
 * Example 1: Default Behavior - Atomic Writes Enabled
 *
 * By default, atomic writes are enabled to protect your data.
 */
async function example1() {
  console.log("\n📝 Example 1: Default Atomic Writes (Enabled)");
  console.log("-".repeat(60));

  const testFile = path.join(testDir, "atomic-default.json");
  const file = new Filejson();

  await file.load(testFile, { status: "initial", count: 0 });
  console.log("✅ File loaded with atomic writes enabled (default)");

  // Make changes - these will be saved atomically
  file.contents.status = "updated";
  file.contents.count = 100;
  file.contents.data = { nested: "value" };

  console.log("✍️  Making changes...");
  await file.save();
  console.log("✅ Changes saved atomically (temp file → rename)");
  console.log("   - No corruption possible even if process crashes");
  console.log("   - Other processes never see partial writes");
}

/**
 * Example 2: Explicitly Enabling Atomic Writes
 *
 * You can explicitly enable atomic writes in the config.
 */
async function example2() {
  console.log("\n📝 Example 2: Explicitly Enable Atomic Writes");
  console.log("-".repeat(60));

  const testFile = path.join(testDir, "atomic-explicit.json");
  const file = new Filejson({
    atomicWrites: true, // Explicitly enabled
    verbose: false,
  });

  await file.load(testFile, { critical: "data" });
  console.log("✅ Atomic writes explicitly enabled");

  file.contents.critical = "important information";
  file.contents.timestamp = Date.now();

  await file.save();
  console.log("✅ Critical data saved with atomic write protection");
}

/**
 * Example 3: Disabling Atomic Writes
 *
 * In some edge cases (e.g., network file systems), you may want
 * to disable atomic writes for performance.
 */
async function example3() {
  console.log("\n📝 Example 3: Disable Atomic Writes (Not Recommended)");
  console.log("-".repeat(60));

  const testFile = path.join(testDir, "no-atomic.json");
  const file = new Filejson({
    atomicWrites: false, // Disabled
  });

  await file.load(testFile, { data: "test" });
  console.log("⚠️  Atomic writes disabled");

  file.contents.data = "updated";
  await file.save();
  console.log("✅ Saved directly (faster but not crash-safe)");
  console.log("   - Risk: File could be corrupted if process crashes");
  console.log("   - Use only for non-critical data or special file systems");
}

/**
 * Example 4: Atomic Writes with Debounce
 *
 * Atomic writes work seamlessly with the debounce feature.
 */
async function example4() {
  console.log("\n📝 Example 4: Atomic Writes + Debounce");
  console.log("-".repeat(60));

  const testFile = path.join(testDir, "atomic-debounce.json");
  const file = new Filejson({
    saveDelay: 100, // Debounce for 100ms
    atomicWrites: true, // Atomic writes enabled
  });

  await file.load(testFile, { counter: 0 });
  console.log("✅ Loaded with both debounce and atomic writes");

  // Make rapid changes
  console.log("✍️  Making 1000 rapid changes...");
  for (let i = 1; i <= 1000; i++) {
    file.contents.counter = i;
  }

  console.log("⏳ Waiting for debounce...");
  await new Promise((resolve) => setTimeout(resolve, 200));

  console.log("✅ Only ONE atomic write occurred (despite 1000 changes)");
  console.log("   - Debounce reduced writes");
  console.log("   - Atomic write ensured safety");

  const data = JSON.parse(fs.readFileSync(testFile, "utf-8"));
  console.log(`   - Final value: ${data.counter}`);
}

/**
 * Example 5: Production Use Case
 *
 * Real-world scenario: Storing critical application state.
 */
async function example5() {
  console.log("\n📝 Example 5: Production Use Case");
  console.log("-".repeat(60));

  const testFile = path.join(testDir, "app-state.json");
  const appState = new Filejson({
    saveDelay: 100, // Debounce frequent updates
    atomicWrites: true, // Crash safety
    space: 2, // Pretty formatting
  });

  // Initialize or load existing state
  await appState.load(testFile, {
    version: "1.0.0",
    users: [],
    settings: {},
    lastUpdate: null,
  });

  console.log("✅ Application state loaded");

  // Simulate application updates
  console.log("✍️  Simulating user activity...");

  appState.contents.users.push({ id: 1, name: "Alice" });
  appState.contents.users.push({ id: 2, name: "Bob" });
  appState.contents.settings.theme = "dark";
  appState.contents.settings.language = "en";
  appState.contents.lastUpdate = new Date().toISOString();

  // Wait for debounce
  await new Promise((resolve) => setTimeout(resolve, 150));

  console.log("✅ Application state saved atomically");
  console.log("   - If app crashes, state is never corrupted");
  console.log("   - Users won't lose data");
  console.log("   - Safe for production use");

  const state = JSON.parse(fs.readFileSync(testFile, "utf-8"));
  console.log(`   - Users stored: ${state.users.length}`);
  console.log(`   - Settings: ${Object.keys(state.settings).length}`);
}

/**
 * Example 6: Comparing Behaviors
 *
 * Demonstrates the difference between atomic and non-atomic writes.
 */
async function example6() {
  console.log("\n📝 Example 6: Comparing Write Behaviors");
  console.log("-".repeat(60));

  console.log("\n🔒 WITH Atomic Writes (Recommended):");
  console.log("   1. Write data to temp file: data.json.tmp123");
  console.log("   2. Rename temp → target: atomic operation");
  console.log("   3. Other processes see: old OR new (never partial)");
  console.log("   ✅ Safe even if crash happens between steps");

  console.log("\n⚠️  WITHOUT Atomic Writes:");
  console.log("   1. Write data directly to: data.json");
  console.log("   2. Other processes might see: partial data");
  console.log("   3. If crash occurs: data.json may be corrupted");
  console.log("   ❌ NOT safe for critical data");

  console.log("\n📊 Performance Comparison:");
  console.log("   - Atomic: ~1-5% slower (one extra rename)");
  console.log("   - Direct: ~1-5% faster (but risky)");
  console.log("   - Recommendation: Use atomic writes (default)");
}

/**
 * Run all examples
 */
async function runAllExamples() {
  try {
    await example1();
    await example2();
    await example3();
    await example4();
    await example5();
    await example6();

    console.log("\n" + "=".repeat(60));
    console.log("✅ All examples completed successfully!");
    console.log("=".repeat(60));
    console.log("\n💡 Key Takeaways:");
    console.log("   • Atomic writes are ENABLED by default");
    console.log("   • They prevent data corruption on crashes");
    console.log("   • Performance overhead is negligible");
    console.log("   • Works great with debounce feature");
    console.log("   • Recommended for production use");
    console.log("   • Disable only for special cases (NFS, etc.)");
    console.log("\n");
  } catch (error) {
    console.error("❌ Error running examples:", error);
  }
}

// Run examples if this file is executed directly
if (require.main === module) {
  runAllExamples();
}

module.exports = { runAllExamples };