@rezwanul7/settings 1.0.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) {
@@ -467,4 +499,300 @@ function asJson(overrides) {
   return JSON.parse(JSON.stringify(overrides));
 }
 
-export { MemoryStore, SettingsConflictError, SettingsDefinitionError, SettingsValidationError, createSettings, defineSettings };
+// src/sealed-store.ts
+var DISCARD_RETRIES = 3;
+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, 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;
+    const paths = /* @__PURE__ */ new Map();
+    for (const [scope, list] of Object.entries(
+      options.paths
+    )) {
+      if (!Object.hasOwn(options.definitions, scope)) {
+        throw new TypeError(
+          `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) {
+    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.#pathsOf(owner)) {
+      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) {
+    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.#pathsOf(owner)) {
+      if (!hasAt(sealed, path)) continue;
+      const value = getAt(sealed, path);
+      if (value === void 0 || skip(value)) continue;
+      sealed = setAt(
+        sealed,
+        path,
+        await this.#vault.encryptJson(value, contextOf(owner, path))
+      );
+    }
+    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) {
+    await this.#store.delete(owner);
+  }
+};
+
+// src/cached-store.ts
+var CachedStore = class {
+  #store;
+  #cache;
+  #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.
+   */
+  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 = 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) {
+    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);
+    }
+    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 {
+      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);
+    }
+  }
+  /** {@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) {
+    const key2 = this.#key(owner);
+    const reading = this.#inFlight.get(key2);
+    if (reading !== void 0) reading.evictions++;
+    try {
+      await this.#cache.delete(key2);
+    } 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/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.0.0",
+  "version": "2.0.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",