next-evolve 0.0.0-stage → 0.1.0

package/dist/config/goals.js

@@ -0,0 +1,85 @@
+import { logRateLimited } from "../core/log.js";
+import { GOAL_KEY_RE, serializedGoalSchema } from "@next-evolve/protocol";
+// src/config/goals.ts
+/** Identity helper for `evolve.goals.ts`: types plus validation (throws on mistakes). */
+function defineGoals(goals) {
+	serializeGoals(goals);
+	return goals;
+}
+/**
+* Goal definitions as sent to the cloud. Function values become
+* `{ kind: "local-fn" }`; the function itself never leaves the app.
+*/
+function serializeGoals(goals) {
+	const out = {};
+	for (const [key, def] of Object.entries(goals)) {
+		if (!GOAL_KEY_RE.test(key)) throw new Error(`[evolve] goal key "${key}" must match ${GOAL_KEY_RE}`);
+		if ("sql" in def) throw new Error(`[evolve] goal "${key}": SQL goals aren't supported yet`);
+		const common = {
+			window: def.window ?? "7d",
+			unit: def.unit ?? "visitor",
+			direction: def.direction ?? "increase"
+		};
+		let wire;
+		if ("event" in def && "pageview" in def) throw new Error(`[evolve] goal "${key}": use either event or pageview, not both`);
+		else if ("event" in def) wire = {
+			kind: "event",
+			event: def.event,
+			source: def.source ?? null,
+			where: def.where ?? null,
+			value: typeof def.value === "function" ? { kind: "local-fn" } : typeof def.value === "string" ? {
+				kind: "prop",
+				path: def.value
+			} : null,
+			...common
+		};
+		else if ("pageview" in def) wire = {
+			kind: "pageview",
+			path: def.pageview,
+			value: null,
+			...common
+		};
+		else throw new Error(`[evolve] goal "${key}" needs event or pageview`);
+		const r = serializedGoalSchema.safeParse(wire);
+		if (!r.success) {
+			const what = r.error.issues.map((i) => `${i.path.join(".") || "goal"}: ${i.message}`);
+			throw new Error(`[evolve] goal "${key}" is invalid (${what.join("; ")})`);
+		}
+		out[key] = r.data;
+	}
+	return out;
+}
+/** True if a stored `$pageview` at `path` would count for some pageview goal. */
+function matchesPageviewGoal(goals, path) {
+	if (!goals) return false;
+	for (const def of Object.values(goals)) {
+		if (!("pageview" in def)) continue;
+		const p = def.pageview;
+		if (p.endsWith("*") ? path.startsWith(p.slice(0, -1)) : path === p) return true;
+	}
+	return false;
+}
+/**
+* Runs the `value` functions of matching event goals. Returns `{ goalKey: n }`
+* or null. A function that throws or returns a non-finite number is skipped.
+*/
+function computeGoalValues(goals, e) {
+	if (!goals) return null;
+	let out = null;
+	for (const [key, def] of Object.entries(goals)) {
+		if (!("event" in def) || typeof def.value !== "function" || def.event !== e.name) continue;
+		if (def.source !== void 0 && def.source !== e.source) continue;
+		if (def.where && !Object.entries(def.where).every(([k, v]) => e.props[k] === v)) continue;
+		try {
+			const v = def.value(e);
+			if (typeof v === "number" && Number.isFinite(v)) {
+				out ??= {};
+				out[key] = v;
+			}
+		} catch (err) {
+			logRateLimited(`goal:${key}`, `goal "${key}": value function threw`, err);
+		}
+	}
+	return out;
+}
+export { computeGoalValues, defineGoals, matchesPageviewGoal, serializeGoals };

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+import { EvolveConfig, ResolvedConfig, RouteConfig, defineConfig, resolveConfig } from "./config.js";
+import { EventGoal, GoalDefinition, GoalEvent, GoalWindow, Goals, PageviewGoal, defineGoals, serializeGoals } from "./goals.js";
+export { type EventGoal, type EvolveConfig, type GoalDefinition, type GoalEvent, type GoalWindow, type Goals, type PageviewGoal, type ResolvedConfig, type RouteConfig, defineConfig, defineGoals, resolveConfig, serializeGoals };

