@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/stores/modules/store/domain/operations/transactions.ts

@@ -0,0 +1,198 @@
+// Store Module - Transaction Operations
+// Clean Architecture: Atomic multi-store updates with rollback
+
+import type { Store } from "#stores/modules/store/types";
+
+// ============================================
+// TRANSACTION TYPES
+// ============================================
+
+export interface TransactionContext<T> {
+	stores: Store<T>[];
+	initialStates: T[];
+	isolationLevel: "read-committed" | "repeatable-read" | "serializable";
+}
+
+export interface Transaction<T> {
+	context: TransactionContext<T>;
+	commit: () => void;
+	rollback: () => void;
+	isActive: boolean;
+}
+
+// ============================================
+// TRANSACTION MANAGER
+// ============================================
+
+export class TransactionManager {
+	private activeTransactions = new Map<string, Transaction<any>>();
+
+	beginTransaction<T>(
+		stores: Store<T>[],
+		id: string,
+		isolationLevel:
+			| "read-committed"
+			| "repeatable-read"
+			| "serializable" = "read-committed",
+	): Transaction<T> {
+		const transactionId = id;
+		const initialStates = stores.map((store) => store.getState());
+
+		const context: TransactionContext<T> = {
+			stores,
+			initialStates,
+			isolationLevel,
+		};
+
+		const transaction: Transaction<T> = {
+			context,
+			commit: () => {
+				this.activeTransactions.delete(transactionId);
+			},
+			rollback: () => {
+				context.stores.forEach((store, index) => {
+					store.setState(context.initialStates[index]);
+				});
+				this.activeTransactions.delete(transactionId);
+			},
+			isActive: true,
+		};
+
+		this.activeTransactions.set(transactionId, transaction);
+		return transaction;
+	}
+
+	getTransaction<T>(transactionId: string): Transaction<T> | undefined {
+		return this.activeTransactions.get(transactionId);
+	}
+
+	rollbackAll(): void {
+		this.activeTransactions.forEach((transaction) => {
+			transaction.rollback();
+		});
+		this.activeTransactions.clear();
+	}
+}
+
+// ============================================
+// TRANSACTION HELPER
+// ============================================
+
+export const withTransaction = async <T>(
+	stores: Store<T>[],
+	operation: (context: TransactionContext<T>) => Promise<void> | void,
+	id: string,
+	options?: {
+		isolationLevel?: "read-committed" | "repeatable-read" | "serializable";
+		onError?: (error: Error) => void;
+	},
+): Promise<void> => {
+	const manager = new TransactionManager();
+	const transaction = manager.beginTransaction(
+		stores,
+		id,
+		options?.isolationLevel || "read-committed",
+	);
+
+	try {
+		await operation(transaction.context);
+		transaction.commit();
+	} catch (error) {
+		transaction.rollback();
+		options?.onError?.(error as Error);
+		throw error;
+	}
+};
+
+// ============================================
+// BATCH TRANSACTION
+// ============================================
+
+export const batchTransaction = async <T>(
+	stores: Store<T>[],
+	updates: Array<(store: Store<T>) => void>,
+	id: string,
+	options?: {
+		isolationLevel?: "read-committed" | "repeatable-read" | "serializable";
+		onError?: (error: Error) => void;
+	},
+): Promise<void> => {
+	return withTransaction(
+		stores,
+		(context) => {
+			context.stores.forEach((store, index) => {
+				if (updates[index]) {
+					updates[index](store);
+				}
+			});
+		},
+		id,
+		options,
+	);
+};
+
+// ============================================
+// TRANSACTION QUEUE
+// ============================================
+
+export class TransactionQueue {
+	private queue: Array<() => Promise<void>> = [];
+	private isProcessing = false;
+
+	async enqueue<T>(operation: () => Promise<T>): Promise<T> {
+		return new Promise((resolve, reject) => {
+			this.queue.push(async () => {
+				try {
+					const result = await operation();
+					resolve(result);
+				} catch (error) {
+					reject(error);
+				}
+			});
+
+			this.process();
+		});
+	}
+
+	private async process(): Promise<void> {
+		if (this.isProcessing || this.queue.length === 0) return;
+
+		this.isProcessing = true;
+
+		while (this.queue.length > 0) {
+			const operation = this.queue.shift();
+			if (operation) {
+				await operation();
+			}
+		}
+
+		this.isProcessing = false;
+	}
+
+	clear(): void {
+		this.queue = [];
+		this.isProcessing = false;
+	}
+}
+
+// ============================================
+// TRANSACTION ISOLATION
+// ============================================
+
+export const applyIsolationLevel = <T>(
+	context: TransactionContext<T>,
+): void => {
+	switch (context.isolationLevel) {
+		case "read-committed":
+			// Default behavior - each read sees committed data
+			break;
+		case "repeatable-read":
+			// Ensure reads are consistent within transaction
+			// In a real implementation, this would involve snapshot isolation
+			break;
+		case "serializable":
+			// Highest isolation - transactions appear to execute sequentially
+			// In a real implementation, this would involve locking
+			break;
+	}
+};

