@rezwanul7/settings 1.1.0 → 2.0.0

package/README.md

@@ -38,7 +38,7 @@ A single-owner Scope, such as `global` for app-wide settings, has exactly one Ow
 import { defineSettings } from "@rezwanul7/settings";
 import { z } from "zod";
 
-export const user = defineSettings({
+export const userDefinition = defineSettings({
   schema: z.object({
     theme: z.enum(["light", "dark", "system"]),
     language: z.string(),
@@ -51,7 +51,7 @@ export const user = defineSettings({
   },
 });
 
-export const global = defineSettings({
+export const globalDefinition = defineSettings({
   schema: z.object({ maintenanceBanner: z.string().nullable() }),
   defaults: { maintenanceBanner: null },
   singleOwner: true,
@@ -76,33 +76,37 @@ the schema again breaks:
 - Don't use schema-level defaults, such as Zod's `.default()`. The Settings definition's `defaults` are the one place
   defaults live, and every field already has one there.
 - Use only JSON values: strings, finite numbers, booleans, `null`, arrays and plain objects. Every Store keeps the
-  Overrides as JSON, so a write with anything else, such as a `Date`, a class instance, a `Map`, `NaN` or an array
-  hole, throws `SettingsValidationError` with a `"Not a JSON value"` issue at its path, even where the schema accepts
-  it. For a date, store the string and convert it where the setting is used.
+  Overrides as JSON. This is checked at compile time: `defineSettings` rejects a schema whose output has a `Date`, a
+  `Map`, a `Set`, a `bigint` or a class instance, such as `z.coerce.date()`, with an error at `schema` that names the
+  path. For a date, store the string and convert it where the setting is used. Where the output type is `unknown` or
+  `any`, or the caller is untyped, a write with a value that isn't JSON, such as a `Date`, `NaN` or an array hole,
+  throws `SettingsValidationError` with a `"Not a JSON value"` issue at its path, even where the schema accepts it.
 
 ## Creating the settings
 
 Pass every Settings definition, by Scope name, and a Store to `createSettings`. Then `scope(name, id)` returns one
-Owner's settings, a `ScopedSettings`: `scope("user", "42")` is user `42`, not every user. Owner ids are strings. A
-single-owner Scope takes no id; any other Scope requires one, and both rules are checked by the types.
+Owner's settings, a `ScopedSettings`: `scope("user", "42")` is user `42`, not every user. Owner ids are non-empty
+strings: `scope("user", "")` throws a `TypeError`, so callers whose session value is missing can't all share one
+Owner. There are no other format rules, so `"42"` and `" 42"` are different Owners. A single-owner Scope takes no id;
+any other Scope requires one, and both rules are checked by the types.
 
 The Scope name is stored with every Owner's Overrides. Renaming a Scope, such as `user` to `member`, leaves the stored
 rows under the old name, so its Owners read the defaults until the rows are migrated to the new name.
 
 ```ts
 import { createSettings, MemoryStore } from "@rezwanul7/settings";
-import { global, user } from "./settings-definitions";
+import { globalDefinition, userDefinition } from "./settings-definitions";
 
 const settings = createSettings({
-  definitions: { user, global },
+  definitions: { user: userDefinition, global: globalDefinition },
   store: new MemoryStore(),
   onInvalid: (owner, issues) => {
-    console.warn("Ignored stale settings", owner, issues);
+    console.warn("Ignored stale Overrides", owner, issues);
   },
   maxRetries: 3,
 });
 
-const userSettings = settings.scope("user", "42");
+const user42Settings = settings.scope("user", "42");
 const globalSettings = settings.scope("global");
 ```
 
@@ -123,17 +127,17 @@ aren't shared between processes. For a database, use the [Prisma Store](#storing
 ## Reading and writing an Owner's settings
 
 ```ts
-const me = settings.scope("user", "42");
+const user42Settings = settings.scope("user", "42");
 
-await me.get(); // { theme: "system", language: "en", notifications: { email: true, push: false } }
-await me.get("notifications.email"); // true
+await user42Settings.get(); // { theme: "system", language: "en", notifications: { email: true, push: false } }
+await user42Settings.get("notifications.email"); // true
 
-await me.set("theme", "dark");
-await me.update({ language: "de", notifications: { push: true } });
-await me.getOverrides(); // { theme: "dark", language: "de", notifications: { push: true } }
+await user42Settings.set("theme", "dark");
+await user42Settings.update({ language: "de", notifications: { push: true } });
+await user42Settings.getOverrides(); // { theme: "dark", language: "de", notifications: { push: true } }
 
-await me.reset("theme"); // theme follows the default again
-await me.reset(); // deletes everything stored for the Owner
+await user42Settings.reset("theme"); // theme follows the default again
+await user42Settings.reset(); // deletes everything stored for the Owner
 ```
 
 | Member             | What it does                                                                                |
@@ -165,6 +169,22 @@ await me.reset(); // deletes everything stored for the Owner
 - `getOverrides()` suits a settings page that marks which values are the Owner's own. It leaves out the Overrides a
   read would ignore, the same as `get()`, so the two always agree, and it is typed like the partial `update` takes.
 
+### Record keys with a dot
+
+A record such as `labels: z.record(z.string(), z.number())` may have keys with a dot, such as `"example.com"`, but a
+dot path can't reach them: each dot in a path goes one level deeper. Change such a key through the whole record
+instead:
+
+```ts
+await siteSettings.update({ labels: { "example.com": 1, other: 2 } });
+await siteSettings.get("labels"); // { "example.com": 1, other: 2 }
+await siteSettings.reset("labels.example.com"); // nothing is at labels → example → com, so this does nothing
+
+const { "example.com": _, ...rest } = await siteSettings.get("labels");
+await siteSettings.set("labels", rest); // replaces the record whole: { other: 2 }
+await siteSettings.reset("labels"); // removes the record's Override, so the default applies again
+```
+
 ### Authorize the Owner first
 
 An Owner id is data, not a credential: the package stores and returns whatever Owner the app names, and checks
@@ -201,20 +221,20 @@ Each row holds one Owner's Overrides; an Owner with nothing stored has no row an
 names, the compound id on `scope` and `ownerId`, and the `version` default of `1`; the model and table names can be
 changed, as long as you pass the matching delegate.
 
-The row is removed by `reset()`, and a row created after it starts again at version 1. So a write that read the Owner
-just before a `reset()`, and stores after another write has recreated the row and brought it back to the version it
-read, overwrites that row: the Overrides written since the reset are lost. The model keeps no version once the row is
-gone, so the Store can't prevent that; call `reset()` when no other write to the Owner is expected, such as when
-deleting the Owner.
+The row is removed by `reset()`, and the model keeps no version once the row is gone. A row created after it starts
+at a random version rather than at 1, so a write that read the Owner just before a `reset()` is very unlikely to match
+the new row's version and is retried as a conflict. It can't be ruled out: if the versions do match, that write
+overwrites the new row and the Overrides written since the reset are lost. Call `reset()` when no other write to the
+Owner is expected, such as when deleting the Owner.
 
 ```ts
 import { createSettings } from "@rezwanul7/settings";
 import { PrismaStore } from "@rezwanul7/settings/prisma";
 import { prisma } from "./db";
-import { global, user } from "./settings-definitions";
+import { globalDefinition, userDefinition } from "./settings-definitions";
 
 export const settings = createSettings({
-  definitions: { user, global },
+  definitions: { user: userDefinition, global: globalDefinition },
   store: new PrismaStore({ delegate: prisma.setting }),
 });
 ```
@@ -233,13 +253,13 @@ import { createSettings } from "@rezwanul7/settings";
 import { PrismaStore } from "@rezwanul7/settings/prisma";
 import { auth } from "./auth";
 import { prisma } from "./db";
-import { global, user } from "./settings-definitions";
+import { globalDefinition, userDefinition } from "./settings-definitions";
 
 export const settings = createSettings({
-  definitions: { user, global },
+  definitions: { user: userDefinition, global: globalDefinition },
   store: new PrismaStore({ delegate: prisma.setting }),
   onInvalid: (owner, issues) => {
-    console.warn("Ignored stale settings", { owner, issues });
+    console.warn("Ignored stale Overrides", { owner, issues });
   },
 });
 
@@ -283,6 +303,8 @@ the Owner's page ([ADR-0001](./docs/adr/0001-overrides-only-ignored-when-invalid
   to ignore. The rest of the Owner's Overrides still apply.
 - `onInvalid(owner, issues)` is called with the issues naming what was ignored; an unknown key is reported as an issue
   with the message `"Unknown setting"`. Without `onInvalid`, they are ignored silently, so pass it to log them.
+  `onInvalid` isn't awaited, and a hook that throws or returns a rejected promise doesn't change the read or write: the
+  failure goes to `console.warn` once for each `createSettings` result.
 - `getOverrides()` ignores them the same way, but returns the Overrides it kept instead of throwing when the
   Effective settings still fail, so a page can show and fix them.
 - A read never changes the stored document. The next successful write for that Owner drops the ignored Overrides.
@@ -302,14 +324,16 @@ is unchanged. If another write got there first, it reads again and applies its c
 requests changing different settings of one Owner both take effect. After `maxRetries` retries that all lost the race,
 it throws `SettingsConflictError`, whose `owner` names the Owner, and stores nothing; it is safe to try the whole write
 again later. `reset()` deletes without a version check. `MemoryStore` keeps an Owner's versions increasing across
-`reset()`, so a write that read the Owner before the reset is a conflict; `PrismaStore` can't, see
-[Storing settings with Prisma](#storing-settings-with-prisma).
+`reset()`, so a write that read the Owner before the reset is a conflict; with `PrismaStore` it is only very likely to
+be one, see [Storing settings with Prisma](#storing-settings-with-prisma).
 
-## Secret settings
+## Sealed settings
 
-Keep a secret setting, such as an SMTP password, sealed by wrapping your Store in `SealedStore` with a
-[`@rezwanul7/secret-vault`](../secret-vault/README.md) `Vault`. List the paths to seal; you call `set` and `get` with
-plain values, the schema validates the Plaintext, and the wrapped Store only ever holds a Sealed value there. This
+Keep a setting that holds a secret, such as an SMTP password, sealed by wrapping your Store in `SealedStore` with a
+[`@rezwanul7/secret-vault`](../secret-vault/README.md) `Vault`. Pass it the same `definitions` as `createSettings` and
+list the paths to seal by Scope; each path is checked against its Scope's settings type, so a misspelled path or Scope
+doesn't compile. You call `set` and `get` with plain values, the schema validates the Plaintext, and the wrapped Store
+only ever holds a Sealed value there. This
 package doesn't depend on Secret Vault: `vault` only needs `encryptJson`, `decryptJson` and, optionally, `isSealed`
 (without it, a string starting with `vault:` counts as sealed, which is what a `Vault` writes).
 
@@ -324,7 +348,7 @@ import { z } from "zod";
 import { prisma } from "./db";
 import { vault } from "./vault";
 
-const organization = defineSettings({
+const organizationDefinition = defineSettings({
   schema: z.object({
     smtp: z.object({
       host: z.string(),
@@ -334,27 +358,40 @@ const organization = defineSettings({
   defaults: { smtp: { host: "localhost", password: null } },
 });
 
+const definitions = { organization: organizationDefinition };
+
 const settings = createSettings({
-  definitions: { organization },
+  definitions,
   store: new SealedStore({
     store: new PrismaStore({ delegate: prisma.setting }),
     vault,
-    paths: ["smtp.password"],
+    definitions,
+    paths: { organization: ["smtp.password"] },
   }),
 });
 
-await settings.scope("organization", orgId).set("smtp.password", "hunter2");
+await settings
+  .scope("organization", organizationId)
+  .set("smtp.password", "hunter2");
 const password = await settings
-  .scope("organization", orgId)
+  .scope("organization", organizationId)
   .get("smtp.password"); // "hunter2"
 ```
 
 - Each Sealed value is bound to its Owner and path (Context `settings:` plus `JSON.stringify([scope, id, path])`), so
   one copied to another Owner or path doesn't open. A script that moves a Sealed setting must open it and seal it
   again.
-- A path may name an object, which is sealed whole as JSON. No path may be inside another.
+- Only the paths listed for an Owner's Scope are sealed: `smtp.password` in another Scope stays plain unless that Scope
+  lists it too. Two Scopes may list the same path.
+- **A Scope left out of `paths` isn't sealed or opened.** If it already holds Sealed values, such as after you remove
+  it from `paths`, they read back as their raw `vault:…` strings. List every Scope that has a Sealed setting.
+- A path may name an object, which is sealed whole as JSON. No path may be inside another of the same Scope. The
+  constructor throws `TypeError` for that, for an empty path, for a Scope that isn't in `definitions`, and when no
+  Scope lists a path.
 - A Sealed value that doesn't open, such as after a wrong Vault secret, makes the read **throw**. It is never ignored
-  as a stale Override, because the next write would replace the secret with its default.
+  as a stale Override, because the next write would replace the secret with its default. Every other operation on
+  that Owner throws too, except `reset()`; to repair just that value, see
+  [Removing a Sealed value that won't open](#removing-a-sealed-value-that-wont-open).
 - Every write seals again with the Vault's current secret, so a Rotation finishes for an Owner the next time it is
   written.
 - Adding a path to `paths` on a deployment that already has plain values there is safe: they read as before and are
@@ -364,11 +401,38 @@ const password = await settings
 - Switching from values you sealed by hand: their Context differs, so open each with your old Context once and write
   the Plaintext back through the settings with a script; `SealedStore` then seals it under its own Context.
 
+### Removing a Sealed value that won't open
+
+`discard(owner, path)` removes one Sealed value that won't open, so the Owner can read its settings and set a new
+secret again. Its other Overrides stay as they are, and its other Sealed values stay sealed and aren't opened.
+
+```ts
+const sealedStore = new SealedStore({ store, vault, definitions, paths });
+
+const removed = await sealedStore.discard(
+  { scope: "organization", id: organizationId },
+  "smtp.password",
+); // true when it removed a value; the Owner now reads the default there
+```
+
+**Check the Vault secret first.** A wrong or missing secret makes every Sealed value fail to open, so `discard` would
+remove secrets that fixing the configuration would have recovered. Only discard once you know the right secret is
+loaded and this one value still doesn't open, such as one sealed under a secret that was since removed.
+
+- It returns `false` and changes nothing when the value opens, isn't a Sealed value, or isn't there, so running the
+  same repair again after the Owner set a new secret doesn't destroy it.
+- It throws `TypeError` for a path not listed for the Owner's Scope. It takes one Owner and one path; there is no bulk
+  form.
+- It writes with the version it read; on a conflict it reads again and retries up to 3 times, then throws
+  `SettingsConflictError`. A `CachedStore` underneath evicts the Owner on the conflict, so the retry reads fresh.
+
 ## Caching reads
 
 `CachedStore` keeps what the Store it wraps returns for `ttl` seconds, so reading one Owner's settings in several
 requests doesn't query the database each time. An Owner with nothing stored is cached too. Every write, conflict and
-delete evicts the Owner, so a write on this instance is read back at once and two concurrent writes both take effect.
+delete evicts the Owner, so two concurrent writes both take effect, and a write on this instance is read back at once by
+this instance, even when one of its reads of that Owner was in flight during the write: a read that an eviction
+overtook returns what it read but isn't cached.
 
 ```ts
 import { CachedStore, MemoryCache, SealedStore } from "@rezwanul7/settings";
@@ -380,15 +444,20 @@ const store = new SealedStore({
     ttl: 60,
   }),
   vault,
-  paths: ["smtp.password"],
+  definitions,
+  paths: { organization: ["smtp.password"] },
 });
 ```
 
 Nest `SealedStore` outermost so the cache only holds Sealed values. A cache that throws is passed to the optional
-`onError` and the Store answers instead; a failing `delete` leaves the entry to expire with its TTL.
+`onError` and the Store answers instead; a failing `delete` leaves the entry to expire with its TTL. `onError` isn't
+awaited, and one that throws or returns a rejected promise doesn't change the operation, so a write still returns the
+wrapped Store's result; the failure goes to `console.warn` once for each `CachedStore`.
 
 `MemoryCache` is per process. With several instances, another instance can serve Overrides up to `ttl` seconds old
-after a write elsewhere. Share a cache to avoid that; any object with three string methods fits `SettingsCache`:
+after a write elsewhere. Share a cache to avoid most of that. Even with a shared cache, a read on another instance that
+was in flight during the write can still cache the old Overrides, which are then read for up to `ttl` seconds. Any
+object with three string methods fits `SettingsCache`:
 
 ```ts
 import type { SettingsCache } from "@rezwanul7/settings";
@@ -415,8 +484,8 @@ const redisCache: SettingsCache = {
   Effective settings still fail it after ignoring stale Overrides. It is a bug in the app's Settings definitions, not
   in the input, so don't show it to a user. It carries the `scope` and, for a failed validation, the `issues`.
 
-`createSettings` also throws a `RangeError` for an invalid `maxRetries`, and `scope()` throws a `TypeError` for an id
-passed to a single-owner Scope or missing for any other, which the types already rule out.
+`createSettings` also throws a `RangeError` for an invalid `maxRetries`, and `scope()` throws a `TypeError` for an
+empty id, and for an id passed to a single-owner Scope or missing for any other, which the types already rule out.
 
 ```ts
 import { SettingsValidationError } from "@rezwanul7/settings";

package/dist/index.cjs

@@ -249,10 +249,39 @@ function coveringOverride(overrides, keys) {
   return [...keys];
 }
 
+// src/warn-once.ts
+function warnOnce(message) {
+  let warned = false;
+  return (failure) => {
+    if (warned) return;
+    warned = true;
+    console.warn(message, failure);
+  };
+}
+function guardHook(hook, message) {
+  if (hook === void 0) return void 0;
+  const warn = warnOnce(message);
+  return (...args) => {
+    try {
+      const result = hook(...args);
+      if (isThenable(result)) Promise.resolve(result).catch(warn);
+    } catch (error) {
+      warn(error);
+    }
+  };
+}
+function isThenable(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+
 // src/settings.ts
 var SINGLE_OWNER_ID = "default";
 function createSettings(options) {
-  const { definitions, store, onInvalid, maxRetries = 3 } = options;
+  const { definitions, store, maxRetries = 3 } = options;
+  const onInvalid = guardHook(
+    options.onInvalid,
+    "@rezwanul7/settings: onInvalid failed, and the operation went on without it. Later failures of this onInvalid aren't reported."
+  );
   if (!Number.isInteger(maxRetries) || maxRetries < 0) {
     throw new RangeError(
       `maxRetries must be a whole number, 0 or more; got ${maxRetries}.`
@@ -417,6 +446,9 @@ function ownerOf(scope, definition, id) {
   if (typeof id !== "string") {
     throw new TypeError(`Scope "${scope}" needs an Owner id.`);
   }
+  if (id === "") {
+    throw new TypeError(`Scope "${scope}" needs a non-empty Owner id.`);
+  }
   return { scope, id };
 }
 function rejectForbiddenKeys(path, value) {
@@ -470,6 +502,7 @@ function asJson(overrides) {
 }
 
 // src/sealed-store.ts
+var DISCARD_RETRIES = 3;
 function defaultIsSealed(value) {
   return typeof value === "string" && value.startsWith("vault:");
 }
@@ -481,22 +514,46 @@ var SealedStore = class {
   #vault;
   #paths;
   /**
-   * @param options - The Store to wrap, the Vault and the sealed paths.
-   * @throws `TypeError` when a path is empty or inside another path.
+   * @param options - The Store to wrap, the Vault, the Settings definitions and the sealed paths by Scope.
+   * @throws `TypeError` when no Scope lists a path, a Scope in `paths` isn't in `definitions`, a path is empty, or a
+   *   path is inside another of the same Scope.
    */
   constructor(options) {
     this.#store = options.store;
     this.#vault = options.vault;
-    this.#paths = [...new Set(options.paths)];
-    for (const path of this.#paths) {
-      if (path === "") throw new TypeError("SealedStore: a path is empty.");
-      const inner = this.#paths.find((p) => p.startsWith(`${path}.`));
-      if (inner !== void 0) {
+    const paths = /* @__PURE__ */ new Map();
+    for (const [scope, list] of Object.entries(
+      options.paths
+    )) {
+      if (!Object.hasOwn(options.definitions, scope)) {
         throw new TypeError(
-          `SealedStore: path "${inner}" is inside path "${path}".`
+          `SealedStore: Scope "${scope}" in paths isn't in definitions.`
         );
       }
+      const unique = [...new Set(list ?? [])];
+      for (const path of unique) {
+        if (path === "") {
+          throw new TypeError(
+            `SealedStore: a path of Scope "${scope}" is empty.`
+          );
+        }
+        const inner = unique.find((p) => p.startsWith(`${path}.`));
+        if (inner !== void 0) {
+          throw new TypeError(
+            `SealedStore: path "${inner}" is inside path "${path}" in Scope "${scope}".`
+          );
+        }
+      }
+      if (unique.length > 0) paths.set(scope, unique);
+    }
+    if (paths.size === 0) {
+      throw new TypeError("SealedStore: no Scope lists a path to seal.");
     }
+    this.#paths = paths;
+  }
+  /** The paths sealed for the Owner's Scope. */
+  #pathsOf(owner) {
+    return this.#paths.get(owner.scope) ?? [];
   }
   /** {@inheritDoc SettingsStore.read} */
   async read(owner) {
@@ -504,7 +561,7 @@ var SealedStore = class {
     if (stored === null) return null;
     const isSealed = this.#vault.isSealed?.bind(this.#vault) ?? defaultIsSealed;
     let overrides = stored.overrides;
-    for (const path of this.#paths) {
+    for (const path of this.#pathsOf(owner)) {
       const value = getAt(overrides, path);
       if (!isSealed(value)) continue;
       const plaintext = await this.#vault.decryptJson(
@@ -517,18 +574,74 @@ var SealedStore = class {
   }
   /** {@inheritDoc SettingsStore.write} */
   async write(owner, overrides, expectedVersion) {
+    return this.#store.write(
+      owner,
+      await this.#seal(owner, overrides, () => false),
+      expectedVersion
+    );
+  }
+  /**
+   * Seals the values at the paths listed for the Owner's Scope, skipping those `skip` matches; `discard` skips the
+   * values already sealed, so it never opens or seals them again.
+   */
+  async #seal(owner, overrides, skip) {
     let sealed = overrides;
-    for (const path of this.#paths) {
+    for (const path of this.#pathsOf(owner)) {
       if (!hasAt(sealed, path)) continue;
       const value = getAt(sealed, path);
-      if (value === void 0) continue;
+      if (value === void 0 || skip(value)) continue;
       sealed = setAt(
         sealed,
         path,
         await this.#vault.encryptJson(value, contextOf(owner, path))
       );
     }
-    return this.#store.write(owner, sealed, expectedVersion);
+    return sealed;
+  }
+  /**
+   * Removes one Sealed value that won't open, so the Owner can read its settings and set a new secret again; its
+   * other Sealed values stay sealed and aren't opened, and a plain value at another listed path is sealed, as on any
+   * write. Its other Overrides stay as they are. A value that opens, a
+   * plain value and an empty path are left alone, so running it again after the Owner set a new secret changes
+   * nothing. Any rejection from `decryptJson` counts as not opening.
+   *
+   * **Check the Vault secret first.** With a wrong or missing secret every Sealed value fails to open, so `discard`
+   * would remove secrets that fixing the configuration would have recovered.
+   *
+   * It reads the wrapped Store and writes with the version it read. On a conflict it reads again and retries, up to 3
+   * times; a {@link CachedStore} underneath evicts on the conflict, so the retry reads fresh Overrides.
+   *
+   * @param owner - The Owner whose Sealed value to remove.
+   * @param path - A path listed for the Owner's Scope, such as `"smtp.password"`.
+   * @returns `true` when a Sealed value that won't open was removed, `false` when nothing was changed.
+   * @throws `TypeError` when `path` isn't listed for the Owner's Scope.
+   * @throws {@link SettingsConflictError} when every write lost the version race to another write.
+   */
+  async discard(owner, path) {
+    if (!this.#pathsOf(owner).includes(path)) {
+      throw new TypeError(
+        `SealedStore: path "${path}" isn't sealed in Scope "${owner.scope}".`
+      );
+    }
+    const isSealed = this.#vault.isSealed?.bind(this.#vault) ?? defaultIsSealed;
+    for (let attempt = 0; attempt <= DISCARD_RETRIES; attempt++) {
+      const stored = await this.#store.read(owner);
+      if (stored === null || !hasAt(stored.overrides, path)) return false;
+      const value = getAt(stored.overrides, path);
+      if (!isSealed(value)) return false;
+      const opens = await this.#vault.decryptJson(value, contextOf(owner, path)).then(
+        () => true,
+        () => false
+      );
+      if (opens) return false;
+      const version = await this.#store.write(
+        owner,
+        await this.#seal(owner, removeAt(stored.overrides, path), isSealed),
+        stored.version
+      );
+      if (version !== null) return true;
+    }
+    throw new SettingsConflictError(owner, DISCARD_RETRIES);
   }
   /** {@inheritDoc SettingsStore.delete} */
   async delete(owner) {
@@ -543,6 +656,12 @@ var CachedStore = class {
   #ttl;
   #prefix;
   #onError;
+  /**
+   * The Owners with a read of the wrapped Store in flight, by cache key: how many such reads there are, and how many
+   * evictions happened since the first began. A read caches only if no eviction happened during it. An entry goes
+   * when its last read finishes, so this holds only the Owners being read right now.
+   */
+  #inFlight = /* @__PURE__ */ new Map();
   /**
    * @param options - The Store to wrap, the cache and the TTL.
    * @throws `RangeError` when `ttl` isn't a positive number.
@@ -555,7 +674,10 @@ var CachedStore = class {
     this.#cache = options.cache;
     this.#ttl = options.ttl;
     this.#prefix = options.prefix ?? "settings";
-    this.#onError = options.onError;
+    this.#onError = guardHook(
+      options.onError,
+      "@rezwanul7/settings: CachedStore onError failed, and the operation went on without it. Later failures of this onError aren't reported."
+    );
   }
   /** {@inheritDoc SettingsStore.read} */
   async read(owner) {
@@ -568,13 +690,33 @@ var CachedStore = class {
     } catch (error) {
       this.#report(error);
     }
-    const stored = await this.#store.read(owner);
+    let reading = this.#inFlight.get(key2);
+    if (reading === void 0) {
+      reading = { reads: 0, evictions: 0 };
+      this.#inFlight.set(key2, reading);
+    }
+    reading.reads++;
+    const evictionsBefore = reading.evictions;
     try {
-      await this.#cache.set(key2, JSON.stringify(stored), this.#ttl);
-    } catch (error) {
-      this.#report(error);
+      const stored = await this.#store.read(owner);
+      if (reading.evictions === evictionsBefore) {
+        try {
+          await this.#cache.set(key2, JSON.stringify(stored), this.#ttl);
+        } catch (error) {
+          this.#report(error);
+        }
+        if (reading.evictions !== evictionsBefore) {
+          try {
+            await this.#cache.delete(key2);
+          } catch (error) {
+            this.#report(error);
+          }
+        }
+      }
+      return stored;
+    } finally {
+      if (--reading.reads === 0) this.#inFlight.delete(key2);
     }
-    return stored;
   }
   /** {@inheritDoc SettingsStore.write} */
   async write(owner, overrides, expectedVersion) {
@@ -593,8 +735,11 @@ var CachedStore = class {
     }
   }
   async #evict(owner) {
+    const key2 = this.#key(owner);
+    const reading = this.#inFlight.get(key2);
+    if (reading !== void 0) reading.evictions++;
     try {
-      await this.#cache.delete(this.#key(owner));
+      await this.#cache.delete(key2);
     } catch (error) {
       this.#report(error);
     }