package/dist/config/index.js

@@ -0,0 +1,3 @@
+import { defineConfig, resolveConfig } from "./config.js";
+import { defineGoals, serializeGoals } from "./goals.js";
+export { defineConfig, defineGoals, resolveConfig, serializeGoals };

package/dist/core/assign.d.ts

@@ -0,0 +1,23 @@
+import { BundlePayload, CodePair } from "@next-evolve/protocol";
+type Variant = {
+  id: string;
+  w: number;
+};
+/** Picks a variant id for r ∈ [0, 1) proportionally to weight (w > 0 only). */
+export declare function weightedPick(variants: readonly Variant[], r: number): string;
+export type Assignment = {
+  /** Pairs for the variant code (unsorted; `encodeCode` sorts). */
+  pairs: CodePair[];
+  /** Assignments to write back to `evolve_a`. */
+  assigned: Map<string, string>;
+  /** Whether `assigned` differs from the cookie that came in. */
+  changed: boolean;
+};
+/**
+ * Assigns a visitor to the experiments on `path` (spec §6.3). Pure: no I/O.
+ * Sticky: an active assignment is kept. Completed experiments render their
+ * winner and aren't counted. Cookie entries for experiments no longer in the
+ * bundle are pruned.
+ */
+export declare function assign(bundle: BundlePayload, path: string, cookie: ReadonlyMap<string, string>, rand: () => number): Assignment;
+export {};

package/dist/core/assign.js

@@ -0,0 +1,82 @@
+import "./cookies.js";
+// src/core/assign.ts
+/** Picks a variant id for r ∈ [0, 1) proportionally to weight (w > 0 only). */
+function weightedPick(variants, r) {
+	let total = 0;
+	for (const v of variants) if (v.w > 0) total += v.w;
+	let acc = 0;
+	let last = variants[0].id;
+	for (const v of variants) {
+		if (v.w <= 0) continue;
+		acc += v.w / total;
+		last = v.id;
+		if (r < acc) return v.id;
+	}
+	return last;
+}
+/**
+* Assigns a visitor to the experiments on `path` (spec §6.3). Pure: no I/O.
+* Sticky: an active assignment is kept. Completed experiments render their
+* winner and aren't counted. Cookie entries for experiments no longer in the
+* bundle are pruned.
+*/
+function assign(bundle, path, cookie, rand) {
+	const { experiments, routes } = bundle.routing;
+	const assigned = /* @__PURE__ */ new Map();
+	let changed = false;
+	for (const [exp, v] of cookie) if (experiments[exp]) assigned.set(exp, v);
+	else changed = true;
+	const pairs = [];
+	for (const exp of routes[path] ?? []) {
+		const e = experiments[exp];
+		if (!e) continue;
+		if (e.status === "completed") {
+			pairs.push({
+				exp,
+				var: e.winner,
+				counted: false
+			});
+			continue;
+		}
+		const a = assigned.get(exp);
+		if (a === "x") {
+			pairs.push({
+				exp,
+				var: e.control,
+				counted: false
+			});
+			continue;
+		}
+		if (a !== void 0 && e.variants.some((v) => v.id === a && v.w > 0)) {
+			pairs.push({
+				exp,
+				var: a,
+				counted: true
+			});
+			continue;
+		}
+		changed = true;
+		if (rand() >= e.traffic) {
+			assigned.set(exp, "x");
+			pairs.push({
+				exp,
+				var: e.control,
+				counted: false
+			});
+			continue;
+		}
+		const v = weightedPick(e.variants, rand());
+		assigned.set(exp, v);
+		pairs.push({
+			exp,
+			var: v,
+			counted: true
+		});
+	}
+	return {
+		pairs,
+		assigned,
+		changed
+	};
+}
+export { assign, weightedPick };