package/src/stores/modules/store/domain/validators/action-validators.ts

@@ -0,0 +1,20 @@
+// Store Module - Domain Validators
+// Clean Architecture: Action validation functions
+
+import type { StoreActionModel } from "#stores/modules/store/domain/models";
+
+export const validateActionType = (type: unknown): boolean =>
+	typeof type === "string";
+
+export const validateActionModel = <T>(
+	model: unknown,
+): model is StoreActionModel<T> => {
+	if (typeof model !== "object" || model === null) return false;
+	const m = model as Record<string, unknown>;
+	return (
+		typeof m.action === "object" &&
+		typeof m.timestamp === "number" &&
+		m.previousState !== undefined &&
+		m.nextState !== undefined
+	);
+};

package/src/stores/modules/store/domain/validators/history-validators.ts

@@ -0,0 +1,19 @@
+// Store Module - Domain Validators
+// Clean Architecture: History validation functions
+
+import type { StoreHistoryModel } from "#stores/modules/store/domain/models";
+
+export const validateHistoryModel = <T>(
+	model: unknown,
+): model is StoreHistoryModel<T> => {
+	if (typeof model !== "object" || model === null) return false;
+	const m = model as Record<string, unknown>;
+	return (
+		typeof m.history === "object" &&
+		Array.isArray((m.history as Record<string, unknown>).past) &&
+		typeof (m.history as Record<string, unknown>).present !== "undefined" &&
+		Array.isArray((m.history as Record<string, unknown>).future) &&
+		typeof m.maxSize === "number" &&
+		typeof m.currentIndex === "number"
+	);
+};

package/src/stores/modules/store/domain/validators/index.ts

@@ -0,0 +1,7 @@
+// Store Module - Domain Validators
+// Clean Architecture: Re-export all validators
+
+export * from "./action-validators";
+export * from "./history-validators";
+export * from "./persistence-validators";
+export * from "./store-validators";

package/src/stores/modules/store/domain/validators/persistence-validators.ts

@@ -0,0 +1,23 @@
+// Store Module - Domain Validators
+// Clean Architecture: Persistence validation functions
+
+import type { PersistenceModel } from "#stores/modules/store/domain/models";
+
+export const validatePersistenceKey = (key: unknown): boolean =>
+	typeof key === "string" && key.length > 0;
+
+export const validatePersistenceVersion = (version: unknown): boolean =>
+	typeof version === "string";
+
+export const validatePersistenceModel = <T>(
+	model: unknown,
+): model is PersistenceModel<T> => {
+	if (typeof model !== "object" || model === null) return false;
+	const m = model as Record<string, unknown>;
+	return (
+		validatePersistenceKey(m.key) &&
+		validatePersistenceVersion(m.version) &&
+		typeof m.state !== "undefined" &&
+		typeof m.timestamp === "number"
+	);
+};

