@wrikka/solid-framework 0.0.0-stage → 0.15.0

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

@@ -0,0 +1,44 @@
+// Store Module - Storage Adapters
+// Clean Architecture: SessionStorage implementation
+
+import type { ISessionStorage } from "#stores/modules/store/ports";
+
+export const createSessionStorageAdapter = (): ISessionStorage => {
+	const storage = typeof window !== "undefined" ? window.sessionStorage : 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 sessionStorage item:", error);
+			}
+		},
+		remove: (key: string): void => {
+			if (!storage) return;
+			try {
+				storage.removeItem(key);
+			} catch (error) {
+				console.error("Failed to remove sessionStorage item:", error);
+			}
+		},
+		clear: (): void => {
+			if (!storage) return;
+			try {
+				storage.clear();
+			} catch (error) {
+				console.error("Failed to clear sessionStorage:", error);
+			}
+		},
+	};
+};

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

@@ -0,0 +1,5 @@
+// Store Module - Sync Adapter
+// Clean Architecture: Cross-tab synchronization
+
+// Re-export tab sync utilities
+export * from "./tab-sync";

package/src/stores/adapters/sync/tab-sync.ts

@@ -0,0 +1,148 @@
+// Store Module - Tab Synchronization
+// Clean Architecture: Cross-tab state synchronization using BroadcastChannel
+
+import type { Store } from "#stores/modules/store/types";
+
+// ============================================
+// TAB SYNC TYPES
+// ============================================
+
+export interface TabSyncOptions<T> {
+	channelName: string;
+	conflictResolution?: "last-write-wins" | "first-write-wins" | "merge";
+	onSync?: (state: T, source: string) => void;
+}
+
+export interface TabSyncAdapter<T> {
+	channel: BroadcastChannel;
+	sync: (state: T) => void;
+	disconnect: () => void;
+}
+
+// ============================================
+// CREATE TAB SYNC ADAPTER
+// ============================================
+
+export const createTabSyncAdapter = <T>(
+	store: Store<T>,
+	options: TabSyncOptions<T>,
+): TabSyncAdapter<T> => {
+	const {
+		channelName,
+		conflictResolution = "last-write-wins",
+		onSync,
+	} = options;
+
+	// Create BroadcastChannel
+	const channel = new BroadcastChannel(channelName);
+
+	// Listen for messages from other tabs
+	channel.onmessage = (event: MessageEvent<{ state: T; source: string }>) => {
+		const { state, source } = event.data;
+
+		// Ignore messages from self (if source tracking is implemented)
+		if (source === "self") return;
+
+		// Apply conflict resolution
+		const currentState = store.getState();
+		let newState = state;
+
+		switch (conflictResolution) {
+			case "last-write-wins":
+				newState = state;
+				break;
+			case "first-write-wins":
+				// Keep current state if it exists
+				if (currentState !== null) {
+					newState = currentState;
+				}
+				break;
+			case "merge":
+				newState = { ...currentState, ...state } as T;
+				break;
+		}
+
+		store.setState(newState);
+		onSync?.(newState, source);
+	};
+
+	// Sync function to broadcast state changes
+	const sync = (state: T): void => {
+		channel.postMessage({
+			state,
+			source: "self",
+		});
+	};
+
+	// Disconnect function
+	const disconnect = (): void => {
+		channel.close();
+	};
+
+	return {
+		channel,
+		sync,
+		disconnect,
+	};
+};
+
+// ============================================
+// SYNC STORE WITH TABS
+// ============================================
+
+export const syncStoreWithTabs = <T>(
+	store: Store<T>,
+	options: TabSyncOptions<T>,
+): (() => void) => {
+	const adapter = createTabSyncAdapter(store, options);
+
+	// Subscribe to store changes and sync to other tabs
+	const unsubscribe = store.subscribe((state) => {
+		adapter.sync(state);
+	});
+
+	// Return cleanup function
+	return () => {
+		unsubscribe();
+		adapter.disconnect();
+	};
+};
+
+// ============================================
+// TAB SYNC MANAGER
+// ============================================
+
+const instances = new Map<string, TabSyncAdapter<unknown>>();
+
+export const TabSyncManager = {
+	getOrCreate<T>(
+		store: Store<T>,
+		options: TabSyncOptions<T>,
+	): TabSyncAdapter<T> {
+		const { channelName } = options;
+
+		const existing = instances.get(channelName);
+		if (existing) {
+			return existing as TabSyncAdapter<T>;
+		}
+
+		const adapter = createTabSyncAdapter(store, options);
+		instances.set(channelName, adapter as TabSyncAdapter<unknown>);
+		return adapter;
+	},
+
+	disconnect(channelName: string): void {
+		const adapter = instances.get(channelName);
+		if (adapter) {
+			adapter.disconnect();
+			instances.delete(channelName);
+		}
+	},
+
+	disconnectAll(): void {
+		for (const adapter of instances.values()) {
+			adapter.disconnect();
+		}
+		instances.clear();
+	},
+};

