@johnhenry/graceholder 0.0.0-stage → 0.0.0

package/src/detmath.js

@@ -0,0 +1,74 @@
+// Deterministic elementary functions built only from + - * / and exact scaling by 2.
+// IEEE-754 basic operations are correctly rounded on every engine, whereas Math.exp, Math.log,
+// Math.pow, Math.sin and Math.cos may differ in the last bit between engines. Output that
+// depends on these functions must be byte-identical everywhere (docs/design.md section 11), so
+// distribution sampling uses these instead. Accuracy is far better than the 2-4 decimals that
+// are ever emitted; determinism, not libm accuracy, is the point.
+
+const LN2 = 0.6931471805599453;
+const TWO_PI = 6.283185307179586;
+
+/** Natural logarithm of x > 0. */
+export function ln(x) {
+  if (!(x > 0)) throw new RangeError(`ln(${x}): need x > 0`);
+  let e = 0;
+  while (x >= 2) { x /= 2; e++; }
+  while (x < 1) { x *= 2; e--; }
+  if (x > 1.4142135623730951) { x /= 2; e++; }
+  const z = (x - 1) / (x + 1);
+  const z2 = z * z;
+  let term = z;
+  let sum = 0;
+  for (let k = 1; k <= 41; k += 2) {
+    sum += term / k;
+    term *= z2;
+  }
+  return 2 * sum + e * LN2;
+}
+
+/** e^x for |x| below about 700. */
+export function exp(x) {
+  const k = Math.round(x / LN2);
+  const r = x - k * LN2;
+  let term = 1;
+  let sum = 1;
+  for (let n = 1; n <= 24; n++) {
+    term = (term * r) / n;
+    sum += term;
+  }
+  const base = k < 0 ? 0.5 : 2;
+  let p = 1;
+  for (let i = Math.abs(k); i > 0; i--) p *= base;
+  return sum * p;
+}
+
+/** x^y for x > 0. */
+export const pow = (x, y) => exp(y * ln(x));
+
+const reduce = (x) => x - Math.round(x / TWO_PI) * TWO_PI;
+
+export function sin(x) {
+  const r = reduce(x);
+  const r2 = r * r;
+  let term = r;
+  let sum = r;
+  for (let n = 1; n <= 15; n++) {
+    term = (-term * r2) / ((2 * n) * (2 * n + 1));
+    sum += term;
+  }
+  return sum;
+}
+
+export function cos(x) {
+  const r = reduce(x);
+  const r2 = r * r;
+  let term = 1;
+  let sum = 1;
+  for (let n = 1; n <= 15; n++) {
+    term = (-term * r2) / ((2 * n - 1) * (2 * n));
+    sum += term;
+  }
+  return sum;
+}
+
+export { TWO_PI };

package/src/directives.js

