@crustjs/store 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -110,7 +110,7 @@ type FieldsDef = Record<string, FieldDef>;
 type JsonCompatibleFields<F extends FieldsDef> = { [K in keyof F]: F[K] extends {
   schema: infer S extends StandardSchema;
 } ? Exclude<InferOutput<S>, undefined> extends JsonCompatible<Exclude<InferOutput<S>, undefined>> ? F[K] : F[K] & {
-  readonly FIX_JSON_OUTPUT: "store schema output must be JSON-compatible data (no Date, Map, bigint, or functions)";
+  readonly FIX_JSON_OUTPUT: "store schema output must be JSON data: objects, arrays, strings, finite numbers, booleans, or null (not Date, Map, Set, bigint, functions, or undefined outside optional properties)";
 } : F[K]; };
 /**
  * Infer the resolved type for a single field definition.
@@ -163,7 +163,8 @@ interface StorePermissionBits {
 /**
  * Persistence visibility for store writes.
  *
- * - `"default"` or omitted uses platform defaults.
+ * - `"default"` or omitted uses the platform default for a new file and keeps
+ *   an existing file's mode.
  * - `"private"` keeps the store owner-only on Unix (`0600` file, `0700` directory).
  * - An object lets advanced callers provide explicit Unix permission bits for
  *   group-readable or public non-secret stores without expanding the preset list.
@@ -211,10 +212,14 @@ interface CreateStoreOptions<F extends FieldsDef> {
    */
   fields: F & JsonCompatibleFields<F>;
   /**
-   * When `true` (the default), persisted keys not present in `fields`
-   * are dropped on read. Set to `false` to preserve unknown keys.
+   * What mutations do with persisted keys not present in `fields`.
    *
-   * @default true
+   * `read()` returns only the declared fields either way. When `false` (the
+   * default), `write`, `update`, and `patch` keep unknown keys in the file, so
+   * an older app version or another tool sharing the file never deletes
+   * fields it does not know. Set to `true` to drop them on the next mutation.
+   *
+   * @default false
    */
   pruneUnknown?: boolean;
   /**
@@ -225,6 +230,10 @@ interface CreateStoreOptions<F extends FieldsDef> {
    * creates the parent directory as `0700`; on Windows it is not enforced
    * because Windows uses ACLs instead of Unix permission bits.
    *
+   * With `"default"`, a new file gets the platform default mode (`0666 & ~umask`
+   * on Unix) and a replaced file keeps its current mode, so a user's
+   * `chmod 600` survives writes.
+   *
    * The only built-in presets are `"default"` and `"private"`. Advanced callers
    * can pass explicit bits with `{ file, directory }` for group-readable or public
    * non-secret stores. The file bits are enforced exactly on every write
@@ -258,8 +267,9 @@ type StoreUpdater<TConfig> = (current: TConfig) => NoInfer<TConfig>;
  *
  * Provides `read`, `write`, `update`, `patch`, and `reset` operations for a
  * single typed config object persisted as JSON on the local filesystem.
- * Mutations are not serialized, including overlapping calls in one process.
- * Await mutations sequentially for each file; coordinate multiple processes externally.
+ * `write`, `update`, `patch`, and `reset` on the same file run one at a time in
+ * call order, across store instances in one process, and hold an advisory lock
+ * file (`<name>.json.lock`) across processes.
  *
  * @typeParam TConfig - The inferred config shape from field definitions.
  *
@@ -315,9 +325,9 @@ interface Store<TConfig> {
    * the updater, validates the result, and persists. Invalid current state
    * rejects before the callback runs; use `write` or `patch` to initialize or repair.
    *
-   * The final file replacement is atomic, but the read-modify-write sequence
-   * is not serialized, even within one process. Await mutations sequentially
-   * to avoid lost updates; coordinate multiple processes externally.
+   * The read-modify-write runs after earlier mutations of the same file settle
+   * and under its cross-process lock, so concurrent updates keep each other's changes.
+   * The final file replacement is atomic.
    *
    * @param updater - Function receiving current config and returning updated config.
    * @returns The persisted config, including schema transformations.
@@ -334,7 +344,8 @@ interface Store<TConfig> {
    * applied but has not undergone full field validation, allowing repairs. The
    * merged result is validated before persistence. Explicit `undefined` is rejected
    * for defaulted core fields; optional core fields and schema-owned optionality
-   * remain supported. Await mutations sequentially to avoid lost updates.
+   * remain supported. Like {@link Store.update}, the read-modify-write is
+   * serialized and locked.
    *
    * @param partial - A partial subset of the config to merge in.
    * @returns The persisted config, including schema transformations.
@@ -490,7 +501,8 @@ interface PlatformEnv {
  *   string without path separators.
  * @param env - Optional platform environment override for testing.
  * @returns Absolute path to the app's config directory.
- * @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+ * @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+ *   or the default location needs a home directory that is not an absolute path.
  *
  * @example
  * ```ts
@@ -516,7 +528,8 @@ export declare function configDir(appName: string, env?: PlatformEnv): string;
  *   string without path separators.
  * @param env - Optional platform environment override for testing.
  * @returns Absolute path to the app's data directory.
- * @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+ * @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+ *   or the default location needs a home directory that is not an absolute path.
  *
  * @example
  * ```ts
@@ -542,7 +555,8 @@ export declare function dataDir(appName: string, env?: PlatformEnv): string;
  *   string without path separators.
  * @param env - Optional platform environment override for testing.
  * @returns Absolute path to the app's state directory.
- * @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+ * @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+ *   or the default location needs a home directory that is not an absolute path.
  *
  * @example
  * ```ts
@@ -568,7 +582,8 @@ export declare function stateDir(appName: string, env?: PlatformEnv): string;
  *   string without path separators.
  * @param env - Optional platform environment override for testing.
  * @returns Absolute path to the app's cache directory.
- * @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+ * @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+ *   or the default location needs a home directory that is not an absolute path.
  *
  * @example
  * ```ts

package/dist/index.js

@@ -1,10 +1,11 @@
-import { homedir } from "node:os";
-import { dirname, join, posix, win32 } from "node:path";
+import { homedir, hostname } from "node:os";
+import { basename, dirname, join, posix, win32 } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { isJsonObject } from "@crustjs/utils/json";
 import { coerceBooleanString, tryCoerceNumber } from "@crustjs/utils/primitive";
 import { normalizeStandardIssues } from "@crustjs/utils/schema";
-import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, chown, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { setTimeout } from "node:timers/promises";
 import { isErrnoException } from "@crustjs/utils/error";
 // src/errors.ts
 /**
@@ -116,17 +117,16 @@ const DIRECTORY_CONFIG = {
 function resolvePlatformDir(kind, appName, env = getRuntimeEnv()) {
 	validateSegment(appName, "appName");
 	const config = DIRECTORY_CONFIG[kind];
-	if (env.platform === "linux" || env.platform === "darwin") {
-		const configured = env.env[config.xdg];
-		const base = configured && posix.isAbsolute(configured) ? configured : join(env.homedir, ...config.unixFallback);
-		return join(base, appName);
-	}
-	if (env.platform === "win32") {
-		const configured = env.env[config.windowsEnv];
-		const base = configured?.trim() ? configured : join(env.homedir, ...config.windowsFallback);
-		return join(base, appName, ...config.windowsSuffix);
-	}
-	throw new CrustStoreError("PATH", `Unsupported platform: ${env.platform}`, { path: env.platform });
+	const windows = env.platform === "win32";
+	if (!windows && env.platform !== "linux" && env.platform !== "darwin") throw new CrustStoreError("PATH", `Unsupported platform: ${env.platform}`, { path: env.platform });
+	const { isAbsolute } = windows ? win32 : posix;
+	const variable = windows ? config.windowsEnv : config.xdg;
+	const suffix = windows ? config.windowsSuffix : [];
+	const configured = env.env[variable];
+	if (configured && isAbsolute(configured)) return join(configured, appName, ...suffix);
+	if (!isAbsolute(env.homedir)) throw new CrustStoreError("PATH", `Cannot resolve the ${kind} directory: home directory "${env.homedir}" is not absolute; set ${windows ? "USERPROFILE" : "HOME"} or ${variable} to an absolute path`, { path: env.homedir });
+	const fallback = windows ? config.windowsFallback : config.unixFallback;
+	return join(env.homedir, ...fallback, appName, ...suffix);
 }
 /**
 * Resolves the platform-standard config directory for the given app.
@@ -141,7 +141,8 @@ function resolvePlatformDir(kind, appName, env = getRuntimeEnv()) {
 *   string without path separators.
 * @param env - Optional platform environment override for testing.
 * @returns Absolute path to the app's config directory.
-* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+*   or the default location needs a home directory that is not an absolute path.
 *
 * @example
 * ```ts
@@ -169,7 +170,8 @@ function configDir(appName, env) {
 *   string without path separators.
 * @param env - Optional platform environment override for testing.
 * @returns Absolute path to the app's data directory.
-* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+*   or the default location needs a home directory that is not an absolute path.
 *
 * @example
 * ```ts
@@ -197,7 +199,8 @@ function dataDir(appName, env) {
 *   string without path separators.
 * @param env - Optional platform environment override for testing.
 * @returns Absolute path to the app's state directory.
-* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+*   or the default location needs a home directory that is not an absolute path.
 *
 * @example
 * ```ts
@@ -225,7 +228,8 @@ function stateDir(appName, env) {
 *   string without path separators.
 * @param env - Optional platform environment override for testing.
 * @returns Absolute path to the app's cache directory.
-* @throws {CrustStoreError} `PATH` if `appName` is invalid or platform is unsupported.
+* @throws {CrustStoreError} `PATH` if `appName` is invalid, the platform is unsupported,
+*   or the default location needs a home directory that is not an absolute path.
 *
 * @example
 * ```ts
@@ -271,7 +275,7 @@ function setDocumentValue(document, key, value) {
 	});
 }
 /**
-* Applies field defaults to a persisted config object.
+* Applies field defaults to a persisted store object.
 *
 * For each field defined in `fields`:
 * - If `persisted` has the key as an own property, the persisted value is used.
@@ -280,32 +284,39 @@ function setDocumentValue(document, key, value) {
 * - If the key is missing and no default exists, the field is omitted
 *   (typed as `T | undefined` in the output).
 *
-* When `pruneUnknown` is `true` (the default), keys in `persisted` that are
-* not defined in `fields` are dropped. Set to `false` to preserve them.
+* Keys in `persisted` that are not defined in `fields` are left out; mutations
+* carry them over with {@link withUnknownKeys}.
 *
-* @param persisted    - Parsed JSON from disk, or `undefined` if no file exists.
-* @param fields       - Store field definitions.
-* @param pruneUnknown - Whether to drop persisted keys not in `fields`. Defaults to `true`.
+* @param persisted - Parsed JSON from disk, or `undefined` if no file exists.
+* @param fields    - Store field definitions.
 * @returns A new object with field defaults applied.
 */