package/dist/core/bots.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns a detector: `isbot` + empty user agent + configured `extraPatterns`
+ * (regex sources, case-insensitive). Bots get `ev_0` and no cookies.
+ */
+export declare function createBotDetector(extraPatterns?: readonly string[]): (ua: string | null | undefined) => boolean;

package/dist/core/bots.js

@@ -0,0 +1,25 @@
+import { isbot } from "isbot";
+// src/core/bots.ts
+/** Unfurlers and tools `isbot` may not flag; all served control and never counted. */
+const EXTRA = [
+	/whatsapp/i,
+	/telegrambot/i,
+	/chrome-lighthouse/i,
+	/headlesschrome/i,
+	/vercelbot/i,
+	/claude-user/i
+];
+/**
+* Returns a detector: `isbot` + empty user agent + configured `extraPatterns`
+* (regex sources, case-insensitive). Bots get `ev_0` and no cookies.
+*/
+function createBotDetector(extraPatterns = []) {
+	const extra = [...EXTRA, ...extraPatterns.map((p) => new RegExp(p, "i"))];
+	return (ua) => {
+		if (!ua?.trim()) return true;
+		if (isbot(ua)) return true;
+		for (const re of extra) if (re.test(ua)) return true;
+		return false;
+	};
+}
+export { createBotDetector };

package/dist/core/constants.d.ts

@@ -0,0 +1,3 @@
+/** Request headers the proxy sets for dynamic-mode routes. */
+export declare const HEADER_CODE = "x-evolve-a";
+export declare const HEADER_PATH = "x-evolve-path";

package/dist/core/constants.js

@@ -0,0 +1,5 @@
+// src/core/constants.ts
+/** Request headers the proxy sets for dynamic-mode routes. */
+const HEADER_CODE = "x-evolve-a";
+const HEADER_PATH = "x-evolve-path";
+export { HEADER_CODE, HEADER_PATH };

package/dist/core/cookies.d.ts

@@ -0,0 +1,12 @@
+/** Cookie names (spec §6.2). */
+export declare const ANON_COOKIE = "evolve_id";
+export declare const ASSIGN_COOKIE = "evolve_a";
+export declare const PREVIEW_COOKIE = "evolve_pv";
+/** Max experiments remembered in `evolve_a`. */
+export declare const MAX_ASSIGNMENTS = 20;
+/** Assignment value meaning "outside the experiment's traffic share". */
+export declare const EXCLUDED = "x";
+/** Parses `evolve_a` (`exp:var` pairs joined by `.`). Malformed entries are dropped. */
+export declare function parseAssignments(raw: string | undefined): Map<string, string>;
+/** Serializes assignments sorted by experiment id, keeping at most {@link MAX_ASSIGNMENTS}. */
+export declare function serializeAssignments(assigned: ReadonlyMap<string, string>): string;

package/dist/core/cookies.js

@@ -0,0 +1,25 @@
+// src/core/cookies.ts
+/** Cookie names (spec §6.2). */
+const ANON_COOKIE = "evolve_id";
+const ASSIGN_COOKIE = "evolve_a";
+const PREVIEW_COOKIE = "evolve_pv";
+/** Max experiments remembered in `evolve_a`. */
+const MAX_ASSIGNMENTS = 20;
+/** Assignment value meaning "outside the experiment's traffic share". */
+const EXCLUDED = "x";
+const ENTRY_RE = /^([a-z0-9]{6}):([a-z0-9]{6}|x)$/;
+/** Parses `evolve_a` (`exp:var` pairs joined by `.`). Malformed entries are dropped. */
+function parseAssignments(raw) {
+	const out = /* @__PURE__ */ new Map();
+	if (!raw) return out;
+	for (const entry of raw.split(".")) {
+		const m = ENTRY_RE.exec(entry);
+		if (m && !out.has(m[1]) && out.size < 20) out.set(m[1], m[2]);
+	}
+	return out;
+}
+/** Serializes assignments sorted by experiment id, keeping at most {@link MAX_ASSIGNMENTS}. */
+function serializeAssignments(assigned) {
+	return [...assigned].sort(([a], [b]) => a < b ? -1 : 1).slice(0, 20).map(([e, v]) => `${e}:${v}`).join(".");
+}
+export { ANON_COOKIE, ASSIGN_COOKIE, EXCLUDED, MAX_ASSIGNMENTS, PREVIEW_COOKIE, parseAssignments, serializeAssignments };

