@rezwanul7/settings 0.1.0 → 1.0.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.
@@ -380,6 +386,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",

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.

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.

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rezwanul7/settings",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",