export type FeatureFlagTenantSize = "1-10" | "11-25" | "26-50" | "51-100" | "100+"; export type FeatureFlagRolloutTenant = { readonly id: string; readonly createdAt: string; readonly size?: FeatureFlagTenantSize | null; readonly industry?: string | null; readonly status?: string | null; readonly subscriptionProductIds?: readonly string[]; }; export type FeatureFlagRolloutCriteria = { readonly tenantSize?: FeatureFlagTenantSize; readonly tenantIndustry?: string; readonly tenantStatus?: string; readonly subscriptionProductId?: string; readonly tenantCreatedAfter?: string; readonly tenantCreatedBefore?: string; readonly tenantIdIn?: readonly string[]; readonly tenantIdNotIn?: readonly string[]; }; export type FeatureFlagRolloutFilter = { readonly id: string; readonly name: string; readonly priority: number; readonly value: boolean; readonly active: boolean; readonly createdAt: string; readonly criteria: FeatureFlagRolloutCriteria; }; export type FeatureFlagRolloutOverride = { readonly tenantId: string; readonly value: boolean; readonly expiresAt?: string | null; }; export type FeatureFlagRolloutDecision = { readonly value: boolean; readonly source: "override" | "filter" | "default"; readonly filterId: string | null; }; export type FeatureFlagRolloutPreview = { readonly enabled: number; readonly disabled: number; readonly overrides: number; readonly filtered: number; readonly defaulted: number; readonly rows: readonly { readonly tenantId: string; readonly decision: FeatureFlagRolloutDecision; }[]; }; export function evaluateFeatureFlagRollout(input: { readonly tenant: FeatureFlagRolloutTenant; readonly defaultValue: boolean; readonly filters: readonly FeatureFlagRolloutFilter[]; readonly override?: FeatureFlagRolloutOverride | null; readonly now?: Date; }): FeatureFlagRolloutDecision { const now = input.now ?? new Date(); if (input.override && !isExpired(input.override.expiresAt, now)) { return { value: input.override.value, source: "override", filterId: null }; } const matchingFilter = [...input.filters] .filter((filter) => filter.active && matchesFeatureFlagCriteria(input.tenant, filter.criteria)) .sort(compareFilters)[0]; if (matchingFilter) { return { value: matchingFilter.value, source: "filter", filterId: matchingFilter.id }; } return { value: input.defaultValue, source: "default", filterId: null }; } export function buildFeatureFlagRolloutPreview(input: { readonly tenants: readonly FeatureFlagRolloutTenant[]; readonly defaultValue: boolean; readonly filters: readonly FeatureFlagRolloutFilter[]; readonly overrides: readonly FeatureFlagRolloutOverride[]; readonly now?: Date; }): FeatureFlagRolloutPreview { const now = input.now ?? new Date(); const overrideByTenant = new Map(input.overrides.map((override) => [override.tenantId, override])); const rows = [...input.tenants] .sort((left, right) => left.id.localeCompare(right.id)) .map((tenant) => ({ tenantId: tenant.id, decision: evaluateFeatureFlagRollout({ tenant, defaultValue: input.defaultValue, filters: input.filters, override: overrideByTenant.get(tenant.id), now, }), })); return { enabled: rows.filter((row) => row.decision.value).length, disabled: rows.filter((row) => !row.decision.value).length, overrides: rows.filter((row) => row.decision.source === "override").length, filtered: rows.filter((row) => row.decision.source === "filter").length, defaulted: rows.filter((row) => row.decision.source === "default").length, rows, }; } export function matchesFeatureFlagCriteria(tenant: FeatureFlagRolloutTenant, criteria: FeatureFlagRolloutCriteria): boolean { if (criteria.tenantSize !== undefined && tenant.size !== criteria.tenantSize) return false; if (criteria.tenantIndustry !== undefined && tenant.industry !== criteria.tenantIndustry) return false; if (criteria.tenantStatus !== undefined && tenant.status !== criteria.tenantStatus) return false; if ( criteria.subscriptionProductId !== undefined && !(tenant.subscriptionProductIds ?? []).includes(criteria.subscriptionProductId) ) { return false; } if (criteria.tenantCreatedAfter !== undefined && compareIso(tenant.createdAt, criteria.tenantCreatedAfter) <= 0) return false; if (criteria.tenantCreatedBefore !== undefined && compareIso(tenant.createdAt, criteria.tenantCreatedBefore) >= 0) return false; if (criteria.tenantIdIn !== undefined && !criteria.tenantIdIn.includes(tenant.id)) return false; if (criteria.tenantIdNotIn !== undefined && criteria.tenantIdNotIn.includes(tenant.id)) return false; return true; } function compareFilters(left: FeatureFlagRolloutFilter, right: FeatureFlagRolloutFilter): number { return right.priority - left.priority || compareIso(left.createdAt, right.createdAt) || left.id.localeCompare(right.id); } function compareIso(left: string, right: string): number { const leftTime = Date.parse(left); const rightTime = Date.parse(right); if (!Number.isFinite(leftTime) || !Number.isFinite(rightTime)) { throw new Error("Feature flag rollout dates must be valid ISO timestamps"); } return leftTime - rightTime; } function isExpired(expiresAt: string | null | undefined, now: Date): boolean { if (!expiresAt) return false; const timestamp = Date.parse(expiresAt); if (!Number.isFinite(timestamp)) throw new Error("Feature flag override expiry must be a valid ISO timestamp"); return timestamp <= now.getTime(); }