@rezwanul7/settings 1.1.0 → 2.0.0

package/dist/index.js

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

package/dist/prisma.cjs

@@ -26,7 +26,7 @@ var PrismaStore = class {
     if (expectedVersion === null) {
       try {
         const row = await this.#delegate.create({
-          data: { ...key(owner), overrides: json }
+          data: { ...key(owner), overrides: json, version: startingVersion() }
         });
         return row.version;
       } catch (error) {
@@ -45,6 +45,9 @@ var PrismaStore = class {
     await this.#delegate.deleteMany({ where: key(owner) });
   }
 };
+function startingVersion() {
+  return Math.floor(Math.random() * (2 ** 30 - 1)) + 1;
+}
 function key(owner) {
   return { scope: owner.scope, ownerId: owner.id };
 }

package/dist/prisma.d.cts

@@ -53,7 +53,7 @@ interface PrismaSettingsDelegate {
     /**
      * Creates a row, rejecting with an error whose `code` is `P2002` when one exists for the key.
      *
-     * @param args - The new row's key and Overrides; its version comes from the column default.
+     * @param args - The new row's key, Overrides and starting version.
      * @returns The created row.
      */
     create(args: {
@@ -63,9 +63,10 @@ interface PrismaSettingsDelegate {
             overrides: {
                 readonly [key: string]: JsonInput;
             };
+            version: number;
         };
     }): PromiseLike<{
-        /** The `version` column, set by its default. */
+        /** The `version` column, as created. */
         version: number;
     }>;
     /**
@@ -113,19 +114,18 @@ interface PrismaSettingsDelegate {
  * An update only matches the row at the version the caller read, and a create that finds the row already there is a
  * conflict, so the retries of the settings created by `createSettings` work against a real database.
  *
- * Known limitation: `delete` removes the row, and a row created after it starts again at the column default of `1`,
- * so versions can repeat across a delete. A write that read version `n` of the old row before `reset()`, and stores
- * after other writes have recreated the row and brought it back to version `n`, overwrites the new row: the Overrides
- * written since the reset are lost and the old ones, with that write's change, come back. It takes a `reset()` and
- * another write to the same Owner both landing while that write is running. Avoiding it would need the version to
- * outlive the row, which the model doesn't keep, so call `reset()` when no other write to the Owner is expected, such
- * as when deleting the Owner.
+ * Known limitation: `delete` removes the row, and the model keeps no version once the row is gone. A row created
+ * after it starts at a random version in `[1, 2^30)` rather than the column default, so a write that read the old row
+ * before `reset()` is very unlikely, though not impossible, to match the new row's version. If it does match, it
+ * overwrites the new row: the Overrides written since the reset are lost and the old ones, with that write's change,
+ * come back. It takes a `reset()` and another write to the same Owner both landing while that write is running, so
+ * call `reset()` when no other write to the Owner is expected, such as when deleting the Owner.
  *
  * @example
  * import { PrismaStore } from "@rezwanul7/settings/prisma";
  *
  * const settings = createSettings({
- *   definitions: { user },
+ *   definitions: { user: userDefinition },
  *   store: new PrismaStore({ delegate: prisma.setting }),
  * });
  */

package/dist/prisma.d.ts

@@ -53,7 +53,7 @@ interface PrismaSettingsDelegate {
     /**
      * Creates a row, rejecting with an error whose `code` is `P2002` when one exists for the key.
      *
-     * @param args - The new row's key and Overrides; its version comes from the column default.
+     * @param args - The new row's key, Overrides and starting version.
      * @returns The created row.
      */
     create(args: {
@@ -63,9 +63,10 @@ interface PrismaSettingsDelegate {
             overrides: {
                 readonly [key: string]: JsonInput;
             };
+            version: number;
         };
     }): PromiseLike<{
-        /** The `version` column, set by its default. */
+        /** The `version` column, as created. */
         version: number;
     }>;
     /**
@@ -113,19 +114,18 @@ interface PrismaSettingsDelegate {
  * An update only matches the row at the version the caller read, and a create that finds the row already there is a
  * conflict, so the retries of the settings created by `createSettings` work against a real database.
  *
- * Known limitation: `delete` removes the row, and a row created after it starts again at the column default of `1`,
- * so versions can repeat across a delete. A write that read version `n` of the old row before `reset()`, and stores
- * after other writes have recreated the row and brought it back to version `n`, overwrites the new row: the Overrides
- * written since the reset are lost and the old ones, with that write's change, come back. It takes a `reset()` and
- * another write to the same Owner both landing while that write is running. Avoiding it would need the version to
- * outlive the row, which the model doesn't keep, so call `reset()` when no other write to the Owner is expected, such
- * as when deleting the Owner.
+ * Known limitation: `delete` removes the row, and the model keeps no version once the row is gone. A row created
+ * after it starts at a random version in `[1, 2^30)` rather than the column default, so a write that read the old row
+ * before `reset()` is very unlikely, though not impossible, to match the new row's version. If it does match, it
+ * overwrites the new row: the Overrides written since the reset are lost and the old ones, with that write's change,
+ * come back. It takes a `reset()` and another write to the same Owner both landing while that write is running, so
+ * call `reset()` when no other write to the Owner is expected, such as when deleting the Owner.
  *
  * @example
  * import { PrismaStore } from "@rezwanul7/settings/prisma";
  *
  * const settings = createSettings({
- *   definitions: { user },
+ *   definitions: { user: userDefinition },
  *   store: new PrismaStore({ delegate: prisma.setting }),
  * });
  */

package/dist/prisma.js

@@ -24,7 +24,7 @@ var PrismaStore = class {
     if (expectedVersion === null) {
       try {
         const row = await this.#delegate.create({
-          data: { ...key(owner), overrides: json }
+          data: { ...key(owner), overrides: json, version: startingVersion() }
         });
         return row.version;
       } catch (error) {
@@ -43,6 +43,9 @@ var PrismaStore = class {
     await this.#delegate.deleteMany({ where: key(owner) });
   }
 };
+function startingVersion() {
+  return Math.floor(Math.random() * (2 ** 30 - 1)) + 1;
+}
 function key(owner) {
   return { scope: owner.scope, ownerId: owner.id };
 }

package/package.json

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