package/src/stores/adapters/validation/arktype-validator.ts

@@ -0,0 +1,32 @@
+// Store Module - Validation Adapter
+// Clean Architecture: Arktype validator factory
+
+import { type } from "arktype";
+import type {
+	IArktypeValidator,
+	IValidator,
+} from "#stores/modules/store/ports";
+
+export const createArktypeValidator = <T>(
+	schemaDefinition: string,
+): IArktypeValidator<T> => {
+	const arktype = type(schemaDefinition as never);
+
+	return {
+		validate: (data: unknown): data is T => {
+			const result = arktype(data);
+			return !(result instanceof type.errors);
+		},
+		assert: (data: unknown): asserts data is T => {
+			const result = arktype(data);
+			if (result instanceof type.errors) {
+				throw new Error(result.summary);
+			}
+		},
+		schema: arktype as never,
+	};
+};
+
+export const createValidator = <T>(schema: string): IValidator<T> => {
+	return createArktypeValidator<T>(schema);
+};

package/src/stores/adapters/validation/error-handling.ts

@@ -0,0 +1,27 @@
+// Store Module - Validation Adapter
+// Clean Architecture: Error handling helpers
+
+import { type } from "arktype";
+import type { IArktypeValidator } from "#stores/modules/store/ports";
+
+export const handleValidationError = <T>(
+	data: unknown,
+	validator: IArktypeValidator<T>,
+): T => {
+	if (validator.validate(data)) {
+		return data;
+	}
+	validator.assert(data);
+	throw new Error("Validation failed");
+};
+
+export const getValidationErrors = <T>(
+	data: unknown,
+	validator: IArktypeValidator<T>,
+): string | null => {
+	const result = validator.schema(data);
+	if (result instanceof type.errors) {
+		return result.summary;
+	}
+	return null;
+};

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

@@ -0,0 +1,61 @@
+// Store Module - Validation Adapter
+// Clean Architecture: Re-export all validation utilities
+
+export * from "./arktype-validator";
+export * from "./error-handling";
+export * from "./schemas";
+
+export const commonSchemas = {
+	// Primitive types
+	string: "string",
+	number: "number",
+	boolean: "boolean",
+	bigint: "bigint",
+	symbol: "symbol",
+
+	// String constraints
+	email: "string.email",
+	url: "string.url",
+	uuid: "string.uuid",
+	uuidv4: "string.uuid.v4",
+	date: "string.date",
+	isoDate: "string.iso.date",
+	json: "string.json.parse",
+	base64: "string.base64",
+	semver: "string.semver",
+
+	// Number constraints
+	integer: "number.integer",
+	positive: "number > 0",
+	nonNegative: "number >= 0",
+	negative: "number < 0",
+	nonPositive: "number <= 0",
+	safe: "number.safe",
+	epoch: "number.epoch",
+
+	// Common object schemas
+	user: {
+		name: "string",
+		email: "string.email",
+		age: "number.integer >= 0",
+	},
+
+	// Store-specific schemas
+	storeConfig: {
+		"name?": "string",
+		"persist?": "boolean",
+		"persistKey?": "string",
+		"validation?": "boolean",
+		"optimisticUpdates?": "boolean",
+		"timeTravel?": "boolean",
+		"deep?": "boolean",
+		"devtools?": "boolean",
+	},
+
+	// Persistence schemas
+	persistenceModel: {
+		key: "string",
+		version: "string.semver",
+		timestamp: "number.epoch",
+	},
+};