@@ -0,0 +1,113 @@
+// Inline directives (docs/design.md 5.1): parsed into the same override properties as the
+// side-car spec, then stripped from the document before validation and execution.
+import { valueFromASTUntyped, Kind, visit } from "graphql";
+import { GraceholderError } from "./errors.js";
+import { normalizeCount, checkPick } from "./spec.js";
+
+export const BUILTIN_DIRECTIVES = new Set(["skip", "include"]);
+export const DIRECTIVES = ["list", "one", "count", "gen", "pattern", "pick", "nullRate", "derive", "type", "seed"];
+
+const lev = (a, b) => {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+};
+
+export const nearest = (name, names) => [...names].sort((x, y) => lev(name, x) - lev(name, y))[0];
+
+function unknownDirective(name) {
+  const near = nearest(name, DIRECTIVES);
+  return new GraceholderError("unknown-directive", `unknown directive @${name}`, {
+    hint: `did you mean @${near}? Known: ${DIRECTIVES.map((d) => `@${d}`).join(", ")}, @skip, @include`,
+  });
+}
+
+/** Throw for any directive that is neither built in nor ours, and for graceholder directives outside fields. */
+export function checkDirectives(roots) {
+  for (const root of roots) {
+    visit(root, {
+      Directive(node, _key, _parent, _path, /** @type {any} */ ancestors) {
+        const name = node.name.value;
+        if (BUILTIN_DIRECTIVES.has(name)) return;
+        if (!DIRECTIVES.includes(name)) throw unknownDirective(name);
+        const owner = ancestors[ancestors.length - 1];
+        const holder = Array.isArray(owner) ? ancestors[ancestors.length - 2] : owner;
+        const ok = holder?.kind === Kind.FIELD || (holder?.kind === Kind.OPERATION_DEFINITION && name === "seed");
+        if (!ok) {
+          throw new GraceholderError("unknown-directive", `@${name} is not allowed here`, { hint: name === "seed" ? "@seed goes on a field or the operation" : `@${name} goes on a field` });
+        }
+      },
+    });
+  }
+}
+
+/** Remove graceholder directives (keeps @skip and @include). */
+export function stripDirectives(node) {
+  return visit(node, {
+    Directive(d) {
+      return BUILTIN_DIRECTIVES.has(d.name.value) ? undefined : null;
+    },
+  });
+}
+
+/**
+ * @param {readonly import("graphql").DirectiveNode[]} directives
+ * @param {Record<string, unknown>} variables
+ * @param {string} path
+ * @returns {Record<string, any>} override properties (same shape as a compiled spec entry)
+ */
+export function directiveProps(directives, variables, path) {
+  const props = {};
+  const fail = (code, name, msg) => new GraceholderError(code, `@${name}: ${msg}`, { path });
+  const badDir = (name) => (msg) => fail("bad-directive", name, msg);
+  const set = (prop, value, name) => {
+    if (props[prop] !== undefined && JSON.stringify(props[prop]) !== JSON.stringify(value)) {
+      throw fail("conflicting-overrides", name, `conflicts with another directive on the same field (${prop})`);
+    }
+    if (props[prop] !== undefined) throw fail("conflicting-overrides", name, `appears more than once on the same field`);
+    props[prop] = value;
+  };
+  for (const d of directives ?? []) {
+    const name = d.name.value;
+    if (BUILTIN_DIRECTIVES.has(name)) continue;
+    const args = {};
+    for (const a of d.arguments ?? []) args[a.name.value] = valueFromASTUntyped(a.value, variables);
+    const only = (...allowed) => {
+      for (const k of Object.keys(args)) if (!allowed.includes(k)) throw fail("bad-directive", name, `unknown argument ${JSON.stringify(k)} (expected ${allowed.join(", ") || "none"})`);
+    };
+    const fb = badDir(name);
+    switch (name) {
+      case "list": only(); set("list", true, name); break;
+      case "one": only(); set("one", true, name); break;
+      case "count": {
+        only("n", "min", "max");
+        const value = args.n !== undefined ? args.n : [args.min, args.max];
+        if (args.n !== undefined && (args.min !== undefined || args.max !== undefined)) throw fb("use n, or min and max, not both");
+        set("count", normalizeCount(value, fb), name);
+        break;
+      }
+      case "gen": {
+        const { name: genName, ...rest } = args;
+        if (typeof genName !== "string") throw fb("name must be a string");
+        set("gen", { name: genName, args: rest }, name);
+        break;
+      }
+      case "pattern": only("p"); if (typeof args.p !== "string") throw fb("p must be a string"); set("gen", { name: "pattern", args: { p: args.p } }, name); break;
+      case "pick": only("values"); set("gen", { name: "oneOf", args: { values: checkPick(args.values, fb) } }, name); break;
+      case "nullRate":
+        only("p");
+        if (typeof args.p !== "number" || !(args.p >= 0 && args.p <= 1)) throw fb("p must be a number between 0 and 1");
+        set("nullRate", args.p, name);
+        break;
+      case "derive": only("from"); if (typeof args.from !== "string" || !args.from) throw fb("from must be a field name"); set("derive", args.from, name); break;
+      case "type": only("name"); if (typeof args.name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(args.name)) throw fb("name must be a GraphQL type name"); set("type", args.name, name); break;
+      case "seed": only("s"); if (typeof args.s !== "string" && typeof args.s !== "number") throw fb("s must be a string or number"); set("seed", String(args.s), name); break;
+      default: throw unknownDirective(name);
+    }
+  }
+  if (props.list && props.one) throw new GraceholderError("conflicting-overrides", "@list and @one on the same field", { path });
+  if (props.one) props.list = false;
+  delete props.one;
+  return props;
+}

package/src/dist.js

