@rezwanul7/settings 0.1.0 → 1.1.0

package/README.md

@@ -76,15 +76,18 @@ 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 `Date` would read back as its ISO string and an `undefined` value would be dropped. For a
-  date, store the string and convert it where the setting is used. `MemoryStore` keeps them as JSON too, so tests
-  show what a database does.
+  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.
 
 ## Creating the settings
 
-Pass every Settings definition, by Scope name, and a Store to `createSettings`. Then `scope(name, id)` gives one
-Owner's `ScopedSettings`. Owner ids are strings. A single-owner Scope takes no id; any other Scope requires one, and
-both rules are checked by the types.
+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.
+
+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";
@@ -140,7 +143,7 @@ await me.reset(); // deletes everything stored for the Owner
 | `get(path)`        | One typed value of the Effective settings, at a dot path such as `"notifications.email"`.   |
 | `set(path, value)` | Stores `value` as the Override at `path`, keeping the other Overrides.                      |
 | `update(partial)`  | Deep-merges `partial` into the Overrides, to change several settings at once.               |
-| `getOverrides()`   | The Overrides as stored, without the defaults, or `{}` when nothing is stored.              |
+| `getOverrides()`   | The Owner's own Overrides, without the defaults, or `{}` when nothing is stored.            |
 | `reset(path)`      | Removes the Override at `path` (and every Override under it), so the default applies again. |
 | `reset()`          | Deletes everything stored for the Owner, so it reads the defaults.                          |
 
@@ -151,15 +154,16 @@ await me.reset(); // deletes everything stored for the Owner
   issue, and `get(path)` reads one as `undefined`. Stored ones are ignored as unknown keys.
 - Merging works the same on reads and in `update`: plain objects merge key by key; arrays, scalars and `null` replace.
 - In `update`, an `undefined` value leaves that Override as it was, and `null` is stored as a value, which passes only
-  if the schema allows it.
+  if the schema allows it. `set(path, undefined)` throws `SettingsValidationError`; use `reset(path)` to remove an
+  Override.
 - A value equal to the current default is still stored as an Override, so a later change of the default doesn't change
   what the Owner chose. `reset(path)` is how an Owner follows the default again; with no Override at `path`, it
   writes nothing.
 - A write whose Effective settings fail the schema throws `SettingsValidationError` and stores nothing. So does a
   write with a key the schema doesn't know, which a schema that strips unknown keys would otherwise drop silently; the
   issue for it has the message `"Unknown setting"`, as on read.
-- `getOverrides()` suits a settings page that marks which values are the Owner's own; it returns the document as
-  stored, including any Overrides a read would ignore.
+- `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.
 
 ### Authorize the Owner first
 
@@ -279,6 +283,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.
+- `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.
 - Writes read the Overrides first, so `onInvalid` can also be called during `set`, `update` or `reset(path)`, and more
   than once for one write when it retries after a conflict.
@@ -301,15 +307,17 @@ again later. `reset()` deletes without a version check. `MemoryStore` keeps an O
 
 ## Secret settings
 
-The package doesn't encrypt anything. Keep a secret setting, such as an SMTP password, sealed with
-[`@rezwanul7/secret-vault`](../secret-vault/README.md): seal it before `set()`, store the Sealed value as a string,
-and open it after `get()`. Give the Context the Owner, so a Sealed value copied to another Owner doesn't open.
+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
+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).
 
 ```ts
 import {
   createSettings,
   defineSettings,
-  type Owner,
+  SealedStore,
 } from "@rezwanul7/settings";
 import { PrismaStore } from "@rezwanul7/settings/prisma";
 import { z } from "zod";
@@ -320,8 +328,7 @@ const organization = defineSettings({
   schema: z.object({
     smtp: z.object({
       host: z.string(),
-      // A Sealed value made by the Vault, never the password itself.
-      password: z.string().startsWith("vault:").nullable(),
+      password: z.string().min(1).nullable(),
     }),
   }),
   defaults: { smtp: { host: "localhost", password: null } },
@@ -329,30 +336,74 @@ const organization = defineSettings({
 
 const settings = createSettings({
   definitions: { organization },
-  store: new PrismaStore({ delegate: prisma.setting }),
+  store: new SealedStore({
+    store: new PrismaStore({ delegate: prisma.setting }),
+    vault,
+    paths: ["smtp.password"],
+  }),
 });
 
-function smtpPasswordContext(owner: Owner): string {
-  return `settings:smtp.password:${owner.scope}:${owner.id}`;
-}
+await settings.scope("organization", orgId).set("smtp.password", "hunter2");
+const password = await settings
+  .scope("organization", orgId)
+  .get("smtp.password"); // "hunter2"
+```
 
-export async function saveSmtpPassword(orgId: string, password: string) {
-  const org = settings.scope("organization", orgId);
-  const sealed = await vault.encrypt(password, smtpPasswordContext(org.owner));
-  await org.set("smtp.password", sealed);
-}
+- 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.
+- 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.
+- 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
+  sealed on each Owner's next write. Values at unlisted paths are never opened.
+- The Effective settings now hold the **Plaintext**. Don't log them or pass them to the client; read the secret on the
+  server, only where it is used.
+- 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.
+
+## 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.
 
