@pattonwebz/split-tester-client 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patton Webz
+
+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,64 @@
+# @pattonwebz/split-tester-client
+
+Client-side split-testing engine for manually defined JavaScript experiments with GA4-friendly analytics hooks.
+
+## Install
+
+```bash
+npm install @pattonwebz/split-tester-client
+```
+
+## ESM-only
+
+This package is published as ESM-only.
+
+## Public API
+
+```js
+import {
+  createEngine,
+  createRuntime,
+  installRuntime,
+  createGa4Adapter,
+  defineExperiments
+} from "@pattonwebz/split-tester-client";
+```
+
+## Preferred usage
+
+```js
+import { installRuntime, createGa4Adapter } from "@pattonwebz/split-tester-client";
+
+const splitTester = installRuntime({
+  analytics: createGa4Adapter({ gtag: window.gtag }),
+  getUserContext: () => ({
+    url: { pathname: window.location.pathname },
+    user: { id: window.__userId }
+  })
+});
+
+splitTester.define(({ context }) => ({
+  id: "hero-copy-test",
+  status: "active",
+  variants: [
+    { id: "control", weight: 50 },
+    { id: "v1", weight: 50 }
+  ],
+  goals: [
+    {
+      id: "signup-intent",
+      events: ["cta_click", "form_start"]
+    }
+  ],
+  variantRules: [
+    {
+      when: ({ events }) => events.includes("viewed_pricing") || context.url.pathname === "/pricing",
+      variant: "v1"
+    }
+  ]
+}));
+
+splitTester.trackEvent("cta_click", { source: "hero" });
+```
+
+`installRuntime()` exposes a singleton on `window.splitTester` and accepts late `define(...)` calls, so other snippets can add tests after the base script loads.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@pattonwebz/split-tester-client",
+  "version": "0.2.0",
+  "description": "Client-side JavaScript split testing engine with GA4 event support.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./ga4": "./src/analytics/ga4.js",
+    "./runtime": "./src/runtime/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ab-testing",
+    "split-testing",
+    "ga4",
+    "experiments",
+    "analytics"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:jest": "NODE_OPTIONS=--experimental-vm-modules jest --runInBand --config jest.config.js"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/src/analytics/ga4.js

@@ -0,0 +1,110 @@
+const DEFAULT_EVENT_NAMES = Object.freeze({
+  impression: "split_test_impression",
+  conversion: "split_test_conversion"
+});
+
+function normalizePagePath(pagePath) {
+  return typeof pagePath === "string" && pagePath.trim() !== "" ? pagePath : "/";
+}
+
+function addDefined(target, key, value) {
+  if (value !== undefined && value !== null) {
+    target[key] = value;
+  }
+}
+
+export function buildGa4ImpressionPayload({
+  experimentId,
+  variantId,
+  pagePath,
+  payload = {},
+  eventName = DEFAULT_EVENT_NAMES.impression
+} = {}) {
+  const params = { ...payload };
+  addDefined(params, "experiment_id", experimentId);
+  addDefined(params, "variant_id", variantId);
+  addDefined(params, "page_path", normalizePagePath(pagePath));
+
+  return { eventName, params };
+}
+
+export function buildGa4ConversionPayload({
+  experimentId,
+  variantId,
+  goalId,
+  pagePath,
+  payload = {},
+  eventName = DEFAULT_EVENT_NAMES.conversion
+} = {}) {
+  const params = { ...payload };
+  addDefined(params, "experiment_id", experimentId);
+  addDefined(params, "variant_id", variantId);
+  addDefined(params, "goal_id", goalId);
+  addDefined(params, "page_path", normalizePagePath(pagePath));
+
+  return { eventName, params };
+}
+
+export function buildGa4EventPayload({
+  eventName,
+  experimentId,
+  variantId,
+  goalId,
+  pagePath,
+  payload = {}
+} = {}) {
+  const params = { ...payload };
+  addDefined(params, "event_name", eventName);
+  addDefined(params, "experiment_id", experimentId);
+  addDefined(params, "variant_id", variantId);
+  addDefined(params, "goal_id", goalId);
+  addDefined(params, "page_path", normalizePagePath(pagePath));
+
+  return { eventName, params };
+}
+
+function emit(gtag, eventName, params) {
+  if (typeof gtag === "function") {
+    gtag("event", eventName, params);
+  }
+}
+
+/**
+ * Creates a dependency-free GA4 adapter for engine analytics hooks.
+ *
+ * @param {{
+ *   gtag: (...args: unknown[]) => void,
+ *   eventNames?: { impression?: string, conversion?: string },
+ *   baseParams?: Record<string, unknown>
+ * }} options
+ */
+export function createGa4Adapter({ gtag, eventNames = {}, baseParams = {} } = {}) {
+  if (typeof gtag !== "function") {
+    throw new Error("createGa4Adapter requires a gtag-like function.");
+  }
+
+  const names = { ...DEFAULT_EVENT_NAMES, ...eventNames };
+
+  return {
+    trackImpression(input = {}) {
+      const { eventName, params } = buildGa4ImpressionPayload({
+        ...input,
+        eventName: names.impression
+      });
+      emit(gtag, eventName, { ...baseParams, ...params });
+    },
+
+    trackConversion(input = {}) {
+      const { eventName, params } = buildGa4ConversionPayload({
+        ...input,
+        eventName: names.conversion
+      });
+      emit(gtag, eventName, { ...baseParams, ...params });
+    },
+
+    trackEvent(input = {}) {
+      const { eventName, params } = buildGa4EventPayload(input);
+      emit(gtag, eventName, { ...baseParams, ...params });
+    }
+  };
+}

