@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/router/modules/route-feature-flags/domain/models/index.ts

@@ -0,0 +1,102 @@
+export interface FeatureFlagCondition {
+	readonly type: "user-segment" | "time-based" | "custom";
+	readonly value: unknown;
+}
+
+export type FeatureFlag = {
+	readonly name: string;
+	readonly enabled: boolean;
+	readonly rolloutPercentage?: number;
+	readonly conditions?: readonly FeatureFlagCondition[];
+	readonly dependencies?: readonly string[];
+	readonly description?: string;
+	readonly metadata?: Readonly<Record<string, unknown>>;
+};
+
+export interface UserSegment {
+	readonly name: string;
+	readonly users: readonly string[];
+	readonly rules: readonly ((userId: string) => boolean)[];
+}
+
+export interface AuditLogEntry {
+	readonly timestamp: Date;
+	readonly flag: string;
+	readonly action: string;
+	readonly userId?: string;
+	readonly result: boolean;
+}
+
+export type FeatureFlagState = {
+	readonly flags: Readonly<Record<string, FeatureFlag>>;
+	readonly routeFlags: Readonly<Record<string, readonly string[]>>;
+	readonly userSegments: Readonly<Record<string, UserSegment>>;
+	readonly auditLog: readonly AuditLogEntry[];
+};
+
+// Pure function to create initial feature flag state
+export const createFeatureFlagState = (): FeatureFlagState => {
+	return Object.freeze({
+		flags: Object.freeze({}),
+		routeFlags: Object.freeze({}),
+		userSegments: Object.freeze({}),
+		auditLog: Object.freeze([]),
+	});
+};
+
+// Pure function to create feature flag
+export const createFeatureFlag = (
+	name: string,
+	enabled: boolean,
+	options: Partial<FeatureFlag> = {},
+): FeatureFlag => {
+	return Object.freeze({
+		name,
+		enabled,
+		...(options.rolloutPercentage !== undefined && {
+			rolloutPercentage: options.rolloutPercentage,
+		}),
+		...(options.conditions !== undefined && {
+			conditions: Object.freeze(options.conditions),
+		}),
+		...(options.dependencies !== undefined && {
+			dependencies: Object.freeze(options.dependencies),
+		}),
+		...(options.description !== undefined && {
+			description: options.description,
+		}),
+		...(options.metadata !== undefined && {
+			metadata: Object.freeze(options.metadata),
+		}),
+	});
+};
+
+// Pure function to create user segment
+export const createUserSegment = (
+	name: string,
+	users: string[],
+	rules: ((userId: string) => boolean)[],
+): UserSegment => {
+	return Object.freeze({
+		name,
+		users: Object.freeze(users),
+		rules: Object.freeze(rules),
+	});
+};
+
+// Pure function to create audit log entry
+export const createAuditLogEntry = (
+	flag: string,
+	action: string,
+	result: boolean,
+	now: Date,
+	userId?: string,
+): AuditLogEntry => {
+	return Object.freeze({
+		timestamp: now,
+		flag,
+		action,
+		result,
+		...(userId !== undefined && { userId }),
+	});
+};

package/src/router/modules/route-feature-flags/domain/operations/feature-flag-audit.ts

@@ -0,0 +1,37 @@
+import type { AuditLogEntry, FeatureFlagState } from "../models";
+import { createAuditLogEntry } from "../models";
+
+// Helper function to add audit log entry
+export const addAuditLogEntry = (
+	auditLog: readonly AuditLogEntry[],
+	flag: string,
+	action: string,
+	result: boolean,
+	now: Date,
+	userId?: string,
+): readonly AuditLogEntry[] => {
+	const newEntry = createAuditLogEntry(flag, action, result, now, userId);
+	const newLog = [...auditLog, newEntry];
+
+	// Keep only last 1000 entries
+	if (newLog.length > 1000) {
+		return Object.freeze(newLog.slice(-1000));
+	}
+
+	return Object.freeze(newLog);
+};
+
+// Pure function to get audit log
+export const getAuditLog = (
+	state: FeatureFlagState,
+	flagName?: string,
+	limit = 100,
+): readonly AuditLogEntry[] => {
+	let logs = state.auditLog;
+
+	if (flagName) {
+		logs = logs.filter((log) => log.flag === flagName);
+	}
+
+	return logs.slice(-limit);
+};