package/src/stores/modules/store/domain/validators/store-validators.ts

@@ -0,0 +1,41 @@
+// Store Module - Domain Validators
+// Clean Architecture: Store validation functions
+
+import type { StoreModel } from "#stores/modules/store/domain/models";
+import type { StoreConfig } from "#stores/modules/store/types";
+
+export const validateStoreState = <T>(_state: T): _state is T => true;
+
+export const validateStoreConfig = (config: unknown): config is StoreConfig => {
+	if (typeof config !== "object" || config === null) return false;
+	const cfg = config as Record<string, unknown>;
+	if (cfg.name !== undefined && typeof cfg.name !== "string") return false;
+	if (cfg.persist !== undefined && typeof cfg.persist !== "boolean")
+		return false;
+	if (cfg.persistKey !== undefined && typeof cfg.persistKey !== "string")
+		return false;
+	if (cfg.validation !== undefined && typeof cfg.validation !== "boolean")
+		return false;
+	if (
+		cfg.optimisticUpdates !== undefined &&
+		typeof cfg.optimisticUpdates !== "boolean"
+	)
+		return false;
+	if (cfg.timeTravel !== undefined && typeof cfg.timeTravel !== "boolean")
+		return false;
+	return true;
+};
+
+export const validateStoreModel = <T>(
+	model: unknown,
+): model is StoreModel<T> => {
+	if (typeof model !== "object" || model === null) return false;
+	const m = model as Record<string, unknown>;
+	return (
+		typeof m.state !== "undefined" &&
+		Array.isArray(m.listeners) &&
+		typeof m.config === "object" &&
+		typeof m.createdAt === "number" &&
+		typeof m.updatedAt === "number"
+	);
+};

package/src/stores/modules/store/index.ts

@@ -0,0 +1,9 @@
+// Store Module - Public API
+// Clean Architecture: Module entry point
+
+export * from "./application/usecases";
+export * from "./domain/models";
+export * from "./domain/operations";
+export * from "./domain/validators";
+export * from "./ports";
+export * from "./types";

package/src/stores/modules/store/ports/index.ts

@@ -0,0 +1,104 @@
+// Store Module - Ports
+// Clean Architecture: Interfaces for external dependencies
+
+import type { PersistenceModel } from "#stores/modules/store/domain/models";
+import type { StoreConfig } from "#stores/modules/store/types";
+
+// ============================================
+// STORAGE PORTS
+// ============================================
+
+export interface IStorage {
+	get<T>(key: string): T | null;
+	set<T>(key: string, value: T): void;
+	remove(key: string): void;
+	clear(): void;
+}
+
+export interface ILocalStorage extends IStorage {}
+
+export interface ISessionStorage extends IStorage {}
+
+export interface IIndexedDBStorage {
+	open(dbName: string, version: number): Promise<void>;
+	get<T>(storeName: string, key: string): Promise<T | null>;
+	set<T>(storeName: string, key: string, value: T): Promise<void>;
+	remove(storeName: string, key: string): Promise<void>;
+	clear(storeName: string): Promise<void>;
+}
+
+// ============================================
+// PERSISTENCE PORTS
+// ============================================
+
+export interface IPersistenceAdapter {
+	save<T>(model: PersistenceModel<T>): Promise<void>;
+	load<T>(key: string): Promise<PersistenceModel<T> | null>;
+	remove(key: string): Promise<void>;
+	clear(): Promise<void>;
+}
+
+export interface ILocalStorageAdapter extends IPersistenceAdapter {}
+
+export interface IIndexedDBAdapter extends IPersistenceAdapter {}
+
+export interface IRemoteSyncAdapter {
+	sync<T>(key: string, state: T): Promise<void>;
+	fetch<T>(key: string): Promise<T | null>;
+	conflictResolver<T>(local: T, remote: T): T;
+}
+
+// ============================================
+// VALIDATION PORTS
+// ============================================
+
+export interface IValidator<T> {
+	validate(data: unknown): data is T;
+	schema: unknown;
+}
+
+export interface IArktypeValidator<T> extends IValidator<T> {
+	validate(data: unknown): data is T;
+	assert(data: unknown): asserts data is T;
+	schema: {
+		(data: unknown): unknown;
+		infer: unknown;
+	};
+}
+
+// ============================================
+// LOGGER PORTS
+// ============================================
+
+export interface ILogger {
+	log(message: string, ...args: unknown[]): void;
+	warn(message: string, ...args: unknown[]): void;
+	error(message: string, ...args: unknown[]): void;
+	debug(message: string, ...args: unknown[]): void;
+}
+
+// ============================================
+// CLOCK PORT
+// ============================================
+
+export interface IClock {
+	now: () => number;
+}
+
+// ============================================
+// DEVTOOLS PORTS
+// ============================================
+
+export interface IStoreDevtools {
+	registerStore<T>(
+		name: string,
+		store: { getState: () => T },
+		config: StoreConfig,
+	): void;
+	unregisterStore(name: string): void;
+	updateStore<T>(name: string, state: T): void;
+	logAction<T>(name: string, action: string, prevState: T, nextState: T): void;
+	startTimeTravel(): void;
+	stopTimeTravel(): void;
+	jumpToState<T>(name: string, state: T): void;
+}