@@ -0,0 +1,90 @@
+// Distribution sampling (docs/design.md section 17). Every function draws only from the
+// stream it is given (the per-value stream), so a value never depends on any other value.
+// Only IEEE basic operations and src/detmath.js are used, so results are identical on every engine.
+import { ln, exp, pow, cos, TWO_PI } from "./detmath.js";
+import { GraceholderError } from "./errors.js";
+
+export const DISTRIBUTIONS = Object.freeze(["uniform", "normal", "lognormal", "zipf", "powerlaw"]);
+
+const badArgs = (name, msg) => new GraceholderError("bad-generator-args", `${name}: ${msg}`);
+
+/** Standard normal by Box-Muller (the cosine branch); consumes exactly two floats. */
+export function normal01(s) {
+  const u1 = 1 - s.float(); // (0, 1]
+  const u2 = s.float();
+  return Math.sqrt(-2 * ln(u1)) * cos(TWO_PI * u2);
+}
+
+/** Truncated normal on [lo, hi] by rejection (at most 12 attempts, then clamped). */
+function truncNormal(s, mu, sigma, lo, hi) {
+  let x = mu;
+  for (let i = 0; i < 12; i++) {
+    x = mu + sigma * normal01(s);
+    if (x >= lo && x <= hi) return x;
+  }
+  return Math.min(hi, Math.max(lo, x));
+}
+
+/** Inverse CDF of the density proportional to y^-alpha on [1, top]; u in [0, 1). */
+export function boundedPowerInverse(u, alpha, top) {
+  if (top <= 1) return 1;
+  if (alpha === 1) return exp(u * ln(top));
+  const a = 1 - alpha;
+  return pow(1 + u * (pow(top, a) - 1), 1 / a);
+}
+
+/** Validate and read the distribution arguments shared by int, float and money. */
+export function distArgs(name, args) {
+  const dist = args.dist ?? "uniform";
+  if (!DISTRIBUTIONS.includes(dist)) throw badArgs(name, `unknown dist ${JSON.stringify(dist)} (known: ${DISTRIBUTIONS.join(", ")})`);
+  for (const k of ["mean", "sd", "mu", "sigma", "alpha", "s"]) {
+    if (args[k] !== undefined && !Number.isFinite(args[k])) throw badArgs(name, `${k} must be a number`);
+  }
+  if (args.sd !== undefined && !(args.sd > 0)) throw badArgs(name, "sd must be positive");
+  if (args.sigma !== undefined && !(args.sigma > 0)) throw badArgs(name, "sigma must be positive");
+  if (args.alpha !== undefined && !(args.alpha > 0)) throw badArgs(name, "alpha must be positive");
+  if (args.s !== undefined && !(args.s > 0)) throw badArgs(name, "s must be positive");
+  return dist;
+}
+
+/**
+ * A real number in [min, max] from the named distribution.
+ *  - uniform: min + u (max - min)
+ *  - normal: mean (default the midpoint), sd (default range / 6), truncated to [min, max]
+ *  - lognormal: y = x - min + 1 in [1, range + 1]; ln y ~ N(mu, sigma) truncated to the support;
+ *    defaults mu = 0.35 ln(range + 1), sigma = ln(range + 1) / 6.5 (median well below the middle, long right tail)
+ *  - powerlaw: density proportional to y^-alpha on [1, range + 1] (default alpha 2), inverse CDF
+ *  - zipf: only meaningful for integers, see {@link zipfRank}; here it is the same as powerlaw with exponent `s`
+ */
+export function sampleReal(s, dist, min, max, args = {}) {
+  const range = max - min;
+  switch (dist) {
+    case "uniform":
+      return min + s.float() * range;
+    case "normal":
+      return truncNormal(s, args.mean ?? min + range / 2, args.sd ?? range / 6, min, max);
+    case "lognormal": {
+      const top = ln(range + 1);
+      const y = exp(truncNormal(s, args.mu ?? 0.35 * top, args.sigma ?? top / 6.5, 0, top));
+      return Math.min(max, min + (y - 1));
+    }
+    case "powerlaw":
+      return Math.min(max, min + (boundedPowerInverse(s.float(), args.alpha ?? 2, range + 1) - 1));
+    default:
+      return Math.min(max, min + (boundedPowerInverse(s.float(), args.s ?? 1.1, range + 1) - 1));
+  }
+}
+
+/**
+ * Integer in [min, max] from the named distribution. zipf is the bounded power law discretised
+ * by flooring: rank k in 1..N has probability proportional to k^(1-s) - (k+1)^(1-s), and the
+ * result is min + k - 1, so the smallest value is the most likely.
+ */
+export function sampleInt(s, dist, min, max, args = {}) {
+  if (dist === "zipf") {
+    const n = max - min + 1;
+    const y = boundedPowerInverse(s.float(), args.s ?? 1.1, n + 1);
+    return min + Math.min(n, Math.floor(y)) - 1;
+  }
+  return Math.min(max, Math.max(min, Math.round(sampleReal(s, dist, min, max, args))));
+}

package/src/errors.js

@@ -0,0 +1,17 @@
+/** Error codes are part of the public API (docs/design.md section 9). */
+export class GraceholderError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {{ path?: string, hint?: string, cause?: unknown, errors?: readonly any[], data?: unknown }} [extra]
+   */
+  constructor(code, message, extra = {}) {
+    super(message, extra.cause === undefined ? undefined : { cause: extra.cause });
+    this.name = "GraceholderError";
+    this.code = code;
+    if (extra.path !== undefined) this.path = extra.path;
+    if (extra.hint !== undefined) this.hint = extra.hint;
+    if (extra.errors !== undefined) this.errors = extra.errors;
+    if (extra.data !== undefined) this.data = extra.data;
+  }
+}