@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/stores/adapters/analytics/monitoring.ts

@@ -0,0 +1,164 @@
+// Store Module - Monitoring and Analytics
+// Clean Architecture: Store monitoring and analytics adapter
+
+import type { Store } from "#stores/modules/store/types";
+
+// ============================================
+// MONITORING TYPES
+// ============================================
+
+export interface StoreMetrics {
+	changeCount: number;
+	lastChangeTime: number;
+	averageChangeFrequency: number;
+}
+
+export interface AnalyticsEvent {
+	timestamp: number;
+	type: "state_change" | "subscription" | "unsubscription";
+	storeId: string;
+	data?: unknown;
+}
+
+export interface MonitoringOptions {
+	trackChanges?: boolean;
+	trackSubscriptions?: boolean;
+	maxEvents?: number;
+	onEvent?: (event: AnalyticsEvent) => void;
+}
+
+// ============================================
+// MONITORING ADAPTER
+// ============================================
+
+export const createMonitoringAdapter = <T>(
+	store: Store<T>,
+	options: MonitoringOptions = {},
+	now: number = Date.now(),
+	random: () => number = Math.random,
+) => {
+	const storeId = `store-${now}-${random()}`;
+	const events: AnalyticsEvent[] = [];
+	const metrics: StoreMetrics = {
+		changeCount: 0,
+		lastChangeTime: 0,
+		averageChangeFrequency: 0,
+	};
+
+	const maxEvents = options.maxEvents || 1000;
+
+	const trackEvent = (event: AnalyticsEvent): void => {
+		events.push(event);
+
+		if (events.length > maxEvents) {
+			events.shift();
+		}
+
+		options.onEvent?.(event);
+	};
+
+	// Create monitored store wrapper
+	const monitoredStore: Store<T> = {
+		getState: store.getState,
+		setState: (state: T | ((prev: T) => T), now: number = Date.now()): void => {
+			const startTime = performance.now();
+			store.setState(state);
+			const endTime = performance.now();
+
+			if (options.trackChanges) {
+				metrics.changeCount++;
+				metrics.lastChangeTime = now;
+
+				const timeDiff =
+					metrics.lastChangeTime -
+					(events[0]?.timestamp || metrics.lastChangeTime);
+				if (timeDiff > 0) {
+					metrics.averageChangeFrequency =
+						metrics.changeCount / (timeDiff / 1000);
+				}
+
+				trackEvent({
+					timestamp: now,
+					type: "state_change",
+					storeId,
+					data: {
+						duration: endTime - startTime,
+					},
+				});
+			}
+		},
+		subscribe: (
+			listener: (state: T) => void,
+			now: number = Date.now(),
+		): (() => void) => {
+			if (options.trackSubscriptions) {
+				trackEvent({
+					timestamp: now,
+					type: "subscription",
+					storeId,
+				});
+			}
+
+			const unsubscribe = store.subscribe(listener);
+
+			return (now: number = Date.now()) => {
+				if (options.trackSubscriptions) {
+					trackEvent({
+						timestamp: now,
+						type: "unsubscription",
+						storeId,
+					});
+				}
+				unsubscribe();
+			};
+		},
+	};
+
+	return {
+		store: monitoredStore,
+		getMetrics: () => metrics,
+		getEvents: () => [...events],
+		getEventsByType: (type: AnalyticsEvent["type"]) => {
+			return events.filter((e) => e.type === type);
+		},
+		clearEvents: () => {
+			events.length = 0;
+		},
+		resetMetrics: () => {
+			metrics.changeCount = 0;
+			metrics.lastChangeTime = 0;
+			metrics.averageChangeFrequency = 0;
+		},
+	};
+};
+
+// ============================================
+// ANALYTICS MIDDLEWARE
+// ============================================
+
+export const createAnalyticsMiddleware = (options?: MonitoringOptions) => {
+	const adapters = new Map<
+		Store<any>,
+		ReturnType<typeof createMonitoringAdapter<any>>
+	>();
+
+	return (store: Store<any>) => {
+		const adapter = createMonitoringAdapter(store, options);
+		adapters.set(store, adapter);
+
+		return {
+			getMetrics: () => adapter.getMetrics(),
+			getEvents: () => adapter.getEvents(),
+			getAllMetrics: () => {
+				const allMetrics = new Map<string, StoreMetrics>();
+				adapters.forEach((adapter, store) => {
+					allMetrics.set(
+						JSON.stringify(store.getState()),
+						adapter.getMetrics(),
+					);
+				});
+				return allMetrics;
+			},
+		};
+	};
+};

package/src/stores/adapters/devtools/index.ts