package/src/stores/modules/store/types/index.ts

@@ -0,0 +1,35 @@
+// Store Module - Types
+// Clean Architecture: Domain type definitions
+
+export type Store<T> = {
+	readonly getState: () => T;
+	readonly setState: (state: T | ((prev: T) => T), now?: number) => void;
+	readonly subscribe: (listener: (state: T) => void) => () => void;
+};
+
+export type StoreConfig = {
+	readonly name?: string;
+	readonly persist?: boolean;
+	readonly persistKey?: string;
+	readonly validation?: boolean;
+	readonly optimisticUpdates?: boolean;
+	readonly timeTravel?: boolean;
+	readonly deep?: boolean;
+	readonly devtools?: boolean;
+};
+
+export type StoreListener<T> = (state: T) => void;
+
+export type StoreUnsubscribe = () => void;
+
+export type StoreAction = {
+	readonly type: string;
+	readonly payload?: unknown;
+	readonly timestamp: number;
+};
+
+export type StoreHistory<T> = {
+	past: T[];
+	present: T;
+	future: T[];
+};

package/src/stores/shared/constants/index.ts

@@ -0,0 +1,50 @@
+// Shared Kernel - Constants
+// Clean Architecture: Static constants
+
+// ============================================
+// STORE CONSTANTS
+// ============================================
+
+export const MAX_STORE_LISTENERS = 1000;
+export const MAX_HISTORY_SIZE = 50;
+export const DEFAULT_HISTORY_SIZE = 50;
+
+export const DEFAULT_STORE_NAME = "anonymous-store";
+export const DEFAULT_PERSIST_KEY = "solid-stores";
+
+export const STORAGE_VERSION = "1.0.0";
+export const STORAGE_KEY_PREFIX = "solid-stores-";
+
+// ============================================
+// PERSISTENCE CONSTANTS
+// ============================================
+
+export const LOCAL_STORAGE_KEY = `${STORAGE_KEY_PREFIX}local`;
+export const SESSION_STORAGE_KEY = `${STORAGE_KEY_PREFIX}session`;
+export const INDEXED_DB_NAME = `${STORAGE_KEY_PREFIX}db`;
+export const INDEXED_DB_VERSION = 1;
+
+export const PERSISTENCE_DEBOUNCE_MS = 1000;
+export const PERSISTENCE_THROTTLE_MS = 500;
+
+// ============================================
+// VALIDATION CONSTANTS
+// ============================================
+
+export const VALIDATION_DEBOUNCE_MS = 300;
+export const VALIDATION_THROTTLE_MS = 100;
+
+// ============================================
+// DEVTOOLS CONSTANTS
+// ============================================
+
+export const DEVTOOLS_MESSAGE_TYPE = "SOLID_STORES_DEVTOOLS";
+export const DEVTOOLS_PORT = 9877;
+
+export const DEVTOOLS_EVENT_REGISTER_STORE = "REGISTER_STORE";
+export const DEVTOOLS_EVENT_UNREGISTER_STORE = "UNREGISTER_STORE";
+export const DEVTOOLS_EVENT_UPDATE_STORE = "UPDATE_STORE";
+export const DEVTOOLS_EVENT_LOG_ACTION = "LOG_ACTION";
+export const DEVTOOLS_EVENT_START_TIME_TRAVEL = "START_TIME_TRAVEL";
+export const DEVTOOLS_EVENT_STOP_TIME_TRAVEL = "STOP_TIME_TRAVEL";
+export const DEVTOOLS_EVENT_JUMP_TO_STATE = "JUMP_TO_STATE";

