@zodal/dials-store-jsonc 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @zodal/dials-store-jsonc
+
+JSONC-file [`LayerStore`](https://github.com/i2mint/zodal-dials) for **zodal-dials** with **format-preserving** writes (VS Code `settings.json` style). **Node-only.**
+
+```bash
+npm i @zodal/dials-store-jsonc @zodal/dials-core
+```
+
+```ts
+import { createJsoncStore } from '@zodal/dials-store-jsonc';
+
+const store = createJsoncStore({ path: '~/.config/myapp/settings.jsonc' });
+await store.load();                              // { 'editor.fontSize': 14, ... }
+await store.save({ 'editor.fontSize': 16 });     // comments & key order preserved
+```
+
+The file is a **flat** map of dotted keys → values (`{"editor.fontSize": 14}`), comments allowed. Writes apply targeted `jsonc-parser` edits (comments/order/whitespace preserved), `mkdir` the parent, and write atomically (temp + rename). Saves on one store are **serialized**. The `UNSET` sentinel deletes a key; a plain `undefined` is skipped.
+
+| Capability | |
+|---|---|
+| readable | ✅ |
+| writable | ✅ |
+| watchable | ❌ |
+
+## Security
+
+A settings file is plaintext. Either pass **`sensitivityFor`** so the store redacts `secret` keys on save (fail-closed, they never hit disk), or split secrets out yourself (dials-core's `splitBySensitivity`) **before** calling `save`.
+
+```ts
+createJsoncStore({ path, sensitivityFor: dials.sensitivityFor }); // secret keys never written
+```
+
+Part of the [zodal-dials](https://github.com/i2mint/zodal-dials) ecosystem.

package/dist/index.cjs

@@ -0,0 +1,107 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createJsoncStore: () => createJsoncStore
+});
+module.exports = __toCommonJS(index_exports);
+var import_jsonc_parser = require("jsonc-parser");
+var import_dials_core = require("@zodal/dials-core");
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+var tmpCounter = 0;
+function nodeFileIO() {
+  return {
+    async read(path) {
+      try {
+        const fs = await import("fs/promises");
+        return await fs.readFile(path, "utf8");
+      } catch (error) {
+        if (error.code === "ENOENT") return void 0;
+        throw error;
+      }
+    },
+    async write(path, text) {
+      const fs = await import("fs/promises");
+      const nodePath = await import("path");
+      await fs.mkdir(nodePath.dirname(path), { recursive: true });
+      const pid = globalThis.process?.pid ?? 0;
+      const tmp = `${path}.tmp-${pid}-${tmpCounter += 1}`;
+      await fs.writeFile(tmp, text, "utf8");
+      await fs.rename(tmp, path);
+    }
+  };
+}
+function createJsoncStore(options) {
+  const scope = options.scope ?? "file";
+  const io = options.fs ?? nodeFileIO();
+  const sensitivityFor = options.sensitivityFor;
+  let writeQueue = Promise.resolve();
+  return {
+    scope,
+    getCapabilities: () => ({ readable: true, writable: true, watchable: false }),
+    async load() {
+      const text = await io.read(options.path);
+      if (text === void 0 || text.trim() === "") return {};
+      const parsed = (0, import_jsonc_parser.parse)(text);
+      return isPlainObject(parsed) ? parsed : {};
+    },
+    save(layer) {
+      const run = async () => {
+        let text = await io.read(options.path) ?? "{}";
+        if (text.trim() === "" || !isPlainObject((0, import_jsonc_parser.parse)(text))) text = "{}";
+        const formattingOptions = { tabSize: 2, insertSpaces: true, eol: "\n" };
+        for (const [key, value] of Object.entries(layer)) {
+          if (sensitivityFor && sensitivityFor(key) === "secret") continue;
+          let newValue;
+          if ((0, import_dials_core.isUnset)(value)) {
+            newValue = void 0;
+          } else if (value === void 0) {
+            continue;
+          } else {
+            newValue = value;
+          }
+          const edits = (0, import_jsonc_parser.modify)(text, [key], newValue, { formattingOptions });
+          text = (0, import_jsonc_parser.applyEdits)(text, edits);
+        }
+        await io.write(options.path, text);
+      };
+      writeQueue = writeQueue.then(run, run);
+      return writeQueue;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createJsoncStore
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @zodal/dials-store-jsonc — a JSONC-file `LayerStore` for zodal-dials. **Node-only** (it owns a file).\n *\n * The file is a FLAT map of dotted setting keys -> values (the VS Code `settings.json` convention),\n * with `//` and block comments allowed. Reads parse it to a layer; writes are FORMAT-PRESERVING —\n * comments, key order, and whitespace are kept — by applying targeted `jsonc-parser` edits rather\n * than re-stringifying. The UNSET sentinel removes a key; a plain `undefined` is skipped (it is NOT\n * a delete). File IO is injectable (defaults to Node fs, which mkdir's the parent and writes\n * atomically via temp-file + rename). Saves on one store are serialized to avoid lost updates.\n *\n * SECURITY: a settings file is plaintext. Pass `sensitivityFor` to REDACT secret keys on save (they\n * are never written to disk); otherwise the caller MUST split secrets out (e.g. dials-core's\n * `splitBySensitivity`) before calling `save`. See the README.\n */\n\nimport { applyEdits, modify, parse } from 'jsonc-parser';\nimport { isUnset } from '@zodal/dials-core';\nimport type { Layer, LayerStore, LayerStoreCapabilities, Sensitivity } from '@zodal/dials-core';\n\n/** Minimal file IO contract (injectable for tests / non-Node hosts). `read` returns undefined when\n *  the file is absent. */\nexport interface FileIO {\n  read(path: string): Promise<string | undefined>;\n  write(path: string, text: string): Promise<void>;\n}\n\nexport interface JsoncStoreOptions {\n  /** Scope id. Default: 'file'. */\n  scope?: string;\n  /** Path to the JSONC file. */\n  path: string;\n  /** File IO. Default: Node fs (mkdir parent + atomic temp-then-rename; read returns undefined on ENOENT). */\n  fs?: FileIO;\n  /** Classify a setting's sensitivity. When provided, `secret` keys are REDACTED on save (never\n   *  written to disk) — fail-closed. Without it, the caller is responsible for excluding secrets. */\n  sensitivityFor?: (key: string) => Sensitivity;\n}\n\nfunction isPlainObject(value: unknown): boolean {\n  return !!value && typeof value === 'object' && !Array.isArray(value);\n}\n\nlet tmpCounter = 0;\n\nfunction nodeFileIO(): FileIO {\n  return {\n    async read(path: string): Promise<string | undefined> {\n      try {\n        const fs = await import('node:fs/promises');\n        return await fs.readFile(path, 'utf8');\n      } catch (error) {\n        if ((error as { code?: string }).code === 'ENOENT') return undefined;\n        throw error;\n      }\n    },\n    async write(path: string, text: string): Promise<void> {\n      const fs = await import('node:fs/promises');\n      const nodePath = await import('node:path');\n      await fs.mkdir(nodePath.dirname(path), { recursive: true });\n      // Atomic-ish: write a temp sibling then rename over the target so a crash can't truncate it.\n      const pid = (globalThis as { process?: { pid?: number } }).process?.pid ?? 0;\n      const tmp = `${path}.tmp-${pid}-${(tmpCounter += 1)}`;\n      await fs.writeFile(tmp, text, 'utf8');\n      await fs.rename(tmp, path);\n    },\n  };\n}\n\n/** Create a JSONC-file LayerStore with format-preserving, secret-aware, serialized writes. */\nexport function createJsoncStore(options: JsoncStoreOptions): LayerStore {\n  const scope = options.scope ?? 'file';\n  const io = options.fs ?? nodeFileIO();\n  const sensitivityFor = options.sensitivityFor;\n  let writeQueue: Promise<void> = Promise.resolve();\n\n  return {\n    scope,\n    getCapabilities: (): LayerStoreCapabilities => ({ readable: true, writable: true, watchable: false }),\n\n    async load(): Promise<Layer> {\n      const text = await io.read(options.path);\n      if (text === undefined || text.trim() === '') return {};\n      const parsed = parse(text) as unknown;\n      return isPlainObject(parsed) ? (parsed as Layer) : {};\n    },\n\n    save(layer: Layer): Promise<void> {\n      const run = async (): Promise<void> => {\n        let text = (await io.read(options.path)) ?? '{}';\n        // Reset a non-object root (array/scalar/null/empty) to an empty object so edits never throw.\n        if (text.trim() === '' || !isPlainObject(parse(text))) text = '{}';\n        const formattingOptions = { tabSize: 2, insertSpaces: true, eol: '\\n' };\n        for (const [key, value] of Object.entries(layer)) {\n          if (sensitivityFor && sensitivityFor(key) === 'secret') continue; // never persist secrets\n          let newValue: unknown;\n          if (isUnset(value)) {\n            newValue = undefined; // jsonc modify with undefined deletes the property\n          } else if (value === undefined) {\n            continue; // a plain `undefined` is NOT a delete (distinct from the UNSET sentinel) — skip\n          } else {\n            newValue = value;\n          }\n          const edits = modify(text, [key], newValue, { formattingOptions });\n          text = applyEdits(text, edits);\n        }\n        await io.write(options.path, text);\n      };\n      // Serialize saves to this store so concurrent calls can't lose updates (read-modify-write).\n      writeQueue = writeQueue.then(run, run);\n      return writeQueue;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,0BAA0C;AAC1C,wBAAwB;AAsBxB,SAAS,cAAc,OAAyB;AAC9C,SAAO,CAAC,CAAC,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AACrE;AAEA,IAAI,aAAa;AAEjB,SAAS,aAAqB;AAC5B,SAAO;AAAA,IACL,MAAM,KAAK,MAA2C;AACpD,UAAI;AACF,cAAM,KAAK,MAAM,OAAO,aAAkB;AAC1C,eAAO,MAAM,GAAG,SAAS,MAAM,MAAM;AAAA,MACvC,SAAS,OAAO;AACd,YAAK,MAA4B,SAAS,SAAU,QAAO;AAC3D,cAAM;AAAA,MACR;AAAA,IACF;AAAA,IACA,MAAM,MAAM,MAAc,MAA6B;AACrD,YAAM,KAAK,MAAM,OAAO,aAAkB;AAC1C,YAAM,WAAW,MAAM,OAAO,MAAW;AACzC,YAAM,GAAG,MAAM,SAAS,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;AAE1D,YAAM,MAAO,WAA8C,SAAS,OAAO;AAC3E,YAAM,MAAM,GAAG,IAAI,QAAQ,GAAG,IAAK,cAAc,CAAE;AACnD,YAAM,GAAG,UAAU,KAAK,MAAM,MAAM;AACpC,YAAM,GAAG,OAAO,KAAK,IAAI;AAAA,IAC3B;AAAA,EACF;AACF;AAGO,SAAS,iBAAiB,SAAwC;AACvE,QAAM,QAAQ,QAAQ,SAAS;AAC/B,QAAM,KAAK,QAAQ,MAAM,WAAW;AACpC,QAAM,iBAAiB,QAAQ;AAC/B,MAAI,aAA4B,QAAQ,QAAQ;AAEhD,SAAO;AAAA,IACL;AAAA,IACA,iBAAiB,OAA+B,EAAE,UAAU,MAAM,UAAU,MAAM,WAAW,MAAM;AAAA,IAEnG,MAAM,OAAuB;AAC3B,YAAM,OAAO,MAAM,GAAG,KAAK,QAAQ,IAAI;AACvC,UAAI,SAAS,UAAa,KAAK,KAAK,MAAM,GAAI,QAAO,CAAC;AACtD,YAAM,aAAS,2BAAM,IAAI;AACzB,aAAO,cAAc,MAAM,IAAK,SAAmB,CAAC;AAAA,IACtD;AAAA,IAEA,KAAK,OAA6B;AAChC,YAAM,MAAM,YAA2B;AACrC,YAAI,OAAQ,MAAM,GAAG,KAAK,QAAQ,IAAI,KAAM;AAE5C,YAAI,KAAK,KAAK,MAAM,MAAM,CAAC,kBAAc,2BAAM,IAAI,CAAC,EAAG,QAAO;AAC9D,cAAM,oBAAoB,EAAE,SAAS,GAAG,cAAc,MAAM,KAAK,KAAK;AACtE,mBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,cAAI,kBAAkB,eAAe,GAAG,MAAM,SAAU;AACxD,cAAI;AACJ,kBAAI,2BAAQ,KAAK,GAAG;AAClB,uBAAW;AAAA,UACb,WAAW,UAAU,QAAW;AAC9B;AAAA,UACF,OAAO;AACL,uBAAW;AAAA,UACb;AACA,gBAAM,YAAQ,4BAAO,MAAM,CAAC,GAAG,GAAG,UAAU,EAAE,kBAAkB,CAAC;AACjE,qBAAO,gCAAW,MAAM,KAAK;AAAA,QAC/B;AACA,cAAM,GAAG,MAAM,QAAQ,MAAM,IAAI;AAAA,MACnC;AAEA,mBAAa,WAAW,KAAK,KAAK,GAAG;AACrC,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,38 @@
+import { Sensitivity, LayerStore } from '@zodal/dials-core';
+
+/**
+ * @zodal/dials-store-jsonc — a JSONC-file `LayerStore` for zodal-dials. **Node-only** (it owns a file).
+ *
+ * The file is a FLAT map of dotted setting keys -> values (the VS Code `settings.json` convention),
+ * with `//` and block comments allowed. Reads parse it to a layer; writes are FORMAT-PRESERVING —
+ * comments, key order, and whitespace are kept — by applying targeted `jsonc-parser` edits rather
+ * than re-stringifying. The UNSET sentinel removes a key; a plain `undefined` is skipped (it is NOT
+ * a delete). File IO is injectable (defaults to Node fs, which mkdir's the parent and writes
+ * atomically via temp-file + rename). Saves on one store are serialized to avoid lost updates.
+ *
+ * SECURITY: a settings file is plaintext. Pass `sensitivityFor` to REDACT secret keys on save (they
+ * are never written to disk); otherwise the caller MUST split secrets out (e.g. dials-core's
+ * `splitBySensitivity`) before calling `save`. See the README.
+ */
+
+/** Minimal file IO contract (injectable for tests / non-Node hosts). `read` returns undefined when
+ *  the file is absent. */
+interface FileIO {
+    read(path: string): Promise<string | undefined>;
+    write(path: string, text: string): Promise<void>;
+}
+interface JsoncStoreOptions {
+    /** Scope id. Default: 'file'. */
+    scope?: string;
+    /** Path to the JSONC file. */
+    path: string;
+    /** File IO. Default: Node fs (mkdir parent + atomic temp-then-rename; read returns undefined on ENOENT). */
+    fs?: FileIO;
+    /** Classify a setting's sensitivity. When provided, `secret` keys are REDACTED on save (never
+     *  written to disk) — fail-closed. Without it, the caller is responsible for excluding secrets. */
+    sensitivityFor?: (key: string) => Sensitivity;
+}
+/** Create a JSONC-file LayerStore with format-preserving, secret-aware, serialized writes. */
+declare function createJsoncStore(options: JsoncStoreOptions): LayerStore;
+
+export { type FileIO, type JsoncStoreOptions, createJsoncStore };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { Sensitivity, LayerStore } from '@zodal/dials-core';
+
+/**
+ * @zodal/dials-store-jsonc — a JSONC-file `LayerStore` for zodal-dials. **Node-only** (it owns a file).
+ *
+ * The file is a FLAT map of dotted setting keys -> values (the VS Code `settings.json` convention),
+ * with `//` and block comments allowed. Reads parse it to a layer; writes are FORMAT-PRESERVING —
+ * comments, key order, and whitespace are kept — by applying targeted `jsonc-parser` edits rather
+ * than re-stringifying. The UNSET sentinel removes a key; a plain `undefined` is skipped (it is NOT
+ * a delete). File IO is injectable (defaults to Node fs, which mkdir's the parent and writes
+ * atomically via temp-file + rename). Saves on one store are serialized to avoid lost updates.
+ *
+ * SECURITY: a settings file is plaintext. Pass `sensitivityFor` to REDACT secret keys on save (they
+ * are never written to disk); otherwise the caller MUST split secrets out (e.g. dials-core's
+ * `splitBySensitivity`) before calling `save`. See the README.
+ */
+
+/** Minimal file IO contract (injectable for tests / non-Node hosts). `read` returns undefined when
+ *  the file is absent. */
+interface FileIO {
+    read(path: string): Promise<string | undefined>;
+    write(path: string, text: string): Promise<void>;
+}
+interface JsoncStoreOptions {
+    /** Scope id. Default: 'file'. */
+    scope?: string;
+    /** Path to the JSONC file. */
+    path: string;
+    /** File IO. Default: Node fs (mkdir parent + atomic temp-then-rename; read returns undefined on ENOENT). */
+    fs?: FileIO;
+    /** Classify a setting's sensitivity. When provided, `secret` keys are REDACTED on save (never
+     *  written to disk) — fail-closed. Without it, the caller is responsible for excluding secrets. */
+    sensitivityFor?: (key: string) => Sensitivity;
+}
+/** Create a JSONC-file LayerStore with format-preserving, secret-aware, serialized writes. */
+declare function createJsoncStore(options: JsoncStoreOptions): LayerStore;
+
+export { type FileIO, type JsoncStoreOptions, createJsoncStore };

package/dist/index.js

@@ -0,0 +1,72 @@
+// src/index.ts
+import { applyEdits, modify, parse } from "jsonc-parser";
+import { isUnset } from "@zodal/dials-core";
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+var tmpCounter = 0;
+function nodeFileIO() {
+  return {
+    async read(path) {
+      try {
+        const fs = await import("fs/promises");
+        return await fs.readFile(path, "utf8");
+      } catch (error) {
+        if (error.code === "ENOENT") return void 0;
+        throw error;
+      }
+    },
+    async write(path, text) {
+      const fs = await import("fs/promises");
+      const nodePath = await import("path");
+      await fs.mkdir(nodePath.dirname(path), { recursive: true });
+      const pid = globalThis.process?.pid ?? 0;
+      const tmp = `${path}.tmp-${pid}-${tmpCounter += 1}`;
+      await fs.writeFile(tmp, text, "utf8");
+      await fs.rename(tmp, path);
+    }
+  };
+}
+function createJsoncStore(options) {
+  const scope = options.scope ?? "file";
+  const io = options.fs ?? nodeFileIO();
+  const sensitivityFor = options.sensitivityFor;
+  let writeQueue = Promise.resolve();
+  return {
+    scope,
+    getCapabilities: () => ({ readable: true, writable: true, watchable: false }),
+    async load() {
+      const text = await io.read(options.path);
+      if (text === void 0 || text.trim() === "") return {};
+      const parsed = parse(text);
+      return isPlainObject(parsed) ? parsed : {};
+    },
+    save(layer) {
+      const run = async () => {
+        let text = await io.read(options.path) ?? "{}";
+        if (text.trim() === "" || !isPlainObject(parse(text))) text = "{}";
+        const formattingOptions = { tabSize: 2, insertSpaces: true, eol: "\n" };
+        for (const [key, value] of Object.entries(layer)) {
+          if (sensitivityFor && sensitivityFor(key) === "secret") continue;
+          let newValue;
+          if (isUnset(value)) {
+            newValue = void 0;
+          } else if (value === void 0) {
+            continue;
+          } else {
+            newValue = value;
+          }
+          const edits = modify(text, [key], newValue, { formattingOptions });
+          text = applyEdits(text, edits);
+        }
+        await io.write(options.path, text);
+      };
+      writeQueue = writeQueue.then(run, run);
+      return writeQueue;
+    }
+  };
+}
+export {
+  createJsoncStore
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @zodal/dials-store-jsonc — a JSONC-file `LayerStore` for zodal-dials. **Node-only** (it owns a file).\n *\n * The file is a FLAT map of dotted setting keys -> values (the VS Code `settings.json` convention),\n * with `//` and block comments allowed. Reads parse it to a layer; writes are FORMAT-PRESERVING —\n * comments, key order, and whitespace are kept — by applying targeted `jsonc-parser` edits rather\n * than re-stringifying. The UNSET sentinel removes a key; a plain `undefined` is skipped (it is NOT\n * a delete). File IO is injectable (defaults to Node fs, which mkdir's the parent and writes\n * atomically via temp-file + rename). Saves on one store are serialized to avoid lost updates.\n *\n * SECURITY: a settings file is plaintext. Pass `sensitivityFor` to REDACT secret keys on save (they\n * are never written to disk); otherwise the caller MUST split secrets out (e.g. dials-core's\n * `splitBySensitivity`) before calling `save`. See the README.\n */\n\nimport { applyEdits, modify, parse } from 'jsonc-parser';\nimport { isUnset } from '@zodal/dials-core';\nimport type { Layer, LayerStore, LayerStoreCapabilities, Sensitivity } from '@zodal/dials-core';\n\n/** Minimal file IO contract (injectable for tests / non-Node hosts). `read` returns undefined when\n *  the file is absent. */\nexport interface FileIO {\n  read(path: string): Promise<string | undefined>;\n  write(path: string, text: string): Promise<void>;\n}\n\nexport interface JsoncStoreOptions {\n  /** Scope id. Default: 'file'. */\n  scope?: string;\n  /** Path to the JSONC file. */\n  path: string;\n  /** File IO. Default: Node fs (mkdir parent + atomic temp-then-rename; read returns undefined on ENOENT). */\n  fs?: FileIO;\n  /** Classify a setting's sensitivity. When provided, `secret` keys are REDACTED on save (never\n   *  written to disk) — fail-closed. Without it, the caller is responsible for excluding secrets. */\n  sensitivityFor?: (key: string) => Sensitivity;\n}\n\nfunction isPlainObject(value: unknown): boolean {\n  return !!value && typeof value === 'object' && !Array.isArray(value);\n}\n\nlet tmpCounter = 0;\n\nfunction nodeFileIO(): FileIO {\n  return {\n    async read(path: string): Promise<string | undefined> {\n      try {\n        const fs = await import('node:fs/promises');\n        return await fs.readFile(path, 'utf8');\n      } catch (error) {\n        if ((error as { code?: string }).code === 'ENOENT') return undefined;\n        throw error;\n      }\n    },\n    async write(path: string, text: string): Promise<void> {\n      const fs = await import('node:fs/promises');\n      const nodePath = await import('node:path');\n      await fs.mkdir(nodePath.dirname(path), { recursive: true });\n      // Atomic-ish: write a temp sibling then rename over the target so a crash can't truncate it.\n      const pid = (globalThis as { process?: { pid?: number } }).process?.pid ?? 0;\n      const tmp = `${path}.tmp-${pid}-${(tmpCounter += 1)}`;\n      await fs.writeFile(tmp, text, 'utf8');\n      await fs.rename(tmp, path);\n    },\n  };\n}\n\n/** Create a JSONC-file LayerStore with format-preserving, secret-aware, serialized writes. */\nexport function createJsoncStore(options: JsoncStoreOptions): LayerStore {\n  const scope = options.scope ?? 'file';\n  const io = options.fs ?? nodeFileIO();\n  const sensitivityFor = options.sensitivityFor;\n  let writeQueue: Promise<void> = Promise.resolve();\n\n  return {\n    scope,\n    getCapabilities: (): LayerStoreCapabilities => ({ readable: true, writable: true, watchable: false }),\n\n    async load(): Promise<Layer> {\n      const text = await io.read(options.path);\n      if (text === undefined || text.trim() === '') return {};\n      const parsed = parse(text) as unknown;\n      return isPlainObject(parsed) ? (parsed as Layer) : {};\n    },\n\n    save(layer: Layer): Promise<void> {\n      const run = async (): Promise<void> => {\n        let text = (await io.read(options.path)) ?? '{}';\n        // Reset a non-object root (array/scalar/null/empty) to an empty object so edits never throw.\n        if (text.trim() === '' || !isPlainObject(parse(text))) text = '{}';\n        const formattingOptions = { tabSize: 2, insertSpaces: true, eol: '\\n' };\n        for (const [key, value] of Object.entries(layer)) {\n          if (sensitivityFor && sensitivityFor(key) === 'secret') continue; // never persist secrets\n          let newValue: unknown;\n          if (isUnset(value)) {\n            newValue = undefined; // jsonc modify with undefined deletes the property\n          } else if (value === undefined) {\n            continue; // a plain `undefined` is NOT a delete (distinct from the UNSET sentinel) — skip\n          } else {\n            newValue = value;\n          }\n          const edits = modify(text, [key], newValue, { formattingOptions });\n          text = applyEdits(text, edits);\n        }\n        await io.write(options.path, text);\n      };\n      // Serialize saves to this store so concurrent calls can't lose updates (read-modify-write).\n      writeQueue = writeQueue.then(run, run);\n      return writeQueue;\n    },\n  };\n}\n"],"mappings":";AAeA,SAAS,YAAY,QAAQ,aAAa;AAC1C,SAAS,eAAe;AAsBxB,SAAS,cAAc,OAAyB;AAC9C,SAAO,CAAC,CAAC,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AACrE;AAEA,IAAI,aAAa;AAEjB,SAAS,aAAqB;AAC5B,SAAO;AAAA,IACL,MAAM,KAAK,MAA2C;AACpD,UAAI;AACF,cAAM,KAAK,MAAM,OAAO,aAAkB;AAC1C,eAAO,MAAM,GAAG,SAAS,MAAM,MAAM;AAAA,MACvC,SAAS,OAAO;AACd,YAAK,MAA4B,SAAS,SAAU,QAAO;AAC3D,cAAM;AAAA,MACR;AAAA,IACF;AAAA,IACA,MAAM,MAAM,MAAc,MAA6B;AACrD,YAAM,KAAK,MAAM,OAAO,aAAkB;AAC1C,YAAM,WAAW,MAAM,OAAO,MAAW;AACzC,YAAM,GAAG,MAAM,SAAS,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;AAE1D,YAAM,MAAO,WAA8C,SAAS,OAAO;AAC3E,YAAM,MAAM,GAAG,IAAI,QAAQ,GAAG,IAAK,cAAc,CAAE;AACnD,YAAM,GAAG,UAAU,KAAK,MAAM,MAAM;AACpC,YAAM,GAAG,OAAO,KAAK,IAAI;AAAA,IAC3B;AAAA,EACF;AACF;AAGO,SAAS,iBAAiB,SAAwC;AACvE,QAAM,QAAQ,QAAQ,SAAS;AAC/B,QAAM,KAAK,QAAQ,MAAM,WAAW;AACpC,QAAM,iBAAiB,QAAQ;AAC/B,MAAI,aAA4B,QAAQ,QAAQ;AAEhD,SAAO;AAAA,IACL;AAAA,IACA,iBAAiB,OAA+B,EAAE,UAAU,MAAM,UAAU,MAAM,WAAW,MAAM;AAAA,IAEnG,MAAM,OAAuB;AAC3B,YAAM,OAAO,MAAM,GAAG,KAAK,QAAQ,IAAI;AACvC,UAAI,SAAS,UAAa,KAAK,KAAK,MAAM,GAAI,QAAO,CAAC;AACtD,YAAM,SAAS,MAAM,IAAI;AACzB,aAAO,cAAc,MAAM,IAAK,SAAmB,CAAC;AAAA,IACtD;AAAA,IAEA,KAAK,OAA6B;AAChC,YAAM,MAAM,YAA2B;AACrC,YAAI,OAAQ,MAAM,GAAG,KAAK,QAAQ,IAAI,KAAM;AAE5C,YAAI,KAAK,KAAK,MAAM,MAAM,CAAC,cAAc,MAAM,IAAI,CAAC,EAAG,QAAO;AAC9D,cAAM,oBAAoB,EAAE,SAAS,GAAG,cAAc,MAAM,KAAK,KAAK;AACtE,mBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,cAAI,kBAAkB,eAAe,GAAG,MAAM,SAAU;AACxD,cAAI;AACJ,cAAI,QAAQ,KAAK,GAAG;AAClB,uBAAW;AAAA,UACb,WAAW,UAAU,QAAW;AAC9B;AAAA,UACF,OAAO;AACL,uBAAW;AAAA,UACb;AACA,gBAAM,QAAQ,OAAO,MAAM,CAAC,GAAG,GAAG,UAAU,EAAE,kBAAkB,CAAC;AACjE,iBAAO,WAAW,MAAM,KAAK;AAAA,QAC/B;AACA,cAAM,GAAG,MAAM,QAAQ,MAAM,IAAI;AAAA,MACnC;AAEA,mBAAa,WAAW,KAAK,KAAK,GAAG;AACrC,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@zodal/dials-store-jsonc",
+  "version": "0.1.0",
+  "description": "JSONC-file LayerStore for zodal-dials with format-preserving writes (VS Code settings.json style)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  },
+  "peerDependencies": {
+    "@zodal/core": "^0.1.2",
+    "@zodal/dials-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@zodal/core": "^0.1.2",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@zodal/dials-core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}