@rezwanul7/settings 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,436 @@
+// 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));
+}
+
+export { MemoryStore, SettingsConflictError, SettingsDefinitionError, SettingsValidationError, createSettings, defineSettings };

package/dist/prisma.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+// src/prisma.ts
+var PrismaStore = class {
+  #delegate;
+  /**
+   * @param options - Takes `delegate`: the app's Prisma model delegate, such as `prisma.setting`.
+   */
+  constructor(options) {
+    this.#delegate = options.delegate;
+  }
+  /** {@inheritDoc @rezwanul7/settings!SettingsStore.read} */
+  async read(owner) {
+    const row = await this.#delegate.findUnique({
+      where: { scope_ownerId: key(owner) }
+    });
+    if (row === null) return null;
+    return {
+      overrides: row.overrides,
+      version: row.version
+    };
+  }
+  /** {@inheritDoc @rezwanul7/settings!SettingsStore.write} */
+  async write(owner, overrides, expectedVersion) {
+    const json = overrides;
+    if (expectedVersion === null) {
+      try {
+        const row = await this.#delegate.create({
+          data: { ...key(owner), overrides: json }
+        });
+        return row.version;
+      } catch (error) {
+        if (isUniqueConstraintError(error)) return null;
+        throw error;
+      }
+    }
+    const { count } = await this.#delegate.updateMany({
+      where: { ...key(owner), version: expectedVersion },
+      data: { overrides: json, version: { increment: 1 } }
+    });
+    return count === 0 ? null : expectedVersion + 1;
+  }
+  /** {@inheritDoc @rezwanul7/settings!SettingsStore.delete} */
+  async delete(owner) {
+    await this.#delegate.deleteMany({ where: key(owner) });
+  }
+};
+function key(owner) {
+  return { scope: owner.scope, ownerId: owner.id };
+}
+function isUniqueConstraintError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "P2002";
+}
+
+exports.PrismaStore = PrismaStore;

package/dist/prisma.d.cts

@@ -0,0 +1,148 @@
+import { S as SettingsStore, O as Owner, a as StoredOverrides } from './store-B4pWek75.cjs';
+
+/**
+ * @rezwanul7/settings/prisma: a Store over the app's own Prisma model delegate, such as `prisma.setting`. The package
+ * doesn't depend on `@prisma/client`; {@link PrismaSettingsDelegate} describes the methods the Store calls, and the
+ * delegate Prisma generates for the model below fits it.
+ *
+ * ```prisma
+ * model Setting {
+ *   scope     String
+ *   ownerId   String
+ *   overrides Json
+ *   version   Int      @default(1)
+ *   createdAt DateTime @default(now())
+ *   updatedAt DateTime @updatedAt
+ *
+ *   @@id([scope, ownerId])
+ *   @@map("settings")
+ * }
+ * ```
+ *
+ * @module prisma
+ */
+
+/** A JSON value as Prisma accepts it for a `Json` field. */
+type JsonInput = string | number | boolean | null | {
+    readonly [key: string]: JsonInput;
+} | readonly JsonInput[];
+/**
+ * The methods of a Prisma model delegate that {@link PrismaStore} calls, typed by their shape so the package needn't
+ * depend on `@prisma/client`. Pass the delegate Prisma generates for the Setting model, such as `prisma.setting`.
+ */
+interface PrismaSettingsDelegate {
+    /**
+     * Reads one row by the `scope_ownerId` compound key.
+     *
+     * @param args - The compound key to find.
+     * @returns The row, or `null` when there is none.
+     */
+    findUnique(args: {
+        where: {
+            scope_ownerId: {
+                scope: string;
+                ownerId: string;
+            };
+        };
+    }): PromiseLike<{
+        /** The `overrides` column. */
+        overrides: unknown;
+        /** The `version` column. */
+        version: number;
+    } | null>;
+    /**
+     * 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.
+     * @returns The created row.
+     */
+    create(args: {
+        data: {
+            scope: string;
+            ownerId: string;
+            overrides: {
+                readonly [key: string]: JsonInput;
+            };
+        };
+    }): PromiseLike<{
+        /** The `version` column, set by its default. */
+        version: number;
+    }>;
+    /**
+     * Updates the rows matching a filter.
+     *
+     * @param args - The row's key and the version it must be at, and the new Overrides with the version increment.
+     * @returns How many rows were updated.
+     */
+    updateMany(args: {
+        where: {
+            scope: string;
+            ownerId: string;
+            version: number;
+        };
+        data: {
+            overrides: {
+                readonly [key: string]: JsonInput;
+            };
+            version: {
+                increment: number;
+            };
+        };
+    }): PromiseLike<{
+        /** How many rows matched. */
+        count: number;
+    }>;
+    /**
+     * Deletes the rows matching a filter; matching none is not an error.
+     *
+     * @param args - The row's key.
+     * @returns How many rows were deleted.
+     */
+    deleteMany(args: {
+        where: {
+            scope: string;
+            ownerId: string;
+        };
+    }): PromiseLike<{
+        /** How many rows matched. */
+        count: number;
+    }>;
+}
+/**
+ * A Store that keeps each Owner's Overrides as one row of the app's Prisma model, guarded by its `version` column.
+ * 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.
+ *
+ * @example
+ * import { PrismaStore } from "@rezwanul7/settings/prisma";
+ *
+ * const settings = createSettings({
+ *   definitions: { user },
+ *   store: new PrismaStore({ delegate: prisma.setting }),
+ * });
+ */
+declare class PrismaStore implements SettingsStore {
+    #private;
+    /**
+     * @param options - Takes `delegate`: the app's Prisma model delegate, such as `prisma.setting`.
+     */
+    constructor(options: {
+        delegate: PrismaSettingsDelegate;
+    });
+    /** {@inheritDoc @rezwanul7/settings!SettingsStore.read} */
+    read(owner: Owner): Promise<StoredOverrides | null>;
+    /** {@inheritDoc @rezwanul7/settings!SettingsStore.write} */
+    write(owner: Owner, overrides: Record<string, unknown>, expectedVersion: number | null): Promise<number | null>;
+    /** {@inheritDoc @rezwanul7/settings!SettingsStore.delete} */
+    delete(owner: Owner): Promise<void>;
+}
+
+export { type PrismaSettingsDelegate, PrismaStore };