@crustjs/store 0.2.0 → 0.3.1

package/dist/index.js

@@ -1,4 +1,727 @@
-// @bun
-class X extends Error{code;details;cause;constructor(q,H,G){super(H);this.name="CrustStoreError",this.code=q,this.details=G}is(q){return this.code===q}withCause(q){return this.cause=q,this}}import{isStandardSchema as d,normalizeStandardIssues as o}from"@crustjs/utils/schema";function l(q){return async(H)=>{let G=await q["~standard"].validate(H);if(G.issues){let Q=o(G.issues).map((Y)=>Y.path?`${Y.path}: ${Y.message}`:Y.message);throw Error(Q.join("; "))}return{value:G.value}}}function i(q,H){if(!d(q))throw new X("DEFINITION",`field(): argument must be a Standard Schema v1 object (got ${typeof q})`,{});let K={validate:l(q),validateMissing:!0};if(H?.type!==void 0)K.type=H.type;if(H?.array===!0)K.array=!0;if(H?.description!==void 0)K.description=H.description;if(H&&"default"in H)K.default=H.default;return K}import{homedir as s}from"os";import{join as J}from"path";var t="config";function b(){return{platform:process.platform,env:process.env,homedir:s()}}function j(q){if(!q||q.trim().length===0)throw new X("PATH","appName must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new X("PATH","appName must not contain path separators",{path:q})}function r(q){if(!q||q.trim().length===0)throw new X("PATH","name must be a non-empty string",{path:q??""});if(q.includes("/")||q.includes("\\"))throw new X("PATH","name must not contain path separators",{path:q});if(q.endsWith(".json"))throw new X("PATH","name must not include the .json extension",{path:q})}function a(q){if(!q||q.trim().length===0)throw new X("PATH","dirPath must be a non-empty string",{path:q??""});if(!(q.startsWith("/")||/^[A-Za-z]:[/\\]/.test(q)))throw new X("PATH","dirPath must be an absolute path",{path:q});if(q.endsWith(".json"))throw new X("PATH","dirPath must be a directory path, not a file path (should not end with .json)",{path:q})}function C(q,H,G,K){let Q=q.env[H],Y=Q&&Q.trim().length>0?Q:J(q.homedir,...G);return J(Y,K)}function D(q){throw new X("PATH",`Unsupported platform: ${q}`,{path:q})}function e(q,H){j(q);let G=H??b();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_CONFIG_HOME",[".config"],q);case"win32":{let K=G.env.APPDATA,Q=K&&K.trim().length>0?K:J(G.homedir,"AppData","Roaming");return J(Q,q)}default:D(G.platform)}}function qq(q,H){j(q);let G=H??b();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_DATA_HOME",[".local","share"],q);case"win32":{let K=G.env.LOCALAPPDATA,Q=K&&K.trim().length>0?K:J(G.homedir,"AppData","Local");return J(Q,q,"Data")}default:D(G.platform)}}function Gq(q,H){j(q);let G=H??b();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_STATE_HOME",[".local","state"],q);case"win32":{let K=G.env.LOCALAPPDATA,Q=K&&K.trim().length>0?K:J(G.homedir,"AppData","Local");return J(Q,q,"State")}default:D(G.platform)}}function Hq(q,H){j(q);let G=H??b();switch(G.platform){case"linux":case"darwin":return C(G,"XDG_CACHE_HOME",[".cache"],q);case"win32":{let K=G.env.LOCALAPPDATA,Q=K&&K.trim().length>0?K:J(G.homedir,"AppData","Local");return J(Q,q,"Cache")}default:D(G.platform)}}function S(q,H){a(q);let G=H??t;if(H!==void 0)r(H);return J(q,`${G}.json`)}import{coerceBooleanString as Iq,tryCoerceNumber as Wq}from"@crustjs/utils";function y(q,H,G=!0){let K={};for(let[Q,Y]of Object.entries(H))if(q&&Q in q){let Z=q[Q];K[Q]=Array.isArray(Z)?[...Z]:Z}else if("default"in Y&&Y.default!==void 0)K[Q]=Array.isArray(Y.default)?[...Y.default]:Y.default;if(!G&&q!==void 0){for(let[Q,Y]of Object.entries(q))if(!(Q in H))K[Q]=Array.isArray(Y)?[...Y]:Y}return K}import{randomUUID as Kq}from"crypto";import{chmod as g,mkdir as Qq,readFile as Xq,rename as Yq,rm as $q,unlink as Lq,writeFile as Bq}from"fs/promises";import{dirname as Zq,join as _q}from"path";async function E(q){let H;try{H=await Xq(q,"utf-8")}catch(G){if(v(G))return;throw new X("IO",`Failed to read config file: ${q}`,{path:q,operation:"read"}).withCause(G)}try{return JSON.parse(H)}catch(G){throw new X("PARSE",`Malformed JSON in config file: ${q}`,{path:q}).withCause(G)}}async function z(q,H,G={}){let K=process.platform==="win32",Q=K?void 0:G.fileMode,Y=K?void 0:G.directoryMode,Z=Zq(q),T=_q(Z,`.config-${Kq()}.tmp`),V;try{V=await Qq(Z,{recursive:!0,mode:Y})}catch(I){throw new X("IO",`Failed to create config directory: ${Z}`,{path:q,operation:"write"}).withCause(I)}if(Y!==void 0&&V!==void 0)try{await g(Z,Y)}catch(I){throw new X("IO",`Failed to set permissions on config directory: ${Z}`,{path:q,operation:"write"}).withCause(I)}try{let I=JSON.stringify(H,null,"\t");if(await Bq(T,I,{encoding:"utf-8",mode:Q}),Q!==void 0)await g(T,Q)}catch(I){throw await N(T),new X("IO",`Failed to write config file: ${q}`,{path:q,operation:"write"}).withCause(I)}try{await Yq(T,q)}catch(I){throw await N(T),new X("IO",`Failed to finalize config file: ${q}`,{path:q,operation:"write"}).withCause(I)}}async function P(q){try{await Lq(q)}catch(H){if(v(H))return;throw new X("IO",`Failed to delete config file: ${q}`,{path:q,operation:"delete"}).withCause(H)}}function v(q){return q!==null&&typeof q==="object"&&"code"in q&&q.code==="ENOENT"}async function N(q){try{await $q(q,{force:!0})}catch{}}function f(q){return typeof q==="object"&&q!==null&&"value"in q&&!("ok"in q)}function Jq(q){if(q==="private")return{fileMode:384,directoryMode:448};if(q===void 0||q==="default")return{};return{fileMode:q.file,directoryMode:q.directory}}function Oq(q){let{dirPath:H,name:G,fields:K,pruneUnknown:Q,access:Y}=q,Z=S(H,G),T=Q??!0,V=Jq(Y);function I($,L){if(L===void 0)return $;if(L==="number"&&typeof $==="string")return Wq($)??$;if(L==="boolean"&&typeof $==="string")return Iq($);return $}function R($){let B={...$};for(let[_,W]of Object.entries(K)){if(!(_ in B))continue;let O=B[_];if(W.array===!0&&Array.isArray(O)){B[_]=O.map((M)=>I(M,W.type));continue}B[_]=I(O,W.type)}return B}async function U($,L){let B=[],_=$;for(let[W,O]of Object.entries(K)){if(!O.validate)continue;let M=_[W];if(M===void 0&&O.validateMissing!==!0)continue;let A;try{A=await O.validate(M)}catch(x){let F=x instanceof Error?x.message:"Validation failed";B.push({message:F,path:W});continue}if(A===void 0)continue;if(f(A)){let x=A.value;if(L==="read"){if(M===void 0)_[W]=x;continue}if(!Bun.deepEquals(x,M)){let F;try{F=await O.validate(x)}catch(w){let n=w instanceof Error?w.message:"re-validation failed";B.push({message:`read-unstable transform: ${n}`,path:W});continue}if(F!==void 0&&(!f(F)||!Bun.deepEquals(F.value,x))){B.push({message:"read-unstable transform: output would be transformed again on re-read",path:W});continue}_[W]=x}continue}throw TypeError("FieldDef.validate must return void or { value } (see @crustjs/store validation docs).")}if(B.length>0){let W=B.map((M)=>`  - ${M.path}: ${M.message}`),O=`Store validation failed (${L})
-${W.join(`
-`)}`;throw new X("VALIDATION",O,{operation:L,issues:B})}}async function k(){let $=await E(Z),L=y($,K,T);return R(L)}async function c(){let $=await k();return await U($,"read"),$}async function h($){let L=R($);await U(L,"write"),await z(Z,L,V)}async function u($){let L=await k(),B=$(L),_=R(B);await U(_,"update"),await z(Z,_,V)}async function m($){let B={...await k(),...$},_=R(B);await U(_,"patch"),await z(Z,_,V)}async function p(){await P(Z)}return{read:c,write:h,update:u,patch:m,reset:p}}export{Gq as stateDir,i as field,qq as dataDir,Oq as createStore,e as configDir,Hq as cacheDir,X as CrustStoreError};
+import { homedir } from "node:os";
+import { dirname, join, win32 } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+//#region src/errors.ts
+/**
+* A typed error thrown by `@crustjs/store` for path, parse, IO, and validation failures.
+*
+* Every `CrustStoreError` carries a {@link StoreErrorCode} that identifies the failure
+* category. Codes other than `DEFINITION` include structured {@link StoreErrorDetails}
+* for programmatic handling without fragile message parsing.
+*
+* @example
+* ```ts
+* import { CrustStoreError } from "@crustjs/store";
+*
+* try {
+*   const config = await store.read();
+* } catch (err) {
+*   if (err instanceof CrustStoreError && err.is("PARSE")) {
+*     console.error(`Corrupt config at ${err.details.path}`);
+*   }
+* }
+* ```
+*/
+var CrustStoreError = class extends Error {
+	/** Machine-readable error code for programmatic handling. */
+	code;
+	/** Structured payload with context about the failure. */
+	details;
+	constructor(code, message, ...[details, cause]) {
+		super(message, { cause });
+		this.name = "CrustStoreError";
+		this.code = code;
+		this.details = details;
+	}
+	/**
+	* Type-guard that narrows this error to a specific {@link StoreErrorCode}.
+	*
+	* When the guard returns `true`, TypeScript narrows the `details` property
+	* to the corresponding details type.
+	*
+	* @example
+	* ```ts
+	* if (err.is("IO")) {
+	*   // err.details is IOErrorDetails
+	*   console.error(err.details.operation, err.details.path);
+	* }
+	* ```
+	*/
+	is(code) {
+		return Object.is(this.code, code);
+	}
+};
+//#endregion
+//#region src/path.ts
+/**
+* Returns the current runtime environment for path resolution.
+*
+* @returns Platform environment values sourced from `process` and `os.homedir()`.
+*/
+function getRuntimeEnv() {
+	return {
+		platform: process.platform,
+		env: process.env,
+		homedir: homedir()
+	};
+}
+/** Validates a path input according to its role. */
+function validatePath(value, field) {
+	if (!value.trim()) throw new CrustStoreError("PATH", `${field} must be a non-empty string`, { path: value });
+	if (field !== "dirPath" && (value.includes("/") || value.includes("\\"))) throw new CrustStoreError("PATH", `${field} must not contain path separators`, { path: value });
+	if (field === "dirPath" && !win32.isAbsolute(value)) throw new CrustStoreError("PATH", "dirPath must be an absolute path", { path: value });
+	if (field === "name" && value.endsWith(".json")) throw new CrustStoreError("PATH", "name must not include the .json extension", { path: value });
+	if (field === "dirPath" && value.endsWith(".json")) throw new CrustStoreError("PATH", "dirPath must be a directory path, not a file path (should not end with .json)", { path: value });
+}
+const DIRECTORY_CONFIG = {
+	config: {
+		xdg: "XDG_CONFIG_HOME",
+		unixFallback: [".config"],
+		windowsEnv: "APPDATA",
+		windowsFallback: ["AppData", "Roaming"],
+		windowsSuffix: []
+	},
+	data: {
+		xdg: "XDG_DATA_HOME",
+		unixFallback: [".local", "share"],
+		windowsEnv: "LOCALAPPDATA",
+		windowsFallback: ["AppData", "Local"],
+		windowsSuffix: ["Data"]
+	},
+	state: {
+		xdg: "XDG_STATE_HOME",
+		unixFallback: [".local", "state"],
+		windowsEnv: "LOCALAPPDATA",
+		windowsFallback: ["AppData", "Local"],
+		windowsSuffix: ["State"]
+	},
+	cache: {
+		xdg: "XDG_CACHE_HOME",
+		unixFallback: [".cache"],
+		windowsEnv: "LOCALAPPDATA",
+		windowsFallback: ["AppData", "Local"],
+		windowsSuffix: ["Cache"]
+	}
+};
+function resolvePlatformDir(kind, appName, env = getRuntimeEnv()) {
+	validatePath(appName, "appName");
+	const config = DIRECTORY_CONFIG[kind];
+	if (env.platform === "linux" || env.platform === "darwin") {
+		const configured = env.env[config.xdg];
+		const base = configured?.trim() ? 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 });
+}
+/**
+* Resolves the platform-standard config directory for the given app.
+*
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_CONFIG_HOME/<appName>` or `~/.config/<appName>`
+* - **Windows**: `%APPDATA%/<appName>` or `~/AppData/Roaming/<appName>`
+*
+* macOS uses XDG conventions for consistency with Linux.
+*
+* @param appName - Application name used as directory name. Must be a non-empty
+*   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.
+*
+* @example
+* ```ts
+* import { configDir } from "@crustjs/store";
+*
+* const dir = configDir("my-cli");
+* // → "/home/user/.config/my-cli" (Linux)
+* // → "/Users/user/.config/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Roaming\\my-cli" (Windows)
+* ```
+*/
+function configDir(appName, env) {
+	return resolvePlatformDir("config", appName, env);
+}
+/**
+* Resolves the platform-standard data directory for the given app.
+*
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_DATA_HOME/<appName>` or `~/.local/share/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/Data` or `~/AppData/Local/<appName>/Data`
+*
+* macOS uses XDG conventions for consistency with Linux.
+*
+* @param appName - Application name used as directory name. Must be a non-empty
+*   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.
+*
+* @example
+* ```ts
+* import { dataDir } from "@crustjs/store";
+*
+* const dir = dataDir("my-cli");
+* // → "/home/user/.local/share/my-cli" (Linux)
+* // → "/Users/user/.local/share/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Local\\my-cli\\Data" (Windows)
+* ```
+*/
+function dataDir(appName, env) {
+	return resolvePlatformDir("data", appName, env);
+}
+/**
+* Resolves the platform-standard state directory for the given app.
+*
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_STATE_HOME/<appName>` or `~/.local/state/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/State` or `~/AppData/Local/<appName>/State`
+*
+* macOS uses XDG conventions for consistency with Linux.
+*
+* @param appName - Application name used as directory name. Must be a non-empty
+*   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.
+*
+* @example
+* ```ts
+* import { stateDir } from "@crustjs/store";
+*
+* const dir = stateDir("my-cli");
+* // → "/home/user/.local/state/my-cli" (Linux)
+* // → "/Users/user/.local/state/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Local\\my-cli\\State" (Windows)
+* ```
+*/
+function stateDir(appName, env) {
+	return resolvePlatformDir("state", appName, env);
+}
+/**
+* Resolves the platform-standard cache directory for the given app.
+*
+* Platform conventions:
+* - **Linux / macOS**: `$XDG_CACHE_HOME/<appName>` or `~/.cache/<appName>`
+* - **Windows**: `%LOCALAPPDATA%/<appName>/Cache` or `~/AppData/Local/<appName>/Cache`
+*
+* macOS uses XDG conventions for consistency with Linux.
+*
+* @param appName - Application name used as directory name. Must be a non-empty
+*   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.
+*
+* @example
+* ```ts
+* import { cacheDir } from "@crustjs/store";
+*
+* const dir = cacheDir("my-cli");
+* // → "/home/user/.cache/my-cli" (Linux)
+* // → "/Users/user/.cache/my-cli" (macOS)
+* // → "C:\\Users\\user\\AppData\\Local\\my-cli\\Cache" (Windows)
+* ```
+*/
+function cacheDir(appName, env) {
+	return resolvePlatformDir("cache", appName, env);
+}
+/**
+* Constructs the absolute store file path from a directory and store name.
+*
+* Validates `dirPath` (must be absolute, not end in `.json`) and `name`
+* (no path separators, no `.json` suffix), then joins them as
+* `<dirPath>/<name>.json`.
+*
+* @param dirPath - Absolute directory path.
+* @param name - Store name used as the JSON filename.
+* @returns Absolute path to the store file.
+* @throws {CrustStoreError} `PATH` if `dirPath` or `name` is invalid.
+*/
+function resolveStorePath(dirPath, name) {
+	validatePath(dirPath, "dirPath");
+	validatePath(name, "name");
+	return join(dirPath, `${name}.json`);
+}
+//#endregion
+//#region ../utils/src/json.ts
+/** Narrow a JSON document root to an object (not array/scalar/null). */
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region ../utils/src/primitive.ts
+/**
+* Attempts to coerce a string to a number, returning `undefined` only when the
+* result is `NaN`. Callers decide whether `undefined` means throw or fallback.
+*
+* @example
+* ```ts
+* tryCoerceNumber("42"); // 42
+* tryCoerceNumber("abc"); // undefined
+* tryCoerceNumber(""); // 0
+* ```
+*/
+function tryCoerceNumber(raw) {
+	const num = Number(raw);
+	return Number.isNaN(num) ? void 0 : num;
+}
+/**
+* Coerces Crust boolean strings using the existing strict truthy spellings.
+*
+* @example
+* ```ts
+* coerceBooleanString("true"); // true
+* coerceBooleanString("1"); // true
+* coerceBooleanString("false"); // false
+* ```
+*/
+function coerceBooleanString(raw) {
+	return raw === "true" || raw === "1";
+}
+//#endregion
+//#region ../utils/src/schema.ts
+/**
+* Format an issue path into a dot-path string.
+*
+* - Numeric keys (array indexes) are rendered with bracket notation: `items[0]`
+* - String/symbol keys are joined with dots: `flags.verbose`
+* - An empty path array produces an empty string (root-level issue)
+*
+* @example
+* ```ts
+* formatPath(["flags", "verbose"]);
+* // => "flags.verbose"
+*
+* formatPath(["args", 0]);
+* // => "args[0]"
+*
+* formatPath([]);
+* // => ""
+* ```
+*/
+function isNumericPathSegment(segment) {
+	return typeof segment === "number";
+}
+function formatPath(path) {
+	return path.map((segment, index) => isNumericPathSegment(segment) ? `[${segment}]` : index > 0 ? `.${String(segment)}` : String(segment)).join("");
+}
+/**
+* Normalize a Standard Schema issue path to an array of `PropertyKey`.
+*
+* Standard Schema paths contain either bare `PropertyKey` values or
+* `{ key: PropertyKey }` segment objects; both forms are flattened to
+* plain `PropertyKey`. Returns an empty array for a root-level issue
+* (`undefined`).
+*/
+function isStandardPathSegment(segment) {
+	return typeof segment === "object" && segment !== null && "key" in segment;
+}
+function normalizeStandardPath(path) {
+	if (!path) return [];
+	return path.map((segment) => isStandardPathSegment(segment) ? segment.key : segment);
+}
+/**
+* Normalize Standard Schema issues into canonical `ValidationIssue` objects.
+*
+* Applies an optional prefix (e.g. `["flags", "verbose"]`) to each issue
+* path, then formats each path to its canonical dot-path string.
+*
+* @param issues — Raw Standard Schema issues from a failed validation
+* @param prefix — Optional path segments prepended to each issue path
+*/
+function normalizeStandardIssues(issues, prefix = []) {
+	return issues.map((issue) => {
+		const resolvedPath = normalizeStandardPath(issue.path);
+		const fullPath = [...prefix, ...resolvedPath];
+		return {
+			message: issue.message,
+			path: formatPath(fullPath)
+		};
+	});
+}
+//#endregion
+//#region src/merge.ts
+/**
+* Applies field defaults to a persisted config object.
+*
+* For each field defined in `fields`:
+* - If the key exists in `persisted`, the persisted value is used.
+* - If the key is missing and the field has a `default`, the default is used.
+*   Defaults are deep-copied to prevent shared nested mutation.
+* - 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.
+*
+* @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`.
+* @returns A new object with field defaults applied.
+*/
+function applyFieldDefaults(persisted, fields, pruneUnknown = true) {
+	const result = {};
+	for (const [key, def] of Object.entries(fields)) if (persisted && key in persisted) result[key] = persisted[key];
+	else if ("default" in def && def.default !== void 0) result[key] = structuredClone(def.default);
+	if (!pruneUnknown && persisted !== void 0) {
+		for (const [key, value] of Object.entries(persisted)) if (!(key in fields)) result[key] = value;
+	}
+	return result;
+}
+//#endregion
+//#region ../utils/src/error.ts
+/** Narrows a caught Node.js system error to its stable errno contract. */
+function isErrnoException(error) {
+	return error instanceof Error && "code" in error && typeof error.code === "string";
+}
+//#endregion
+//#region src/persistence.ts
+/**
+* Reads and parses a JSON config 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.
+* @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.
+*/
+async function readJson(filePath) {
+	let raw;
+	try {
+		raw = await readFile(filePath, "utf-8");
+	} catch (err) {
+		if (isEnoent(err)) return;
+		throw new CrustStoreError("IO", `Failed to read config file: ${filePath}`, {
+			path: filePath,
+			operation: "read"
+		}, err);
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new CrustStoreError("PARSE", `Malformed JSON in config file: ${filePath}`, { path: filePath }, 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.
+* 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.
+*/
+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;
+	const dir = dirname(filePath);
+	const tempPath = join(dir, `.config-${crypto.randomUUID()}.tmp`);
+	let createdDir;
+	try {
+		createdDir = await mkdir(dir, {
+			recursive: true,
+			mode: directoryMode
+		});
+	} catch (err) {
+		throw new CrustStoreError("IO", `Failed to create config directory: ${dir}`, {
+			path: filePath,
+			operation: "write"
+		}, err);
+	}
+	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}`, {
+			path: filePath,
+			operation: "write"
+		}, err);
+	}
+	try {
+		const json = JSON.stringify(data, null, "	");
+		await writeFile(tempPath, json, {
+			encoding: "utf-8",
+			mode: fileMode
+		});
+		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}`, {
+			path: filePath,
+			operation: "write"
+		}, err);
+	}
+	try {
+		await rename(tempPath, filePath);
+	} catch (err) {
+		await rm(tempPath, { force: true }).catch(() => {});
+		throw new CrustStoreError("IO", `Failed to finalize config file: ${filePath}`, {
+			path: filePath,
+			operation: "write"
+		}, err);
+	}
+}
+/**
+* Deletes a persisted config file from disk.
+*
+* Silently succeeds when the file does not exist (ENOENT) — deleting an
+* already-absent config is not an error.
+*
+* @param filePath - Absolute path to the JSON config 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}`, {
+			path: filePath,
+			operation: "delete"
+		}, err);
+	}
+}
+/**
+* Checks whether a thrown error is a filesystem "file not found" error.
+*/
+function isEnoent(cause) {
+	return isErrnoException(cause) && cause.code === "ENOENT";
+}
+//#endregion
+//#region src/store.ts
+function makeSchemaValidator(schema) {
+	return async (value) => {
+		const result = await schema["~standard"].validate(value);
+		if (result.issues) {
+			const messages = normalizeStandardIssues(result.issues).map((issue) => issue.path ? `${issue.path}: ${issue.message}` : issue.message);
+			throw new Error(messages.join("; "));
+		}
+		return { value: result.value };
+	};
+}
+/** Narrow a field validator return to the exact transform-result shape. */
+function isFieldValueResult(result) {
+	return typeof result === "object" && result !== null && Object.hasOwn(result, "value") && Object.keys(result).length === 1;
+}
+function matchesDeclaredType(def, value) {
+	const matches = (item) => {
+		return typeof item === def.type && (def.type !== "number" || Number.isFinite(item));
+	};
+	return def.array === true ? Array.isArray(value) && value.every(matches) : matches(value);
+}
+function expectedTypeMessage(def) {
+	return `Expected ${def.type}${def.array === true ? "[]" : ""}`;
+}
+/**
+* Creates a typed async config store backed by a local JSON file.
+*
+* The store resolves its file path once at creation time from `dirPath` and
+* `name`. Core field definitions infer from `type` and `default`;
+* schema-backed fields use the Standard Schema's exact output type.
+*
+* @typeParam F - Field definitions record (inferred via `const` generic).
+* @param options - Store configuration options.
+* @returns A {@link Store} instance with `read`, `write`, `update`, `patch`, and `reset` methods.
+* @throws {CrustStoreError} `PATH` if `dirPath` or `name` is invalid.
+* @throws {CrustStoreError} `DEFINITION` if a field mixes `schema` with `default` or `validate`.
+*
+* @example
+* ```ts
+* import { createStore, configDir } from "@crustjs/store";
+*
+* const store = createStore({
+*   dirPath: configDir("my-cli"),
+*   name: "config",
+*   fields: {
+*     theme: { type: "string", default: "light" },
+*     verbose: { type: "boolean", default: false },
+*     token: { type: "string" },
+*   },
+* });
+*
+* const config = await store.read();
+* // → { theme: "light", verbose: false, token: undefined }
+*
+* await store.write({ theme: "dark", verbose: true, token: "abc" });
+* await store.update((c) => ({ ...c, theme: "light" }));
+* await store.patch({ theme: "solarized" });
+* await store.reset();
+* ```
+*/
+function createStore(options) {
+	const { dirPath, name, fields, pruneUnknown, access } = options;
+	const validators = /* @__PURE__ */ new Map();
+	for (const [key, def] of Object.entries(fields)) if (def.schema !== void 0) {
+		for (const option of ["default", "validate"]) if (def[option] !== void 0) throw new CrustStoreError("DEFINITION", `field "${key}" mixes "schema" with "${option}" — the schema exclusively owns validation, transformation, defaults, and optionality`);
+		validators.set(key, makeSchemaValidator(def.schema));
+	} else if (def.validate !== void 0) validators.set(key, def.validate);
+	const filePath = resolveStorePath(dirPath, name);
+	const shouldPrune = pruneUnknown ?? true;
+	const writeOptions = access === "private" ? {
+		fileMode: 384,
+		directoryMode: 448
+	} : access === void 0 || access === "default" ? {} : {
+		fileMode: access.file,
+		directoryMode: access.directory
+	};
+	function coerceByType(value, type) {
+		if (type === "number" && typeof value === "string") return tryCoerceNumber(value) ?? value;
+		if (type === "boolean" && typeof value === "string") return coerceBooleanString(value);
+		return value;
+	}
+	function normalizeStateTypes(state) {
+		const normalized = { ...state };
+		for (const [key, def] of Object.entries(fields)) {
+			if (!(key in normalized) || def.schema !== void 0) continue;
+			const value = normalized[key];
+			if (value === void 0) continue;
+			if (def.array === true && Array.isArray(value)) {
+				normalized[key] = value.map((item) => coerceByType(item, def.type));
+				continue;
+			}
+			normalized[key] = coerceByType(value, def.type);
+		}
+		return normalized;
+	}
+	async function runFieldValidators(mutableState, operation) {
+		const issues = [];
+		for (const [key, def] of Object.entries(fields)) {
+			const value = mutableState[key];
+			if (value === void 0 && def.schema === void 0) continue;
+			if (value !== void 0 && def.schema === void 0 && !matchesDeclaredType(def, value)) {
+				issues.push({
+					message: expectedTypeMessage(def),
+					path: key
+				});
+				continue;
+			}
+			const validator = validators.get(key);
+			if (!validator) continue;
+			let result;
+			try {
+				result = await validator(value);
+			} catch (cause) {
+				const message = cause instanceof Error ? cause.message : "Validation failed";
+				issues.push({
+					message,
+					path: key
+				});
+				continue;
+			}
+			if (result === void 0) continue;
+			if (isFieldValueResult(result)) {
+				const transformed = result.value;
+				if (operation === "read") {
+					if (value === void 0) mutableState[key] = transformed;
+					continue;
+				}
+				if (def.schema === void 0 && !matchesDeclaredType(def, transformed)) {
+					issues.push({
+						message: expectedTypeMessage(def),
+						path: key
+					});
+					continue;
+				}
+				if (!isDeepStrictEqual(transformed, value)) {
+					let recheck;
+					try {
+						recheck = await validator(transformed);
+					} catch (cause) {
+						const message = cause instanceof Error ? cause.message : "re-validation failed";
+						issues.push({
+							message: `read-unstable transform: ${message}`,
+							path: key
+						});
+						continue;
+					}
+					if (recheck !== void 0 && (!isFieldValueResult(recheck) || !isDeepStrictEqual(recheck.value, transformed))) {
+						issues.push({
+							message: `read-unstable transform: output would be transformed again on re-read`,
+							path: key
+						});
+						continue;
+					}
+					mutableState[key] = transformed;
+				}
+			}
+		}
+		if (operation !== "read") for (const [key, value] of Object.entries(mutableState)) {
+			if (value === void 0) continue;
+			if (!isDeepStrictEqual(JSON.parse(JSON.stringify(value)), value)) issues.push({
+				message: "value does not survive JSON serialization (NaN, Infinity, -0, sparse arrays, or undefined properties)",
+				path: key
+			});
+		}
+		if (issues.length > 0) throw new CrustStoreError("VALIDATION", `Store validation failed (${operation})\n${issues.map((i) => `  - ${i.path}: ${i.message}`).join("\n")}`, {
+			operation,
+			issues
+		});
+	}
+	async function readRaw(materializeSchemaDefaults = false) {
+		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 });
+		const merged = applyFieldDefaults(persistedObject, fields, shouldPrune);
+		if (materializeSchemaDefaults) for (const [key, def] of Object.entries(fields)) {
+			if (merged[key] !== void 0 || def.schema === void 0) continue;
+			try {
+				const result = await validators.get(key)?.(void 0);
+				if (result !== void 0 && isFieldValueResult(result)) merged[key] = result.value;
+			} catch {}
+		}
+		return normalizeStateTypes(merged);
+	}
+	async function read() {
+		const document = await readRaw();
+		await runFieldValidators(document, "read");
+		return document;
+	}
+	async function write(config) {
+		const normalized = normalizeStateTypes({ ...config });
+		await runFieldValidators(normalized, "write");
+		await writeJson(filePath, normalized, writeOptions);
+		return normalized;
+	}
+	async function update(updater) {
+		const normalized = normalizeStateTypes({ ...updater(await readRaw(true)) });
+		await runFieldValidators(normalized, "update");
+		await writeJson(filePath, normalized, writeOptions);
+		return normalized;
+	}
+	async function patch(partial) {
+		const normalized = normalizeStateTypes({
+			...await readRaw(true),
+			...partial
+		});
+		await runFieldValidators(normalized, "patch");
+		await writeJson(filePath, normalized, writeOptions);
+		return normalized;
+	}
+	async function reset() {
+		await deleteJson(filePath);
+	}
+	return {
+		read,
+		write,
+		update,
+		patch,
+		reset
+	};
+}
+//#endregion
+export { CrustStoreError, cacheDir, configDir, createStore, dataDir, stateDir };