package/src/engine/contract.js

@@ -0,0 +1,84 @@
+import { validateExperiments } from "../experiments/schema.js";
+
+/**
+ * @typedef {Object} VariantConfig
+ * @property {string} id
+ * @property {number} weight
+ */
+
+/**
+ * @typedef {Object} GoalConfig
+ * @property {string} id
+ * @property {string} [gaEventName]
+ * @property {string[]} [events]
+ */
+
+/**
+ * @typedef {Object} AssignmentConfig
+ * @property {"sticky-hash"} [strategy]
+ * @property {(input: AssignmentInput) => string|null|undefined} [forceVariant]
+ */
+
+/**
+ * @typedef {Object} VariantRuleConfig
+ * @property {(input: AssignmentInput) => boolean} when
+ * @property {string} variant
+ */
+
+/**
+ * @typedef {Object} ExperimentConfig
+ * @property {string} id
+ * @property {"draft"|"active"|"paused"} status
+ * @property {VariantConfig[]} variants
+ * @property {(context: UserContext) => boolean} [targeting]
+ * @property {string|null} [mutualExclusionGroup]
+ * @property {number} [priority]
+ * @property {AssignmentConfig} [assignment]
+ * @property {VariantRuleConfig[]} [variantRules]
+ * @property {GoalConfig[]} [goals]
+ */
+
+/**
+ * @typedef {Object} UserContext
+ * @property {{ pathname: string }} url
+ * @property {Record<string, unknown>} [user]
+ * @property {string} [sessionId]
+ */
+
+/**
+ * @typedef {Object} AssignmentInput
+ * @property {UserContext} context
+ * @property {string[]} events
+ */
+
+/**
+ * @typedef {Object} AnalyticsAdapter
+ * @property {(payload: Record<string, unknown>) => void} [trackImpression]
+ * @property {(payload: { eventName: string, payload: Record<string, unknown>, pagePath?: string }) => void} [trackEvent]
+ * @property {(payload: Record<string, unknown>) => void} [trackConversion]
+ */
+
+/**
+ * @typedef {Object} StorageAdapter
+ * @property {(key: string) => string|null} [getItem]
+ * @property {(key: string, value: string) => void} [setItem]
+ * @property {(key: string) => void} [removeItem]
+ */
+
+/**
+ * @typedef {Object} EngineInitOptions
+ * @property {ExperimentConfig[]} experiments
+ * @property {() => UserContext} [getUserContext]
+ * @property {AnalyticsAdapter} [analytics]
+ * @property {StorageAdapter} [storage]
+ */
+
+/**
+ * Validates and returns experiment configs for runtime registration.
+ *
+ * @param {ExperimentConfig[]} experiments
+ * @returns {ExperimentConfig[]}
+ */
+export function defineExperiments(experiments) {
+  return validateExperiments(experiments);
+}