package/dist/core/keys.d.ts

@@ -0,0 +1,14 @@
+import { KeyRing } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
+/**
+ * Public keys this app trusts for bundles and preview tokens: Evolve Cloud's
+ * production keys, plus an optional test key for local development and the
+ * fake cloud.
+ *
+ * `EVOLVE_UNSAFE_TEST_PUBLIC_KEY=<kid>:<x>` is ignored when
+ * NODE_ENV=production, unless `EVOLVE_UNSAFE_ALLOW_TEST_KEY=1` is also set
+ * (needed only to run SDK e2e tests against a production build).
+ */
+export declare function trustedKeySet(env?: Env): Record<string, string>;
+export declare function trustedKeys(env?: Env): KeyRing;
+export {};

package/dist/core/keys.js

@@ -0,0 +1,38 @@
+import { EVOLVE_PUBLIC_KEYS, createKeyRing } from "@next-evolve/protocol";
+// src/core/keys.ts
+let warned = false;
+/**
+* Public keys this app trusts for bundles and preview tokens: Evolve Cloud's
+* production keys, plus an optional test key for local development and the
+* fake cloud.
+*
+* `EVOLVE_UNSAFE_TEST_PUBLIC_KEY=<kid>:<x>` is ignored when
+* NODE_ENV=production, unless `EVOLVE_UNSAFE_ALLOW_TEST_KEY=1` is also set
+* (needed only to run SDK e2e tests against a production build).
+*/
+function trustedKeySet(env = process.env) {
+	const keys = { ...EVOLVE_PUBLIC_KEYS };
+	const test = env.EVOLVE_UNSAFE_TEST_PUBLIC_KEY;
+	if (!test) return keys;
+	const prod = env.NODE_ENV === "production";
+	if (prod && env.EVOLVE_UNSAFE_ALLOW_TEST_KEY !== "1") {
+		if (!warned) {
+			warned = true;
+			console.error("[evolve] EVOLVE_UNSAFE_TEST_PUBLIC_KEY is ignored in production.");
+		}
+		return keys;
+	}
+	const m = /^([A-Za-z0-9_.-]{1,64}):([A-Za-z0-9_-]{43})$/.exec(test);
+	if (!m) {
+		console.error("[evolve] EVOLVE_UNSAFE_TEST_PUBLIC_KEY must be <kid>:<base64url x>; ignored.");
+		return keys;
+	}
+	if (m[1] in keys) return keys;
+	if (prod) console.error("[evolve] UNSAFE: trusting a test signing key in a production build.");
+	keys[m[1]] = m[2];
+	return keys;
+}
+function trustedKeys(env = process.env) {
+	return createKeyRing(trustedKeySet(env));
+}
+export { trustedKeySet, trustedKeys };

package/dist/core/log.d.ts

@@ -0,0 +1,2 @@
+/** Logs at most once per `intervalMs` per key (default 60 s), so a hot path can't flood logs. */
+export declare function logRateLimited(key: string, message: string, err?: unknown, intervalMs?: number): void;

package/dist/core/log.js

