@rezwanul7/settings 1.0.0 → 2.0.0

package/dist/index.cjs

@@ -249,10 +249,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}.`
@@ -417,6 +446,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) {
@@ -469,7 +501,306 @@ function asJson(overrides) {
   return JSON.parse(JSON.stringify(overrides));
 }
 
+// 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);
+  }
+};
+
+exports.CachedStore = CachedStore;
+exports.MemoryCache = MemoryCache;
 exports.MemoryStore = MemoryStore;
+exports.SealedStore = SealedStore;
 exports.SettingsConflictError = SettingsConflictError;
 exports.SettingsDefinitionError = SettingsDefinitionError;
 exports.SettingsValidationError = SettingsValidationError;