package/src/engine/runtime.js

@@ -0,0 +1,274 @@
+import { validateExperiments } from "../experiments/schema.js";
+import { createAssignmentStore } from "../storage/assignment-store.js";
+
+function defaultGetUserContext() {
+  return { url: { pathname: "/" }, user: {} };
+}
+
+function hashString(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) | 0;
+  }
+  return Math.abs(hash);
+}
+
+function resolveUserKey(context) {
+  if (context?.user && typeof context.user.id === "string" && context.user.id.trim() !== "") {
+    return `user:${context.user.id}`;
+  }
+
+  if (typeof context?.sessionId === "string" && context.sessionId.trim() !== "") {
+    return `session:${context.sessionId}`;
+  }
+
+  return "anonymous";
+}
+
+function getAssignmentKey(experimentId, context) {
+  return `split-tester:${experimentId}:${resolveUserKey(context)}`;
+}
+
+function selectWeightedVariant(experiment, userKey) {
+  const totalWeight = experiment.variants.reduce((sum, variant) => sum + variant.weight, 0);
+  const bucket = hashString(`${userKey}:${experiment.id}`) % totalWeight;
+
+  let running = 0;
+  for (const variant of experiment.variants) {
+    running += variant.weight;
+    if (bucket < running) {
+      return variant.id;
+    }
+  }
+
+  return experiment.variants[experiment.variants.length - 1].id;
+}
+
+function getPriority(experiment) {
+  return experiment.priority ?? 0;
+}
+
+function assertKnownVariant(experiment, variantId) {
+  if (!experiment.variants.some((variant) => variant.id === variantId)) {
+    throw new Error(`Experiment "${experiment.id}" resolved unknown variant "${variantId}".`);
+  }
+}
+
+function getGoalMatches(experiment, eventName) {
+  if (!Array.isArray(experiment.goals)) {
+    return [];
+  }
+
+  return experiment.goals.filter((goal) => Array.isArray(goal.events) && goal.events.includes(eventName));
+}
+
+/**
+ * @param {import("./contract.js").EngineInitOptions} [options]
+ */
+export function createEngine(options = {}) {
+  const analytics = options.analytics ?? {};
+  const getUserContext = options.getUserContext ?? defaultGetUserContext;
+  const assignmentStore = options.assignmentStore ?? createAssignmentStore(options.storage);
+
+  /** @type {import("./contract.js").ExperimentConfig[]} */
+  let experiments = [];
+  const assignments = new Map();
+  const emittedImpressions = new Set();
+  const seenEvents = new Set();
+
+  function registerExperiments(nextExperiments) {
+    const merged = [...experiments, ...nextExperiments];
+    experiments = validateExperiments(merged);
+    return experiments;
+  }
+
+  function listExperiments() {
+    return [...experiments];
+  }
+
+  if (options.experiments?.length) {
+    registerExperiments(options.experiments);
+  }
+
+  function resolveExplicitVariant(experiment, context, eventNames) {
+    const input = { context, events: eventNames };
+
+    const forcedVariant = experiment.assignment?.forceVariant?.(input);
+    if (forcedVariant) {
+      assertKnownVariant(experiment, forcedVariant);
+      return forcedVariant;
+    }
+
+    if (experiment.variantRules) {
+      for (const rule of experiment.variantRules) {
+        if (rule.when(input)) {
+          assertKnownVariant(experiment, rule.variant);
+          return rule.variant;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  function readStickyVariant(experiment, context) {
+    const stored = assignmentStore.get(getAssignmentKey(experiment.id, context));
+    if (!stored) {
+      return null;
+    }
+
+    if (!experiment.variants.some((variant) => variant.id === stored)) {
+      assignmentStore.delete(getAssignmentKey(experiment.id, context));
+      return null;
+    }
+
+    return stored;
+  }
+
+  function persistVariant(experiment, context, variantId) {
+    const key = getAssignmentKey(experiment.id, context);
+    assignmentStore.set(key, variantId);
+    assignments.set(key, variantId);
+  }
+
+  function assignExperiment(experiment, context, eventNames) {
+    const explicitVariant = resolveExplicitVariant(experiment, context, eventNames);
+    if (explicitVariant) {
+      persistVariant(experiment, context, explicitVariant);
+      return explicitVariant;
+    }
+
+    const stickyVariant = readStickyVariant(experiment, context);
+    if (stickyVariant) {
+      assignments.set(getAssignmentKey(experiment.id, context), stickyVariant);
+      return stickyVariant;
+    }
+
+    const existing = assignments.get(getAssignmentKey(experiment.id, context));
+    if (existing) {
+      return existing;
+    }
+
+    const userKey = resolveUserKey(context);
+    const variantId = selectWeightedVariant(experiment, userKey);
+    persistVariant(experiment, context, variantId);
+    return variantId;
+  }
+
+  function shouldRunExperiment(experiment, context) {
+    if (experiment.status !== "active") {
+      return false;
+    }
+
+    if (!experiment.targeting) {
+      return true;
+    }
+
+    return Boolean(experiment.targeting(context));
+  }
+
+  function getActiveExperimentsForPage(context = getUserContext()) {
+    const eventNames = [...seenEvents];
+    const active = experiments
+      .filter((experiment) => shouldRunExperiment(experiment, context))
+      .sort((left, right) => getPriority(right) - getPriority(left));
+
+    const selectedGroups = new Set();
+    const result = {};
+
+    for (const experiment of active) {
+      const group = experiment.mutualExclusionGroup;
+      if (group && selectedGroups.has(group)) {
+        continue;
+      }
+
+      const variantId = assignExperiment(experiment, context, eventNames);
+      result[experiment.id] = variantId;
+
+      if (group) {
+        selectedGroups.add(group);
+      }
+
+      const impressionKey = `${resolveUserKey(context)}:${experiment.id}:${variantId}`;
+      if (!emittedImpressions.has(impressionKey) && analytics.trackImpression) {
+        analytics.trackImpression({
+          experimentId: experiment.id,
+          variantId,
+          pagePath: context?.url?.pathname ?? "/"
+        });
+        emittedImpressions.add(impressionKey);
+      }
+    }
+
+    return result;
+  }
+
+  function getVariant(experimentId, context = getUserContext()) {
+    const assignmentsForPage = getActiveExperimentsForPage(context);
+    return assignmentsForPage[experimentId] ?? null;
+  }
+
+  function trackEvent(eventName, payload = {}, context = getUserContext()) {
+    seenEvents.add(eventName);
+
+    if (analytics.trackEvent) {
+      analytics.trackEvent({
+        eventName,
+        payload,
+        pagePath: context?.url?.pathname ?? "/"
+      });
+    }
+
+    const assignmentsForPage = getActiveExperimentsForPage(context);
+
+    for (const experiment of experiments) {
+      const variantId = assignmentsForPage[experiment.id];
+      if (!variantId) {
+        continue;
+      }
+
+      for (const goal of getGoalMatches(experiment, eventName)) {
+        if (analytics.trackConversion) {
+          analytics.trackConversion({
+            experimentId: experiment.id,
+            variantId,
+            goalId: goal.id,
+            eventName,
+            payload,
+            pagePath: context?.url?.pathname ?? "/"
+          });
+        }
+      }
+    }
+
+    return assignmentsForPage;
+  }
+
+  function trackConversion(experimentId, goalId, payload = {}, context = getUserContext()) {
+    const variantId = getVariant(experimentId, context);
+    if (!variantId) {
+      return null;
+    }
+
+    if (analytics.trackConversion) {
+      analytics.trackConversion({
+        experimentId,
+        variantId,
+        goalId,
+        payload,
+        pagePath: context?.url?.pathname ?? "/"
+      });
+    }
+
+    return { experimentId, variantId, goalId };
+  }
+
+  return {
+    registerExperiments,
+    listExperiments,
+    getActiveExperimentsForPage,
+    getVariant,
+    trackEvent,
+    trackConversion
+  };
+}

package/src/experiments/schema.js

@@ -0,0 +1,161 @@
+const ALLOWED_STATUSES = new Set(["draft", "active", "paused"]);
+
+function assertObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object.`);
+  }
+}
+
+function assertNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+}
+
+function validateVariant(variant, experimentId) {
+  assertObject(variant, `Variant in experiment "${experimentId}"`);
+  assertNonEmptyString(variant.id, `Variant id in experiment "${experimentId}"`);
+
+  if (typeof variant.weight !== "number" || !Number.isFinite(variant.weight) || variant.weight <= 0) {
+    throw new Error(`Variant "${variant.id}" in experiment "${experimentId}" must have a positive numeric weight.`);
+  }
+}
+
+function validateVariantRules(experiment) {
+  if (experiment.variantRules === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(experiment.variantRules)) {
+    throw new Error(`Experiment "${experiment.id}" variantRules must be an array when provided.`);
+  }
+
+  for (const rule of experiment.variantRules) {
+    assertObject(rule, `Variant rule in experiment "${experiment.id}"`);
+    assertNonEmptyString(rule.variant, `Variant rule target in experiment "${experiment.id}"`);
+    if (typeof rule.when !== "function") {
+      throw new Error(`Variant rule "${rule.variant}" in experiment "${experiment.id}" must define a when function.`);
+    }
+  }
+}
+
+function validateAssignment(experiment) {
+  if (experiment.assignment === undefined) {
+    return;
+  }
+
+  assertObject(experiment.assignment, `Experiment "${experiment.id}" assignment`);
+
+  if (experiment.assignment.strategy !== undefined && experiment.assignment.strategy !== "sticky-hash") {
+    throw new Error(`Experiment "${experiment.id}" assignment.strategy must be "sticky-hash" when provided.`);
+  }
+
+  if (experiment.assignment.forceVariant !== undefined && typeof experiment.assignment.forceVariant !== "function") {
+    throw new Error(`Experiment "${experiment.id}" assignment.forceVariant must be a function when provided.`);
+  }
+}
+
+function validateGoal(goal, experimentId) {
+  assertObject(goal, `Goal in experiment "${experimentId}"`);
+  assertNonEmptyString(goal.id, `Goal id in experiment "${experimentId}"`);
+
+  if (goal.gaEventName !== undefined) {
+    assertNonEmptyString(goal.gaEventName, `Goal "${goal.id}" gaEventName in experiment "${experimentId}"`);
+  }
+
+  if (goal.events !== undefined) {
+    if (!Array.isArray(goal.events) || goal.events.length === 0) {
+      throw new Error(`Goal "${goal.id}" events in experiment "${experimentId}" must be a non-empty array.`);
+    }
+    for (const eventName of goal.events) {
+      assertNonEmptyString(eventName, `Goal "${goal.id}" event name in experiment "${experimentId}"`);
+    }
+  }
+
+  if (goal.gaEventName === undefined && goal.events === undefined) {
+    throw new Error(`Goal "${goal.id}" in experiment "${experimentId}" must define gaEventName and/or events.`);
+  }
+}
+
+export function validateExperimentConfig(experiment) {
+  assertObject(experiment, "Experiment");
+  assertNonEmptyString(experiment.id, "Experiment id");
+
+  if (!ALLOWED_STATUSES.has(experiment.status)) {
+    throw new Error(`Experiment "${experiment.id}" status must be one of: draft, active, paused.`);
+  }
+
+  if (!Array.isArray(experiment.variants) || experiment.variants.length < 2) {
+    throw new Error(`Experiment "${experiment.id}" must define at least two variants.`);
+  }
+
+  let totalWeight = 0;
+  const variantIds = new Set();
+  for (const variant of experiment.variants) {
+    validateVariant(variant, experiment.id);
+    if (variantIds.has(variant.id)) {
+      throw new Error(`Experiment "${experiment.id}" has duplicate variant id "${variant.id}".`);
+    }
+    variantIds.add(variant.id);
+    totalWeight += variant.weight;
+  }
+
+  if (totalWeight <= 0) {
+    throw new Error(`Experiment "${experiment.id}" must have a positive total variant weight.`);
+  }
+
+  if (experiment.targeting !== undefined && typeof experiment.targeting !== "function") {
+    throw new Error(`Experiment "${experiment.id}" targeting must be a function when provided.`);
+  }
+
+  if (
+    experiment.mutualExclusionGroup !== undefined &&
+    experiment.mutualExclusionGroup !== null &&
+    typeof experiment.mutualExclusionGroup !== "string"
+  ) {
+    throw new Error(`Experiment "${experiment.id}" mutualExclusionGroup must be a string or null when provided.`);
+  }
+
+  if (experiment.priority !== undefined && typeof experiment.priority !== "number") {
+    throw new Error(`Experiment "${experiment.id}" priority must be a number when provided.`);
+  }
+
+  validateAssignment(experiment);
+  validateVariantRules(experiment);
+
+  if (experiment.goals !== undefined) {
+    if (!Array.isArray(experiment.goals)) {
+      throw new Error(`Experiment "${experiment.id}" goals must be an array when provided.`);
+    }
+
+    for (const goal of experiment.goals) {
+      validateGoal(goal, experiment.id);
+    }
+  }
+
+  if (experiment.variantRules) {
+    for (const rule of experiment.variantRules) {
+      if (!variantIds.has(rule.variant)) {
+        throw new Error(`Experiment "${experiment.id}" variant rule points to unknown variant "${rule.variant}".`);
+      }
+    }
+  }
+}
+
+export function validateExperiments(experiments) {
+  if (!Array.isArray(experiments)) {
+    throw new Error("Experiments must be provided as an array.");
+  }
+
+  const ids = new Set();
+  for (const experiment of experiments) {
+    validateExperimentConfig(experiment);
+
+    if (ids.has(experiment.id)) {
+      throw new Error(`Duplicate experiment id "${experiment.id}" is not allowed.`);
+    }
+    ids.add(experiment.id);
+  }
+
+  return experiments;
+}

package/src/index.js

@@ -0,0 +1,11 @@
+export { defineExperiments } from "./engine/contract.js";
+export { createEngine } from "./engine/runtime.js";
+export { createRuntime, getRuntime, installRuntime } from "./runtime/index.js";
+export {
+  buildGa4ConversionPayload,
+  buildGa4EventPayload,
+  buildGa4ImpressionPayload,
+  createGa4Adapter
+} from "./analytics/ga4.js";
+export { validateExperimentConfig, validateExperiments } from "./experiments/schema.js";
+export { createAssignmentStore } from "./storage/assignment-store.js";

package/src/runtime/index.js

@@ -0,0 +1,100 @@
+import { defineExperiments } from "../engine/contract.js";
+import { createEngine } from "../engine/runtime.js";
+
+const RUNTIME_KEY = Symbol.for("split-tester-client.runtime");
+
+function normalizeDefinitions(definition, runtime) {
+  const resolved =
+    typeof definition === "function"
+      ? definition({
+          runtime,
+          context: runtime.getUserContext(),
+          experiments: runtime.listExperiments()
+        })
+      : definition;
+
+  if (resolved === undefined || resolved === null) {
+    return [];
+  }
+
+  return Array.isArray(resolved) ? resolved : [resolved];
+}
+
+function createQueue(runtime) {
+  return {
+    push(definition) {
+      return runtime.define(definition);
+    }
+  };
+}
+
+export function createRuntime(options = {}) {
+  const engine = createEngine(options);
+
+  const runtime = {
+    getUserContext: options.getUserContext ?? (() => ({ url: { pathname: "/" }, user: {} })),
+
+    define(definition) {
+      const configs = defineExperiments(normalizeDefinitions(definition, runtime));
+      if (configs.length > 0) {
+        engine.registerExperiments(configs);
+      }
+      return configs;
+    },
+
+    defineMany(definitions) {
+      return runtime.define(definitions);
+    },
+
+    listExperiments() {
+      return engine.listExperiments();
+    },
+
+    getActiveExperimentsForPage(context) {
+      return engine.getActiveExperimentsForPage(context);
+    },
+
+    getVariant(experimentId, context) {
+      return engine.getVariant(experimentId, context);
+    },
+
+    trackEvent(eventName, payload, context) {
+      return engine.trackEvent(eventName, payload, context);
+    },
+
+    trackConversion(experimentId, goalId, payload, context) {
+      return engine.trackConversion(experimentId, goalId, payload, context);
+    }
+  };
+
+  return runtime;
+}
+
+export function installRuntime(options = {}, globalScope = globalThis) {
+  const existing = globalScope[RUNTIME_KEY];
+  if (existing) {
+    return existing;
+  }
+
+  const runtime = createRuntime(options);
+  const queue = createQueue(runtime);
+
+  const preexistingQueue = globalScope.splitTesterQueue;
+  if (Array.isArray(preexistingQueue)) {
+    while (preexistingQueue.length > 0) {
+      runtime.define(preexistingQueue.shift());
+    }
+  } else if (typeof preexistingQueue?.drain === "function") {
+    preexistingQueue.drain();
+  }
+
+  globalScope.splitTester = runtime;
+  globalScope.splitTesterQueue = queue;
+  globalScope[RUNTIME_KEY] = runtime;
+
+  return runtime;
+}
+
+export function getRuntime(globalScope = globalThis) {
+  return globalScope[RUNTIME_KEY] ?? globalScope.splitTester ?? null;
+}

package/src/storage/assignment-store.js

@@ -0,0 +1,78 @@
+const sharedMemoryEntries = new Map();
+
+function createMemoryStorage() {
+  return {
+    getItem(key) {
+      return sharedMemoryEntries.has(key) ? sharedMemoryEntries.get(key) : null;
+    },
+    setItem(key, value) {
+      sharedMemoryEntries.set(key, String(value));
+    },
+    removeItem(key) {
+      sharedMemoryEntries.delete(key);
+    }
+  };
+}
+
+function getBrowserStorage() {
+  if (typeof globalThis === "undefined") {
+    return null;
+  }
+
+  try {
+    const storage = globalThis.localStorage;
+    if (!storage) {
+      return null;
+    }
+    const testKey = "__split_tester_test__";
+    storage.setItem(testKey, "1");
+    storage.removeItem(testKey);
+    return storage;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeStorage(storage) {
+  if (!storage) {
+    return createMemoryStorage();
+  }
+
+  if (
+    typeof storage.getItem === "function" &&
+    typeof storage.setItem === "function" &&
+    typeof storage.removeItem === "function"
+  ) {
+    return storage;
+  }
+
+  return createMemoryStorage();
+}
+
+export function createAssignmentStore(storage = getBrowserStorage()) {
+  const backend = normalizeStorage(storage);
+
+  return {
+    get(key) {
+      try {
+        return backend.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        backend.setItem(key, value);
+      } catch {
+        // Ignore storage failures and continue with in-memory assignments.
+      }
+    },
+    delete(key) {
+      try {
+        backend.removeItem(key);
+      } catch {
+        // Ignore storage failures.
+      }
+    }
+  };
+}