-export async function readSmtpPassword(orgId: string): Promise<string | null> {
-  const org = settings.scope("organization", orgId);
-  const sealed = await org.get("smtp.password");
-  return sealed === null
-    ? null
-    : vault.decrypt(sealed, smtpPasswordContext(org.owner));
-}
+```ts
+import { CachedStore, MemoryCache, SealedStore } from "@rezwanul7/settings";
+
+const store = new SealedStore({
+  store: new CachedStore({
+    store: new PrismaStore({ delegate: prisma.setting }),
+    cache: new MemoryCache({ maxEntries: 5000 }),
+    ttl: 60,
+  }),
+  vault,
+  paths: ["smtp.password"],
+});
 ```
 
-The Effective settings then hold only the Sealed value, so they can be logged or passed around without exposing the
-secret; open it on the server, only where it is used.
+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.
+
+`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`:
+
+```ts
+import type { SettingsCache } from "@rezwanul7/settings";
+import { redis } from "./redis";
+
+const redisCache: SettingsCache = {
+  get: async (key) => (await redis.get(key)) ?? undefined,
+  set: async (key, value, ttlSeconds) => {
+    await redis.set(key, value, "EX", Math.ceil(ttlSeconds));
+  },
+  delete: async (key) => {
+    await redis.del(key);
+  },
+};
+```
 
 ## Errors
 
@@ -380,6 +431,10 @@ try {
 }
 ```
 
+Each error sets `name` to its class name. When the app may load both the ESM and the CommonJS build of the package,
+as mixed bundling can, `instanceof` fails across the two copies; check `error.name === "SettingsValidationError"`
+there instead.
+
 ## API reference
 
 Every export, parameter, and default is listed in the [API reference](./docs/api/README.md), generated from the source.

package/dist/index.cjs

@@ -140,6 +140,25 @@ function forbiddenKeysIn(value, path) {
     ([key2, child]) => FORBIDDEN_KEYS.has(key2) ? [{ message: "Forbidden key", path: [...path, key2] }] : forbiddenKeysIn(child, [...path, key2])
   );
 }
+function nonJsonValues(path, value) {
+  return nonJsonValuesIn(value, path === void 0 ? [] : keysOf(path));
+}
+function nonJsonValuesIn(value, path) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return Array.from(value).flatMap(
+      (item, index) => nonJsonValuesIn(item, [...path, index])
+    );
+  }
+  if (isPlainObject(value) && Object.getOwnPropertySymbols(value).length === 0) {
+    return Object.entries(value).flatMap(
+      ([key2, child]) => child === void 0 ? [] : nonJsonValuesIn(child, [...path, key2])
+    );
+  }
+  return [{ message: "Not a JSON value", path: [...path] }];
+}
 function getAt(value, path) {
   let current = value;
   for (const key2 of keysOf(path)) {
@@ -349,16 +368,27 @@ function createSettings(options) {
         },
         async set(path, value) {
           rejectForbiddenKeys(path, value);
+          if (value === void 0) {
+            throw new SettingsValidationError([
+              {
+                message: "Not a JSON value: use reset(path) to remove an Override",
+                path: path.split(".")
+              }
+            ]);
+          }
+          rejectNonJsonValues(path, value);
           await change((overrides) => setAt(overrides, path, value));
         },
         async update(partial) {
           rejectForbiddenKeys(void 0, partial);
+          rejectNonJsonValues(void 0, partial);
           await change(
             (overrides) => mergeOverrides(overrides, withoutUndefined(partial))
           );
         },
         async getOverrides() {
-          return (await readOverrides())?.overrides ?? {};
+          const stored = await readOverrides();
+          return (await withoutStale(stored?.overrides ?? {})).overrides;
         },
         async reset(path) {
           if (path === void 0) {
@@ -393,6 +423,10 @@ function rejectForbiddenKeys(path, value) {
   const issues = forbiddenKeys(path, value);
   if (issues.length > 0) throw new SettingsValidationError(issues);
 }
+function rejectNonJsonValues(path, value) {
+  const issues = nonJsonValues(path, value);
+  if (issues.length > 0) throw new SettingsValidationError(issues);
+}
 function unknownSettings(overrides, output) {
   return unknownKeys(overrides, output).map((path) => ({
     message: "Unknown setting",
@@ -435,7 +469,193 @@ function asJson(overrides) {
   return JSON.parse(JSON.stringify(overrides));
 }
 
+// src/sealed-store.ts
+function defaultIsSealed(value) {
+  return typeof value === "string" && value.startsWith("vault:");
+}
+function contextOf(owner, path) {
+  return `settings:${JSON.stringify([owner.scope, owner.id, path])}`;
+}
+var SealedStore = class {
+  #store;
+  #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.
+   */
+  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) {
+        throw new TypeError(
+          `SealedStore: path "${inner}" is inside path "${path}".`
+        );
+      }
+    }
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const stored = await this.#store.read(owner);
+    if (stored === null) return null;
+    const isSealed = this.#vault.isSealed?.bind(this.#vault) ?? defaultIsSealed;
+    let overrides = stored.overrides;
+    for (const path of this.#paths) {
+      const value = getAt(overrides, path);
+      if (!isSealed(value)) continue;
+      const plaintext = await this.#vault.decryptJson(
+        value,
+        contextOf(owner, path)
+      );
+      overrides = setAt(overrides, path, plaintext);
+    }
+    return { overrides, version: stored.version };
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    let sealed = overrides;
+    for (const path of this.#paths) {
+      if (!hasAt(sealed, path)) continue;
+      const value = getAt(sealed, path);
+      if (value === void 0) continue;
+      sealed = setAt(
+        sealed,
+        path,
+        await this.#vault.encryptJson(value, contextOf(owner, path))
+      );
+    }
+    return this.#store.write(owner, sealed, expectedVersion);
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    await this.#store.delete(owner);
+  }
+};
+
+// src/cached-store.ts
+var CachedStore = class {
+  #store;
+  #cache;
+  #ttl;
+  #prefix;
+  #onError;
+  /**
+   * @param options - The Store to wrap, the cache and the TTL.
+   * @throws `RangeError` when `ttl` isn't a positive number.
+   */
+  constructor(options) {
+    if (!(options.ttl > 0) || !Number.isFinite(options.ttl)) {
+      throw new RangeError("CachedStore: ttl must be a positive number.");
+    }
+    this.#store = options.store;
+    this.#cache = options.cache;
+    this.#ttl = options.ttl;
+    this.#prefix = options.prefix ?? "settings";
+    this.#onError = options.onError;
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const key2 = this.#key(owner);
+    try {
+      const cached = await this.#cache.get(key2);
+      if (cached !== void 0) {
+        return JSON.parse(cached);
+      }
+    } catch (error) {
+      this.#report(error);
+    }
+    const stored = await this.#store.read(owner);
+    try {
+      await this.#cache.set(key2, JSON.stringify(stored), this.#ttl);
+    } catch (error) {
+      this.#report(error);
+    }
+    return stored;
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    try {
+      return await this.#store.write(owner, overrides, expectedVersion);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    try {
+      await this.#store.delete(owner);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  async #evict(owner) {
+    try {
+      await this.#cache.delete(this.#key(owner));
+    } catch (error) {
+      this.#report(error);
+    }
+  }
+  #key(owner) {
+    return `${this.#prefix}:${JSON.stringify([owner.scope, owner.id])}`;
+  }
+  #report(error) {
+    this.#onError?.(error);
+  }
+};
+
+// src/memory-cache.ts
+var MemoryCache = class {
+  #entries = /* @__PURE__ */ new Map();
+  #maxEntries;
+  /**
+   * @param options - The size limit.
+   * @throws `RangeError` when `maxEntries` isn't a positive integer.
+   */
+  constructor(options = {}) {
+    const { maxEntries = 1e3 } = options;
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw new RangeError(
+        "MemoryCache: maxEntries must be a positive integer."
+      );
+    }
+    this.#maxEntries = maxEntries;
+  }
+  /** {@inheritDoc SettingsCache.get} */
+  async get(key2) {
+    const entry = this.#entries.get(key2);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key2);
+      return void 0;
+    }
+    return entry.value;
+  }
+  /** {@inheritDoc SettingsCache.set} */
+  async set(key2, value, ttlSeconds) {
+    this.#entries.delete(key2);
+    this.#entries.set(key2, {
+      value,
+      expiresAt: Date.now() + ttlSeconds * 1e3
+    });
+    while (this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next().value;
+      this.#entries.delete(oldest);
+    }
+  }
+  /** {@inheritDoc SettingsCache.delete} */
+  async delete(key2) {
+    this.#entries.delete(key2);
+  }
+};
+
+exports.CachedStore = CachedStore;
+exports.MemoryCache = MemoryCache;
 exports.MemoryStore = MemoryStore;
