From 33863591de28a28acd31d9cf9bb6f108b6a0a059 Mon Sep 17 00:00:00 2001
From: lluviaoscuradeldoce-design <lluviaoscuradeldoce@example.com>
Date: Thu, 29 Jan 2026 16:30:18 -0500
Subject: [PATCH] perf(infra): add async versions of JSON file operations

- Add loadJsonFileAsync() for non-blocking file reads
- Add saveJsonFileAsync() for non-blocking file writes
- Preserves original sync functions for backward compatibility
---
 src/infra/json-file.ts | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/src/infra/json-file.ts b/src/infra/json-file.ts
index 19c8169f7..2afc82d13 100644
--- a/src/infra/json-file.ts
+++ b/src/infra/json-file.ts
@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 
+/**
+ * Synchronously loads a JSON file. Use `loadJsonFileAsync` for non-blocking I/O.
+ */
 export function loadJsonFile(pathname: string): unknown {
   try {
     if (!fs.existsSync(pathname)) return undefined;
@@ -11,6 +14,22 @@ export function loadJsonFile(pathname: string): unknown {
   }
 }
 
+/**
+ * Asynchronously loads a JSON file. Preferred for hot paths to avoid blocking.
+ */
+export async function loadJsonFileAsync(pathname: string): Promise<unknown> {
+  try {
+    await fs.promises.access(pathname, fs.constants.F_OK);
+    const raw = await fs.promises.readFile(pathname, "utf8");
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Synchronously saves a JSON file. Use `saveJsonFileAsync` for non-blocking I/O.
+ */
 export function saveJsonFile(pathname: string, data: unknown) {
   const dir = path.dirname(pathname);
   if (!fs.existsSync(dir)) {
@@ -19,3 +38,21 @@ export function saveJsonFile(pathname: string, data: unknown) {
   fs.writeFileSync(pathname, `${JSON.stringify(data, null, 2)}\n`, "utf8");
   fs.chmodSync(pathname, 0o600);
 }
+
+/**
+ * Asynchronously saves a JSON file. Preferred for hot paths to avoid blocking.
+ */
+export async function saveJsonFileAsync(pathname: string, data: unknown): Promise<void> {
+  const dir = path.dirname(pathname);
+  try {
+    await fs.promises.access(dir, fs.constants.F_OK);
+  } catch {
+    await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+  }
+  await fs.promises.writeFile(pathname, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  try {
+    await fs.promises.chmod(pathname, 0o600);
+  } catch {
+    // Best-effort on platforms without chmod support
+  }
+}