@@ -0,0 +1,10 @@
+// src/core/log.ts
+const last = /* @__PURE__ */ new Map();
+/** Logs at most once per `intervalMs` per key (default 60 s), so a hot path can't flood logs. */
+function logRateLimited(key, message, err, intervalMs = 6e4) {
+	const now = Date.now();
+	if ((last.get(key) ?? 0) + intervalMs > now) return;
+	last.set(key, now);
+	console.error(`[evolve] ${message}`, ...err === void 0 ? [] : [err]);
+}
+export { logRateLimited };

package/dist/db/client.d.ts

@@ -0,0 +1,22 @@
+import postgres from "postgres";
+export type Sql = postgres.Sql;
+type Env = Record<string, string | undefined>;
+/** True on hosts where each request may run in a fresh, short-lived instance. */
+export declare function isServerless(env?: Env): boolean;
+/**
+ * Opens a connection pool. Prepared statements are off so pooled endpoints
+ * (Neon's `-pooler` host, PgBouncer in transaction mode) work.
+ */
+export declare function createSql(url: string, opts?: {
+  env?: Env;
+  max?: number;
+  debug?: postgres.Options<Record<string, never>>["debug"];
+}): Sql;
+/**
+ * The process-wide pool for the customer DB, created on first use. Null when
+ * the URL variable isn't set. The proxy never imports this module.
+ */
+export declare function getSql(urlEnv?: string, env?: Env): Sql | null;
+/** Closes every pool (tests, CLI). */
+export declare function closeAllSql(): Promise<void>;
+export {};

package/dist/db/client.js

@@ -0,0 +1,50 @@
+import postgres from "postgres";
+// src/db/client.ts
+/** True on hosts where each request may run in a fresh, short-lived instance. */
+function isServerless(env = process.env) {
+	return Boolean(env.VERCEL || env.AWS_LAMBDA_FUNCTION_NAME || env.NETLIFY);
+}
+/**
+* Opens a connection pool. Prepared statements are off so pooled endpoints
+* (Neon's `-pooler` host, PgBouncer in transaction mode) work.
+*/
+function createSql(url, opts = {}) {
+	return postgres(url, {
+		max: opts.max ?? (isServerless(opts.env) ? 1 : 10),
+		prepare: false,
+		idle_timeout: 20,
+		connect_timeout: 10,
+		onnotice: () => {},
+		connection: { application_name: "next-evolve" },
+		...opts.debug ? { debug: opts.debug } : {}
+	});
+}
+const POOLS = Symbol.for("next-evolve.sql");
+const pools = () => {
+	const g = globalThis;
+	g[POOLS] ??= /* @__PURE__ */ new Map();
+	return g[POOLS];
+};
+/**
+* The process-wide pool for the customer DB, created on first use. Null when
+* the URL variable isn't set. The proxy never imports this module.
+*/
+function getSql(urlEnv = "EVOLVE_DATABASE_URL", env = process.env) {
+	const url = env[urlEnv];
+	if (!url) return null;
+	const all = pools();
+	let sql = all.get(url);
+	if (!sql) {
+		sql = createSql(url, { env });
+		all.set(url, sql);
+	}
+	return sql;
+}
+/** Closes every pool (tests, CLI). */
+async function closeAllSql() {
+	const all = pools();
+	const list = [...all.values()];
+	all.clear();
+	await Promise.all(list.map((s) => s.end({ timeout: 5 })));
+}
+export { closeAllSql, createSql, getSql, isServerless };

package/dist/db/migrate.d.ts

@@ -0,0 +1,18 @@
+import { Sql } from "./client.js";
+/** Shipped with the package: `next-evolve/migrations/*.sql`. */
+export declare const MIGRATIONS_DIR: URL;
+export type Migration = {
+  id: string;
+  sql: string;
+};
+export type MigrateResult = {
+  applied: string[];
+  skipped: string[];
+};
+export declare function loadMigrations(dir?: URL): Promise<Migration[]>;
+/**
+ * Applies pending migrations in order, all in one transaction under an
+ * advisory lock, so concurrent runs (several instances booting) are safe and
+ * a failure leaves nothing half-applied. Idempotent.
+ */
+export declare function migrate(sql: Sql, migrations?: Migration[]): Promise<MigrateResult>;