+exports.SealedStore = SealedStore;
 exports.SettingsConflictError = SettingsConflictError;
 exports.SettingsDefinitionError = SettingsDefinitionError;
 exports.SettingsValidationError = SettingsValidationError;

package/dist/index.d.cts

@@ -180,6 +180,10 @@ interface SettingsOptions<Definitions extends Record<string, SettingsDefinition>
  * The keys `__proto__`, `constructor` and `prototype` can't be setting names: a write with one in its path or value
  * throws {@link SettingsValidationError} with a `"Forbidden key"` issue, and `get(path)` reads one as `undefined`.
  *
+ * Overrides are kept as JSON, so a write with a value that isn't JSON, such as a `Date`, a class instance, `NaN` or an
+ * array hole, throws {@link SettingsValidationError} with a `"Not a JSON value"` issue at its path, even where the
+ * schema accepts it.
+ *
  * @typeParam T - The Scope's settings type.
  */
 interface ScopedSettings<T> {
@@ -208,9 +212,11 @@ interface ScopedSettings<T> {
      * still stored, so a later change of the default doesn't change what the Owner chose.
      *
      * @param path - A dot path into the settings, such as `"notifications.email"`.
-     * @param value - The value to store at `path`.
-     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, or the change has
-     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue; nothing is stored.
+     * @param value - The value to store at `path`. Use {@link ScopedSettings.reset} rather than `undefined` to remove an
+     *   Override.
+     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, the change has
+     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue, or `value` is `undefined` or isn't JSON;
+     *   nothing is stored.
      * @throws {@link SettingsConflictError} If other writes to the Owner kept winning the version race for `maxRetries`
      *   retries; nothing is stored.
      */
@@ -221,19 +227,23 @@ interface ScopedSettings<T> {
      * stored as a value and passes only if the schema allows it.
      *
      * @param partial - The settings to change, at any depth, such as `{ theme: "dark", notifications: { email: false } }`.
-     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, or `partial` has
-     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue; nothing is stored.
+     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, `partial` has
+     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue, or a value in it isn't JSON; nothing is
+     *   stored.
      * @throws {@link SettingsConflictError} If other writes to the Owner kept winning the version race for `maxRetries`
      *   retries; nothing is stored.
      */
     update(partial: DeepPartial<T>): Promise<void>;
     /**
-     * Reads the Owner's Overrides as stored, without the defaults, for example to show which values are the Owner's
-     * own choices. Overrides a read would ignore are included until the next write drops them.
+     * Reads the Owner's Overrides without the defaults, for example to show which values are the Owner's own choices.
+     * Overrides a read would ignore are left out and reported to `onInvalid`, the same as {@link ScopedSettings.get},
+     * so the two always agree; the stored document isn't changed. Unlike `get`, it doesn't throw when the Effective
+     * settings still fail after leaving those out, so a page can show the Overrides that remain and fix them.
      *
-     * @returns The stored Overrides, or `{}` when nothing is stored.
+     * @returns The Overrides a read uses, or `{}` when nothing is stored.
+     * @throws {@link SettingsDefinitionError} If the Scope's defaults fail its schema.
      */
-    getOverrides(): Promise<Record<string, unknown>>;
+    getOverrides(): Promise<DeepPartial<T>>;
     /**
      * Removes the Override at `path`, so that setting follows the default again. Resetting an object removes every
      * Override under it. With no Override at or under `path`, it writes nothing.
@@ -257,6 +267,9 @@ type OwnerIdArgs<D> = D extends SettingsDefinition<unknown, true> ? [] : [id: st
  * Creates the settings for an app's Scopes over one Store. Call `scope(name, id)` on the result to read and write
  * one Owner's settings; a single-owner Scope takes no id.
  *
+ * The Scope name is stored with every Owner's Overrides, so renaming a Scope needs a migration of its stored rows;
+ * until then its Owners read the defaults.
+ *
  * Each Scope's defaults are validated against its schema on the first operation on that Scope, and the outcome is
  * kept for the life of the returned object. If the validation itself throws, such as an async validator that can't
  * reach its service, that operation rejects with the error and the next one checks again.
@@ -301,6 +314,175 @@ declare class MemoryStore implements SettingsStore {
     delete(owner: Owner): Promise<void>;
 }
 
+/**
+ * The part of a Secret Vault `Vault` that {@link SealedStore} uses, so this package doesn't depend on Secret Vault.
+ * A `Vault` fits.
+ */
+interface SealingVault {
+    /**
+     * Seals a JSON value.
+     *
+     * @param value - The value to seal.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value.
+     */
+    encryptJson(value: unknown, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by `encryptJson`; rejects when it doesn't open.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext value.
+     */
+    decryptJson(sealed: string, context: string): Promise<unknown>;
+    /**
+     * Whether a stored value is a Sealed value rather than plain text still stored at a listed path. Optional: a Secret
+     * Vault `Vault` has `isSealed` only as a static method, so without it `SealedStore` treats a string starting with
+     * `vault:` as sealed.
+     *
+     * @param value - A stored value.
+     */
+    isSealed?(value: unknown): boolean;
+}
+/** Options of {@link SealedStore}. */
+interface SealedStoreOptions {
+    /** The Store that keeps the Sealed values. */
+    readonly store: SettingsStore;
+    /** Seals and opens values; a Secret Vault `Vault` fits. */
+    readonly vault: SealingVault;
+    /**
+     * Dot paths into the settings to keep sealed, such as `"smtp.password"`. A path may name an object, which is sealed
+     * whole as JSON. No path may be inside another.
+     */
+    readonly paths: readonly string[];
+}
+/**
+ * A Store that keeps the Overrides at the listed paths as Sealed values in the Store it wraps, and hands the core
+ * their Plaintext. The schema validates the Plaintext, and the app calls `set` and `get` with plain values.
+ *
+ * Every write seals again with the Vault's current secret, which finishes a Rotation for that Owner. A Sealed value
+ * that doesn't open makes the read throw: it is never ignored as a stale Override, because the next write would
+ * replace the secret with its default. A plain value at a listed path reads as it is and is sealed on the Owner's next
+ * write. Values at unlisted paths are never opened.
+ *
+ * Nest it outermost, around a {@link CachedStore}, so the cache holds only Sealed values.
+ *
+ * @example
+ * const store = new SealedStore({
+ *   store: new PrismaStore({ delegate: prisma.setting }),
+ *   vault,
+ *   paths: ["smtp.password"],
+ * });
+ */
+declare class SealedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the Vault and the sealed paths.
+     * @throws `TypeError` when a path is empty or inside another path.
+     */
+    constructor(options: SealedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/**
+ * A cache of strings with a time to live, which {@link CachedStore} keeps Overrides in. {@link MemoryCache} fits;
+ * so does a thin wrapper around Redis or Keyv.
+ */
+interface SettingsCache {
+    /**
+     * Reads an entry.
+     *
+     * @param key - The cache key.
+     * @returns The value, or `undefined` when there is none or it expired.
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Stores an entry, replacing any under the key.
+     *
+     * @param key - The cache key.
+     * @param value - The string to keep.
+     * @param ttlSeconds - Seconds until the entry expires.
+     */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Removes an entry; removing a missing one does nothing.
+     *
+     * @param key - The cache key.
+     */
+    delete(key: string): Promise<void>;
+}
+/** Options of {@link CachedStore}. */
+interface CachedStoreOptions {
+    /** The Store to read through. */
+    readonly store: SettingsStore;
+    /** Where to keep what the Store returns. */
+    readonly cache: SettingsCache;
+    /** Seconds an entry stays cached. */
+    readonly ttl: number;
+    /** Starts every cache key. Defaults to `"settings"`. */
+    readonly prefix?: string;
+    /** Called with an error a cache method threw; the Store then answers instead. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * A Store that keeps what the Store it wraps returns in a cache for `ttl` seconds, an Owner with nothing stored
+ * included. Every write, conflict and delete evicts the Owner, so a write on this instance is read back at once and a
+ * conflicting write retries against fresh Overrides. A cache that throws is reported to `onError` and the Store
+ * answers instead.
+ *
+ * With a per-process cache and several instances, another instance can read Overrides up to `ttl` seconds old. Share
+ * a cache, such as Redis, to avoid it.
+ *
+ * @example
+ * const store = new CachedStore({ store: prismaStore, cache: new MemoryCache(), ttl: 60 });
+ */
+declare class CachedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the cache and the TTL.
+     * @throws `RangeError` when `ttl` isn't a positive number.
+     */
+    constructor(options: CachedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/** Options of {@link MemoryCache}. */
+interface MemoryCacheOptions {
+    /** Most entries kept; the oldest are evicted past it. Defaults to 1000. */
+    readonly maxEntries?: number;
+}
+/**
+ * A {@link SettingsCache} in process memory. Entries expire after their TTL and the oldest are evicted past
+ * `maxEntries`. It is per process: instances don't share it.
+ *
+ * @example
+ * const cache = new MemoryCache({ maxEntries: 5000 });
+ */
+declare class MemoryCache implements SettingsCache {
+    #private;
+    /**
+     * @param options - The size limit.
+     * @throws `RangeError` when `maxEntries` isn't a positive integer.
+     */
+    constructor(options?: MemoryCacheOptions);
+    /** {@inheritDoc SettingsCache.get} */
+    get(key: string): Promise<string | undefined>;
+    /** {@inheritDoc SettingsCache.set} */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** {@inheritDoc SettingsCache.delete} */
+    delete(key: string): Promise<void>;
+}
+
 /**
  * A write would make an Owner's Effective settings fail its Scope's schema, so nothing was stored. `issues` are the
  * Standard Schema issues, with paths into the Effective settings, for showing next to a form field.
@@ -345,4 +527,4 @@ declare class SettingsDefinitionError extends Error {
     constructor(message: string, scope: string, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
 }
 
-export { MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };
+export { CachedStore, type CachedStoreOptions, MemoryCache, type MemoryCacheOptions, MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SealedStore, type SealedStoreOptions, type SealingVault, type SettingsCache, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };

package/dist/index.d.ts

@@ -180,6 +180,10 @@ interface SettingsOptions<Definitions extends Record<string, SettingsDefinition>
  * The keys `__proto__`, `constructor` and `prototype` can't be setting names: a write with one in its path or value
  * throws {@link SettingsValidationError} with a `"Forbidden key"` issue, and `get(path)` reads one as `undefined`.
  *
+ * Overrides are kept as JSON, so a write with a value that isn't JSON, such as a `Date`, a class instance, `NaN` or an
+ * array hole, throws {@link SettingsValidationError} with a `"Not a JSON value"` issue at its path, even where the
+ * schema accepts it.
+ *
  * @typeParam T - The Scope's settings type.
  */
 interface ScopedSettings<T> {
@@ -208,9 +212,11 @@ interface ScopedSettings<T> {
      * still stored, so a later change of the default doesn't change what the Owner chose.
      *
      * @param path - A dot path into the settings, such as `"notifications.email"`.
-     * @param value - The value to store at `path`.
-     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, or the change has
-     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue; nothing is stored.
+     * @param value - The value to store at `path`. Use {@link ScopedSettings.reset} rather than `undefined` to remove an
+     *   Override.
+     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, the change has
+     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue, or `value` is `undefined` or isn't JSON;
+     *   nothing is stored.
      * @throws {@link SettingsConflictError} If other writes to the Owner kept winning the version race for `maxRetries`
      *   retries; nothing is stored.
      */
@@ -221,19 +227,23 @@ interface ScopedSettings<T> {
      * stored as a value and passes only if the schema allows it.
      *
      * @param partial - The settings to change, at any depth, such as `{ theme: "dark", notifications: { email: false } }`.
-     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, or `partial` has
-     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue; nothing is stored.
+     * @throws {@link SettingsValidationError} If the Effective settings with the change fail the schema, `partial` has
+     *   a key the schema doesn't know, reported as an `"Unknown setting"` issue, or a value in it isn't JSON; nothing is
+     *   stored.
      * @throws {@link SettingsConflictError} If other writes to the Owner kept winning the version race for `maxRetries`
      *   retries; nothing is stored.
      */
     update(partial: DeepPartial<T>): Promise<void>;
     /**
-     * Reads the Owner's Overrides as stored, without the defaults, for example to show which values are the Owner's
-     * own choices. Overrides a read would ignore are included until the next write drops them.
+     * Reads the Owner's Overrides without the defaults, for example to show which values are the Owner's own choices.
+     * Overrides a read would ignore are left out and reported to `onInvalid`, the same as {@link ScopedSettings.get},
+     * so the two always agree; the stored document isn't changed. Unlike `get`, it doesn't throw when the Effective
+     * settings still fail after leaving those out, so a page can show the Overrides that remain and fix them.
      *
-     * @returns The stored Overrides, or `{}` when nothing is stored.
+     * @returns The Overrides a read uses, or `{}` when nothing is stored.
+     * @throws {@link SettingsDefinitionError} If the Scope's defaults fail its schema.
      */
-    getOverrides(): Promise<Record<string, unknown>>;
+    getOverrides(): Promise<DeepPartial<T>>;
     /**
      * Removes the Override at `path`, so that setting follows the default again. Resetting an object removes every
      * Override under it. With no Override at or under `path`, it writes nothing.
@@ -257,6 +267,9 @@ type OwnerIdArgs<D> = D extends SettingsDefinition<unknown, true> ? [] : [id: st
  * Creates the settings for an app's Scopes over one Store. Call `scope(name, id)` on the result to read and write
  * one Owner's settings; a single-owner Scope takes no id.
  *
+ * The Scope name is stored with every Owner's Overrides, so renaming a Scope needs a migration of its stored rows;
+ * until then its Owners read the defaults.
+ *
  * Each Scope's defaults are validated against its schema on the first operation on that Scope, and the outcome is
  * kept for the life of the returned object. If the validation itself throws, such as an async validator that can't
  * reach its service, that operation rejects with the error and the next one checks again.
@@ -301,6 +314,175 @@ declare class MemoryStore implements SettingsStore {
     delete(owner: Owner): Promise<void>;
 }
 
+/**
+ * The part of a Secret Vault `Vault` that {@link SealedStore} uses, so this package doesn't depend on Secret Vault.
+ * A `Vault` fits.
+ */
+interface SealingVault {
+    /**
+     * Seals a JSON value.
+     *
+     * @param value - The value to seal.
+     * @param context - Where the Sealed value is stored.
+     * @returns The Sealed value.
+     */
+    encryptJson(value: unknown, context: string): Promise<string>;
+    /**
+     * Opens a Sealed value made by `encryptJson`; rejects when it doesn't open.
+     *
+     * @param sealed - The Sealed value.
+     * @param context - The Context it was sealed under.
+     * @returns The Plaintext value.
+     */
+    decryptJson(sealed: string, context: string): Promise<unknown>;
+    /**
+     * Whether a stored value is a Sealed value rather than plain text still stored at a listed path. Optional: a Secret
+     * Vault `Vault` has `isSealed` only as a static method, so without it `SealedStore` treats a string starting with
+     * `vault:` as sealed.
+     *
+     * @param value - A stored value.
+     */
+    isSealed?(value: unknown): boolean;
+}
+/** Options of {@link SealedStore}. */
+interface SealedStoreOptions {
+    /** The Store that keeps the Sealed values. */
+    readonly store: SettingsStore;
+    /** Seals and opens values; a Secret Vault `Vault` fits. */
+    readonly vault: SealingVault;
+    /**
+     * Dot paths into the settings to keep sealed, such as `"smtp.password"`. A path may name an object, which is sealed
+     * whole as JSON. No path may be inside another.
+     */
+    readonly paths: readonly string[];
+}
+/**
+ * A Store that keeps the Overrides at the listed paths as Sealed values in the Store it wraps, and hands the core
+ * their Plaintext. The schema validates the Plaintext, and the app calls `set` and `get` with plain values.
+ *
+ * Every write seals again with the Vault's current secret, which finishes a Rotation for that Owner. A Sealed value
+ * that doesn't open makes the read throw: it is never ignored as a stale Override, because the next write would
+ * replace the secret with its default. A plain value at a listed path reads as it is and is sealed on the Owner's next
+ * write. Values at unlisted paths are never opened.
+ *
+ * Nest it outermost, around a {@link CachedStore}, so the cache holds only Sealed values.
+ *
+ * @example
+ * const store = new SealedStore({
+ *   store: new PrismaStore({ delegate: prisma.setting }),
+ *   vault,
+ *   paths: ["smtp.password"],
+ * });
+ */
+declare class SealedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the Vault and the sealed paths.
+     * @throws `TypeError` when a path is empty or inside another path.
+     */
+    constructor(options: SealedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/**
+ * A cache of strings with a time to live, which {@link CachedStore} keeps Overrides in. {@link MemoryCache} fits;
+ * so does a thin wrapper around Redis or Keyv.
+ */
+interface SettingsCache {
+    /**
+     * Reads an entry.
+     *
+     * @param key - The cache key.
+     * @returns The value, or `undefined` when there is none or it expired.
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Stores an entry, replacing any under the key.
+     *
+     * @param key - The cache key.
+     * @param value - The string to keep.
+     * @param ttlSeconds - Seconds until the entry expires.
+     */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Removes an entry; removing a missing one does nothing.
+     *
+     * @param key - The cache key.
+     */
+    delete(key: string): Promise<void>;
+}
+/** Options of {@link CachedStore}. */
+interface CachedStoreOptions {
+    /** The Store to read through. */
+    readonly store: SettingsStore;
+    /** Where to keep what the Store returns. */
+    readonly cache: SettingsCache;
+    /** Seconds an entry stays cached. */
+    readonly ttl: number;
+    /** Starts every cache key. Defaults to `"settings"`. */
+    readonly prefix?: string;
+    /** Called with an error a cache method threw; the Store then answers instead. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * A Store that keeps what the Store it wraps returns in a cache for `ttl` seconds, an Owner with nothing stored
+ * included. Every write, conflict and delete evicts the Owner, so a write on this instance is read back at once and a
+ * conflicting write retries against fresh Overrides. A cache that throws is reported to `onError` and the Store
+ * answers instead.
+ *
+ * With a per-process cache and several instances, another instance can read Overrides up to `ttl` seconds old. Share
+ * a cache, such as Redis, to avoid it.
+ *
+ * @example
+ * const store = new CachedStore({ store: prismaStore, cache: new MemoryCache(), ttl: 60 });
+ */
+declare class CachedStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - The Store to wrap, the cache and the TTL.
+     * @throws `RangeError` when `ttl` isn't a positive number.
+     */
+    constructor(options: CachedStoreOptions);
+    /** {@inheritDoc SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+/** Options of {@link MemoryCache}. */
+interface MemoryCacheOptions {
+    /** Most entries kept; the oldest are evicted past it. Defaults to 1000. */
+    readonly maxEntries?: number;
+}
+/**
+ * A {@link SettingsCache} in process memory. Entries expire after their TTL and the oldest are evicted past
+ * `maxEntries`. It is per process: instances don't share it.
+ *
+ * @example
+ * const cache = new MemoryCache({ maxEntries: 5000 });
+ */
+declare class MemoryCache implements SettingsCache {
+    #private;
+    /**
+     * @param options - The size limit.
+     * @throws `RangeError` when `maxEntries` isn't a positive integer.
+     */
+    constructor(options?: MemoryCacheOptions);
+    /** {@inheritDoc SettingsCache.get} */
+    get(key: string): Promise<string | undefined>;
+    /** {@inheritDoc SettingsCache.set} */
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /** {@inheritDoc SettingsCache.delete} */
+    delete(key: string): Promise<void>;
+}
+
 /**
  * A write would make an Owner's Effective settings fail its Scope's schema, so nothing was stored. `issues` are the
  * Standard Schema issues, with paths into the Effective settings, for showing next to a form field.
@@ -345,4 +527,4 @@ declare class SettingsDefinitionError extends Error {
     constructor(message: string, scope: string, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
 }
 
-export { MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };
+export { CachedStore, type CachedStoreOptions, MemoryCache, type MemoryCacheOptions, MemoryStore, Owner, type Path, type PathValue, type ScopedSettings, SealedStore, type SealedStoreOptions, type SealingVault, type SettingsCache, SettingsConflictError, type SettingsDefinition, SettingsDefinitionError, type SettingsOptions, SettingsStore, SettingsValidationError, StoredOverrides, createSettings, defineSettings };

package/dist/index.js

@@ -138,6 +138,25 @@ function forbiddenKeysIn(value, path) {
     ([key2, child]) => FORBIDDEN_KEYS.has(key2) ? [{ message: "Forbidden key", path: [...path, key2] }] : forbiddenKeysIn(child, [...path, key2])
   );
 }
+function nonJsonValues(path, value) {
+  return nonJsonValuesIn(value, path === void 0 ? [] : keysOf(path));
+}
+function nonJsonValuesIn(value, path) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return Array.from(value).flatMap(
+      (item, index) => nonJsonValuesIn(item, [...path, index])
+    );
+  }
+  if (isPlainObject(value) && Object.getOwnPropertySymbols(value).length === 0) {
+    return Object.entries(value).flatMap(
+      ([key2, child]) => child === void 0 ? [] : nonJsonValuesIn(child, [...path, key2])
+    );
+  }
+  return [{ message: "Not a JSON value", path: [...path] }];
+}
 function getAt(value, path) {
   let current = value;
   for (const key2 of keysOf(path)) {
@@ -347,16 +366,27 @@ function createSettings(options) {
         },
         async set(path, value) {
           rejectForbiddenKeys(path, value);
+          if (value === void 0) {
+            throw new SettingsValidationError([
+              {
+                message: "Not a JSON value: use reset(path) to remove an Override",
+                path: path.split(".")
+              }
+            ]);
+          }
+          rejectNonJsonValues(path, value);
           await change((overrides) => setAt(overrides, path, value));
         },
         async update(partial) {
           rejectForbiddenKeys(void 0, partial);
+          rejectNonJsonValues(void 0, partial);
           await change(
             (overrides) => mergeOverrides(overrides, withoutUndefined(partial))
           );
         },
         async getOverrides() {
-          return (await readOverrides())?.overrides ?? {};
+          const stored = await readOverrides();
+          return (await withoutStale(stored?.overrides ?? {})).overrides;
         },
         async reset(path) {
           if (path === void 0) {
@@ -391,6 +421,10 @@ function rejectForbiddenKeys(path, value) {
   const issues = forbiddenKeys(path, value);
   if (issues.length > 0) throw new SettingsValidationError(issues);
 }
+function rejectNonJsonValues(path, value) {
+  const issues = nonJsonValues(path, value);
+  if (issues.length > 0) throw new SettingsValidationError(issues);
+}
 function unknownSettings(overrides, output) {
   return unknownKeys(overrides, output).map((path) => ({
     message: "Unknown setting",
@@ -433,4 +467,187 @@ function asJson(overrides) {
   return JSON.parse(JSON.stringify(overrides));
 }
 
-export { MemoryStore, SettingsConflictError, SettingsDefinitionError, SettingsValidationError, createSettings, defineSettings };
+// src/sealed-store.ts
+function defaultIsSealed(value) {
+  return typeof value === "string" && value.startsWith("vault:");
+}
+function contextOf(owner, path) {
+  return `settings:${JSON.stringify([owner.scope, owner.id, path])}`;
+}
+var SealedStore = class {
+  #store;
+  #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.
+   */
+  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) {
+        throw new TypeError(
+          `SealedStore: path "${inner}" is inside path "${path}".`
+        );
+      }
+    }
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const stored = await this.#store.read(owner);
+    if (stored === null) return null;
+    const isSealed = this.#vault.isSealed?.bind(this.#vault) ?? defaultIsSealed;
+    let overrides = stored.overrides;
+    for (const path of this.#paths) {
+      const value = getAt(overrides, path);
+      if (!isSealed(value)) continue;
+      const plaintext = await this.#vault.decryptJson(
+        value,
+        contextOf(owner, path)
+      );
+      overrides = setAt(overrides, path, plaintext);
+    }
+    return { overrides, version: stored.version };
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    let sealed = overrides;
+    for (const path of this.#paths) {
+      if (!hasAt(sealed, path)) continue;
+      const value = getAt(sealed, path);
+      if (value === void 0) continue;
+      sealed = setAt(
+        sealed,
+        path,
+        await this.#vault.encryptJson(value, contextOf(owner, path))
+      );
+    }
+    return this.#store.write(owner, sealed, expectedVersion);
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    await this.#store.delete(owner);
+  }
+};
+
+// src/cached-store.ts
+var CachedStore = class {
+  #store;
+  #cache;
+  #ttl;
+  #prefix;
+  #onError;
+  /**
+   * @param options - The Store to wrap, the cache and the TTL.
+   * @throws `RangeError` when `ttl` isn't a positive number.
+   */
+  constructor(options) {
+    if (!(options.ttl > 0) || !Number.isFinite(options.ttl)) {
+      throw new RangeError("CachedStore: ttl must be a positive number.");
+    }
+    this.#store = options.store;
+    this.#cache = options.cache;
+    this.#ttl = options.ttl;
+    this.#prefix = options.prefix ?? "settings";
+    this.#onError = options.onError;
+  }
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const key2 = this.#key(owner);
+    try {
+      const cached = await this.#cache.get(key2);
+      if (cached !== void 0) {
+        return JSON.parse(cached);
+      }
+    } catch (error) {
+      this.#report(error);
+    }
+    const stored = await this.#store.read(owner);
+    try {
+      await this.#cache.set(key2, JSON.stringify(stored), this.#ttl);
+    } catch (error) {
+      this.#report(error);
+    }
+    return stored;
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    try {
+      return await this.#store.write(owner, overrides, expectedVersion);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    try {
+      await this.#store.delete(owner);
+    } finally {
+      await this.#evict(owner);
+    }
+  }
+  async #evict(owner) {
+    try {
+      await this.#cache.delete(this.#key(owner));
+    } catch (error) {
+      this.#report(error);
+    }
+  }
+  #key(owner) {
+    return `${this.#prefix}:${JSON.stringify([owner.scope, owner.id])}`;
+  }
+  #report(error) {
+    this.#onError?.(error);
+  }
+};
+
+// src/memory-cache.ts
+var MemoryCache = class {
+  #entries = /* @__PURE__ */ new Map();
+  #maxEntries;
+  /**
+   * @param options - The size limit.
+   * @throws `RangeError` when `maxEntries` isn't a positive integer.
+   */
+  constructor(options = {}) {
+    const { maxEntries = 1e3 } = options;
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw new RangeError(
+        "MemoryCache: maxEntries must be a positive integer."
+      );
+    }
+    this.#maxEntries = maxEntries;
+  }
+  /** {@inheritDoc SettingsCache.get} */
+  async get(key2) {
+    const entry = this.#entries.get(key2);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key2);
+      return void 0;
+    }
+    return entry.value;
+  }
+  /** {@inheritDoc SettingsCache.set} */
+  async set(key2, value, ttlSeconds) {
+    this.#entries.delete(key2);
+    this.#entries.set(key2, {
+      value,
+      expiresAt: Date.now() + ttlSeconds * 1e3
+    });
+    while (this.#entries.size > this.#maxEntries) {
+      const oldest = this.#entries.keys().next().value;
+      this.#entries.delete(oldest);
+    }
+  }
+  /** {@inheritDoc SettingsCache.delete} */
+  async delete(key2) {
+    this.#entries.delete(key2);
+  }
+};
+
+export { CachedStore, MemoryCache, MemoryStore, SealedStore, SettingsConflictError, SettingsDefinitionError, SettingsValidationError, createSettings, defineSettings };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rezwanul7/settings",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -45,6 +45,7 @@
   },
   "devDependencies": {
     "@repo/eslint-config": "0.0.0",
+    "@rezwanul7/secret-vault": "0.1.0",
     "@repo/typescript-config": "0.0.0",
     "@types/node": "^22.15.3",
     "@vitest/coverage-v8": "4.0.18",