package/src/stores/adapters/validation/schemas/api-schemas.ts

@@ -0,0 +1,30 @@
+// Store Module - Validation Schemas
+// Clean Architecture: API response schemas
+
+import { type } from "arktype";
+
+export const SuccessResponseSchema = type({
+	success: "true",
+	data: "unknown",
+	"message?": "string",
+});
+
+export const ErrorResponseSchema = type({
+	success: "false",
+	error: "string",
+	"message?": "string",
+	"code?": "string",
+});
+
+export const PaginatedResponseSchema = type({
+	data: "unknown[]",
+	total: "number.integer >= 0",
+	page: "number.integer >= 1",
+	limit: "number.integer >= 1",
+	"hasNext?": "boolean",
+	"hasPrev?": "boolean",
+});
+
+export type SuccessResponse = typeof SuccessResponseSchema.infer;
+export type ErrorResponse = typeof ErrorResponseSchema.infer;
+export type PaginatedResponse = typeof PaginatedResponseSchema.infer;

package/src/stores/adapters/validation/schemas/common-schemas.ts

@@ -0,0 +1,32 @@
+// Store Module - Validation Schemas
+// Clean Architecture: Common object schemas
+
+import { type } from "arktype";
+
+export const UserSchema = type({
+	name: "string",
+	email: "string.email",
+	age: "number.integer >= 0",
+});
+
+export const AddressSchema = type({
+	street: "string",
+	city: "string",
+	"state?": "string",
+	"zipCode?": "string",
+	country: "string",
+});
+
+export const PersonSchema = type({
+	id: "string.uuid",
+	name: "string",
+	email: "string.email",
+	"phone?": "string",
+	"address?": AddressSchema,
+	createdAt: "number.epoch",
+	"updatedAt?": "number.epoch",
+});
+
+export type User = typeof UserSchema.infer;
+export type Address = typeof AddressSchema.infer;
+export type Person = typeof PersonSchema.infer;

package/src/stores/adapters/validation/schemas/config-schemas.ts

@@ -0,0 +1,22 @@
+// Store Module - Validation Schemas
+// Clean Architecture: Configuration schemas
+
+import { type } from "arktype";
+
+export const AppConfigSchema = type({
+	apiUrl: "string.url",
+	"apiVersion?": "string.semver",
+	"timeout?": "number.integer > 0",
+	"retries?": "number.integer >= 0",
+	"debug?": "boolean",
+});
+
+export const ThemeConfigSchema = type({
+	mode: "'light' | 'dark' | 'auto'",
+	"primaryColor?": "string",
+	"secondaryColor?": "string",
+	"fontSize?": "number.integer",
+});
+
+export type AppConfig = typeof AppConfigSchema.infer;
+export type ThemeConfig = typeof ThemeConfigSchema.infer;

package/src/stores/adapters/validation/schemas/constraint-schemas.ts

