@rezwanul7/settings 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,443 @@
+'use strict';
+
+// src/definition.ts
+function defineSettings(definition) {
+  return {
+    schema: definition.schema,
+    defaults: definition.defaults,
+    singleOwner: definition.singleOwner ?? false
+  };
+}
+
+// src/errors.ts
+var SettingsValidationError = class extends Error {
+  /** The Standard Schema issues the Effective settings failed with. */
+  issues;
+  /**
+   * @param issues - The Standard Schema issues.
+   */
+  constructor(issues) {
+    super(`The settings are invalid: ${issues.map(describeIssue).join("; ")}`);
+    this.name = "SettingsValidationError";
+    this.issues = issues;
+  }
+};
+var SettingsConflictError = class extends Error {
+  /** The Owner whose Overrides couldn't be written. */
+  owner;
+  /**
+   * @param owner - The Owner whose Overrides couldn't be written.
+   * @param retries - How many times the write re-read and applied its change again.
+   */
+  constructor(owner, retries) {
+    super(
+      `Writing the Overrides of ${describeOwner(owner)} conflicted with other writes ${retries + 1} times in a row.`
+    );
+    this.name = "SettingsConflictError";
+    this.owner = owner;
+  }
+};
+var SettingsDefinitionError = class extends Error {
+  /** The Scope name the error is about. */
+  scope;
+  /** The Standard Schema issues, when the error is a failed validation. */
+  issues;
+  /**
+   * @param message - The error message.
+   * @param scope - The Scope name.
+   * @param issues - The Standard Schema issues, if any.
+   */
+  constructor(message, scope, issues = []) {
+    super(message);
+    this.name = "SettingsDefinitionError";
+    this.scope = scope;
+    this.issues = issues;
+  }
+};
+function describeOwner(owner) {
+  return `${owner.scope} "${owner.id}"`;
+}
+function issuePath(issue) {
+  return (issue.path ?? []).map(
+    (segment) => String(typeof segment === "object" ? segment.key : segment)
+  );
+}
+function describeIssue(issue) {
+  const path = issuePath(issue).join(".");
+  return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+
+// src/merge.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function ownValue(object, key2) {
+  return Object.hasOwn(object, key2) ? object[key2] : void 0;
+}
+function setOwn(object, key2, value) {
+  Object.defineProperty(object, key2, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  });
+}
+function withoutUndefined(partial) {
+  if (!isPlainObject(partial)) return partial;
+  const result = {};
+  for (const [key2, value] of Object.entries(partial)) {
+    if (value === void 0) continue;
+    const kept = withoutUndefined(value);
+    if (isPlainObject(value) && Object.keys(value).length > 0 && Object.keys(kept).length === 0) {
+      continue;
+    }
+    setOwn(result, key2, kept);
+  }
+  return result;
+}
+function mergeOverrides(defaults, overrides) {
+  if (overrides === void 0) return structuredClone(defaults);
+  if (!isPlainObject(overrides)) return structuredClone(overrides);
+  const base = isPlainObject(defaults) ? defaults : {};
+  const merged = {};
+  for (const [key2, value] of Object.entries(base)) {
+    setOwn(merged, key2, mergeOverrides(value, ownValue(overrides, key2)));
+  }
+  for (const [key2, value] of Object.entries(overrides)) {
+    if (value === void 0 || Object.hasOwn(base, key2)) continue;
+    setOwn(merged, key2, mergeOverrides(void 0, value));
+  }
+  return merged;
+}
+
+// src/overrides.ts
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+function keysOf(path) {
+  return path.split(".");
+}
+function forbiddenKeys(path, value) {
+  const keys = path === void 0 ? [] : keysOf(path);
+  const forbidden = keys.findIndex((key2) => FORBIDDEN_KEYS.has(key2));
+  if (forbidden !== -1) {
+    return [{ message: "Forbidden key", path: keys.slice(0, forbidden + 1) }];
+  }
+  return forbiddenKeysIn(value, keys);
+}
+function forbiddenKeysIn(value, path) {
+  if (Array.isArray(value)) {
+    return value.flatMap(
+      (item, index) => forbiddenKeysIn(item, [...path, index])
+    );
+  }
+  if (!isPlainObject(value)) return [];
+  return Object.entries(value).flatMap(
+    ([key2, child]) => FORBIDDEN_KEYS.has(key2) ? [{ message: "Forbidden key", path: [...path, key2] }] : forbiddenKeysIn(child, [...path, key2])
+  );
+}
+function getAt(value, path) {
+  let current = value;
+  for (const key2 of keysOf(path)) {
+    if (!isPlainObject(current)) return void 0;
+    current = ownValue(current, key2);
+  }
+  return current;
+}
+function hasAt(overrides, path) {
+  let current = overrides;
+  for (const key2 of keysOf(path)) {
+    if (!isPlainObject(current) || !Object.hasOwn(current, key2)) return false;
+    current = current[key2];
+  }
+  return true;
+}
+function setAt(overrides, path, value) {
+  const result = structuredClone(overrides);
+  const keys = keysOf(path);
+  const last = keys.pop();
+  let parent = result;
+  for (const key2 of keys) {
+    const child = ownValue(parent, key2);
+    if (isPlainObject(child)) {
+      parent = child;
+    } else {
+      const created = {};
+      setOwn(parent, key2, created);
+      parent = created;
+    }
+  }
+  setOwn(parent, last, structuredClone(value));
+  return result;
+}
+function removeAt(overrides, path) {
+  return removeKeys(overrides, keysOf(path));
+}
+function removeKeys(overrides, path) {
+  if (path.length === 0) return {};
+  const result = structuredClone(overrides);
+  const keys = [...path];
+  const last = keys.pop();
+  const parents = [result];
+  for (const key2 of keys) {
+    const child = ownValue(parents[parents.length - 1] ?? {}, key2);
+    if (!isPlainObject(child)) return result;
+    parents.push(child);
+  }
+  delete parents[parents.length - 1]?.[last];
+  for (let depth = keys.length - 1; depth >= 0; depth--) {
+    const parent = parents[depth];
+    const key2 = keys[depth];
+    if (Object.keys(parent[key2]).length > 0) break;
+    delete parent[key2];
+  }
+  return result;
+}
+function withoutIssues(overrides, issues) {
+  let result = overrides;
+  for (const path of issues.flatMap(pathsOfIssue)) {
+    const covering = coveringOverride(result, path);
+    if (covering !== void 0) result = removeKeys(result, covering);
+  }
+  return result;
+}
+function pathsOfIssue(issue) {
+  const path = issuePath(issue);
+  const { keys } = issue;
+  if (Array.isArray(keys) && keys.every((key2) => typeof key2 === "string")) {
+    return keys.map((key2) => [...path, key2]);
+  }
+  return [path];
+}
+function unknownKeys(overrides, output, path = []) {
+  if (!isPlainObject(output)) return [];
+  return Object.entries(overrides).flatMap(([key2, value]) => {
+    if (!Object.hasOwn(output, key2)) return [[...path, key2]];
+    return isPlainObject(value) ? unknownKeys(value, output[key2], [...path, key2]) : [];
+  });
+}
+function coveringOverride(overrides, keys) {
+  let current = overrides;
+  for (const [depth, key2] of keys.entries()) {
+    if (!isPlainObject(current)) return keys.slice(0, depth);
+    if (!Object.hasOwn(current, key2)) return void 0;
+    current = current[key2];
+  }
+  return [...keys];
+}
+
+// src/settings.ts
+var SINGLE_OWNER_ID = "default";
+function createSettings(options) {
+  const { definitions, store, onInvalid, maxRetries = 3 } = options;
+  if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+    throw new RangeError(
+      `maxRetries must be a whole number, 0 or more; got ${maxRetries}.`
+    );
+  }
+  const checkedDefaults = /* @__PURE__ */ new Map();
+  function checkDefaults(name, definition) {
+    let check = checkedDefaults.get(name);
+    if (check === void 0) {
+      check = validate(definition.schema, definition.defaults).then(
+        (result) => {
+          if (result.issues === void 0) return;
+          throw new SettingsDefinitionError(
+            `The defaults of Scope "${name}" fail its schema: ${result.issues.map(describeIssue).join("; ")}`,
+            name,
+            result.issues
+          );
+        }
+      );
+      checkedDefaults.set(name, check);
+      const pending = check;
+      pending.catch((error) => {
+        if (!(error instanceof SettingsDefinitionError) && checkedDefaults.get(name) === pending) {
+          checkedDefaults.delete(name);
+        }
+      });
+    }
+    return check;
+  }
+  return {
+    scope(name, ...[id]) {
+      if (!Object.hasOwn(definitions, name)) {
+        throw new SettingsDefinitionError(`Unknown Scope "${name}".`, name);
+      }
+      const definition = definitions[name];
+      const owner = ownerOf(name, definition, id);
+      async function readOverrides() {
+        await checkDefaults(name, definition);
+        return store.read(owner);
+      }
+      async function withoutStale(overrides) {
+        let kept = overrides;
+        const ignored = [];
+        let result = await validate(
+          definition.schema,
+          mergeOverrides(definition.defaults, kept)
+        );
+        while (result.issues !== void 0) {
+          const next = withoutIssues(kept, result.issues);
+          if (next === kept) break;
+          ignored.push(...result.issues);
+          kept = next;
+          result = await validate(
+            definition.schema,
+            mergeOverrides(definition.defaults, kept)
+          );
+        }
+        if (result.issues === void 0) {
+          const unknown = unknownSettings(kept, result.value);
+          if (unknown.length > 0) {
+            ignored.push(...unknown);
+            kept = withoutIssues(kept, unknown);
+          }
+        }
+        if (ignored.length > 0) onInvalid?.(owner, ignored);
+        return { overrides: kept, result };
+      }
+      async function effective() {
+        const stored = await readOverrides();
+        const { result } = await withoutStale(stored?.overrides ?? {});
+        if (result.issues !== void 0) {
+          throw new SettingsDefinitionError(
+            `The Effective settings of ${describeOwner(owner)} fail the Scope's schema: ${result.issues.map(describeIssue).join("; ")}`,
+            name,
+            result.issues
+          );
+        }
+        return result.value;
+      }
+      async function change(apply, {
+        onlyIf
+      } = {}) {
+        for (let retries = 0; ; retries++) {
+          const stored = await readOverrides();
+          if (onlyIf !== void 0 && !onlyIf(stored?.overrides ?? {})) return;
+          const usable = (await withoutStale(stored?.overrides ?? {})).overrides;
+          const next = apply(usable);
+          const result = await validate(
+            definition.schema,
+            mergeOverrides(definition.defaults, next)
+          );
+          if (result.issues !== void 0) {
+            throw new SettingsValidationError(result.issues);
+          }
+          const unknown = unknownSettings(next, result.value);
+          if (unknown.length > 0) throw new SettingsValidationError(unknown);
+          const version = await store.write(
+            owner,
+            next,
+            stored?.version ?? null
+          );
+          if (version !== null) return;
+          if (retries >= maxRetries) {
+            throw new SettingsConflictError(owner, retries);
+          }
+        }
+      }
+      return {
+        owner,
+        async get(path) {
+          const settings = await effective();
+          return path === void 0 ? settings : getAt(settings, path);
+        },
+        async set(path, value) {
+          rejectForbiddenKeys(path, value);
+          await change((overrides) => setAt(overrides, path, value));
+        },
+        async update(partial) {
+          rejectForbiddenKeys(void 0, partial);
+          await change(
+            (overrides) => mergeOverrides(overrides, withoutUndefined(partial))
+          );
+        },
+        async getOverrides() {
+          return (await readOverrides())?.overrides ?? {};
+        },
+        async reset(path) {
+          if (path === void 0) {
+            await checkDefaults(name, definition);
+            await store.delete(owner);
+            return;
+          }
+          rejectForbiddenKeys(path, void 0);
+          await change((overrides) => removeAt(overrides, path), {
+            onlyIf: (stored) => hasAt(stored, path)
+          });
+        }
+      };
+    }
+  };
+}
+function ownerOf(scope, definition, id) {
+  if (definition.singleOwner) {
+    if (id !== void 0) {
+      throw new TypeError(
+        `Scope "${scope}" has a single Owner and takes no id.`
+      );
+    }
+    return { scope, id: SINGLE_OWNER_ID };
+  }
+  if (typeof id !== "string") {
+    throw new TypeError(`Scope "${scope}" needs an Owner id.`);
+  }
+  return { scope, id };
+}
+function rejectForbiddenKeys(path, value) {
+  const issues = forbiddenKeys(path, value);
+  if (issues.length > 0) throw new SettingsValidationError(issues);
+}
+function unknownSettings(overrides, output) {
+  return unknownKeys(overrides, output).map((path) => ({
+    message: "Unknown setting",
+    path
+  }));
+}
+async function validate(schema, value) {
+  return schema["~standard"].validate(value);
+}
+
+// src/memory-store.ts
+var MemoryStore = class {
+  #documents = /* @__PURE__ */ new Map();
+  // The last version each Owner had, kept across deletes so a recreated document never reuses a version.
+  #lastVersions = /* @__PURE__ */ new Map();
+  /** {@inheritDoc SettingsStore.read} */
+  async read(owner) {
+    const stored = this.#documents.get(key(owner));
+    return stored === void 0 ? null : structuredClone(stored);
+  }
+  /** {@inheritDoc SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    const ownerKey = key(owner);
+    const currentVersion = this.#documents.get(ownerKey)?.version ?? null;
+    if (currentVersion !== expectedVersion) return null;
+    const version = (this.#lastVersions.get(ownerKey) ?? 0) + 1;
+    this.#documents.set(ownerKey, { overrides: asJson(overrides), version });
+    this.#lastVersions.set(ownerKey, version);
+    return version;
+  }
+  /** {@inheritDoc SettingsStore.delete} */
+  async delete(owner) {
+    this.#documents.delete(key(owner));
+  }
+};
+function key(owner) {
+  return JSON.stringify([owner.scope, owner.id]);
+}
+function asJson(overrides) {
+  return JSON.parse(JSON.stringify(overrides));
+}
+
+exports.MemoryStore = MemoryStore;
+exports.SettingsConflictError = SettingsConflictError;
+exports.SettingsDefinitionError = SettingsDefinitionError;
+exports.SettingsValidationError = SettingsValidationError;
+exports.createSettings = createSettings;
+exports.defineSettings = defineSettings;