Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/** JSON, JSONL, and cached-store file IO helpers. */
import { open, readFile, readdir, stat } from 'fs/promises';
import { basename, dirname } from 'path';
import { appendFileGuarded, atomicWrite, ensureDir, sleep } from './fileCore.js';
import { createFileWriteQueue } from './fileWriteQueue.js';
const isWindows = () => process.platform === 'win32';
const WIN_RETRY_ATTEMPTS = 5;
const WIN_RETRY_DELAY_MS = 10;
const WIN_READ_LOCK_CODES = ['EPERM', 'EACCES', 'EBUSY'];
/**
* Index of the first JSON array token in `str`, or -1 when it holds none.
*
* Split out of `extractJSONArray` so a caller can tell "found an array" from "found
* nothing" — a distinction `extractJSONArray` erases by design (it manufactures a
* literal '[]' for the not-found case). `readJSONFileStrict` needs it: for a
* swallowing caller a manufactured '[]' is just the default, but for a strict one it
* would forge a trustworthy-looking EMPTY out of unreadable bytes.
*
* @param {string} str
* @returns {number} Index of the array start, or -1
*/
function findJSONArrayStart(str) {
if (!str) return -1;
// Look for '[{' (array with objects) first
const objectStart = str.indexOf('[{');
if (objectStart >= 0) return objectStart;
// Check for empty array - find '[]' that's not part of ANSI codes like [31m
const emptyMatch = str.match(/\[\](?![0-9])/);
return emptyMatch ? str.indexOf(emptyMatch[0]) : -1;
}
/**
* Extract JSON array from string that may contain ANSI codes or other noise.
* Useful for parsing pm2 jlist output which may include warnings before the JSON.
*
* @param {string} str - String potentially containing JSON array
* @returns {string} Extracted JSON or '[]' if not found
*/
export function extractJSONArray(str) {
const jsonStart = findJSONArrayStart(str);
return jsonStart >= 0 ? str.slice(jsonStart) : '[]';
}
/**
* Safely parse JSON with validation and fallback.
* Avoids "Unexpected end of JSON input" errors from empty/corrupted files.
* For arrays, automatically extracts JSON from strings with ANSI codes/noise (e.g., pm2 output).
*
* @param {string} str - JSON string to parse
* @param {*} defaultValue - Default value if parsing fails (default: null)
* @param {Object} options - Parse options
* @param {boolean} [options.allowArray=true] - Allow array JSON
* @param {boolean} [options.logError=false] - Log parsing errors
* @param {string} [options.context=''] - Context for error logging
* @returns {*} Parsed JSON or default value
*
* @example
* safeJSONParse('{"key": "value"}', {}) // { key: "value" }
* safeJSONParse('', {}) // {}
* safeJSONParse('invalid', []) // []
* safeJSONParse(null, { default: true }) // { default: true }
*/
export function safeJSONParse(str, defaultValue = null, { allowArray = true, logError = false, context = '' } = {}) {
// For arrays, try to extract JSON from noisy output (e.g., pm2 with ANSI codes)
if (allowArray && Array.isArray(defaultValue) && str && !str.trim().startsWith('[')) {
str = extractJSONArray(str);
}
if (!str || !str.trim()) {
if (logError && str) {
console.warn(`⚠️ Invalid JSON${context ? ` in ${context}` : ''}: empty or malformed content`);
}
return defaultValue;
}
try {
const parsed = JSON.parse(str);
if (!allowArray && Array.isArray(parsed)) {
if (logError) {
console.warn(`⚠️ Invalid JSON${context ? ` in ${context}` : ''}: array not allowed`);
}
return defaultValue;
}
return parsed;
} catch (err) {
if (logError) {
console.warn(`⚠️ Failed to parse JSON${context ? ` in ${context}` : ''}: ${err.message}`);
}
return defaultValue;
}
}
/**
* Read a file, returning null on any error (missing file, permission denied, etc.).
*
* Collapses the inlined `readFile(path, encoding).catch(() => null)` pattern used
* across services for "optional file — fall through if absent." For Buffer reads,
* pass `encoding: null` (or omit when calling with no second arg, default 'utf8').
*
* NOTE: like `readJSONFile`, this conflates "absent" with "unreadable" — both
* return null. When the caller derives a user-visible stat from the result (where
* a fake empty is a lie, not a default), reach for `tryReadFileStrict` (raw bytes)
* or `readJSONFileStrict` (parsed JSON) instead.
*
* @param {string} filePath - Path to read
* @param {string|null} [encoding='utf8'] - Encoding (null for Buffer)
* @returns {Promise<string|Buffer|null>} File contents or null on any read error
*/
export async function tryReadFile(filePath, encoding = 'utf8') {
return readFile(filePath, encoding).catch(() => null);
}
/**
* `tryReadFile` that reports whether the read is TRUSTWORTHY — the raw-bytes
* counterpart to `readJSONFileStrict`, for callers that parse (or count, or
* display) the contents themselves rather than handing the file to JSON.parse.
*
* - ENOENT (never written) → `{ ok: true, value: null }` — a genuine "nothing
* here yet". Safe to treat as a real empty.
* - any other read error → `{ ok: false, value: null }` — EACCES, EIO,
* EISDIR, a transient FS failure. We do NOT know the file is absent.
* - read → `{ ok: true, value: contents }`
*
* So the three states `tryReadFile` collapses into one `null` stay separable:
* `ok && value !== null` = read, `ok && value === null` = absent, `!ok` =
* present-but-unreadable. Windows swap-window retries are shared with
* `readJSONFileStrict`, so an `atomicWrite` in flight can't masquerade as ENOENT.
*
* @param {string} filePath - Path to read
* @param {string|null} [encoding='utf8'] - Encoding (null for Buffer)
* @returns {Promise<{ ok: boolean, value: string|Buffer|null }>}
*
* @example
* const { ok, value } = await tryReadFileStrict(LEDGER_FILE);
* if (!ok) throw new Error('ledger unreadable'); // never report a fake 0
*/
export async function tryReadFileStrict(filePath, encoding = 'utf8') {
return readWithSwapRetry(filePath, encoding).then(
(value) => ({ ok: true, value }),
// ENOENT is the ONLY errno that proves absence. Everything else — EACCES on
// the file or a parent dir, ENOTDIR, EIO — means we could not confirm it,
// which must stay distinct from "confirmed empty".
(err) => ({ ok: err?.code === 'ENOENT', value: null })
);
}
/**
* Read at most `maxBytes` from the END of a file, as UTF-8.
*
* The bounded-memory counterpart to `tryReadFile` for append-only logs and
* spools that have no upper size bound (agent transcripts, PTY spools, CLI
* rollout JSONL). `readFile` on one of those loads the whole thing into heap;
* this reads only the trailing window.
*
* Non-throwing, with the sentinel distinction the AGENTS.md rule demands:
* - missing / unopenable / read error → `null`
* - zero-byte file → `''`
* so a caller can tell "nothing to read" from "couldn't read".
*
* The window starts at a BYTE offset, so when the file is larger than
* `maxBytes` the first line comes back partial (and can begin mid-multibyte
* character). Callers that split on newlines should drop that leading fragment.
*
* @param {string} path - File to read
* @param {number} maxBytes - Maximum trailing bytes to read
* @returns {Promise<string|null>} Trailing text, `''` for an empty file, or null on error
*/
export async function readFileTail(path, maxBytes) {
const info = await stat(path).catch(() => null);
if (!info) return null;
if (info.size === 0) return '';
const start = Math.max(0, info.size - maxBytes);
const length = info.size - start;
const handle = await open(path, 'r').catch(() => null);
if (!handle) return null;
try {
const buffer = Buffer.alloc(length);
// Honour bytesRead — the file can shrink between stat and read, or the OS
// can return a short read; decoding the whole `buffer` would append NULs.
// A read failure surfaces as null so callers keep the ''-vs-null contract.
const result = await handle.read(buffer, 0, length, start).catch(() => null);
if (result === null) return null;
return buffer.toString('utf8', 0, result.bytesRead);
} finally {
await handle.close().catch(() => {});
}
}
// Private sentinel for "the parse produced nothing usable". A unique Symbol, NOT
// null/undefined — a file whose real contents parse to the caller's defaultValue
// must stay distinguishable from a file that failed to parse at all, and any
// in-band marker could legitimately BE the parsed value.
const PARSE_FAILED = Symbol('json-parse-failed');
/**
* True when a `<filePath>.*.bak` sibling is on disk — the signature of an
* `atomicWrite` backup swap that is mid-flight for THIS file, i.e. the only
* window in which the destination legitimately vanishes.
*
* Deliberately does NOT match `.tmp`: `atomicWrite` writes its temp file on
* EVERY write, including the first-ever create of a file that has no
* destination yet. Treating a `.tmp` sibling as evidence of a swap would turn a
* plain "not written yet" read into a retry that waits for the in-flight write
* and returns its brand-new contents — a different value than the read was
* entitled to, and a behavior change on POSIX-shaped callers. The `.bak` only
* exists between the swap's two renames.
*
* Non-throwing: an unreadable parent directory just means "no evidence of a
* swap". Only consulted on win32, and only after a read already failed with
* ENOENT, so the directory listing never lands on a POSIX read or a successful
* one. A `.bak` orphaned by a crash mid-swap costs the bounded retry budget
* (~50ms) on subsequent ENOENT reads of that path, never an incorrect answer.
*
* Matching is case-INSENSITIVE: NTFS/FAT are case-insensitive, so the reader's
* `filePath` casing need not match the casing the writer used to create the
* file (and therefore the casing `readdir` reports). A case-sensitive compare
* would miss the sibling and let the phantom-empty through.
*
* @param {string} filePath
* @returns {Promise<boolean>}
*/
async function hasSwapSibling(filePath) {
const entries = await readdir(dirname(filePath)).catch(() => null);
if (!entries) return false;
const prefix = `${basename(filePath).toLowerCase()}.`;
return entries.some((entry) => {
const name = entry.toLowerCase();
return name.startsWith(prefix) && name.endsWith('.bak');
});
}
/**
* Error for a missing canonical file that has a legacy `.bak` sibling: the only
* copy of the data may live at the backup path. Deliberately NOT ENOENT, so both
* strict readers report it as unreadable/recovery-required instead of absent.
* Carries no file contents; the guide is docs/TROUBLESHOOTING.md.
*/
function orphanedBackupError(filePath, cause) {
const err = new Error(`${basename(filePath)} is missing but a ${basename(filePath)}.*.bak backup sibling exists — recovery required; stop writers and restore it manually (see docs/TROUBLESHOOTING.md "Recovering a store with an orphaned .bak file")`, { cause });
err.code = 'EBACKUP_ORPHANED';
return err;
}
/**
* `readFile(filePath, encoding)` with the Windows-only retries that keep a read
* racing `atomicWrite` from being mistaken for an empty/absent file (#4095).
*
* On POSIX this is a straight delegate — zero extra syscalls, zero delay.
*
* On win32 two transient failures are retried with a short backoff:
* - EPERM/EACCES/EBUSY — the destination is momentarily locked (AV scan, the
* writer's own open handle).
* - ENOENT, but ONLY when `hasSwapSibling` shows a backup swap is mid-flight.
* A file that was simply never written — or one whose first-ever write is
* still in its temp stage — stays a silent "nothing here yet": one failed
* read, no retry, no sleep.
*
* Rejects with the last error once the attempts are exhausted, so the caller's
* existing errno handling is unchanged.
*
* @param {string} filePath
* @param {string|null} [encoding='utf-8'] - Encoding (null for Buffer)
* @returns {Promise<string|Buffer>}
*/
async function readWithSwapRetry(filePath, encoding = 'utf-8') {
if (!isWindows()) return readFile(filePath, encoding);
for (let attempt = 0; ; attempt += 1) {
const outcome = await readFile(filePath, encoding).then((content) => ({ content }), (err) => ({ err }));
if (!outcome.err) {
if (attempt > 0) console.log(`⚠️ read succeeded after ${attempt} retry(s) — write swap in flight: ${basename(filePath)}`);
return outcome.content;
}
const last = attempt >= WIN_RETRY_ATTEMPTS - 1;
// Retries exhausted on a vanished file that still has a `.bak` sibling: a legacy
// backup swap lost its canonical copy (#9556). Never report this as absent.
if (last && outcome.err.code === 'ENOENT' && await hasSwapSibling(filePath)) throw orphanedBackupError(filePath, outcome.err);
const retriable = WIN_READ_LOCK_CODES.includes(outcome.err.code)
|| (outcome.err.code === 'ENOENT' && !last && await hasSwapSibling(filePath));
if (last || !retriable) throw outcome.err;
await sleep(WIN_RETRY_DELAY_MS);
}
}
/**
* Read a JSON file, reporting whether the read is TRUSTWORTHY rather than
* collapsing every failure into the default (the `readJSONFile` behavior below).
*
* The absent-vs-unreadable distinction (see AGENTS.md's "Sentinel + validate"):
*
* - ENOENT (never written) → `{ ok: true, value: defaultValue }` — a genuine
* empty. A caller counting records may trust this as a real zero.
* - any other read error → `{ ok: false, value: defaultValue }` — EACCES,
* EIO, EISDIR, a transient FS failure. We do NOT know the file is empty.
* - unparseable / truncated → `{ ok: false, value: defaultValue }` — corrupt
* bytes are not an empty collection.
* - parsed → `{ ok: true, value: parsed }`
*
* `value` is always populated so an `ok`-indifferent caller can ignore the flag and
* behave exactly like `readJSONFile` — which is how `readJSONFile` is implemented.
*
* Generalizes the local `{ ok, list }` precedent in
* `services/mediaAssetIndex/db.js#readVideoHistoryStrict`, written because "corrupt
* history" reading as "no videos exist" would have pruned every still-on-disk video
* from the index. Same bug class, shared helper (#2726).
*
* @param {string} filePath - Path to JSON file
* @param {*} defaultValue - Value returned whenever the file yields no parsed value
* @param {Object} options - Options
* @param {boolean} [options.allowArray=true] - Allow array JSON
* @param {boolean} [options.logError=true] - Log read/parse errors
* @returns {Promise<{ ok: boolean, value: * }>}
*
* @example
* const { ok, value } = await readJSONFileStrict('./sessions.json', { sessions: [] });
* if (!ok) throw new Error('sessions unreadable'); // never report a fake 0
*/
export async function readJSONFileStrict(filePath, defaultValue = null, { allowArray = true, logError = true } = {}) {
let content;
try {
content = await readWithSwapRetry(filePath);
} catch (err) {
// ENOENT = file doesn't exist → a trustworthy "nothing here yet", silently.
// On win32 an ENOENT that was really an `atomicWrite` swap window has
// already been retried above, so reaching here means genuinely absent.
if (err.code === 'ENOENT') {
return { ok: true, value: defaultValue };
}
if (logError) {
console.warn(`⚠️ Failed to read file ${filePath}: ${err.message}`);
}
return { ok: false, value: defaultValue };
}
// Mirror safeJSONParse's noisy-output affordance BEFORE delegating: it keys the
// extraction off `Array.isArray(defaultValue)`, and the sentinel we pass as its
// fallback below is not an array — so an array-defaulted caller (e.g. pm2 jlist
// with ANSI codes) would silently lose the extraction if we left it to that call.
//
// Deliberately NOT via `extractJSONArray`: it returns a literal '[]' when the text
// holds no array at all, which would parse cleanly and report `ok: true` — forging
// a trustworthy empty out of unreadable bytes, the exact lie this function exists
// to prevent. Only a real find rewrites `text`; otherwise the parse below fails and
// the read is correctly reported as untrustworthy.
let text = content;
if (allowArray && Array.isArray(defaultValue) && text && !text.trim().startsWith('[')) {
const arrayStart = findJSONArrayStart(text);
if (arrayStart >= 0) text = text.slice(arrayStart);
}
const parsed = safeJSONParse(text, PARSE_FAILED, { allowArray, logError, context: filePath });
if (parsed === PARSE_FAILED) return { ok: false, value: defaultValue };
// An array `defaultValue` is the caller declaring "I expect a list" — every such
// caller in-tree goes straight to `.filter`/`.find`/`.findIndex` on the result. A
// parsed object root therefore isn't a usable read: swallowing callers must still
// get their list back (a hand-edited or legacy-shaped file used to degrade to `[]`
// here, via the manufactured-'[]' path above, and would now TypeError instead), and
// a strict caller must refuse to count a shape it cannot count.
if (allowArray && Array.isArray(defaultValue) && !Array.isArray(parsed)) {
if (logError) {
console.warn(`⚠️ Expected a JSON array in ${filePath}, got ${parsed === null ? 'null' : typeof parsed}`);
}
return { ok: false, value: defaultValue };
}
return { ok: true, value: parsed };
}
/**
* Stable request-facing error for a durable JSON store whose bytes could not
* be trusted. Callers may surface the code without exposing the local path;
* the message keeps the path for server logs and direct service diagnostics.
*/
export function unreadableStoreError(filePath) {
return Object.assign(new Error(`Unreadable JSON file: ${filePath}`), {
status: 500,
code: 'UNREADABLE_STORE',
responseMessage: 'Durable data store is unreadable',
});
}
/**
* Read a JSON file safely with validation and default fallback.
* Combines file reading with safe JSON parsing.
*
* By default this SWALLOWS every failure — a missing file, an unreadable one, and
* corrupt JSON all return `defaultValue`. That is the right shape for config-ish
* reads with a sensible fallback, and is the long-standing behavior of every
* existing caller.
*
* It is the WRONG shape when the value is counted or shown to the user, because a
* fake empty then reads as fact ("0 sessions logged" when the truth is "we could not
* read your sessions"). Those callers pass `{ strict: true }` to convert an
* untrustworthy read into a throw, or use `readJSONFileStrict` for the `{ ok, value }`
* pair directly.
*
* @param {string} filePath - Path to JSON file
* @param {*} defaultValue - Default value if file doesn't exist or is invalid
* @param {Object} options - Options
* @param {boolean} [options.allowArray=true] - Allow array JSON
* @param {boolean} [options.logError=true] - Log errors
* @param {boolean} [options.strict=false] - Throw instead of returning `defaultValue`
* when the file exists but could not be read or parsed. A genuinely absent file
* (ENOENT) still returns `defaultValue` — absent is a trustworthy empty.
* @returns {Promise<*>} Parsed JSON or default value
* @throws {Error} Only when `strict` and the file is present-but-unreadable/corrupt
*
* @example
* const config = await readJSONFile('./config.json', { port: 3000 });
* const items = await readJSONFile('./items.json', []);
* const real = await readJSONFile('./sessions.json', [], { strict: true }); // throws if corrupt
*/
export async function readJSONFile(filePath, defaultValue = null, { allowArray = true, logError = true, strict = false } = {}) {
const { ok, value } = await readJSONFileStrict(filePath, defaultValue, { allowArray, logError });
if (!ok && strict) {
throw unreadableStoreError(filePath);
}
return value;
}
/**
* Parse JSONL (JSON Lines) content safely.
* Handles empty lines, whitespace, and malformed lines gracefully.
*
* @param {string} content - JSONL content (newline-separated JSON objects)
* @param {Object} options - Options
* @param {boolean} [options.logErrors=false] - Log individual line parsing errors
* @param {string} [options.context=''] - Context for error logging
* @returns {Array} Array of parsed objects (invalid lines are skipped)
*
* @example
* const lines = safeJSONLParse('{"a":1}\n{"b":2}\n'); // [{ a: 1 }, { b: 2 }]
* const lines = safeJSONLParse('{"a":1}\ninvalid\n{"b":2}'); // [{ a: 1 }, { b: 2 }]
*/
export function safeJSONLParse(content, { logErrors = false, context = '' } = {}) {
if (!content || !content.trim()) return [];
// Split on CRLF or LF to handle both Windows and Unix line endings
const lines = content
.split(/\r?\n/)
.map(line => line.trim())
.filter(Boolean);
const results = [];
for (const line of lines) {
const parsed = safeJSONParse(line, null, { allowArray: false, logError: logErrors, context });
if (parsed !== null) {
results.push(parsed);
}
}
return results;
}
/**
* Read a JSONL file safely.
*
* @param {string} filePath - Path to JSONL file
* @param {Object} options - Options
* @param {boolean} [options.logErrors=false] - Log individual line parsing errors
* @returns {Promise<Array>} Array of parsed objects
*
* @example
* const entries = await readJSONLFile('./logs.jsonl');
*/
export async function readJSONLFile(filePath, { logErrors = false } = {}) {
let content;
try {
content = await readFile(filePath, 'utf-8');
} catch (err) {
// ENOENT = file doesn't exist, return empty array silently
if (err.code === 'ENOENT') {
return [];
}
// Log other I/O errors if requested
if (logErrors) {
console.warn(`⚠️ Failed to read file ${filePath}: ${err.message}`);
}
return [];
}
return safeJSONLParse(content, { logErrors, context: filePath });
}
/**
* Append one JSON-serializable value to a JSON Lines file.
* Creates the parent directory as needed and writes exactly one trailing
* newline so readers can stream or split the file without special-casing the
* final record.
*
* @param {string} filePath - Path to JSONL file
* @param {*} value - JSON-serializable value to append
* @returns {Promise<void>}
*/
export async function appendJSONLine(filePath, value) {
const serialized = JSON.stringify(value);
if (serialized === undefined) {
throw new TypeError('appendJSONLine value must be JSON-serializable');
}
await ensureDir(dirname(filePath));
await appendFileGuarded(filePath, serialized + '\n');
}
/**
* Read JSON Lines with optional offset/limit slicing.
*
* @param {string} filePath - Path to JSONL file
* @param {Object} options - Options
* @param {number} [options.from=0] - Zero-based record offset
* @param {number} [options.limit] - Maximum number of records to return
* @param {boolean} [options.logErrors=false] - Log malformed JSONL lines
* @returns {Promise<Array>} Parsed records
*/
export async function readJSONLines(filePath, { from = 0, limit, logErrors = false } = {}) {
const entries = await readJSONLFile(filePath, { logErrors });
const start = Number.isFinite(from) && from > 0 ? Math.floor(from) : 0;
if (limit === undefined || limit === null) return entries.slice(start);
const count = Number.isFinite(limit) && limit >= 0 ? Math.floor(limit) : 0;
return entries.slice(start, start + count);
}
/**
* Replace a JSON Lines file with the supplied records.
* Intended for compaction/retention and delete/clear flows; hot append paths
* should use appendJSONLine().
*
* @param {string} filePath - Path to JSONL file
* @param {Array} values - JSON-serializable records
* @returns {Promise<void>}
*/
export async function writeJSONLines(filePath, values) {
if (!Array.isArray(values)) {
throw new TypeError('writeJSONLines values must be an array');
}
const lines = values.map((value) => {
const serialized = JSON.stringify(value);
if (serialized === undefined) {
throw new TypeError('writeJSONLines values must be JSON-serializable');
}
return serialized;
});
await atomicWrite(filePath, lines.length > 0 ? `${lines.join('\n')}\n` : '');
}
/**
* Time constants in milliseconds.
* Single source of truth — import these instead of declaring inline.
*/
/**
* Create a cached JSON file store with TTL-based invalidation.
* Eliminates the repeated cache/load/save/invalidate pattern across services.
*
* @param {string} filePath - Path to the JSON file
* @param {*} defaultValue - Default value when file doesn't exist
* @param {Object} options
* @param {number} [options.ttl=2000] - Cache TTL in milliseconds
* @param {string} [options.context=''] - Context label for error logging
* @returns {{ load, save, mutate, invalidateCache }}
*
* `load()` is STRICT (#4115): a present-but-unreadable or corrupt file rejects
* with `Unreadable JSON file: <path>` instead of reading as `defaultValue`,
* because `mutate` persists whatever `load` returned — a swallowed default
* would be written over the real file on the next mutation. Only a genuinely
* absent file (ENOENT) yields the default. For a flat settings document with
* shipped defaults and a PATCH surface, use `createSettingsStore`
* (`settingsStore.js`) instead.
*
* Writes are serialized through a single-tail `createFileWriteQueue` so two
* concurrent `save()` calls can't interleave their `atomicWrite` + cache
* assignment. For read-modify-write, use `mutate(fn)` — it runs the whole
* `load → fn → persist` cycle under the same tail, so a `load` always sees the
* previous cycle's committed result and one writer can't clobber the other
* (AGENTS.md: "serialize writes server-side… a single tail per shared file").
* `mutate` edits a private clone and publishes it to the cache only after the
* atomic write succeeds. A rejected callback or write leaves committed reads
* intact and cannot leak rejected changes into the next queued mutation.
* A bare `load()` + `save()` pair does NOT get that guarantee; reach for
* `mutate()` whenever the new value depends on the current one.
*/
export function createCachedStore(filePath, defaultValue, { ttl = 2000, context = '' } = {}) {
let cache = null;
let cacheTimestamp = 0;
let writeSeq = 0;
const dir = dirname(filePath);
const queueWrite = createFileWriteQueue();
// Safe clone for plain JSON defaults (structuredClone requires Node 17+)
const cloneDefault = () => JSON.parse(JSON.stringify(defaultValue));
const load = async () => {
const now = Date.now();
if (cache && (now - cacheTimestamp) < ttl) return cache;
const readSeq = writeSeq;
await ensureDir(dir);
// Strict (#4115): `mutate` is load → fn → persist over this value, so a
// present-but-unreadable file must reject here rather than read as the
// default and be overwritten by the very next write. ENOENT is the one
// errno that proves absence and still yields the default.
const { ok, value } = await readJSONFileStrict(filePath, null, { logError: true });
if (!ok) {
throw new Error(`Unreadable JSON file: ${filePath}${context ? ` (${context})` : ''}`);
}
// A serialized write may have completed while this disk read was in
// flight. In that case the bytes we just read can predate the persisted
// state, so keep and return the newer cache instead of replacing it.
if (readSeq !== writeSeq) return cache === null ? load() : cache;
cache = value === null ? cloneDefault() : value;
cacheTimestamp = now;
return cache;
};
// Persist `data` and refresh the cache — the shared write body. Callers reach
// it via the serialized `save`/`mutate`, never directly.
const persist = async (data) => {
await atomicWrite(filePath, data);
writeSeq += 1;
cache = data;
cacheTimestamp = Date.now();
return data;
};
const save = (data) => queueWrite(() => persist(data));
// Serialized read-modify-write: load the freshest state under the tail, apply
// `fn`, then persist. `fn` may mutate the loaded object in place and/or return
// the value to write (returning `undefined` persists the mutated input).
const mutate = (fn) => queueWrite(async () => {
const data = structuredClone(await load());
const result = await fn(data);
return persist(result === undefined ? data : result);
});
const invalidateCache = () => {
cache = null;
cacheTimestamp = 0;
};
return { load, save, mutate, invalidateCache };
}