package/src/router/modules/route-feature-flags/domain/operations/feature-flag-conditions.ts

@@ -0,0 +1,52 @@
+import { evaluateTimeCondition } from "../../../../shared/utils/time-condition";
+import type { FeatureFlagState } from "../models";
+
+// Helper function to evaluate condition
+export const evaluateCondition = (
+	state: FeatureFlagState,
+	condition: import("../models").FeatureFlagCondition,
+	userId: string,
+	now: Date,
+): boolean => {
+	switch (condition.type) {
+		case "user-segment":
+			return isUserInSegment(state, condition.value as string, userId);
+		case "time-based":
+			return evaluateTimeCondition(condition.value, now);
+		case "custom":
+			return true;
+		default:
+			return true;
+	}
+};
+
+// Helper function to check if user is in segment
+export const isUserInSegment = (
+	state: FeatureFlagState,
+	segmentName: string,
+	userId: string,
+): boolean => {
+	const segment = state.userSegments[segmentName];
+	if (!segment) return false;
+
+	// Check if user is explicitly in segment
+	if (segment.users.includes(userId)) return true;
+
+	// Check segment rules
+	for (const rule of segment.rules) {
+		if (rule(userId)) return true;
+	}
+
+	return false;
+};
+
+// Helper function to hash user ID
+export const hashUserId = (userId: string): number => {
+	let hash = 0;
+	for (let i = 0; i < userId.length; i++) {
+		const char = userId.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	return Math.abs(hash);
+};

package/src/router/modules/route-feature-flags/domain/operations/feature-flag-flags.ts

@@ -0,0 +1,205 @@
+import type { FeatureFlag, FeatureFlagState } from "../models";
+import { addAuditLogEntry } from "./feature-flag-audit";
+import { evaluateCondition, hashUserId } from "./feature-flag-conditions";
+
+// Pure function to set flag
+export const setFlag = (
+	state: FeatureFlagState,
+	flag: FeatureFlag,
+	now: Date,
+): FeatureFlagState => {
+	const newFlags = { ...state.flags, [flag.name]: flag };
+	const newAuditLog = addAuditLogEntry(
+		state.auditLog,
+		flag.name,
+		"set",
+		flag.enabled,
+		now,
+	);
+
+	return {
+		...state,
+		flags: Object.freeze(newFlags),
+		auditLog: Object.freeze(newAuditLog),
+	};
+};
+
+// Pure function to get flag
+export const getFlag = (
+	state: FeatureFlagState,
+	name: string,
+): FeatureFlag | undefined => {
+	return state.flags[name];
+};
+
+// Pure function to check if flag is enabled
+export const isEnabled = (
+	state: FeatureFlagState,
+	name: string,
+	now: Date,
+	userId?: string,
+): { readonly result: boolean; readonly state: FeatureFlagState } => {
+	const flag = state.flags[name];
+	if (!flag) {
+		const newAuditLog = addAuditLogEntry(
+			state.auditLog,
+			name,
+			"check",
+			false,
+			now,
+			userId,
+		);
+		return {
+			result: false,
+			state: { ...state, auditLog: Object.freeze(newAuditLog) },
+		};
+	}
+
+	if (!flag.enabled) {
+		const newAuditLog = addAuditLogEntry(
+			state.auditLog,
+			name,
+			"check",
+			false,
+			now,
+			userId,
+		);
+		return {
+			result: false,
+			state: { ...state, auditLog: Object.freeze(newAuditLog) },
+		};
+	}
+
+	// Check dependencies
+	if (flag.dependencies) {
+		for (const dep of flag.dependencies) {
+			const depCheck = isEnabled(state, dep, now, userId);
+			if (!depCheck.result) {
+				const newAuditLog = addAuditLogEntry(
+					state.auditLog,
+					name,
+					"check",
+					false,
+					now,
+					userId,
+				);
+				return {
+					result: false,
+					state: { ...state, auditLog: Object.freeze(newAuditLog) },
+				};
+			}
+		}
+	}
+
+	// Check conditions
+	if (flag.conditions && userId) {
+		for (const condition of flag.conditions) {
+			if (!evaluateCondition(state, condition, userId, now)) {
+				const newAuditLog = addAuditLogEntry(
+					state.auditLog,
+					name,
+					"check",
+					false,
+					now,
+					userId,
+				);
+				return {
+					result: false,
+					state: { ...state, auditLog: Object.freeze(newAuditLog) },
+				};
+			}
+		}
+	}
+
+	// Check rollout percentage
+	if (flag.rolloutPercentage && userId) {
+		const hash = hashUserId(userId);
+		const result = hash % 100 < flag.rolloutPercentage;
+		const newAuditLog = addAuditLogEntry(
+			state.auditLog,
+			name,
+			"check",
+			result,
+			now,
+			userId,
+		);
+		return {
+			result,
+			state: { ...state, auditLog: Object.freeze(newAuditLog) },
+		};
+	}
+
+	const newAuditLog = addAuditLogEntry(
+		state.auditLog,
+		name,
+		"check",
+		true,
+		now,
+		userId,
+	);
+	return {
+		result: true,
+		state: { ...state, auditLog: Object.freeze(newAuditLog) },
+	};
+};
+
+// Pure function to toggle flag
+export const toggleFlag = (
+	state: FeatureFlagState,
+	name: string,
+	now: Date,
+): { readonly result: boolean; readonly state: FeatureFlagState } => {
+	const flag = state.flags[name];
+	if (!flag) {
+		return { result: false, state };
+	}
+
+	const newFlag = { ...flag, enabled: !flag.enabled };
+	const newFlags = { ...state.flags, [name]: newFlag };
+	const newAuditLog = addAuditLogEntry(
+		state.auditLog,
+		name,
+		"toggle",
+		newFlag.enabled,
+		now,
+	);
+
+	return {
+		result: true,
+		state: {
+			...state,
+			flags: Object.freeze(newFlags),
+			auditLog: Object.freeze(newAuditLog),
+		},
+	};
+};
+
+// Pure function to delete flag
+export const deleteFlag = (
+	state: FeatureFlagState,
+	name: string,
+	now: Date,
+): { readonly result: boolean; readonly state: FeatureFlagState } => {
+	if (!state.flags[name]) {
+		return { result: false, state };
+	}
+
+	const newFlags = { ...state.flags };
+	delete newFlags[name];
+	const newAuditLog = addAuditLogEntry(
+		state.auditLog,
+		name,
+		"delete",
+		false,
+		now,
+	);
+
+	return {
+		result: true,
+		state: {
+			...state,
+			flags: Object.freeze(newFlags),
+			auditLog: Object.freeze(newAuditLog),
+		},
+	};
+};

package/src/router/modules/route-feature-flags/domain/operations/feature-flag-routes.ts

@@ -0,0 +1,54 @@
+import type { FeatureFlagState } from "../models";
+import { isEnabled } from "./feature-flag-flags";
+
+// Pure function to add route flag
+export const addRouteFlag = (
+	state: FeatureFlagState,
+	routePath: string,
+	flagName: string,
+): FeatureFlagState => {
+	const existing = state.routeFlags[routePath] || [];
+	const newRouteFlags = {
+		...state.routeFlags,
+		[routePath]: [...existing, flagName],
+	};
+
+	return {
+		...state,
+		routeFlags: Object.freeze(newRouteFlags),
+	};
+};
+
+// Pure function to check if route is enabled
+export const isRouteEnabled = (
+	state: FeatureFlagState,
+	routePath: string,
+	now: Date,
+	userId?: string,
+): { readonly result: boolean; readonly state: FeatureFlagState } => {
+	const flags = state.routeFlags[routePath] || [];
+	let currentState = state;
+
+	for (const flagName of flags) {
+		const check = isEnabled(currentState, flagName, now, userId);
+		if (!check.result) {
+			return { result: false, state: check.state };
+		}
+		currentState = check.state;
+	}
+
+	return { result: true, state: currentState };
+};
+
+// Pure function to filter routes by flags
+export const filterRoutesByFlags = (
+	state: FeatureFlagState,
+	routes: import("../../../../shared/types").RouteConfig[],
+	now: Date,
+	userId?: string,
+): import("../../../../shared/types").RouteConfig[] => {
+	return routes.filter((route) => {
+		const check = isRouteEnabled(state, route.path, now, userId);
+		return check.result;
+	});
+};

package/src/router/modules/route-feature-flags/domain/operations/feature-flag-segments.ts

@@ -0,0 +1,22 @@
+import type { FeatureFlagState, UserSegment } from "../models";
+
+// Pure function to add user segment
+export const addUserSegment = (
+	state: FeatureFlagState,
+	segment: UserSegment,
+): FeatureFlagState => {
+	const newUserSegments = { ...state.userSegments, [segment.name]: segment };
+
+	return {
+		...state,
+		userSegments: Object.freeze(newUserSegments),
+	};
+};
+
+// Pure function to get user segment
+export const getUserSegment = (
+	state: FeatureFlagState,
+	name: string,
+): UserSegment | undefined => {
+	return state.userSegments[name];
+};

package/src/router/modules/route-feature-flags/domain/operations/feature-flag-statistics.ts

@@ -0,0 +1,22 @@
+import type { FeatureFlagState } from "../models";
+
+// Pure function to get flag statistics
+export const getFlagStatistics = (
+	state: FeatureFlagState,
+): {
+	readonly totalFlags: number;
+	readonly enabledFlags: number;
+	readonly flagsWithRollout: number;
+	readonly flagsWithConditions: number;
+} => {
+	const flags = Object.values(state.flags);
+	return {
+		totalFlags: flags.length,
+		enabledFlags: flags.filter((f) => f.enabled).length,
+		flagsWithRollout: flags.filter((f) => f.rolloutPercentage !== undefined)
+			.length,
+		flagsWithConditions: flags.filter(
+			(f) => f.conditions && f.conditions.length > 0,
+		).length,
+	};
+};

package/src/router/modules/route-feature-flags/domain/operations/index.ts

@@ -0,0 +1,6 @@
+export * from "./feature-flag-audit";
+export * from "./feature-flag-conditions";
+export * from "./feature-flag-flags";
+export * from "./feature-flag-routes";
+export * from "./feature-flag-segments";
+export * from "./feature-flag-statistics";

package/src/router/modules/route-feature-flags/domain/validators/index.ts

@@ -0,0 +1,40 @@
+import type { FeatureFlag, FeatureFlagCondition, UserSegment } from "../models";
+
+export const validateFeatureFlag = (flag: FeatureFlag): boolean => {
+	if (!flag.name || typeof flag.name !== "string") return false;
+	if (typeof flag.enabled !== "boolean") return false;
+	if (
+		flag.rolloutPercentage !== undefined &&
+		(typeof flag.rolloutPercentage !== "number" ||
+			flag.rolloutPercentage < 0 ||
+			flag.rolloutPercentage > 100)
+	)
+		return false;
+	if (flag.conditions && !Array.isArray(flag.conditions)) return false;
+	if (flag.dependencies && !Array.isArray(flag.dependencies)) return false;
+	return true;
+};
+
+export const validateUserSegment = (segment: UserSegment): boolean => {
+	if (!segment.name || typeof segment.name !== "string") return false;
+	if (!Array.isArray(segment.users)) return false;
+	if (!Array.isArray(segment.rules)) return false;
+	return true;
+};
+
+export const validateFeatureFlagCondition = (
+	condition: FeatureFlagCondition,
+): boolean => {
+	const validTypes = ["user-segment", "time-based", "custom"];
+	if (!validTypes.includes(condition.type)) return false;
+	return true;
+};
+
+export const validateRolloutPercentage = (percentage: number): boolean => {
+	return typeof percentage === "number" && percentage >= 0 && percentage <= 100;
+};
+
+export const validateFlagName = (name: string): boolean => {
+	if (!name || typeof name !== "string") return false;
+	return /^[a-z][a-z0-9-]*$/.test(name);
+};

package/src/router/modules/route-feature-flags/index.ts

@@ -0,0 +1,8 @@
+// Public API exports for route-feature-flags module
+
+export * from "./application/usecases";
+export * from "./domain/models";
+export * from "./domain/operations";
+export * from "./domain/validators";
+export * from "./ports";
+export * from "./types";

package/src/router/modules/route-feature-flags/ports/index.ts

@@ -0,0 +1,23 @@
+import type { AuditLogEntry, FeatureFlag, UserSegment } from "../types";
+
+// Port for feature flag storage (dependency injection point)
+export interface IFeatureFlagStorage {
+	saveFlag(flag: FeatureFlag): Promise<void>;
+	getFlag(name: string): Promise<FeatureFlag | undefined>;
+	deleteFlag(name: string): Promise<void>;
+	getAllFlags(): Promise<FeatureFlag[]>;
+}
+
+// Port for user segment storage (dependency injection point)
+export interface IUserSegmentStorage {
+	saveSegment(segment: UserSegment): Promise<void>;
+	getSegment(name: string): Promise<UserSegment | undefined>;
+	deleteSegment(name: string): Promise<void>;
+	getAllSegments(): Promise<UserSegment[]>;
+}
+
+// Port for audit logging (dependency injection point)
+export interface IAuditLogger {
+	log(entry: AuditLogEntry): Promise<void>;
+	getLogs(flagName?: string, limit?: number): Promise<AuditLogEntry[]>;
+}

package/src/router/modules/route-feature-flags/types/index.ts

@@ -0,0 +1,7 @@
+export type {
+	AuditLogEntry,
+	FeatureFlag,
+	FeatureFlagCondition,
+	FeatureFlagState,
+	UserSegment,
+} from "../domain";

package/src/router/modules/route-i18n/application/usecases/index.ts

@@ -0,0 +1,81 @@
+import { addRouteTranslation, setLocale } from "../../domain/models";
+import {
+	delocalizePath,
+	detectLocale,
+	formatRoute,
+	getAllLocalePaths,
+	getLocalizedRoutes,
+	getRouteTranslation,
+	localizePath,
+} from "../../domain/operations";
+import type { I18nState, Locale } from "../../types";
+
+// Use case: Set current locale
+export const setLocaleUseCase = (
+	state: I18nState,
+	locale: Locale,
+): I18nState => {
+	return setLocale(state, locale);
+};
+
+// Use case: Detect locale from request
+export const detectLocaleUseCase = (
+	state: I18nState,
+	path: string,
+	headers?: Record<string, string>,
+): Locale => {
+	return detectLocale(state, path, headers);
+};
+
+// Use case: Add route translation
+export const addRouteTranslationUseCase = (
+	state: I18nState,
+	translation: { path: string; translations: Record<string, string> },
+): I18nState => {
+	return addRouteTranslation(state, translation);
+};
+
+// Use case: Get localized path
+export const getLocalizedPathUseCase = (
+	state: I18nState,
+	path: string,
+	locale: Locale,
+): string => {
+	const translatedPath = getRouteTranslation(state, path, locale);
+	return translatedPath || localizePath(state, path, locale);
+};
+
+// Use case: Delocalize path (remove locale prefix)
+export const delocalizePathUseCase = (
+	state: I18nState,
+	path: string,
+): string => {
+	return delocalizePath(state, path);
+};
+
+// Use case: Get all localized versions of a path
+export const getAllLocalePathsUseCase = (
+	state: I18nState,
+	path: string,
+): Record<string, string> => {
+	return getAllLocalePaths(state, path);
+};
+
+// Use case: Format route with parameters
+export const formatRouteUseCase = (
+	state: I18nState,
+	path: string,
+	params: Record<string, string>,
+	locale?: Locale,
+): string => {
+	return formatRoute(state, path, params, locale);
+};
+
+// Use case: Localize all routes
+export const localizeRoutesUseCase = (
+	state: I18nState,
+	routes: import("../../../../shared/types").RouteConfig[],
+	locale: Locale,
+): import("../../../../shared/types").RouteConfig[] => {
+	return getLocalizedRoutes(state, routes, locale);
+};