@@ -0,0 +1,34 @@
+// Store Module - Validation Schemas
+// Clean Architecture: String and number constraint schemas
+
+import { type } from "arktype";
+
+// String constraints
+export const EmailSchema = type("string.email");
+export const UrlSchema = type("string.url");
+export const UuidSchema = type("string.uuid");
+export const UuidV4Schema = type("string.uuid.v4");
+export const DateSchema = type("string.date");
+export const IsoDateSchema = type("string");
+export const JsonSchema: ReturnType<typeof type> = type("string.json.parse");
+export const Base64Schema = type("string.base64");
+export const SemverSchema = type("string.semver");
+
+// String length constraints
+export const UsernameSchema = type("string.alphanumeric");
+export const PasswordSchema = type("string");
+export const PhoneNumberSchema = type("string");
+
+// Number constraints
+export const IntegerSchema = type("number.integer");
+export const PositiveNumberSchema = type("number > 0");
+export const NonNegativeNumberSchema = type("number >= 0");
+export const NegativeNumberSchema = type("number < 0");
+export const NonPositiveNumberSchema = type("number <= 0");
+export const SafeNumberSchema = type("number.safe");
+export const EpochSchema = type("number.epoch");
+
+// Range constraints
+export const AgeSchema = type("number.integer >= 0");
+export const PercentageSchema = type("number >= 0");
+export const RatingSchema = type("number.integer >= 1");

package/src/stores/adapters/validation/schemas/ecommerce-schemas.ts

@@ -0,0 +1,43 @@
+// Store Module - Validation Schemas
+// Clean Architecture: E-commerce schemas
+
+import { type } from "arktype";
+import { AddressSchema } from "./common-schemas";
+
+export const ProductSchema = type({
+	id: "string.uuid",
+	name: "string",
+	description: "string",
+	price: "number > 0",
+	"quantity?": "number.integer >= 0",
+	"category?": "string",
+	"images?": "string[]",
+	"createdAt?": "number.epoch",
+	"updatedAt?": "number.epoch",
+});
+
+export const CartItemSchema = type({
+	product: ProductSchema,
+	quantity: "number.integer >= 1",
+});
+
+export const CartSchema = type({
+	items: CartItemSchema.array(),
+	total: "number >= 0",
+	"updatedAt?": "number.epoch",
+});
+
+export const OrderSchema = type({
+	id: "string.uuid",
+	items: CartItemSchema.array(),
+	total: "number > 0",
+	status: "'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled'",
+	"shippingAddress?": AddressSchema,
+	createdAt: "number.epoch",
+	"updatedAt?": "number.epoch",
+});
+
+export type Product = typeof ProductSchema.infer;
+export type CartItem = typeof CartItemSchema.infer;
+export type Cart = typeof CartSchema.infer;
+export type Order = typeof OrderSchema.infer;

package/src/stores/adapters/validation/schemas/form-schemas.ts

@@ -0,0 +1,27 @@
+// Store Module - Validation Schemas
+// Clean Architecture: Form schemas
+
+import { type } from "arktype";
+
+export const LoginFormSchema = type({
+	email: "string.email",
+	password: "string >= 8",
+});
+
+export const RegisterFormSchema = type({
+	name: "string >= 2",
+	email: "string.email",
+	password: "string >= 8",
+	confirmPassword: "string >= 8",
+});
+
+export const ContactFormSchema = type({
+	name: "string >= 2",
+	email: "string.email",
+	subject: "string >= 5",
+	message: "string >= 10",
+});
+
+export type LoginForm = typeof LoginFormSchema.infer;
+export type RegisterForm = typeof RegisterFormSchema.infer;
+export type ContactForm = typeof ContactFormSchema.infer;

package/src/stores/adapters/validation/schemas/primitive-schemas.ts

@@ -0,0 +1,9 @@
+// Store Module - Validation Schemas
+// Clean Architecture: Primitive type schemas
+
+import { type } from "arktype";
+
+export const StringSchema = type("string");
+export const NumberSchema = type("number");
+export const BooleanSchema = type("boolean");
+export const BigIntSchema = type("bigint");

package/src/stores/adapters/validation/schemas/store-schemas.ts