package/src/stores/shared/errors/index.ts

@@ -0,0 +1,122 @@
+// Shared Kernel - Errors
+// Clean Architecture: Error types
+
+// ============================================
+// BASE ERROR
+// ============================================
+
+export class AppError extends Error {
+	public readonly code: string;
+	public readonly context?: Record<string, unknown>;
+
+	constructor(
+		message: string,
+		code: string,
+		context?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = "AppError";
+		this.code = code;
+		this.context = context;
+	}
+}
+
+// ============================================
+// VALIDATION ERROR
+// ============================================
+
+export class ValidationError extends AppError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, "VALIDATION_ERROR", context);
+		this.name = "ValidationError";
+	}
+}
+
+// ============================================
+// NOT FOUND ERROR
+// ============================================
+
+export class NotFoundError extends AppError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, "NOT_FOUND_ERROR", context);
+		this.name = "NotFoundError";
+	}
+}
+
+// ============================================
+// CONFLICT ERROR
+// ============================================
+
+export class ConflictError extends AppError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, "CONFLICT_ERROR", context);
+		this.name = "ConflictError";
+	}
+}
+
+// ============================================
+// PERMISSION ERROR
+// ============================================
+
+export class PermissionError extends AppError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, "PERMISSION_ERROR", context);
+		this.name = "PermissionError";
+	}
+}
+
+// ============================================
+// NETWORK ERROR
+// ============================================
+
+export class NetworkError extends AppError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, "NETWORK_ERROR", context);
+		this.name = "NetworkError";
+	}
+}
+
+// ============================================
+// TIMEOUT ERROR
+// ============================================
+
+export class TimeoutError extends AppError {
+	constructor(message: string, context?: Record<string, unknown>) {
+		super(message, "TIMEOUT_ERROR", context);
+		this.name = "TimeoutError";
+	}
+}
+
+// ============================================
+// ERROR FACTORY
+// ============================================
+
+export const createValidationError = (
+	message: string,
+	context?: Record<string, unknown>,
+) => new ValidationError(message, context);
+
+export const createNotFoundError = (
+	message: string,
+	context?: Record<string, unknown>,
+) => new NotFoundError(message, context);
+
+export const createConflictError = (
+	message: string,
+	context?: Record<string, unknown>,
+) => new ConflictError(message, context);
+
+export const createPermissionError = (
+	message: string,
+	context?: Record<string, unknown>,
+) => new PermissionError(message, context);
+
+export const createNetworkError = (
+	message: string,
+	context?: Record<string, unknown>,
+) => new NetworkError(message, context);
+
+export const createTimeoutError = (
+	message: string,
+	context?: Record<string, unknown>,
+) => new TimeoutError(message, context);

package/src/stores/shared/index.ts

@@ -0,0 +1,7 @@
+// Shared Kernel - Public API
+// Clean Architecture: Shared utilities exports
+
+export * from "#stores/shared/constants";
+export * from "#stores/shared/errors";
+export * from "#stores/shared/schema-generator";
+export * from "#stores/shared/types";