@ubean/server 0.1.12 → 0.2.0

package/dist/feature-flags-CdLwsMD2.js

@@ -0,0 +1,657 @@
+//#region src/analytics.ts
+/** log provider:输出到 console */
+function createLogAnalyticsProvider() {
+	return {
+		name: "log",
+		track(event, properties, context) {
+			const summary = {
+				event,
+				...properties
+			};
+			if (Object.keys(context).length > 0) summary.context = context;
+			console.log("[analytics]", JSON.stringify(summary));
+		}
+	};
+}
+/** memory provider:存储在内存,用于测试 */
+function createMemoryAnalyticsProvider() {
+	const records = [];
+	return {
+		name: "memory",
+		records,
+		track(event, properties, context) {
+			records.push({
+				event,
+				type: event === "page_view" ? "page_view" : "event",
+				timestamp: Date.now(),
+				properties: { ...properties },
+				context: { ...context }
+			});
+		},
+		flush: async () => {},
+		destroy() {
+			records.length = 0;
+		},
+		clear() {
+			records.length = 0;
+		}
+	};
+}
+/** mock provider:记录调用次数,用于断言 */
+function createMockAnalyticsProvider(impl) {
+	const calls = [];
+	return {
+		name: impl?.name || "mock",
+		calls,
+		get callCount() {
+			return calls.length;
+		},
+		track(event, properties, context) {
+			calls.push({
+				event,
+				properties: { ...properties },
+				context: { ...context }
+			});
+			impl?.track?.(event, properties, context);
+		},
+		flush: impl?.flush,
+		destroy: impl?.destroy,
+		reset() {
+			calls.length = 0;
+		}
+	};
+}
+const providerRegistry = /* @__PURE__ */ new Map();
+let globalProvider = null;
+/** 注册一个 provider 到全局 registry */
+function registerAnalyticsProvider(provider) {
+	providerRegistry.set(provider.name, provider);
+}
+/** 取消注册 */
+function unregisterAnalyticsProvider(name) {
+	providerRegistry.delete(name);
+}
+/** 从 registry 获取指定名称的 provider */
+function getAnalyticsProvider(name) {
+	return providerRegistry.get(name);
+}
+/** 获取所有已注册的 provider */
+function listAnalyticsProviders() {
+	return Array.from(providerRegistry.values());
+}
+/** 清空 registry(主要供测试使用) */
+function clearAnalyticsProviders() {
+	providerRegistry.clear();
+	globalProvider = null;
+}
+/** 设置全局默认 provider */
+function setGlobalAnalyticsProvider(provider) {
+	globalProvider = provider;
+}
+/** 获取全局默认 provider(若未设置,返回空 provider) */
+function getGlobalAnalyticsProvider() {
+	if (globalProvider) return globalProvider;
+	const fallback = createLogAnalyticsProvider();
+	globalProvider = fallback;
+	return fallback;
+}
+/** 从 Hono 上下文中自动抽取 analytics context */
+function extractAnalyticsContext(c) {
+	const path = c.req.path;
+	const method = c.req.method;
+	const referrer = c.req.header("referer") || c.req.header("referrer") || void 0;
+	const userAgent = c.req.header("user-agent") || void 0;
+	const locale = c.req.header("accept-language") || void 0;
+	const requestId = c.get("requestId") || void 0;
+	const ip = c.req.header("x-forwarded-for")?.split(",")[0].trim() || c.req.header("x-real-ip") || void 0;
+	const ctxLocale = c.get("locale") || locale;
+	return {
+		path,
+		method,
+		status: c.res?.status,
+		referrer,
+		userAgent,
+		locale: ctxLocale,
+		requestId,
+		ip
+	};
+}
+function resolveProviders(provider) {
+	const source = provider ?? getGlobalAnalyticsProvider();
+	if (Array.isArray(source)) return source;
+	return [source];
+}
+/**
+* 跟踪一次页面浏览
+*/
+async function trackPageView(c, options = {}) {
+	const { autoContext = true, properties = {}, eventName = "page_view", awaitFlush = false } = options;
+	const context = autoContext ? extractAnalyticsContext(c) : {};
+	const providers = resolveProviders();
+	const tasks = providers.map((p) => p.track(eventName, properties, context));
+	if (awaitFlush) {
+		await Promise.all(tasks);
+		await Promise.all(providers.map((p) => p.flush?.()));
+	} else Promise.all(tasks).catch(() => {});
+}
+/**
+* 跟踪一次自定义事件
+*/
+async function trackEvent(c, name, properties = {}) {
+	const context = extractAnalyticsContext(c);
+	const tasks = resolveProviders().map((p) => p.track(name, properties, context));
+	Promise.all(tasks).catch(() => {});
+}
+/** 直接调用 provider 跟踪事件(无 Hono 上下文) */
+async function trackRaw(event, properties = {}, context = {}, provider) {
+	const providers = resolveProviders(provider);
+	await Promise.all(providers.map((p) => p.track(event, properties, context)));
+}
+/**
+* 定义一个 analytics provider,并注册到全局 registry
+*
+* @example
+* ```ts
+* const provider = defineAnalyticsProvider({
+*   name: 'posthog',
+*   track(event, properties, context) {
+*     await fetch('https://app.posthog.com/capture/', { ... });
+*   }
+* });
+* ```
+*/
+function defineAnalyticsProvider(options) {
+	if (!options.name) throw new Error("[ubean/analytics] AnalyticsProvider requires a `name`");
+	const provider = {
+		name: options.name,
+		track: options.track,
+		flush: options.flush,
+		destroy: options.destroy
+	};
+	registerAnalyticsProvider(provider);
+	return provider;
+}
+function isExcluded(path, exclude) {
+	if (!exclude || exclude.length === 0) return false;
+	return exclude.some((pattern) => {
+		if (pattern.endsWith("/**")) return path.startsWith(pattern.slice(0, -3));
+		if (pattern.endsWith("/*")) {
+			const prefix = pattern.slice(0, -2);
+			return path.startsWith(prefix) && !path.slice(prefix.length).includes("/");
+		}
+		return path === pattern;
+	});
+}
+/**
+* 创建 analytics 中间件,自动跟踪页面浏览
+*
+* @example
+* ```ts
+* const memory = createMemoryAnalyticsProvider();
+* app.use('*', createAnalyticsMiddleware({ provider: memory }));
+* ```
+*/
+function createAnalyticsMiddleware(options = {}) {
+	const { provider, methods = ["GET"], exclude = [], trackAllStatus = false, shouldTrack, getProperties, eventName = "page_view" } = options;
+	const normalizedMethods = new Set(methods.map((m) => m.toUpperCase()));
+	return async function analyticsMiddleware(c, next) {
+		if (isExcluded(c.req.path, exclude)) {
+			await next();
+			return;
+		}
+		if (!normalizedMethods.has(c.req.method.toUpperCase())) {
+			await next();
+			return;
+		}
+		if (shouldTrack && !await shouldTrack(c)) {
+			await next();
+			return;
+		}
+		const start = Date.now();
+		let error = void 0;
+		try {
+			await next();
+		} catch (err) {
+			error = err;
+		}
+		const duration = Date.now() - start;
+		const status = c.res?.status ?? 200;
+		if (trackAllStatus || status >= 200 && status < 400) {
+			const context = extractAnalyticsContext(c);
+			context.status = status;
+			context.duration = duration;
+			const extraProperties = getProperties ? await getProperties(c) : {};
+			const tasks = resolveProviders(provider).map((p) => p.track(eventName, extraProperties, context));
+			Promise.all(tasks).catch(() => {});
+		}
+		if (error !== void 0) throw error;
+	};
+}
+/** 定义 analytics 中间件(等同于 createAnalyticsMiddleware) */
+function defineAnalytics(options) {
+	return createAnalyticsMiddleware(options);
+}
+/** 从上下文获取 analytics provider(便于在 handler 中手动 track) */
+function useAnalytics(c, provider) {
+	const buildContext = () => c ? extractAnalyticsContext(c) : {};
+	return {
+		trackPageView(properties = {}) {
+			const ctx = buildContext();
+			const providers = resolveProviders(provider);
+			Promise.all(providers.map((p) => p.track("page_view", properties, ctx))).catch(() => {});
+		},
+		trackEvent(name, properties = {}) {
+			const ctx = buildContext();
+			const providers = resolveProviders(provider);
+			Promise.all(providers.map((p) => p.track(name, properties, ctx))).catch(() => {});
+		}
+	};
+}
+//#endregion
+//#region src/feature-flags.ts
+function createMemoryFeatureFlagStore() {
+	const flags = /* @__PURE__ */ new Map();
+	const experiments = /* @__PURE__ */ new Map();
+	return {
+		async getFlag(name) {
+			return flags.get(name);
+		},
+		async setFlag(name, flag) {
+			flags.set(name, flag);
+		},
+		async deleteFlag(name) {
+			flags.delete(name);
+		},
+		async listFlags() {
+			return Array.from(flags.values());
+		},
+		async getExperiment(name) {
+			return experiments.get(name);
+		},
+		async setExperiment(name, exp) {
+			experiments.set(name, exp);
+		},
+		async deleteExperiment(name) {
+			experiments.delete(name);
+		},
+		async listExperiments() {
+			return Array.from(experiments.values());
+		}
+	};
+}
+const flagRegistry = /* @__PURE__ */ new Map();
+const experimentRegistry = /* @__PURE__ */ new Map();
+let globalStore = null;
+/** 设置全局 feature flag store */
+function setGlobalFeatureFlagStore(store) {
+	globalStore = store;
+}
+/** 获取全局 store(默认内存 store) */
+function getGlobalFeatureFlagStore() {
+	if (!globalStore) globalStore = createMemoryFeatureFlagStore();
+	return globalStore;
+}
+/** 清空全局 store 和 registry(供测试使用) */
+function clearFeatureFlags() {
+	flagRegistry.clear();
+	experimentRegistry.clear();
+	globalStore = null;
+}
+/**
+* 简单的字符串哈希(FNV-1a 32-bit),用于一致性分配
+* 同样的输入始终产生同样的输出,无副作用
+*/
+function hashString(input) {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+}
+/** 返回 0-99 的整数(基于 hash 输入的稳定百分比) */
+function hashToBucket(hashInput) {
+	return hashString(hashInput) % 100;
+}
+/** 生成一致性哈希的输入 key */
+function buildHashKey(name, identity, salt) {
+	return `${name}:${salt || ""}:${identity}`;
+}
+function resolveIdentity(context) {
+	if (!context) return "anonymous";
+	return context.userId || context.anonymousId || context.sessionId || "anonymous";
+}
+function matchRule(rule, context) {
+	const attrValue = context[rule.attribute];
+	switch (rule.operator) {
+		case "eq": return attrValue === rule.value;
+		case "neq": return attrValue !== rule.value;
+		case "in": return Array.isArray(rule.values) && rule.values.includes(attrValue);
+		case "not_in": return !Array.isArray(rule.values) || !rule.values.includes(attrValue);
+		case "contains":
+			if (typeof attrValue !== "string" || typeof rule.value !== "string") return false;
+			return attrValue.includes(rule.value);
+		case "gt": return typeof attrValue === "number" && typeof rule.value === "number" && attrValue > rule.value;
+		case "lt": return typeof attrValue === "number" && typeof rule.value === "number" && attrValue < rule.value;
+		case "gte": return typeof attrValue === "number" && typeof rule.value === "number" && attrValue >= rule.value;
+		case "lte": return typeof attrValue === "number" && typeof rule.value === "number" && attrValue <= rule.value;
+		case "exists": return attrValue !== void 0 && attrValue !== null;
+		case "not_exists": return attrValue === void 0 || attrValue === null;
+		default: return false;
+	}
+}
+function matchSegment(segment, context) {
+	if (segment.enabled === false) return false;
+	if (!segment.rules || segment.rules.length === 0) return true;
+	return segment.rules.every((rule) => matchRule(rule, context));
+}
+function matchAnySegment(segments, context) {
+	if (!segments || segments.length === 0) return true;
+	return segments.some((seg) => matchSegment(seg, context));
+}
+function pickVariant(variants, hashInput) {
+	if (variants.length === 0) return void 0;
+	const totalWeight = variants.reduce((sum, v) => sum + Math.max(0, v.weight), 0);
+	if (totalWeight <= 0) return variants[0];
+	const bucket = hashString(hashInput) % totalWeight;
+	let acc = 0;
+	for (const v of variants) {
+		acc += Math.max(0, v.weight);
+		if (bucket < acc) return v;
+	}
+	return variants[variants.length - 1];
+}
+/**
+* 定义一个 feature flag,注册到全局 registry 和 store
+*
+* @example
+* ```ts
+* defineFeatureFlag('new_dashboard', {
+*   kind: 'percentage',
+*   percentage: 50,
+*   defaultValue: false
+* });
+*
+* defineFeatureFlag('checkout_flow', {
+*   kind: 'multivariate',
+*   variants: [
+*     { key: 'control', weight: 1, value: 'v1' },
+*     { key: 'treatment', weight: 1, value: 'v2' }
+*   ],
+*   defaultValue: 'v1'
+* });
+* ```
+*/
+function defineFeatureFlag(name, options = {}) {
+	const def = {
+		name,
+		kind: options.kind || "boolean",
+		defaultValue: options.defaultValue ?? (options.kind === "multivariate" ? "" : false),
+		variants: options.variants,
+		percentage: options.percentage,
+		segments: options.segments,
+		enabled: options.enabled ?? true,
+		description: options.description,
+		salt: options.salt
+	};
+	flagRegistry.set(name, def);
+	getGlobalFeatureFlagStore().setFlag(name, def);
+	return def;
+}
+/**
+* 定义一个 A/B 测试实验,注册到全局 registry 和 store
+*
+* @example
+* ```ts
+* defineExperiment('checkout_v2_test', {
+*   variants: [
+*     { key: 'control', weight: 1, value: 'A' },
+*     { key: 'treatment', weight: 1, value: 'B' }
+*   ],
+*   traffic: 50
+* });
+* ```
+*/
+function defineExperiment(name, options) {
+	const def = {
+		name,
+		description: options.description,
+		variants: options.variants,
+		traffic: options.traffic ?? 100,
+		segments: options.segments,
+		enabled: options.enabled ?? true,
+		salt: options.salt
+	};
+	experimentRegistry.set(name, def);
+	getGlobalFeatureFlagStore().setExperiment(name, def);
+	return def;
+}
+/** 解析 flag 定义(优先 registry,次选 store) */
+async function resolveFlag(name, store) {
+	if (flagRegistry.has(name)) return flagRegistry.get(name);
+	return (store || getGlobalFeatureFlagStore()).getFlag(name);
+}
+async function resolveExperiment(name, store) {
+	if (experimentRegistry.has(name)) return experimentRegistry.get(name);
+	return (store || getGlobalFeatureFlagStore()).getExperiment(name);
+}
+/**
+* 评估一个 flag,返回 boolean 或 variant value
+*
+* - boolean flag:返回 true / false
+* - percentage flag:返回 true / false(基于用户身份的稳定百分比)
+* - multivariate flag:返回选中的 variant value
+*/
+async function evaluateFlag(name, context = {}, store) {
+	return (await evaluateFlagWithReason(name, context, store)).value;
+}
+/** 评估 flag 并返回原因(用于调试 / debug) */
+async function evaluateFlagWithReason(name, context = {}, store) {
+	const flag = await resolveFlag(name, store);
+	if (!flag) return {
+		name,
+		kind: "boolean",
+		value: false,
+		reason: "default"
+	};
+	if (flag.enabled === false) return {
+		name,
+		kind: flag.kind,
+		value: flag.defaultValue,
+		reason: "disabled"
+	};
+	if (flag.segments && flag.segments.length > 0 && !matchAnySegment(flag.segments, context)) return {
+		name,
+		kind: flag.kind,
+		value: flag.defaultValue,
+		reason: "segment"
+	};
+	const hashKey = buildHashKey(name, resolveIdentity(context), flag.salt);
+	switch (flag.kind) {
+		case "boolean": return {
+			name,
+			kind: "boolean",
+			value: true,
+			reason: "enabled"
+		};
+		case "percentage": {
+			const pct = typeof flag.percentage === "number" ? Math.max(0, Math.min(100, flag.percentage)) : 0;
+			if (hashToBucket(hashKey) < pct) return {
+				name,
+				kind: "percentage",
+				value: true,
+				reason: "percentage"
+			};
+			return {
+				name,
+				kind: "percentage",
+				value: false,
+				reason: "percentage"
+			};
+		}
+		case "multivariate": {
+			if (!flag.variants || flag.variants.length === 0) return {
+				name,
+				kind: "multivariate",
+				value: flag.defaultValue,
+				reason: "default"
+			};
+			const variant = pickVariant(flag.variants, hashKey);
+			return {
+				name,
+				kind: "multivariate",
+				value: variant?.value ?? variant?.key ?? flag.defaultValue,
+				reason: "variant",
+				variant: variant?.key
+			};
+		}
+		default: return {
+			name,
+			kind: "boolean",
+			value: flag.defaultValue,
+			reason: "default"
+		};
+	}
+}
+/**
+* 获取一个实验分配给当前用户的 variant key
+*/
+async function getVariant(name, context = {}, store) {
+	return (await getVariantAssignment(name, context, store)).variant;
+}
+/** 获取实验分配详情(用于调试) */
+async function getVariantAssignment(name, context = {}, store) {
+	const exp = await resolveExperiment(name, store);
+	if (!exp) return {
+		name,
+		variant: "",
+		inExperiment: false,
+		reason: "no_variants"
+	};
+	if (exp.enabled === false) return {
+		name,
+		variant: "",
+		inExperiment: false,
+		reason: "disabled"
+	};
+	if (!exp.variants || exp.variants.length === 0) return {
+		name,
+		variant: "",
+		inExperiment: false,
+		reason: "no_variants"
+	};
+	if (exp.segments && exp.segments.length > 0 && !matchAnySegment(exp.segments, context)) return {
+		name,
+		variant: "",
+		inExperiment: false,
+		reason: "segment"
+	};
+	const traffic = typeof exp.traffic === "number" ? Math.max(0, Math.min(100, exp.traffic)) : 100;
+	const hashKey = buildHashKey(name, resolveIdentity(context), exp.salt);
+	if (hashToBucket(hashKey) >= traffic) return {
+		name,
+		variant: "",
+		inExperiment: false,
+		reason: "traffic"
+	};
+	return {
+		name,
+		variant: pickVariant(exp.variants, hashKey)?.key || "",
+		inExperiment: true,
+		reason: "enabled"
+	};
+}
+/** 默认从 Hono 上下文提取 flag context */
+function extractFlagContext(c) {
+	const userId = c.get("userId") || void 0;
+	const sessionId = c.get("sessionId") || void 0;
+	const locale = c.get("locale") || void 0;
+	const ip = c.req.header("x-forwarded-for")?.split(",")[0].trim() || c.req.header("x-real-ip") || void 0;
+	const cookieHeader = c.req.header("cookie") || "";
+	let anonymousId;
+	const match = cookieHeader.match(/(?:^|;\s*)ubean_aid=([^;]+)/);
+	if (match) anonymousId = match[1];
+	return {
+		userId,
+		sessionId,
+		locale,
+		ip,
+		anonymousId
+	};
+}
+/**
+* 创建 feature flags 中间件,把 flag/experiment 评估附加到 context
+*
+* @example
+* ```ts
+* app.use('*', createFeatureFlagsMiddleware());
+*
+* app.get('/', (c) => {
+*   const flags = useFlags(c);
+*   if (flags.new_dashboard) {
+*     return c.render('dashboard-v2');
+*   }
+*   return c.render('dashboard');
+* });
+* ```
+*/
+function createFeatureFlagsMiddleware(options = {}) {
+	const { store, getContext, flagsVarKey = "flags", experimentsVarKey = "experiments" } = options;
+	return async function featureFlagsMiddleware(c, next) {
+		const flagContext = getContext ? await getContext(c) : extractFlagContext(c);
+		const s = store || getGlobalFeatureFlagStore();
+		const allFlags = await s.listFlags();
+		const flags = {};
+		for (const flag of allFlags) flags[flag.name] = await evaluateFlag(flag.name, flagContext, s);
+		c.set(flagsVarKey, flags);
+		const allExperiments = await s.listExperiments();
+		const experiments = {};
+		for (const exp of allExperiments) {
+			const assignment = await getVariantAssignment(exp.name, flagContext, s);
+			experiments[exp.name] = assignment.variant;
+		}
+		c.set(experimentsVarKey, experiments);
+		c.set("flagContext", flagContext);
+		await next();
+	};
+}
+/** 从 Hono 上下文中获取所有 flag(由中间件写入) */
+function useFlags(c) {
+	return c.get("flags") || {};
+}
+/** 从 Hono 上下文中获取所有 experiment 分配 */
+function useExperiments(c) {
+	return c.get("experiments") || {};
+}
+/** 获取当前请求的 flag context(由中间件写入) */
+function useFlagContext(c) {
+	return c.get("flagContext") || {};
+}
+/** 在 handler 中即时评估一个 flag(如果未启用中间件也可用) */
+async function evaluateFlagFromContext(c, name, store) {
+	return evaluateFlag(name, c.get("flagContext") || extractFlagContext(c), store);
+}
+/** 在 handler 中即时获取一个实验的 variant(如果未启用中间件也可用) */
+async function getVariantFromContext(c, name, store) {
+	return getVariant(name, c.get("flagContext") || extractFlagContext(c), store);
+}
+/** 列出所有已注册的 flag 名称 */
+function listFlagNames() {
+	return Array.from(flagRegistry.keys());
+}
+/** 列出所有已注册的 experiment 名称 */
+function listExperimentNames() {
+	return Array.from(experimentRegistry.keys());
+}
+/** 从 registry 中删除一个 flag */
+function removeFeatureFlag(name) {
+	flagRegistry.delete(name);
+	getGlobalFeatureFlagStore().deleteFlag(name);
+}
+/** 从 registry 中删除一个实验 */
+function removeExperiment(name) {
+	experimentRegistry.delete(name);
+	getGlobalFeatureFlagStore().deleteExperiment(name);
+}
+//#endregion
+export { getAnalyticsProvider as A, createAnalyticsMiddleware as C, defineAnalytics as D, createMockAnalyticsProvider as E, trackEvent as F, trackPageView as I, trackRaw as L, listAnalyticsProviders as M, registerAnalyticsProvider as N, defineAnalyticsProvider as O, setGlobalAnalyticsProvider as P, unregisterAnalyticsProvider as R, clearAnalyticsProviders as S, createMemoryAnalyticsProvider as T, removeFeatureFlag as _, defineFeatureFlag as a, useFlagContext as b, evaluateFlagWithReason as c, getVariant as d, getVariantAssignment as f, removeExperiment as g, listFlagNames as h, defineExperiment as i, getGlobalAnalyticsProvider as j, extractAnalyticsContext as k, extractFlagContext as l, listExperimentNames as m, createFeatureFlagsMiddleware as n, evaluateFlag as o, getVariantFromContext as p, createMemoryFeatureFlagStore as r, evaluateFlagFromContext as s, clearFeatureFlags as t, getGlobalFeatureFlagStore as u, setGlobalFeatureFlagStore as v, createLogAnalyticsProvider as w, useFlags as x, useExperiments as y, useAnalytics as z };