@@ -0,0 +1,80 @@
+// Store Module - DevTools Adapter
+// Clean Architecture: DevTools implementation
+
+import type { IStoreDevtools } from "#stores/modules/store/ports";
+import type { StoreConfig } from "#stores/modules/store/types";
+
+// ============================================
+// DEVTOOLS ADAPTER
+// ============================================
+
+export const createDevtoolsAdapter = (): IStoreDevtools => {
+	const stores = new Map<string, { getState: () => unknown }>();
+	let timeTravelEnabled = false;
+
+	return {
+		registerStore<T>(
+			name: string,
+			store: { getState: () => T },
+			config: StoreConfig,
+		): void {
+			stores.set(name, store);
+
+			if (
+				typeof window !== "undefined" &&
+				(window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__
+			) {
+				const hook = (window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__;
+				hook.emit("init", { name, state: store.getState(), config });
+			}
+		},
+		unregisterStore(name: string): void {
+			stores.delete(name);
+
+			if (
+				typeof window !== "undefined" &&
+				(window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__
+			) {
+				const hook = (window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__;
+				hook.emit("unregister", { name });
+			}
+		},
+		updateStore<T>(name: string, state: T): void {
+			if (timeTravelEnabled) return;
+
+			if (
+				typeof window !== "undefined" &&
+				(window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__
+			) {
+				const hook = (window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__;
+				hook.emit("update", { name, state });
+			}
+		},
+		logAction<T>(
+			name: string,
+			action: string,
+			prevState: T,
+			nextState: T,
+		): void {
+			if (
+				typeof window !== "undefined" &&
+				(window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__
+			) {
+				const hook = (window as any).__SOLID_DEVTOOLS_GLOBAL_HOOK__;
+				hook.emit("action", { name, action, prevState, nextState });
+			}
+		},
+		startTimeTravel(): void {
+			timeTravelEnabled = true;
+		},
+		stopTimeTravel(): void {
+			timeTravelEnabled = false;
+		},
+		jumpToState<T>(name: string, state: T): void {
+			const store = stores.get(name);
+			if (store && typeof (store as any).setState === "function") {
+				(store as any).setState(state);
+			}
+		},
+	};
+};

package/src/stores/adapters/persistence/index.ts

@@ -0,0 +1,5 @@
+// Store Module - Persistence Adapter
+// Clean Architecture: Storage implementation
+
+// Re-export versioning utilities
+export * from "./versioning";

package/src/stores/adapters/persistence/versioning.ts

@@ -0,0 +1,142 @@
+// Store Module - Persistence Versioning
+// Clean Architecture: Schema migration and version management
+
+import type { PersistenceModel } from "#stores/modules/store/domain/models";
+
+// ============================================
+// MIGRATION TYPES
+// ============================================
+
+export type Migration<T, U> = (oldState: T) => U;
+
+export interface SchemaVersion<T> {
+	version: string;
+	migrateTo?: (state: unknown) => T;
+	validate?: (state: unknown) => state is T;
+}
+
+export interface VersionedPersistence<T> {
+	model: PersistenceModel<T>;
+	currentVersion: string;
+	schemaVersions: SchemaVersion<T>[];
+}
+
+// ============================================
+// VERSION REGISTRY
+// ============================================
+
+const versionRegistry = new Map<string, SchemaVersion<any>[]>();
+
+export const registerSchemaVersions = <T>(
+	key: string,
+	versions: SchemaVersion<T>[],
+): void => {
+	versionRegistry.set(key, versions);
+};
+
+export const getSchemaVersions = <T>(key: string): SchemaVersion<T>[] => {
+	return versionRegistry.get(key) || [];
+};
+
+// ============================================
+// MIGRATION HELPER
+// ============================================
+
+export const migrateState = <T>(
+	state: unknown,
+	fromVersion: string,
+	toVersion: string,
+	versions: SchemaVersion<T>[],
+): T => {
+	const fromIndex = versions.findIndex((v) => v.version === fromVersion);
+	const toIndex = versions.findIndex((v) => v.version === toVersion);
+
+	if (fromIndex === -1 || toIndex === -1) {
+		throw new Error(`Invalid version: ${fromVersion} → ${toVersion}`);
+	}
+
+	let currentState = state;
+
+	for (let i = fromIndex; i < toIndex; i++) {
+		const version = versions[i];
+		if (version.migrateTo) {
+			currentState = version.migrateTo(currentState);
+		}
+	}
+
+	return currentState as T;
+};
+
+// ============================================
+// VERSIONED PERSISTENCE
+// ============================================
+
+export const createVersionedPersistence = <T>(
+	key: string,
+	initialState: T,
+	schemaVersions: SchemaVersion<T>[],
+	now: number = Date.now(),
+): VersionedPersistence<T> => {
+	registerSchemaVersions(key, schemaVersions);
+
+	const latestVersion = schemaVersions[schemaVersions.length - 1].version;
+
+	return {
+		model: {
+			key,
+			state: initialState,
+			version: latestVersion,
+			schemaVersion: latestVersion,
+			timestamp: now,
+		},
+		currentVersion: latestVersion,
+		schemaVersions,
+	};
+};
+
+// ============================================
+// LOAD WITH MIGRATION
+// ============================================
+
+export const loadWithMigration = <T>(
+	key: string,
+	loadedModel: PersistenceModel<unknown>,
+	now: number = Date.now(),
+): PersistenceModel<T> => {
+	const versions = getSchemaVersions<T>(key);
+	const currentVersion = loadedModel.schemaVersion || loadedModel.version;
+	const latestVersion = versions[versions.length - 1].version;
+
+	if (currentVersion === latestVersion) {
+		return loadedModel as PersistenceModel<T>;
+	}
+
+	const migratedState = migrateState(
+		loadedModel.state,
+		currentVersion,
+		latestVersion,
+		versions,
+	);
+
+	return {
+		key: loadedModel.key,
+		state: migratedState,
+		version: latestVersion,
+		schemaVersion: latestVersion,
+		timestamp: now,
+	};
+};
+
+// ============================================
+// VALIDATE VERSION
+// ============================================
+
+export const validateVersion = <T>(
+	state: unknown,
+	version: string,
+	versions: SchemaVersion<T>[],
+): boolean => {
+	const versionConfig = versions.find((v) => v.version === version);
+	if (!versionConfig?.validate) return true;
+	return versionConfig.validate(state);
+};

package/src/stores/adapters/router/index.ts

@@ -0,0 +1,144 @@
+// Router Adapter - Integration with @wrikka/solid-framework/router
+// Clean Architecture: Adapter layer for router integration
+
+import { createStore } from "#stores/modules/store";
+import type { Store } from "#stores/modules/store/types";
+
+// Router types (will be imported from @wrikka/solid-framework/router when available)
+export interface Match {
+	readonly path: string;
+	readonly params: Readonly<Record<string, unknown>>;
+	readonly searchParams: Readonly<Record<string, unknown>>;
+}
+
+// ============================================
+// ROUTER STORE SYNC
+// ============================================
+
+export interface RouterSyncOptions<T> {
+	selector?: (state: T) => Record<string, unknown>;
+	onRouteChange?: (match: Match, state: T) => void;
+}
+
+/**
+ * Sync store state with router params
+ */
+export const syncStoreWithRouter = <T>(
+	store: Store<T>,
+	getMatch: () => Match | null,
+	options?: RouterSyncOptions<T>,
+): (() => void) => {
+	const unsubscribe = store.subscribe((state) => {
+		const match = getMatch();
+		if (!match) return;
+
+		// Update route meta based on store state
+		if (options?.selector) {
+			options.selector(state);
+			// Update router meta if needed
+			if (options.onRouteChange) {
+				options.onRouteChange(match, state);
+			}
+		}
+	});
+
+	return unsubscribe;
+};
+
+// ============================================
+// ROUTER PARAMS STORE
+// ============================================
+
+export interface RouterParamsStore {
+	params: Record<string, unknown>;
+	searchParams: Record<string, unknown>;
+	path: string;
+}
+
+/**
+ * Create a store that syncs with router params
+ */
+export const createRouterParamsStore = (
+	getMatch: () => Match | null,
+	now: number,
+): Store<RouterParamsStore> => {
+	const match = getMatch();
+	const initial: RouterParamsStore = {
+		params: match?.params ? { ...match.params } : {},
+		searchParams: match?.searchParams ? { ...match.searchParams } : {},
+		path: match?.path ?? "",
+	};
+	return createStore(initial, {}, now);
+};
+
+// ============================================
+// ROUTER-AWARE ACTIONS
+// ============================================
+
+export interface RouterAction<T = unknown> {
+	type: string;
+	payload?: T;
+	navigate?: string;
+	replace?: boolean;
+}
+
+/**
+ * Create action that can trigger navigation
+ */
+export const createRouterAction = <T = unknown>(
+	type: string,
+	navigateTo?: string,
+): ((payload?: T) => RouterAction<T>) => {
+	return (payload?: T): RouterAction<T> => ({
+		type,
+		payload,
+		navigate: navigateTo,
+	});
+};
+
+// ============================================
+// ROUTER MIDDLEWARE
+// ============================================
+
+export interface RouterMiddlewareOptions {
+	persistState?: boolean;
+	restoreState?: boolean;
+	stateKey?: string;
+}
+
+/**
+ * Middleware to persist/restore state based on route
+ */
+export const createRouterMiddleware = (options?: RouterMiddlewareOptions) => {
+	const {
+		persistState = true,
+		restoreState = true,
+		stateKey = "routeState",
+	} = options || {};
+
+	return {
+		onBeforeNavigation: (match: Match) => {
+			if (restoreState) {
+				// Restore state from storage based on route
+				const stored = sessionStorage.getItem(`${stateKey}:${match.path}`);
+				if (stored) {
+					try {
+						return JSON.parse(stored);
+					} catch {
+						return null;
+					}
+				}
+			}
+			return null;
+		},
+		onAfterNavigation: (match: Match, state: unknown) => {
+			if (persistState) {
+				// Persist state to storage based on route
+				sessionStorage.setItem(
+					`${stateKey}:${match.path}`,
+					JSON.stringify(state),
+				);
+			}
+		},
+	};
+};

package/src/stores/adapters/storage/index.ts

@@ -0,0 +1,6 @@
+// Store Module - Storage Adapters
+// Clean Architecture: Re-export all storage adapters
+
+export * from "./indexed-db";
+export * from "./local-storage";
+export * from "./session-storage";

package/src/stores/adapters/storage/indexed-db.ts

@@ -0,0 +1,83 @@
+// Store Module - Storage Adapters
+// Clean Architecture: IndexedDB implementation
+
+import type { IIndexedDBStorage } from "#stores/modules/store/ports";
+
+export const createIndexedDBAdapter = (): IIndexedDBStorage => {
+	let db: IDBDatabase | null = null;
+
+	return {
+		open: async (dbName: string, version: number): Promise<void> => {
+			return new Promise((resolve, reject) => {
+				const request = indexedDB.open(dbName, version);
+
+				request.onerror = () => reject(request.error);
+				request.onsuccess = () => {
+					db = request.result;
+					resolve();
+				};
+
+				request.onupgradeneeded = (event) => {
+					const database = (event.target as IDBOpenDBRequest).result;
+					if (!database.objectStoreNames.contains("stores")) {
+						database.createObjectStore("stores", { keyPath: "key" });
+					}
+				};
+			});
+		},
+		get: async <T>(storeName: string, key: string): Promise<T | null> => {
+			const database = db;
+			if (!database) return null;
+
+			return new Promise((resolve, reject) => {
+				const transaction = database.transaction([storeName], "readonly");
+				const store = transaction.objectStore(storeName);
+				const request = store.get(key);
+
+				request.onerror = () => reject(request.error);
+				request.onsuccess = () => {
+					resolve(request.result ? (request.result.value as T) : null);
+				};
+			});
+		},
+		set: async <T>(storeName: string, key: string, value: T): Promise<void> => {
+			const database = db;
+			if (!database) return;
+
+			return new Promise((resolve, reject) => {
+				const transaction = database.transaction([storeName], "readwrite");
+				const store = transaction.objectStore(storeName);
+				const request = store.put({ key, value });
+
+				request.onerror = () => reject(request.error);
+				request.onsuccess = () => resolve();
+			});
+		},
+		remove: async (storeName: string, key: string): Promise<void> => {
+			const database = db;
+			if (!database) return;
+
+			return new Promise((resolve, reject) => {
+				const transaction = database.transaction([storeName], "readwrite");
+				const store = transaction.objectStore(storeName);
+				const request = store.delete(key);
+
+				request.onerror = () => reject(request.error);
+				request.onsuccess = () => resolve();
+			});
+		},
+		clear: async (storeName: string): Promise<void> => {
+			const database = db;
+			if (!database) return;
+
+			return new Promise((resolve, reject) => {
+				const transaction = database.transaction([storeName], "readwrite");
+				const store = transaction.objectStore(storeName);
+				const request = store.clear();
+
+				request.onerror = () => reject(request.error);
+				request.onsuccess = () => resolve();
+			});
+		},
+	};
+};

package/src/stores/adapters/storage/local-storage.ts

@@ -0,0 +1,44 @@
+// Store Module - Storage Adapters
+// Clean Architecture: LocalStorage implementation
+
+import type { ILocalStorage } from "#stores/modules/store/ports";
+
+export const createLocalStorageAdapter = (): ILocalStorage => {
+	const storage = typeof window !== "undefined" ? window.localStorage : null;
+
+	return {
+		get: <T>(key: string): T | null => {
+			if (!storage) return null;
+			try {
+				const item = storage.getItem(key);
+				return item ? (JSON.parse(item) as T) : null;
+			} catch {
+				return null;
+			}
+		},
+		set: <T>(key: string, value: T): void => {
+			if (!storage) return;
+			try {
+				storage.setItem(key, JSON.stringify(value));
+			} catch (error) {
+				console.error("Failed to set localStorage item:", error);
+			}
+		},
+		remove: (key: string): void => {
+			if (!storage) return;
+			try {
+				storage.removeItem(key);
+			} catch (error) {
+				console.error("Failed to remove localStorage item:", error);
+			}
+		},
+		clear: (): void => {
+			if (!storage) return;
+			try {
+				storage.clear();
+			} catch (error) {
+				console.error("Failed to clear localStorage:", error);
+			}
+		},
+	};
+};