@@ -0,0 +1,52 @@
+// Store Module - Validation Schemas
+// Clean Architecture: Store-specific schemas
+
+import { type } from "arktype";
+
+export const StoreConfigSchema = type({
+	"name?": "string",
+	"persist?": "boolean",
+	"persistKey?": "string",
+	"validation?": "boolean",
+	"optimisticUpdates?": "boolean",
+	"timeTravel?": "boolean",
+	"deep?": "boolean",
+	"devtools?": "boolean",
+});
+
+export const StoreActionSchema = type({
+	type: "string",
+	"payload?": "unknown",
+	timestamp: "number.epoch",
+});
+
+export const StoreHistorySchema = type({
+	past: "unknown[]",
+	present: "unknown",
+	future: "unknown[]",
+});
+
+export const PersistenceModelSchema = type({
+	key: "string",
+	version: "string.semver",
+	timestamp: "number.epoch",
+});
+
+export const LocalStorageItemSchema = type({
+	key: "string",
+	value: "unknown",
+	timestamp: "number.epoch",
+});
+
+export const SessionStorageItemSchema = type({
+	key: "string",
+	value: "unknown",
+	timestamp: "number.epoch",
+});
+
+export const IndexedDBItemSchema = type({
+	key: "string",
+	value: "unknown",
+	version: "number",
+	timestamp: "number.epoch",
+});

package/src/stores/adapters/validation/schemas.ts

@@ -0,0 +1,11 @@
+// Store Module - Validation Schemas
+// Clean Architecture: Re-export all schemas
+
+export * from "./schemas/api-schemas";
+export * from "./schemas/common-schemas";
+export * from "./schemas/config-schemas";
+export * from "./schemas/constraint-schemas";
+export * from "./schemas/ecommerce-schemas";
+export * from "./schemas/form-schemas";
+export * from "./schemas/primitive-schemas";
+export * from "./schemas/store-schemas";

package/src/stores/index.ts

@@ -0,0 +1,13 @@
+// @wrikka/solid-framework/stores - Public API
+// Clean Architecture: Main entry point
+
+export * from "#stores/adapters/analytics";
+export * from "#stores/adapters/devtools";
+export * from "#stores/adapters/persistence";
+export * from "#stores/adapters/router";
+export * from "#stores/adapters/storage";
+export * from "#stores/adapters/sync";
+export * from "#stores/adapters/validation";
+export * from "#stores/modules/query";
+export * from "#stores/modules/store";
+export * from "#stores/shared";

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

@@ -0,0 +1,24 @@
+// Query/Mutation Library
+// Clean Architecture: Application layer for server state management
+
+export type {
+	MutationConfig,
+	MutationDataState,
+} from "./mutation-state";
+export { initialMutationDataState } from "./mutation-state";
+export { createMutationStore, type MutationStore } from "./mutation-store";
+export {
+	createQueryBuilder,
+	type QueryBuilder,
+} from "./query-builder";
+export { QueryCache, type QueryCacheEntry } from "./query-cache";
+export {
+	createQueryDataManager,
+	type QueryDataManager,
+} from "./query-manager";
+export type {
+	QueryConfig,
+	QueryDataState,
+} from "./query-state";
+export { initialQueryDataState } from "./query-state";
+export { createQueryStore, type QueryStore } from "./query-store";

package/src/stores/modules/query/mutation-state.ts

@@ -0,0 +1,33 @@
+export interface MutationDataState<TData, TVariables> {
+	data: TData | null;
+	error: Error | null;
+	isLoading: boolean;
+	isSuccess: boolean;
+	isError: boolean;
+	variables: TVariables | null;
+}
+
+export const initialMutationDataState = <
+	TData = unknown,
+	TVariables = unknown,
+>(): MutationDataState<TData, TVariables> => ({
+	data: null,
+	error: null,
+	isLoading: false,
+	isSuccess: false,
+	isError: false,
+	variables: null,
+});
+
+export interface MutationConfig<TData, TVariables> {
+	mutationFn: (variables: TVariables) => Promise<TData>;
+	onSuccess?: (data: TData, variables: TVariables) => void;
+	onError?: (error: Error, variables: TVariables) => void;
+	onSettled?: (
+		data: TData | null,
+		error: Error | null,
+		variables: TVariables,
+	) => void;
+	retry?: number;
+	retryDelay?: number;
+}