-function applyFieldDefaults(persisted, fields, pruneUnknown = true) {
+function applyFieldDefaults(persisted, fields) {
 	const result = {};
 	for (const [key, def] of Object.entries(fields)) if (persisted && Object.hasOwn(persisted, key)) setDocumentValue(result, key, persisted[key]);
 	else if (def.default !== void 0) setDocumentValue(result, key, structuredClone(def.default));
-	if (!pruneUnknown && persisted !== void 0) {
-		for (const [key, value] of Object.entries(persisted)) if (!Object.hasOwn(fields, key)) setDocumentValue(result, key, value);
-	}
+	return result;
+}
+/**
+* Returns `document` plus the keys of `persisted` that `fields` does not define,
+* so a store definition that lacks a field (an older app version, another tool)
+* never deletes it. Keys already in `document` win.
+*/
+function withUnknownKeys(document, persisted, fields) {
+	const result = { ...document };
+	if (persisted === void 0) return result;
+	for (const [key, value] of Object.entries(persisted)) if (!Object.hasOwn(fields, key) && !Object.hasOwn(result, key)) setDocumentValue(result, key, value);
 	return result;
 }
 // src/persistence.ts
 /**
-* Reads and parses a JSON config file from disk.
+* Reads and parses a JSON store file from disk.
 *
 * Returns `undefined` when the file does not exist (ENOENT), allowing callers
 * to fall back to defaults. Malformed JSON throws a `CrustStoreError` with `PARSE`
 * code — the store never silently recovers corrupt data.
 *
-* @param filePath - Absolute path to the JSON config file.
+* @param filePath - Absolute path to the JSON store file.
 * @returns Parsed JSON value, or `undefined` if the file does not exist.
 * @throws {CrustStoreError} `PARSE` if the file contains malformed JSON.
 * @throws {CrustStoreError} `IO` on filesystem read failures other than ENOENT.
@@ -316,7 +327,7 @@ async function readJson(filePath) {
 		raw = await readFile(filePath, "utf-8");
 	} catch (err) {
 		if (isErrnoException(err) && err.code === "ENOENT") return;
-		throw new CrustStoreError("IO", `Failed to read config file: ${filePath}`, {
+		throw new CrustStoreError("IO", `Failed to read store file: ${filePath}`, {
 			path: filePath,
 			operation: "read"
 		}, err);
@@ -324,31 +335,23 @@ async function readJson(filePath) {
 	try {
 		return JSON.parse(raw);
 	} catch (err) {
-		throw new CrustStoreError("PARSE", `Malformed JSON in config file: ${filePath}`, { path: filePath }, err);
+		throw new CrustStoreError("PARSE", `Malformed JSON in store file: ${filePath}`, { path: filePath }, err);
 	}
 }
+const isWindows = () => process.platform === "win32";
+/** Whether a failed `chown` only means an unprivileged process cannot give a file away. */
+function isChownErrorOk(err) {
+	if (!isErrnoException(err)) return false;
+	if (err.code === "ENOSYS") return true;
+	return process.getuid?.() !== 0 && (err.code === "EPERM" || err.code === "EINVAL");
+}
 /**
-* Atomically writes a JSON value to disk using a temp-file-and-rename strategy.
-*
-* Steps:
-* 1. Creates the parent directory if it does not exist.
-* 2. Writes serialized JSON to a temporary file in the same directory.
-* 3. Renames the temp file to the target path (atomic on most filesystems).
-*
-* If any step fails, the function cleans up the temp file (best-effort) and
-* throws a `CrustStoreError` with `IO` code.
-*
-* @param filePath - Absolute path to the target JSON config file.
-* @param data - The value to serialize and persist.
-* @param options - Optional file/directory permission bits ({@link WriteJsonOptions}).
-* @throws {CrustStoreError} `IO` on filesystem write failures.
+* Creates the store file's parent directory if missing, enforcing `directoryMode`
+* exactly when this call created it.
 */
-async function writeJson(filePath, data, options = {}) {
-	const isWindows = process.platform === "win32";
-	const fileMode = isWindows ? void 0 : options.fileMode;
-	const directoryMode = isWindows ? void 0 : options.directoryMode;
+async function ensureDirectory(filePath, mode) {
+	const directoryMode = isWindows() ? void 0 : mode;
 	const dir = dirname(filePath);
-	const tempPath = join(dir, `.config-${crypto.randomUUID()}.tmp`);
 	let createdDir;
 	try {
 		createdDir = await mkdir(dir, {
@@ -356,7 +359,7 @@ async function writeJson(filePath, data, options = {}) {
 			mode: directoryMode
 		});
 	} catch (err) {
-		throw new CrustStoreError("IO", `Failed to create config directory: ${dir}`, {
+		throw new CrustStoreError("IO", `Failed to create store directory: ${dir}`, {
 			path: filePath,
 			operation: "write"
 		}, err);
@@ -364,54 +367,202 @@ async function writeJson(filePath, data, options = {}) {
 	if (directoryMode !== void 0 && createdDir !== void 0) try {
 		await chmod(dir, directoryMode);
 	} catch (err) {
-		throw new CrustStoreError("IO", `Failed to set permissions on config directory: ${dir}`, {
+		throw new CrustStoreError("IO", `Failed to set permissions on store directory: ${dir}`, {
 			path: filePath,
 			operation: "write"
 		}, err);
 	}
+}
+/**
+* Atomically writes a JSON value to disk using a temp-file-and-rename strategy.
+*
+* Steps:
+* 1. Creates the parent directory if it does not exist.
+* 2. Writes serialized JSON to a temporary file in the same directory and
+*    flushes it to disk (`fsync`), so a crash after the rename cannot leave an
+*    empty or partial file in place. On POSIX the temp file gets the replaced
+*    file's owner and, unless `fileMode` is set, its mode.
+* 3. Renames the temp file to the target path (atomic on local filesystems).
+*    On Windows, a rename blocked by another program's open handle (`EPERM`,
+*    `EACCES`, `EBUSY`) is retried for up to 2 seconds.
+*
+* If any step fails, the function cleans up the temp file (best-effort) and
+* throws a `CrustStoreError` with `IO` code.
+*
+* @param filePath - Absolute path to the target JSON store file.
+* @param data - The value to serialize and persist.
+* @param options - Optional file/directory permission bits ({@link WriteJsonOptions}).
+* @throws {CrustStoreError} `IO` on filesystem write failures.
+*/
+async function writeJson(filePath, data, options = {}) {
+	const tempPath = join(dirname(filePath), `.${basename(filePath, ".json")}-${crypto.randomUUID()}.tmp`);
+	await ensureDirectory(filePath, options.directoryMode);
+	const existing = isWindows() ? void 0 : await stat(filePath).catch(() => void 0);
+	const fileMode = isWindows() ? void 0 : options.fileMode ?? (existing === void 0 ? void 0 : existing.mode & 4095);
 	try {
 		const json = JSON.stringify(data, null, "	");
-		await writeFile(tempPath, json, {
-			encoding: "utf-8",
-			mode: fileMode
+		const handle = await open(tempPath, "w", fileMode);
+		try {
+			await handle.writeFile(json, "utf-8");
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		if (existing !== void 0) await chown(tempPath, existing.uid, existing.gid).catch((err) => {
+			if (!isChownErrorOk(err)) throw err;
 		});
 		if (fileMode !== void 0) await chmod(tempPath, fileMode);
 	} catch (err) {
 		await rm(tempPath, { force: true }).catch(() => {});
-		throw new CrustStoreError("IO", `Failed to write config file: ${filePath}`, {
+		throw new CrustStoreError("IO", `Failed to write store file: ${filePath}`, {
 			path: filePath,
 			operation: "write"
 		}, err);
 	}
 	try {
-		await rename(tempPath, filePath);
+		await commit(tempPath, filePath);
 	} catch (err) {
 		await rm(tempPath, { force: true }).catch(() => {});
-		throw new CrustStoreError("IO", `Failed to finalize config file: ${filePath}`, {
+		throw new CrustStoreError("IO", `Failed to finalize store file: ${filePath}`, {
 			path: filePath,
 			operation: "write"
 		}, err);
 	}
 }
+/** How long a rename blocked by another program's open handle is retried on Windows. */
+const RENAME_RETRY_MS = 2e3;
+const MAX_RETRY_DELAY_MS = 100;
+const BUSY_CODES = /* @__PURE__ */ new Set([
+	"EPERM",
+	"EACCES",
+	"EBUSY"
+]);
 /**
-* Deletes a persisted config file from disk.
+* Renames `tempPath` over `filePath`.
+*
+* Windows refuses to replace a file that any process holds open, including another
+* process reading this store, an antivirus scanner, or an indexer; such handles are
+* usually brief.
+*/
+async function commit(tempPath, filePath) {
+	const start = Date.now();
+	for (let delay = 1;; delay = Math.min(delay * 2, MAX_RETRY_DELAY_MS)) {
+		try {
+			return await rename(tempPath, filePath);
+		} catch (err) {
+			if (!(isWindows() && isErrnoException(err) && BUSY_CODES.has(err.code ?? "")) || Date.now() - start >= RENAME_RETRY_MS) throw err;
+		}
+		await setTimeout(delay);
+	}
+}
+/**
+* Deletes a persisted store file from disk.
 *
 * Silently succeeds when the file does not exist (ENOENT) — deleting an
-* already-absent config is not an error.
+* already-absent file is not an error.
 *
-* @param filePath - Absolute path to the JSON config file to delete.
+* @param filePath - Absolute path to the JSON store file to delete.
 * @throws {CrustStoreError} `IO` on filesystem deletion failures other than ENOENT.
 */
 async function deleteJson(filePath) {
 	try {
 		await rm(filePath, { force: true });
 	} catch (err) {
-		throw new CrustStoreError("IO", `Failed to delete config file: ${filePath}`, {
+		throw new CrustStoreError("IO", `Failed to delete store file: ${filePath}`, {
 			path: filePath,
 			operation: "delete"
 		}, err);
 	}
 }
+/** A lock older than this was left behind: a mutation takes milliseconds. */
+const STALE_LOCK_MS = 1e4;
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return isErrnoException(err) && err.code === "EPERM";
+	}
+}
+/** The pid a lock file names, or `undefined` when it has none: missing, not yet written, or another host's. */
+async function readLockPid(lockPath) {
+	try {
+		const owner = JSON.parse(await readFile(lockPath, "utf-8"));
+		return owner?.host === hostname() && typeof owner.pid === "number" ? owner.pid : void 0;
+	} catch {
+		return;
+	}
+}
+/** Whether the lock was left behind: its process is gone, or it is older than {@link STALE_LOCK_MS}. */
+async function isStaleLock(lockPath) {
+	const pid = await readLockPid(lockPath);
+	if (pid !== void 0 && !isProcessAlive(pid) && await readLockPid(lockPath) === pid) return true;
+	return stat(lockPath).then((lock) => Date.now() - lock.mtimeMs > STALE_LOCK_MS, () => false);
+}
+/**
+* Runs `fn` while holding `<filePath>.lock`, an advisory lock shared by every
+* process that uses this function on the same file.
+*
+* The lock file is created exclusively (`wx`) and holds the owner's pid and host.
+* Waiters retry with a growing, jittered delay and remove a lock whose process
+* is gone or that is older than 10 seconds. After `fn` settles the lock is removed,
+* unless a takeover has put another process's lock at the path.
+*
+* shortcut: checking a lock and removing it are two steps, so two waiters that find the
+* same abandoned lock at the same instant can both take it, and a mutation running past
+* 10 seconds loses its lock; either costs lost updates, never a corrupt file. Use an
+* OS file lock or a heartbeat if stores ever need exclusion to survive a crashed writer.
+*
+* @throws {CrustStoreError} `IO` when the lock file cannot be created or an abandoned one removed.
+*/
+async function withFileLock(filePath, fn, options) {
+	const lockPath = `${filePath}.lock`;
+	const lockError = (err) => new CrustStoreError("IO", `Failed to lock store file: ${filePath}`, {
+		path: filePath,
+		operation: options.operation
+	}, err);
+	let refusedSince;
+	const isContention = (err) => {
+		const code = isWindows() && isErrnoException(err) ? err.code ?? "" : "";
+		if (code !== "EFAULT" && !BUSY_CODES.has(code)) return false;
+		refusedSince ??= Date.now();
+		return Date.now() - refusedSince < STALE_LOCK_MS;
+	};
+	let named = true;
+	for (let delay = 1;; delay = Math.min(delay * 2, MAX_RETRY_DELAY_MS)) {
+		try {
+			const handle = await open(lockPath, "wx");
+			await handle.writeFile(JSON.stringify({
+				pid: process.pid,
+				host: hostname()
+			})).catch(() => {
+				named = false;
+			});
+			await handle.close();
+			break;
+		} catch (err) {
+			if (isErrnoException(err) && err.code === "ENOENT") {
+				if (options.operation === "delete") return await fn();
+				await ensureDirectory(filePath, options.directoryMode);
+				continue;
+			}
+			if (!(isErrnoException(err) && err.code === "EEXIST") && !isContention(err)) throw lockError(err);
+		}
+		if (!(await isStaleLock(lockPath) && await rm(lockPath, { force: true }).then(() => true, (err) => {
+			if (!isContention(err)) throw lockError(err);
+			return false;
+		}))) await setTimeout(delay * (1 + Math.random()));
+	}
+	try {
+		return await fn();
+	} finally {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			if (named && await readLockPid(lockPath) !== process.pid) break;
+			if (await rm(lockPath, { force: true }).then(() => true, () => !named)) break;
+			await setTimeout(10);
+		}
+	}
+}
 // src/store.ts
 function makeSchemaValidator(schema) {
 	return async (value) => {
@@ -476,6 +627,18 @@ function jsonInstabilityIssues(document) {
 	}
 	return issues;
 }
+/** Tail of each store file's mutation queue, shared by every store instance in the process. */
+const mutationQueues = /* @__PURE__ */ new Map();
+/** Runs `task` after every mutation already queued for `filePath` settles, in call order. */
+function enqueue(filePath, task) {
+	const run = (mutationQueues.get(filePath) ?? Promise.resolve()).then(task);
+	const tail = run.catch(() => {});
+	mutationQueues.set(filePath, tail);
+	tail.then(() => {
+		if (mutationQueues.get(filePath) === tail) mutationQueues.delete(filePath);
+	});
+	return run;
+}
 /**
 * Creates a typed async config store backed by a local JSON file.
 *
@@ -609,37 +772,62 @@ function createStore(options) {
 			issues
 		});
 	}
-	async function readRaw() {
+	async function readPersisted() {
 		const persisted = await readJson(filePath);
-		const persistedObject = persisted !== void 0 && isJsonObject(persisted) ? persisted : void 0;
-		if (persisted !== void 0 && persistedObject === void 0) throw new CrustStoreError("PARSE", `Expected a JSON object in config file: ${filePath}`, { path: filePath });
-		return normalizeStateTypes(applyFieldDefaults(persistedObject, fields, pruneUnknown));
+		if (persisted === void 0 || isJsonObject(persisted)) return persisted;
+		throw new CrustStoreError("PARSE", `Expected a JSON object in store file: ${filePath}`, { path: filePath });
+	}
+	/** The declared fields of a persisted object, with defaults and core coercion applied. */
+	function toDocument(persisted) {
+		return normalizeStateTypes(applyFieldDefaults(persisted, fields));
+	}
+	/** Serialized within the process, then locked across processes. */
+	function mutate(operation, task) {
+		return enqueue(filePath, () => withFileLock(filePath, task, {
+			operation,
+			directoryMode: writeOptions.directoryMode
+		}));
 	}
 	async function read() {
-		const document = await readRaw();
+		const document = toDocument(await readPersisted());
 		await runFieldValidators(document, "read");
 		return document;
 	}
-	async function persist(document, operation) {
+	async function persist(document, operation, persisted) {
 		const normalized = normalizeStateTypes(document);
 		await runFieldValidators(normalized, operation);
-		await writeJson(filePath, normalized, writeOptions);
+		const output = pruneUnknown === true ? normalized : withUnknownKeys(normalized, persisted, fields);
+		await writeJson(filePath, output, writeOptions);
 		return normalized;
 	}
-	async function write(config) {
-		return persist({ ...config }, "write");
+	function write(config) {
+		return mutate("write", async () => {
+			const persisted = pruneUnknown === true ? void 0 : await readPersisted().catch((err) => {
+				if (err instanceof CrustStoreError && err.is("PARSE")) return void 0;
+				throw err;
+			});
+			return persist({ ...config }, "write", persisted);
+		});
 	}
-	async function update(updater) {
-		return persist({ ...updater(await read()) }, "update");
+	function update(updater) {
+		return mutate("write", async () => {
+			const persisted = await readPersisted();
+			const current = toDocument(persisted);
+			await runFieldValidators(current, "read");
+			return persist({ ...updater(current) }, "update", persisted);
+		});
 	}
-	async function patch(partial) {
-		return persist({
-			...await readRaw(),
-			...partial
-		}, "patch");
+	function patch(partial) {
+		return mutate("write", async () => {
+			const persisted = await readPersisted();
+			return persist({
+				...toDocument(persisted),
+				...partial
+			}, "patch", persisted);
+		});
 	}
-	async function reset() {
-		await deleteJson(filePath);
+	function reset() {
+		return mutate("delete", () => deleteJson(filePath));
 	}
 	return {
 		read,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crustjs/store",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Typed JSON persistence for CLI config, data, state, and cache files",
   "type": "module",
   "sideEffects": false,
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crustjs/utils": "^0.3.0"
+    "@crustjs/utils": "^0.3.1"
   },
   "devDependencies": {
     "@crustjs/config": "0.0.0",
@@ -48,7 +48,7 @@
     "vite-plus": "1.4.0"
   },
   "peerDependencies": {
-    "typescript": "^7.0.0"
+    "typescript": ">=5.9.0"
   },
   "peerDependenciesMeta": {
     "typescript": {