@weasel-js/prefs 1.9.3 → 1.9.4

package/dist/index.js

@@ -1,6 +1,28 @@
 import { openRecords, openRecordsSync } from '@weasel-js/storage';
+import { isPlainObject } from '@weasel-js/registry';
 import { unitScale, formatUnit } from '@weasel-js/quantity';
 
+// src/alias.ts
+function prefAliasTarget(alias, leafAt) {
+  const passed = /* @__PURE__ */ new Set();
+  let path = alias.of;
+  for (; ; ) {
+    if (passed.has(path)) return void 0;
+    passed.add(path);
+    const leaf = leafAt(path);
+    if (leaf === void 0) return void 0;
+    if (leaf.kind !== "alias") return { path, leaf };
+    path = leaf.of;
+  }
+}
+function prefAliasedLeaf(alias, target) {
+  return {
+    ...target,
+    name: alias.name === "" ? target.name : alias.name,
+    description: alias.description === "" ? target.description : alias.description
+  };
+}
+
 // src/helpers.ts
 function prefDisplayBounds(p) {
   if (!p.unit) return { min: p.min, max: p.max, step: p.step ?? 1 };
@@ -14,23 +36,61 @@ function prefDisplayBounds(p) {
 function isPrefLeaf(node) {
   return "kind" in node;
 }
+var VALUELESS = /* @__PURE__ */ new Set(["action", "alias", "label", "separator"]);
+function prefHoldsValue(leaf) {
+  return !VALUELESS.has(leaf.kind);
+}
+function isPrefSection(node) {
+  return !isPrefLeaf(node) && "members" in node;
+}
+function prefSectionLeaves(members) {
+  return Object.entries(members).flatMap(
+    ([key, child]) => isPrefLeaf(child) ? [[key, child]] : prefSectionLeaves(child.members)
+  );
+}
+function prefLeafAt(schema, path) {
+  if (isPrefSection(schema)) return prefSectionLeaves(schema.members).find(([key]) => key === path)?.[1];
+  let node = schema;
+  for (const seg of path.split(".")) {
+    if (isPrefLeaf(node) || !Object.hasOwn(node.children, seg)) return void 0;
+    node = node.children[seg];
+  }
+  return isPrefLeaf(node) ? node : void 0;
+}
 function prefValueAtPath(values, path) {
   let cur = values;
   for (const seg of path.split(".")) {
-    if (cur == null || typeof cur !== "object") return void 0;
+    if (cur == null || typeof cur !== "object" || !Object.hasOwn(cur, seg)) return void 0;
     cur = cur[seg];
   }
   return cur;
 }
-function visiblePrefSubtree(node, showHidden) {
-  if (isPrefLeaf(node)) return node.hidden && !showHidden ? null : node;
+function visibleFields(fields, keepEmpty) {
+  const out = {};
+  for (const [key, child] of Object.entries(fields)) {
+    if (isPrefLeaf(child)) {
+      const kept = visiblePrefSubtree(child, false, keepEmpty);
+      if (kept) out[key] = kept;
+      continue;
+    }
+    const members = visibleFields(child.members, keepEmpty);
+    if (Object.keys(members).length > 0 || keepEmpty) out[key] = { ...child, members };
+  }
+  return out;
+}
+function visiblePrefSubtree(node, showHidden, keepEmpty = false) {
+  if (isPrefLeaf(node)) {
+    if (node.hidden && !showHidden) return null;
+    if (showHidden || node.kind !== "object") return node;
+    return { ...node, children: visibleFields(node.children, keepEmpty) };
+  }
   const group = node;
   const children = {};
   for (const [key, child] of Object.entries(group.children)) {
-    const kept = visiblePrefSubtree(child, showHidden);
+    const kept = visiblePrefSubtree(child, showHidden, keepEmpty);
     if (kept) children[key] = kept;
   }
-  if (Object.keys(children).length === 0) return null;
+  if (Object.keys(children).length === 0 && !keepEmpty) return null;
   return { ...node, children };
 }
 var VERSION_RECORD = "$version";
@@ -52,13 +112,17 @@ function prefLeaves(schema) {
   walk(schema, "");
   return out;
 }
+function setOwnPrefValue(tree, key, value) {
+  Object.defineProperty(tree, key, { value, writable: true, enumerable: true, configurable: true });
+}
 function assignPrefValueAtPath(root, path, value) {
   const parts = path.split(".");
   let cursor = root;
-  for (let i = 0; i < parts.length - 1; i++) {
-    cursor = cursor[parts[i]] ??= {};
+  for (const part of parts.slice(0, -1)) {
+    if (!Object.hasOwn(cursor, part) || cursor[part] == null) setOwnPrefValue(cursor, part, {});
+    cursor = cursor[part];
   }
-  cursor[parts[parts.length - 1]] = value;
+  setOwnPrefValue(cursor, parts[parts.length - 1], value);
 }
 function flattenPrefValues(schema, tree) {
   const out = [];
@@ -73,27 +137,85 @@ function prefLeafMatches(pref, path, query) {
   if (pref.description?.toLowerCase().includes(query)) return true;
   return path.toLowerCase().includes(query);
 }
-function filterPrefSubtree(node, query, path = "") {
+function filterPrefSubtree(node, query, path = "", leafAt) {
   const q = query.trim().toLowerCase();
   if (q === "") return node;
-  if (isPrefLeaf(node)) return prefLeafMatches(node, path, q) ? node : null;
+  const find = leafAt ?? ((p) => isPrefLeaf(node) ? void 0 : prefLeafAt(node, p));
+  if (isPrefLeaf(node)) {
+    const target = node.kind === "alias" ? prefAliasTarget(node, find) : void 0;
+    const drawn = target ? prefAliasedLeaf(node, target.leaf) : node;
+    return prefLeafMatches(drawn, path, q) ? node : null;
+  }
   const group = node;
   if (group.name.toLowerCase().includes(q)) return node;
   const children = {};
   for (const [key, child] of Object.entries(group.children)) {
-    const kept = filterPrefSubtree(child, q, path === "" ? key : `${path}.${key}`);
+    const kept = filterPrefSubtree(child, q, path === "" ? key : `${path}.${key}`, find);
     if (kept) children[key] = kept;
   }
   if (Object.keys(children).length === 0) return null;
   return { ...node, children };
 }
 
-// src/migrate.ts
+// src/object.ts
+var isObject = (v) => typeof v === "object" && v !== null;
+function prefObjectBase(pref, held) {
+  if (isObject(held)) return held;
+  return pref.fromScalar?.(held) ?? (isObject(pref.default) ? pref.default : {});
+}
+function prefObjectWithField(pref, held, key, value) {
+  const base = prefObjectBase(pref, held);
+  if (value !== void 0) return { ...base, [key]: value };
+  const { [key]: _dropped, ...rest } = base;
+  return rest;
+}
+
+// src/union.ts
+function prefVariantOf(leaf, value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const key = value[leaf.tag];
+  if (typeof key !== "string" || !Object.hasOwn(leaf.variants, key)) return void 0;
+  return [key, leaf.variants[key]];
+}
+function prefVariantDefault(leaf, key) {
+  const held = leaf.variants[key]?.default;
+  const fields = held !== null && typeof held === "object" ? held : {};
+  return { ...fields, [leaf.tag]: key };
+}
+
+// src/type.ts
+function prefType(name, leaf) {
+  return { ...leaf, type: name };
+}
+
+// src/groups.ts
+function prefGroupIsPage(group) {
+  return group.as === void 0 || group.as === "page";
+}
+
+// src/stamp.ts
 var isVersion = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
-function runPrefsMigrations(cache, migrations) {
+function stampRecord(value, at) {
+  return { $at: at, value };
+}
+function isStampedRecord(record) {
+  if (record === null || typeof record !== "object") return false;
+  const keys = Object.keys(record);
+  return keys.length === 2 && Object.hasOwn(record, "value") && isVersion(record.$at);
+}
+function readRecord(record, unstamped) {
+  return isStampedRecord(record) ? { at: record.$at, value: record.value, stamped: true } : { at: unstamped, value: record, stamped: false };
+}
+function recordValue(record) {
+  return isStampedRecord(record) ? record.value : record;
+}
+
+// src/migrate.ts
+var isVersion2 = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+function runPrefsMigrations(cache, migrations, { stampAll = true } = {}) {
   const target = migrations.length;
   const raw = cache.get(VERSION_RECORD);
-  if (cache.has(VERSION_RECORD) && !isVersion(raw)) {
+  if (cache.has(VERSION_RECORD) && !isVersion2(raw)) {
     console.warn(
       `[prefs] "${cache.prefix}" has an unreadable ${VERSION_RECORD} (${JSON.stringify(raw)}); opening read-only`
     );
@@ -101,19 +223,23 @@ function runPrefsMigrations(cache, migrations) {
     return false;
   }
   const stored = cache.has(VERSION_RECORD) ? raw : 0;
-  if (stored > target) {
+  const held = cache.entries().filter(([name]) => name !== VERSION_RECORD).map(([name, record]) => ({ name, ...readRecord(record, Math.min(stored, target)) }));
+  const newest = Math.max(stored, ...held.map((r) => r.at));
+  if (newest > target) {
     console.warn(
-      `[prefs] "${cache.prefix}" was written at version ${stored}, newer than this build's ${target}; opening read-only`
+      `[prefs] "${cache.prefix}" was written at version ${newest}, newer than this build's ${target}; opening read-only`
     );
     cache.stopWriting();
     return false;
   }
-  if (stored === target || !cache.writable) return false;
-  const before = cache.entries().filter(([name]) => name !== VERSION_RECORD);
-  const records = new Map(before.map(([name, value]) => [name, structuredClone(value)]));
-  for (let v = stored; v < target; v++) {
+  if (!cache.writable) return false;
+  const at = new Map(held.filter((r) => r.at < target).map((r) => [r.name, r.at]));
+  const records = new Map(held.filter((r) => at.has(r.name)).map((r) => [r.name, structuredClone(r.value)]));
+  for (let v = Math.min(target, ...at.values()); v < target; v++) {
+    const due = new Map([...records].filter(([name]) => at.get(name) <= v));
+    const before = [...due.keys()];
     try {
-      migrations[v](records);
+      migrations[v](due);
     } catch (error) {
       console.warn(
         `[prefs] migration ${v} \u2192 ${v + 1} for "${cache.prefix}" threw; opening read-only on the unmigrated records`,
@@ -122,35 +248,76 @@ function runPrefsMigrations(cache, migrations) {
       cache.stopWriting();
       return false;
     }
+    for (const name of before) if (!due.has(name)) records.delete(name);
+    for (const [name, value] of due) {
+      records.set(name, value);
+      at.set(name, v + 1);
+    }
+  }
+  let wrote = false;
+  for (const r of held) {
+    if (at.has(r.name)) {
+      if (!records.has(r.name)) cache.delete(r.name);
+      wrote = true;
+    } else if (stampAll && !r.stamped) {
+      cache.set(r.name, stampRecord(r.value, target));
+      wrote = true;
+    }
   }
-  for (const [name] of before) if (!records.has(name)) cache.delete(name);
   for (const [name, value] of records) {
     if (value === void 0) cache.delete(name);
-    else cache.set(name, value);
+    else cache.set(name, stampRecord(value, target));
   }
-  cache.set(VERSION_RECORD, target);
-  return true;
-}
-function watchPrefsVersion(cache, target) {
-  return cache.subscribe((changes) => {
-    for (const change of changes) {
-      if (change.origin !== "remote" || change.name !== VERSION_RECORD || change.value === void 0) continue;
-      if (!isVersion(change.value)) {
-        console.warn(
-          `[prefs] "${cache.prefix}" has an unreadable ${VERSION_RECORD} (${JSON.stringify(change.value)}) from another writer; no longer persisting`
-        );
-        cache.stopWriting();
-      } else if (change.value > target) {
-        console.warn(
-          `[prefs] "${cache.prefix}" was migrated to version ${change.value} by another writer; this build knows ${target}; no longer persisting`
-        );
-        cache.stopWriting();
-      }
+  if (stored !== target) {
+    cache.set(VERSION_RECORD, target);
+    wrote = true;
+  }
+  return wrote;
+}
+function watchPrefsVersion(cache, migrations) {
+  const target = migrations.length;
+  let versioned = cache.has(VERSION_RECORD);
+  let stopped = false;
+  const migrate = () => {
+    const cleared = versioned && !cache.has(VERSION_RECORD);
+    if (cleared) cache.set(VERSION_RECORD, target);
+    else if (!runPrefsMigrations(cache, migrations, { stampAll: false })) return;
+    versioned = true;
+    void cache.flush();
+  };
+  void cache.whenRead().then(() => {
+    if (!stopped && cache.writable) migrate();
+  });
+  const heard = (version) => {
+    if (!isVersion2(version)) {
+      console.warn(
+        `[prefs] "${cache.prefix}" has an unreadable ${VERSION_RECORD} (${JSON.stringify(version)}) from another writer; no longer persisting`
+      );
+      cache.stopWriting();
+    } else if (version > target) {
+      console.warn(
+        `[prefs] "${cache.prefix}" was migrated to version ${version} by another writer; this build knows ${target}; no longer persisting`
+      );
+      cache.stopWriting();
     }
+  };
+  const stopOverruled = cache.onOverruled((changes) => {
+    for (const [name, value] of changes) if (name === VERSION_RECORD && value !== void 0) heard(value);
   });
+  const stopChanges = cache.subscribe((changes) => {
+    const remote = changes.filter((change) => change.origin === "remote");
+    for (const change of remote) {
+      if (change.name === VERSION_RECORD && change.value !== void 0) heard(change.value);
+    }
+    if (remote.length > 0 && cache.writable) migrate();
+    versioned ||= cache.has(VERSION_RECORD);
+  });
+  return () => {
+    stopped = true;
+    stopOverruled();
+    stopChanges();
+  };
 }
-
-// src/repair.ts
 function repairPrefValue(leaf, stored, validators) {
   if (leaf.kind === "number") {
     if (stored === "Infinity") stored = Infinity;
@@ -180,14 +347,45 @@ function repairPrefValue(leaf, stored, validators) {
       return e.options.some((o) => o.value === stored) ? stored : leaf.default;
     }
     case "object":
-      if (leaf.fromScalar || isPlainObject(stored)) return stored;
-      return leaf.default;
+      if (isPlainObject(stored)) return repairFields(leaf, stored, validators);
+      return leaf.fromScalar ? stored : leaf.default;
+    case "map":
+      return repairMap(leaf, stored, validators);
+    case "union": {
+      const variant = prefVariantOf(leaf, stored);
+      return variant ? repairFields(variant[1], stored, validators) : leaf.default;
+    }
+    case "list":
+      return repairList(leaf, stored, validators);
     default:
       return stored;
   }
 }
-function isPlainObject(v) {
-  return v !== null && typeof v === "object" && !Array.isArray(v);
+function repairFields(leaf, stored, validators) {
+  let out;
+  for (const [key, field] of prefSectionLeaves(leaf.children)) {
+    if (!Object.hasOwn(stored, key) || stored[key] === void 0) continue;
+    const read = repairPrefValue(field, stored[key], validators);
+    if (read !== stored[key]) (out ??= { ...stored })[key] = read;
+  }
+  return out ?? stored;
+}
+function repairMap(leaf, stored, validators) {
+  if (!isPlainObject(stored)) return leaf.default;
+  const held = stored;
+  let out;
+  for (const [key, value] of Object.entries(held)) {
+    const read = repairPrefValue(leaf.item, value, validators);
+    if (read !== value) (out ??= { ...held })[key] = read;
+  }
+  return out ?? stored;
+}
+function repairList(leaf, stored, validators) {
+  if (!Array.isArray(stored)) return leaf.default;
+  if (leaf.minItems !== void 0 && stored.length < leaf.minItems) return leaf.default;
+  const kept = leaf.maxItems !== void 0 && stored.length > leaf.maxItems ? stored.slice(0, leaf.maxItems) : stored;
+  const read = kept.map((entry) => repairPrefValue(leaf.item, entry, validators));
+  return kept === stored && read.every((entry, i) => entry === stored[i]) ? stored : read;
 }
 function repairNumber(leaf, stored) {
   if (typeof stored !== "number" || Number.isNaN(stored)) return leaf.default;
@@ -201,9 +399,30 @@ function repairNumber(leaf, stored) {
 }
 
 // src/store.ts
-var encodeInfinity = (leaf, value) => leaf.kind === "number" && (value === Infinity || value === -Infinity) ? String(value) : value;
-function createPrefsStore(schema, cache, validators, onClose) {
-  const leaves = prefLeaves(schema);
+var encodeInfinity = (leaf, value) => {
+  if (leaf.kind === "number") return value === Infinity || value === -Infinity ? String(value) : value;
+  if (leaf.kind === "list" && Array.isArray(value)) {
+    const { item } = leaf;
+    return value.map((entry) => encodeInfinity(item, entry));
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+  const held = value;
+  if (leaf.kind === "map") {
+    const { item } = leaf;
+    return Object.fromEntries(Object.entries(held).map(([key, entry]) => [key, encodeInfinity(item, entry)]));
+  }
+  const fields = leaf.kind === "union" ? prefVariantOf(leaf, held)?.[1] : leaf;
+  if (fields?.kind !== "object") return value;
+  let out;
+  for (const [key, field] of prefSectionLeaves(fields.children)) {
+    if (!Object.hasOwn(held, key)) continue;
+    const encoded = encodeInfinity(field, held[key]);
+    if (encoded !== held[key]) (out ??= { ...held })[key] = encoded;
+  }
+  return out ?? value;
+};
+function createPrefsStore(schema, cache, validators, onClose, version = 0) {
+  const leaves = new Map([...prefLeaves(schema)].filter(([, leaf]) => prefHoldsValue(leaf)));
   let snapshot = null;
   let previous = null;
   const build = () => {
@@ -218,9 +437,10 @@ function createPrefsStore(schema, cache, validators, onClose) {
         value = leaf.default;
         unset.add(path);
       } else {
-        const stored = cache.get(path);
-        raw.set(path, stored);
-        value = previous?.raw.has(path) && previous.raw.get(path) === stored ? previous.byPath.get(path) : repairPrefValue(leaf, stored, validators);
+        const record = cache.get(path);
+        const stored = recordValue(record);
+        raw.set(path, record);
+        value = previous?.raw.has(path) && previous.raw.get(path) === record ? previous.byPath.get(path) : repairPrefValue(leaf, stored, validators);
       }
       byPath.set(path, value);
       assignPrefValueAtPath(tree, path, value);
@@ -233,8 +453,9 @@ function createPrefsStore(schema, cache, validators, onClose) {
   const buildStored = () => {
     const tree = {};
     const branches = new WeakSet([tree]);
-    for (const [name, value] of cache.entries()) {
+    for (const [name, record] of cache.entries()) {
       if (name === VERSION_RECORD) continue;
+      const value = recordValue(record);
       const parts = name.split(".");
       let cursor = tree;
       for (const part of parts.slice(0, -1)) {
@@ -244,12 +465,12 @@ function createPrefsStore(schema, cache, validators, onClose) {
         } else {
           const branch = {};
           branches.add(branch);
-          cursor[part] = branch;
+          setOwnPrefValue(cursor, part, branch);
           cursor = branch;
         }
       }
       const last = parts[parts.length - 1];
-      if (!branches.has(cursor[last])) cursor[last] = value;
+      if (!branches.has(cursor[last])) setOwnPrefValue(cursor, last, value);
     }
     return tree;
   };
@@ -273,7 +494,8 @@ function createPrefsStore(schema, cache, validators, onClose) {
         console.warn(`[prefs] no leaf at "${path}"; ignoring the write`);
         return;
       }
-      cache.set(path, encodeInfinity(leaf, value));
+      const stored = encodeInfinity(leaf, value);
+      cache.set(path, stored === void 0 ? void 0 : stampRecord(stored, version));
     },
     reset: (path) => {
       for (const p of leaves.keys()) {
@@ -293,6 +515,8 @@ function createPrefsStore(schema, cache, validators, onClose) {
     get writable() {
       return cache.writable;
     },
+    read: () => cache.read(),
+    whenRead: () => cache.whenRead(),
     flush: () => cache.flush(),
     close: async () => {
       onClose?.();
@@ -308,15 +532,43 @@ async function openPrefs(schema, options) {
   const cache = await openRecords({ storage: options.storage, prefix: options.prefix });
   const stop = watch(cache, options);
   if (runPrefsMigrations(cache, options.migrations ?? [])) await cache.flush();
-  return createPrefsStore(schema, cache, options.validators, stop);
+  return createPrefsStore(schema, cache, options.validators, stop, options.migrations?.length ?? 0);
 }
 function openPrefsSync(schema, options) {
   const cache = openRecordsSync({ storage: options.storage, prefix: options.prefix });
   const stop = watch(cache, options);
   if (runPrefsMigrations(cache, options.migrations ?? [])) void cache.flush();
-  return createPrefsStore(schema, cache, options.validators, stop);
+  return createPrefsStore(schema, cache, options.validators, stop, options.migrations?.length ?? 0);
+}
+var watch = (cache, options) => watchPrefsVersion(cache, options.migrations ?? []);
+
+// src/kinds.ts
+var ONE = { compound: false, several: false };
+var MANY = { compound: true, several: true };
+var PREF_KIND_TRAITS = {
+  number: ONE,
+  boolean: ONE,
+  string: ONE,
+  enum: ONE,
+  color: ONE,
+  paint: ONE,
+  object: MANY,
+  list: MANY,
+  map: MANY,
+  union: MANY,
+  field: ONE,
+  action: { compound: false, several: true },
+  alias: ONE,
+  label: ONE,
+  separator: ONE
+};
+var traitsOf = (leaf) => Object.hasOwn(PREF_KIND_TRAITS, leaf.kind) ? PREF_KIND_TRAITS[leaf.kind] : ONE;
+function prefIsCompound(leaf) {
+  return traitsOf(leaf).compound;
+}
+function prefDrawsSeveral(leaf) {
+  return traitsOf(leaf).several;
 }
-var watch = (cache, options) => cache.writable ? watchPrefsVersion(cache, (options.migrations ?? []).length) : void 0;
 function prefUnit(system, display, opts) {
   let self;
   try {
@@ -356,7 +608,14 @@ var PREF_KINDS = {
   color: true,
   paint: true,
   object: true,
-  field: true
+  list: true,
+  map: true,
+  union: true,
+  field: true,
+  action: true,
+  alias: true,
+  label: true,
+  separator: true
 };
 function pairRowsOf(leaves) {
   const rows = /* @__PURE__ */ new Map();
@@ -373,6 +632,6 @@ function isBuiltinPref(leaf) {
   return Object.hasOwn(PREF_KINDS, leaf.kind);
 }
 
-export { PREF_KINDS, VERSION_RECORD, filterPrefSubtree, flattenPrefValues, isBuiltinPref, isPrefLeaf, openPrefs, openPrefsSync, pairRowsOf, prefDisplayBounds, prefLeaves, prefUnit, prefValueAtPath, repairPrefValue, visiblePrefSubtree };
+export { PREF_KINDS, PREF_KIND_TRAITS, VERSION_RECORD, filterPrefSubtree, flattenPrefValues, isBuiltinPref, isPrefLeaf, isPrefSection, openPrefs, openPrefsSync, pairRowsOf, prefAliasTarget, prefAliasedLeaf, prefDisplayBounds, prefDrawsSeveral, prefGroupIsPage, prefHoldsValue, prefIsCompound, prefLeafAt, prefLeaves, prefObjectBase, prefObjectWithField, prefSectionLeaves, prefType, prefUnit, prefValueAtPath, prefVariantDefault, prefVariantOf, repairPrefValue, visiblePrefSubtree };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map