@rezwanul7/settings 1.0.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,63 +324,155 @@ 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
 
-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 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).
 
 ```ts
 import {
   createSettings,
   defineSettings,
-  type Owner,
+  SealedStore,
 } from "@rezwanul7/settings";
 import { PrismaStore } from "@rezwanul7/settings/prisma";
 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(),
-      // 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 } },
 });
 
+const definitions = { organization: organizationDefinition };
+
 const settings = createSettings({
-  definitions: { organization },
-  store: new PrismaStore({ delegate: prisma.setting }),
+  definitions,
+  store: new SealedStore({
+    store: new PrismaStore({ delegate: prisma.setting }),
+    vault,
+    definitions,
+    paths: { organization: ["smtp.password"] },
+  }),
 });
 
-function smtpPasswordContext(owner: Owner): string {
-  return `settings:smtp.password:${owner.scope}:${owner.id}`;
-}
+await settings
+  .scope("organization", organizationId)
+  .set("smtp.password", "hunter2");
+const password = await settings
+  .scope("organization", organizationId)
+  .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.
+- 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. 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
+  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.
+
+### 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.
 
-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
+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 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";
+
+const store = new SealedStore({
+  store: new CachedStore({
+    store: new PrismaStore({ delegate: prisma.setting }),
+    cache: new MemoryCache({ maxEntries: 5000 }),
+    ttl: 60,
+  }),
+  vault,
+  definitions,
+  paths: { organization: ["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. `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 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";
+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
 
@@ -370,8 +484,8 @@ secret; open it on the server, only where it is used.
   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";