@variantlab/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 variantlab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @variantlab/core
+
+The framework-agnostic variantlab engine. Zero dependencies, runs anywhere.
+
+> **Status:** Phase 1 — Pre-alpha. Not ready for production use.
+
+See the [root README](../../README.md) for project overview, motivation, and roadmap.

package/dist/_size/config.cjs

@@ -0,0 +1,634 @@
+'use strict';
+
+// src/config/errors.ts
+var ConfigValidationError = class extends Error {
+  constructor(issues) {
+    super(`Config validation failed with ${issues.length} issue(s)`);
+    this.name = "ConfigValidationError";
+    this.issues = Object.freeze(issues.slice());
+  }
+};
+
+// src/config/freeze.ts
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Object.isFrozen(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      deepFreeze(value[i]);
+    }
+    return Object.freeze(value);
+  }
+  const obj = value;
+  const keys = Object.keys(obj);
+  for (let i = 0; i < keys.length; i++) {
+    deepFreeze(obj[keys[i]]);
+  }
+  return Object.freeze(value);
+}
+
+// src/targeting/glob.ts
+function compileGlob(pattern) {
+  if (pattern.length === 0) return null;
+  if (pattern === "*") return [{ kind: "param" }];
+  if (pattern === "**") return [{ kind: "rest" }];
+  if (pattern[0] !== "/") return null;
+  if (pattern.indexOf("***") >= 0) return null;
+  const normalized = pattern.length > 1 && pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+  if (normalized === "/") return [];
+  const raw = normalized.slice(1).split("/");
+  const segs = [];
+  for (let i = 0; i < raw.length; i++) {
+    const part = raw[i];
+    if (part.length === 0) return null;
+    if (part === "**") {
+      if (i !== raw.length - 1) return null;
+      segs.push({ kind: "rest" });
+      continue;
+    }
+    if (part === "*") {
+      segs.push({ kind: "param" });
+      continue;
+    }
+    if (part[0] === ":") {
+      if (part.length < 2) return null;
+      segs.push({ kind: "param" });
+      continue;
+    }
+    if (/[*:?[\]{}!]/.test(part)) return null;
+    segs.push({ kind: "literal", value: part });
+  }
+  return segs;
+}
+
+// src/targeting/semver.ts
+function parseVersion(s) {
+  if (s.length === 0) return null;
+  const parts = [0, 0, 0];
+  let idx = 0;
+  let part = 0;
+  let seen = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c === 46) {
+      if (!seen) return null;
+      parts[idx++] = part;
+      if (idx > 2) return null;
+      part = 0;
+      seen = false;
+    } else if (c >= 48 && c <= 57) {
+      part = part * 10 + (c - 48);
+      seen = true;
+    } else return null;
+  }
+  if (!seen || idx !== 2) return null;
+  parts[2] = part;
+  return [parts[0], parts[1], parts[2]];
+}
+function parseSemver(s) {
+  if (s.length === 0) return null;
+  const clauses = [];
+  for (const part of s.split("||")) {
+    const c = parseClause(part.trim());
+    if (c === null) return null;
+    clauses.push(c);
+  }
+  return clauses;
+}
+function parseClause(s) {
+  if (s.length === 0) return null;
+  const hy = s.indexOf(" - ");
+  if (hy >= 0) {
+    const lo = parseVersion(s.slice(0, hy).trim());
+    const hi = parseVersion(s.slice(hy + 3).trim());
+    if (lo === null || hi === null) return null;
+    return [
+      { op: ">=", v: lo },
+      { op: "<=", v: hi }
+    ];
+  }
+  const cmps = [];
+  for (const tok of s.split(/\s+/)) {
+    if (tok.length === 0) continue;
+    const parsed = parseComparator(tok);
+    if (parsed === null) return null;
+    for (const c of parsed) cmps.push(c);
+  }
+  return cmps.length > 0 ? cmps : null;
+}
+function parseComparator(s) {
+  const c0 = s[0];
+  if (c0 === "^" || c0 === "~") {
+    const v2 = parseVersion(s.slice(1));
+    if (v2 === null) return null;
+    const upper = c0 === "^" ? [v2[0] + 1, 0, 0] : [v2[0], v2[1] + 1, 0];
+    return [
+      { op: ">=", v: v2 },
+      { op: "<", v: upper }
+    ];
+  }
+  let op = "=";
+  let rest = s;
+  if (c0 === ">" || c0 === "<") {
+    if (s[1] === "=") {
+      op = `${c0}=`;
+      rest = s.slice(2);
+    } else {
+      op = c0;
+      rest = s.slice(1);
+    }
+  } else if (c0 === "=") {
+    rest = s.slice(1);
+  }
+  const v = parseVersion(rest);
+  return v === null ? null : [{ op, v }];
+}
+
+// src/config/validator.ts
+var MAX_BYTES = 1048576;
+var MAX_EXP = 1e3;
+var MAX_VAR = 100;
+var MIN_VAR = 2;
+var MAX_ROUTES = 100;
+var MAX_DEPTH = 10;
+var MAX_NAME = 128;
+var MAX_DESC = 512;
+var ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var RESERVED = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var ASSIGNS = /* @__PURE__ */ new Set(["default", "random", "sticky-hash", "weighted"]);
+var STATUSES = /* @__PURE__ */ new Set(["draft", "active", "archived"]);
+var TYPES = /* @__PURE__ */ new Set(["render", "value"]);
+var PLATFORMS = /* @__PURE__ */ new Set(["ios", "android", "web", "node"]);
+var SIZES = /* @__PURE__ */ new Set(["small", "medium", "large"]);
+function validateConfig(input) {
+  const issues = [];
+  if (measureBytes(input) > MAX_BYTES) {
+    push(issues, "", "config-too-large");
+    throw new ConfigValidationError(issues);
+  }
+  let parsed = input;
+  if (typeof input === "string") {
+    try {
+      parsed = JSON.parse(input);
+    } catch (err) {
+      push(issues, "", "invalid-json", err.message);
+      throw new ConfigValidationError(issues);
+    }
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    push(issues, "", "not-an-object");
+    throw new ConfigValidationError(issues);
+  }
+  const sanitized = sanitize(parsed, issues, "");
+  validateRoot(sanitized, issues);
+  if (issues.length > 0) {
+    throw new ConfigValidationError(issues);
+  }
+  return deepFreeze(sanitized);
+}
+var encoder = new TextEncoder();
+function measureBytes(input) {
+  if (typeof input === "string") return encoder.encode(input).length;
+  try {
+    const s = JSON.stringify(input);
+    if (typeof s !== "string") return 0;
+    return encoder.encode(s).length;
+  } catch {
+    return 0;
+  }
+}
+function sanitize(value, issues, ptr) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+      out.push(sanitize(value[i], issues, `${ptr}/${i}`));
+    }
+    return out;
+  }
+  const src = value;
+  const dst = /* @__PURE__ */ Object.create(null);
+  const keys = Object.keys(src);
+  for (let i = 0; i < keys.length; i++) {
+    const k = keys[i];
+    if (RESERVED.has(k)) {
+      push(issues, jp(ptr, k), "reserved-key", k);
+      continue;
+    }
+    dst[k] = sanitize(src[k], issues, jp(ptr, k));
+  }
+  return dst;
+}
+function validateRoot(root, issues) {
+  const version = root["version"];
+  if (version === void 0) {
+    push(issues, "/version", "version/missing");
+  } else if (version !== 1) {
+    push(issues, "/version", "version/invalid");
+  }
+  const enabled = root["enabled"];
+  if (enabled !== void 0 && typeof enabled !== "boolean") {
+    push(issues, "/enabled", "enabled/invalid");
+  }
+  const signature = root["signature"];
+  if (signature !== void 0 && (typeof signature !== "string" || signature.length === 0)) {
+    push(issues, "/signature", "signature/invalid");
+  }
+  const experiments = root["experiments"];
+  if (experiments === void 0) {
+    push(issues, "/experiments", "experiments/missing");
+    return;
+  }
+  if (!Array.isArray(experiments)) {
+    push(issues, "/experiments", "experiments/not-an-array");
+    return;
+  }
+  if (experiments.length > MAX_EXP) {
+    push(issues, "/experiments", "experiments/too-many");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < experiments.length; i++) {
+    validateExperiment(experiments[i], `/experiments/${i}`, seen, issues);
+  }
+}
+function validateExperiment(exp, p, seen, issues) {
+  if (exp === null || typeof exp !== "object" || Array.isArray(exp)) {
+    push(issues, p, "experiment/not-an-object");
+    return;
+  }
+  const e = exp;
+  const id = e["id"];
+  if (id === void 0) {
+    push(issues, `${p}/id`, "experiment/missing-required", "id");
+  } else if (typeof id !== "string" || !ID_RE.test(id)) {
+    push(issues, `${p}/id`, "experiment/id/invalid");
+  } else if (seen.has(id)) {
+    push(issues, `${p}/id`, "experiment/id/duplicate", id);
+  } else {
+    seen.add(id);
+  }
+  const name = e["name"];
+  if (name === void 0) {
+    push(issues, `${p}/name`, "experiment/missing-required", "name");
+  } else if (typeof name !== "string" || name.length === 0 || name.length > MAX_NAME) {
+    push(issues, `${p}/name`, "experiment/name/invalid");
+  }
+  checkOptString(
+    e["description"],
+    `${p}/description`,
+    MAX_DESC,
+    "experiment/description/invalid",
+    issues
+  );
+  checkEnum(e["type"], `${p}/type`, TYPES, "experiment/type/invalid", issues);
+  checkEnum(e["status"], `${p}/status`, STATUSES, "experiment/status/invalid", issues);
+  checkOptString(e["mutex"], `${p}/mutex`, MAX_NAME, "experiment/mutex/invalid", issues);
+  checkOptString(e["owner"], `${p}/owner`, MAX_NAME, "experiment/owner/invalid", issues);
+  checkOptBool(e["overridable"], `${p}/overridable`, "experiment/overridable/invalid", issues);
+  const variantIds = validateVariants(e["variants"], p, issues);
+  validateDefault(e["default"], variantIds, p, issues);
+  validateAssignment(e["assignment"], e["split"], variantIds, p, issues);
+  validateRoutes(e["routes"], p, issues);
+  validateTargeting(e["targeting"], p, issues);
+  validateDates(e["startDate"], e["endDate"], p, issues);
+  validateRollback(e["rollback"], p, issues);
+}
+function validateVariants(field, p, issues) {
+  const ids = /* @__PURE__ */ new Set();
+  const vp = `${p}/variants`;
+  if (field === void 0) {
+    push(issues, vp, "experiment/variants/missing");
+    return ids;
+  }
+  if (!Array.isArray(field)) {
+    push(issues, vp, "experiment/variants/missing");
+    return ids;
+  }
+  if (field.length < MIN_VAR) {
+    push(issues, vp, "experiment/variants/too-few");
+  }
+  if (field.length > MAX_VAR) {
+    push(issues, vp, "experiment/variants/too-many");
+  }
+  for (let i = 0; i < field.length; i++) {
+    const v = field[i];
+    const vip = `${vp}/${i}`;
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+      push(issues, vip, "variant/not-an-object");
+      continue;
+    }
+    const vo = v;
+    const vid = vo["id"];
+    if (vid === void 0) {
+      push(issues, `${vip}/id`, "experiment/missing-required", "variant.id");
+    } else if (typeof vid !== "string" || !ID_RE.test(vid)) {
+      push(issues, `${vip}/id`, "variant/id/invalid");
+    } else if (ids.has(vid)) {
+      push(issues, `${vip}/id`, "variant/id/duplicate", vid);
+    } else {
+      ids.add(vid);
+    }
+    checkOptString(vo["label"], `${vip}/label`, MAX_NAME, "variant/label/invalid", issues);
+    checkOptString(
+      vo["description"],
+      `${vip}/description`,
+      MAX_DESC,
+      "variant/description/invalid",
+      issues
+    );
+  }
+  return ids;
+}
+function validateDefault(field, ids, p, issues) {
+  const dp = `${p}/default`;
+  if (field === void 0) {
+    push(issues, dp, "experiment/default/missing");
+    return;
+  }
+  if (typeof field !== "string") {
+    push(issues, dp, "experiment/default/unknown-variant");
+    return;
+  }
+  if (ids.size > 0 && !ids.has(field)) {
+    push(issues, dp, "experiment/default/unknown-variant", field);
+  }
+}
+function validateAssignment(aField, sField, ids, p, issues) {
+  let strategy = "default";
+  if (aField !== void 0) {
+    if (typeof aField !== "string" || !ASSIGNS.has(aField)) {
+      push(issues, `${p}/assignment`, "experiment/assignment/invalid");
+    } else {
+      strategy = aField;
+    }
+  }
+  const sp = `${p}/split`;
+  if (strategy === "weighted" && sField === void 0) {
+    push(issues, sp, "split/missing");
+    return;
+  }
+  if (sField === void 0) return;
+  if (sField === null || typeof sField !== "object" || Array.isArray(sField)) {
+    push(issues, sp, "split/not-an-object");
+    return;
+  }
+  const split = sField;
+  const keys = Object.keys(split);
+  let sum = 0;
+  let bad = false;
+  for (let i = 0; i < keys.length; i++) {
+    const k = keys[i];
+    if (ids.size > 0 && !ids.has(k)) {
+      push(issues, `${sp}/${esc(k)}`, "split/unknown-variant", k);
+      bad = true;
+      continue;
+    }
+    const v = split[k];
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > 100) {
+      push(issues, `${sp}/${esc(k)}`, "split/value-invalid");
+      bad = true;
+      continue;
+    }
+    sum += v;
+  }
+  if (!bad && sum !== 100) {
+    push(issues, sp, "split/sum-invalid", String(sum));
+  }
+}
+function validateRoutes(field, p, issues) {
+  if (field === void 0) return;
+  const rp = `${p}/routes`;
+  if (!Array.isArray(field)) {
+    push(issues, rp, "experiment/routes/invalid");
+    return;
+  }
+  if (field.length > MAX_ROUTES) {
+    push(issues, rp, "experiment/routes/invalid");
+  }
+  for (let i = 0; i < field.length; i++) {
+    const r = field[i];
+    if (typeof r !== "string" || compileGlob(r) === null) {
+      push(issues, `${rp}/${i}`, "route/glob/invalid");
+    }
+  }
+}
+function validateTargeting(field, p, issues) {
+  if (field === void 0) return;
+  const tp = `${p}/targeting`;
+  if (field === null || typeof field !== "object" || Array.isArray(field)) {
+    push(issues, tp, "targeting/not-an-object");
+    return;
+  }
+  if (depthOf(field, 0) > MAX_DEPTH) {
+    push(issues, tp, "targeting/depth-exceeded");
+  }
+  const t = field;
+  if (t["platform"] !== void 0) {
+    checkEnumArray(
+      t["platform"],
+      `${tp}/platform`,
+      PLATFORMS,
+      "targeting/platform/invalid",
+      issues
+    );
+  }
+  if (t["appVersion"] !== void 0) {
+    const v = t["appVersion"];
+    if (typeof v !== "string" || parseSemver(v) === null) {
+      push(issues, `${tp}/appVersion`, "targeting/appversion/invalid");
+    }
+  }
+  if (t["locale"] !== void 0) {
+    checkStringArray(t["locale"], `${tp}/locale`, "targeting/locale/invalid", issues);
+  }
+  if (t["screenSize"] !== void 0) {
+    checkEnumArray(
+      t["screenSize"],
+      `${tp}/screenSize`,
+      SIZES,
+      "targeting/screensize/invalid",
+      issues
+    );
+  }
+  if (t["routes"] !== void 0) {
+    const r = t["routes"];
+    if (!Array.isArray(r) || r.length === 0) {
+      push(issues, `${tp}/routes`, "targeting/routes/invalid");
+    } else {
+      for (let i = 0; i < r.length; i++) {
+        const v = r[i];
+        if (typeof v !== "string" || compileGlob(v) === null) {
+          push(issues, `${tp}/routes/${i}`, "targeting/routes/invalid");
+        }
+      }
+    }
+  }
+  if (t["userId"] !== void 0) {
+    validateUserId(t["userId"], `${tp}/userId`, issues);
+  }
+  if (t["attributes"] !== void 0) {
+    const a = t["attributes"];
+    if (a === null || typeof a !== "object" || Array.isArray(a)) {
+      push(issues, `${tp}/attributes`, "targeting/attributes/invalid");
+    }
+  }
+}
+function validateUserId(u, p, issues) {
+  const code = "targeting/userid/invalid";
+  if (Array.isArray(u)) {
+    if (u.length === 0) {
+      push(issues, p, code);
+      return;
+    }
+    for (let i = 0; i < u.length; i++) {
+      const v = u[i];
+      if (typeof v !== "string" || v.length === 0) {
+        push(issues, `${p}/${i}`, code);
+      }
+    }
+    return;
+  }
+  if (u !== null && typeof u === "object") {
+    const o = u;
+    const h = o["hash"];
+    const m = o["mod"];
+    if (typeof h !== "string" || h.length === 0) {
+      push(issues, `${p}/hash`, code);
+    }
+    if (typeof m !== "number" || !Number.isInteger(m) || m < 0 || m > 100) {
+      push(issues, `${p}/mod`, code);
+    }
+    return;
+  }
+  push(issues, p, code);
+}
+function validateDates(sField, eField, p, issues) {
+  let s;
+  let e;
+  if (sField !== void 0) {
+    if (typeof sField !== "string" || !isValidIsoDate(sField)) {
+      push(issues, `${p}/startDate`, "experiment/startdate/invalid");
+    } else {
+      s = Date.parse(sField);
+    }
+  }
+  if (eField !== void 0) {
+    if (typeof eField !== "string" || !isValidIsoDate(eField)) {
+      push(issues, `${p}/endDate`, "experiment/enddate/invalid");
+    } else {
+      e = Date.parse(eField);
+    }
+  }
+  if (s !== void 0 && e !== void 0 && !(e > s)) {
+    push(issues, `${p}/endDate`, "experiment/date-range/invalid");
+  }
+}
+function validateRollback(field, p, issues) {
+  if (field === void 0) return;
+  const rp = `${p}/rollback`;
+  if (field === null || typeof field !== "object" || Array.isArray(field)) {
+    push(issues, rp, "rollback/not-an-object");
+    return;
+  }
+  const r = field;
+  const thr = r["threshold"];
+  if (thr === void 0) {
+    push(issues, `${rp}/threshold`, "rollback/threshold/invalid");
+  } else if (typeof thr !== "number" || !Number.isInteger(thr) || thr < 1 || thr > 100) {
+    push(issues, `${rp}/threshold`, "rollback/threshold/invalid");
+  }
+  const win = r["window"];
+  if (win === void 0) {
+    push(issues, `${rp}/window`, "rollback/window/invalid");
+  } else if (typeof win !== "number" || !Number.isInteger(win) || win < 1e3 || win > 36e5) {
+    push(issues, `${rp}/window`, "rollback/window/invalid");
+  }
+  const persistent = r["persistent"];
+  if (persistent !== void 0 && typeof persistent !== "boolean") {
+    push(issues, `${rp}/persistent`, "rollback/persistent/invalid");
+  }
+}
+function checkOptString(v, p, max, code, issues) {
+  if (v === void 0) return;
+  if (typeof v !== "string" || v.length === 0 || v.length > max) {
+    push(issues, p, code);
+  }
+}
+function checkOptBool(v, p, code, issues) {
+  if (v === void 0) return;
+  if (typeof v !== "boolean") {
+    push(issues, p, code);
+  }
+}
+function checkEnum(v, p, set, code, issues) {
+  if (v === void 0) return;
+  if (typeof v !== "string" || !set.has(v)) {
+    push(issues, p, code);
+  }
+}
+function checkEnumArray(v, p, set, code, issues) {
+  if (!Array.isArray(v) || v.length === 0) {
+    push(issues, p, code);
+    return;
+  }
+  for (let i = 0; i < v.length; i++) {
+    const x = v[i];
+    if (typeof x !== "string" || !set.has(x)) {
+      push(issues, `${p}/${i}`, code);
+    }
+  }
+}
+function checkStringArray(v, p, code, issues) {
+  if (!Array.isArray(v) || v.length === 0) {
+    push(issues, p, code);
+    return;
+  }
+  for (let i = 0; i < v.length; i++) {
+    const x = v[i];
+    if (typeof x !== "string" || x.length === 0) {
+      push(issues, `${p}/${i}`, code);
+    }
+  }
+}
+var ISO_TAIL_RE = /T.*(?:Z|[+-]\d{2}:?\d{2})$/;
+function isValidIsoDate(s) {
+  if (s.length < 10) return false;
+  if (Number.isNaN(Date.parse(s))) return false;
+  return ISO_TAIL_RE.test(s);
+}
+function depthOf(value, current) {
+  if (value === null || typeof value !== "object") return current;
+  let m = current;
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const d = depthOf(value[i], current + 1);
+      if (d > m) m = d;
+    }
+    return m;
+  }
+  const obj = value;
+  const keys = Object.keys(obj);
+  for (let i = 0; i < keys.length; i++) {
+    const d = depthOf(obj[keys[i]], current + 1);
+    if (d > m) m = d;
+  }
+  return m;
+}
+function jp(parent, key) {
+  return `${parent}/${esc(key)}`;
+}
+function esc(s) {
+  return s.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function push(issues, path, code, message) {
+  issues.push({ path, code, message: message ?? code });
+}
+
+exports.ConfigValidationError = ConfigValidationError;
+exports.validateConfig = validateConfig;
+//# sourceMappingURL=config.cjs.map
+//# sourceMappingURL=config.cjs.map