package/dist/db/migrate.js

@@ -0,0 +1,43 @@
+import { readFile, readdir } from "node:fs/promises";
+// src/db/migrate.ts
+/** Shipped with the package: `next-evolve/migrations/*.sql`. */
+const MIGRATIONS_DIR = new URL("../../migrations/", import.meta.url);
+const LOCK_KEY = 1702260588;
+async function loadMigrations(dir = MIGRATIONS_DIR) {
+	const files = (await readdir(dir)).filter((f) => /^\d{4}_[a-z0-9_]+\.sql$/.test(f)).sort();
+	return Promise.all(files.map(async (f) => ({
+		id: f.replace(/\.sql$/, ""),
+		sql: await readFile(new URL(f, dir), "utf8")
+	})));
+}
+/**
+* Applies pending migrations in order, all in one transaction under an
+* advisory lock, so concurrent runs (several instances booting) are safe and
+* a failure leaves nothing half-applied. Idempotent.
+*/
+async function migrate(sql, migrations) {
+	const list = migrations ?? await loadMigrations();
+	return sql.begin(async (tx) => {
+		await tx`select pg_advisory_xact_lock(${LOCK_KEY})`;
+		await tx`create schema if not exists evolve`;
+		await tx`create table if not exists evolve.migrations (
+      id text primary key, applied_at timestamptz not null default now())`;
+		const done = new Set((await tx`select id from evolve.migrations`).map((r) => r.id));
+		const applied = [];
+		const skipped = [];
+		for (const m of list) {
+			if (done.has(m.id)) {
+				skipped.push(m.id);
+				continue;
+			}
+			await tx.unsafe(m.sql);
+			await tx`insert into evolve.migrations (id) values (${m.id})`;
+			applied.push(m.id);
+		}
+		return {
+			applied,
+			skipped
+		};
+	});
+}
+export { MIGRATIONS_DIR, loadMigrations, migrate };

package/dist/db/writer.d.ts

@@ -0,0 +1,51 @@
+import { Sql } from "./client.js";
+type Json = Record<string, unknown>;
+export type ExposureRow = {
+  experiment_id: string;
+  anon_id: string;
+  variant_id: string;
+  path: string;
+};
+export type EventRow = {
+  ts: Date;
+  name: string;
+  anon_id: string | null;
+  user_id: string | null;
+  value: number | null;
+  goal_values: Json | null;
+  props: Json | null;
+  source: string;
+  path: string | null;
+  dedupe_key: string | null;
+};
+export type IdentityRow = {
+  anon_id: string;
+  user_id: string;
+};
+export type WriterOptions = {
+  sql: () => Sql | null;
+  /** node: flush on a timer / row count and keep rows while the DB is down. serverless: flush per request. */
+  mode?: "node" | "serverless";
+  flushMs?: number;
+  flushRows?: number;
+  maxBuffer?: number;
+};
+export type Writer = {
+  readonly mode: "node" | "serverless";
+  exposures(rows: ExposureRow[]): void;
+  events(rows: EventRow[]): void;
+  identities(rows: IdentityRow[]): void;
+  /** Adds tested page views to a UTC day (`YYYY-MM-DD`). */
+  usage(day: string, pageviews: number): void;
+  /** Rows waiting to be written. */
+  pending(): number;
+  /** Writes everything queued so far: one insert per table (chunked at 1,000 rows). */
+  flush(): Promise<void>;
+};
+export declare function createWriter(opts: WriterOptions): Writer;
+/**
+ * The process-wide writer for a DB URL variable. On long-running Node it also
+ * flushes on SIGTERM so a graceful shutdown doesn't lose buffered rows.
+ */
+export declare function getWriter(sql: () => Sql | null, key?: string): Writer;
+export {};