@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/query/modules/query/domain/models/query-observer.ts

@@ -0,0 +1,162 @@
+import {
+	hashKey,
+	isStale,
+	resolveStaleTime,
+} from "#query/modules/query/domain/operations";
+import type {
+	QueryObserverResult,
+	QueryOptions,
+	QueryState,
+} from "#query/modules/query/types";
+import type { Query } from "./query";
+
+const createObserverResult = <TData, TError, TSelected>(
+	state: QueryState<TData, TError>,
+	options: QueryOptions<TData, TError, TSelected>,
+	now: number,
+): QueryObserverResult<TSelected, TError> => {
+	const selectedData =
+		state.data !== undefined && options.select
+			? options.select(state.data)
+			: (state.data as unknown as TSelected);
+
+	const data =
+		selectedData === undefined && options.placeholderData !== undefined
+			? typeof options.placeholderData === "function"
+				? (
+						options.placeholderData as (
+							previousData: TSelected | undefined,
+						) => TSelected | undefined
+					)(selectedData)
+				: (options.placeholderData as unknown as TSelected)
+			: selectedData;
+
+	const isLoading =
+		state.status === "pending" && state.fetchStatus === "fetching";
+	const isFetching = state.fetchStatus === "fetching";
+	const isPending = state.status === "pending";
+	const isSuccess = state.status === "success";
+	const isError = state.status === "error";
+	const isInitialLoading = isLoading && state.data === undefined;
+	const staleTime = resolveStaleTime(
+		options.staleTime,
+		state as QueryState<TData, unknown>,
+	);
+	const isStaleFlag = isStale(
+		{ ...state, data: data as unknown as TData },
+		staleTime,
+		now,
+	);
+
+	return {
+		...state,
+		data,
+		error: state.error,
+		isLoading,
+		isFetching,
+		isPending,
+		isSuccess,
+		isError,
+		isInitialLoading,
+		isStale: isStaleFlag,
+	};
+};
+
+export class QueryObserver<TData = unknown, TError = Error, TSelected = TData> {
+	readonly queryHash: string;
+	readonly query: Query<TData, TError>;
+	private options: QueryOptions<TData, TError, TSelected>;
+	private listeners = new Set<
+		(result: QueryObserverResult<TSelected, TError>) => void
+	>();
+	private currentResult: QueryObserverResult<TSelected, TError>;
+
+	constructor(
+		query: Query<TData, TError>,
+		options: QueryOptions<TData, TError, TSelected>,
+	) {
+		this.query = query;
+		this.options = options;
+		this.queryHash = hashKey(options.queryKey);
+		this.currentResult = createObserverResult(
+			query.getState(),
+			options,
+			query.clock(),
+		);
+		this.query.addObserver(this as QueryObserver<TData, TError, unknown>);
+		this.query.subscribe(() => this.onQueryUpdate());
+	}
+
+	setOptions(options: QueryOptions<TData, TError, TSelected>): void {
+		this.options = { ...this.options, ...options };
+		this.updateResult();
+		void this.refetchIfStale();
+	}
+
+	getCurrentResult(): QueryObserverResult<TSelected, TError> {
+		return this.currentResult;
+	}
+
+	subscribe(
+		listener: (result: QueryObserverResult<TSelected, TError>) => void,
+	): () => void {
+		this.listeners.add(listener);
+		listener(this.currentResult);
+		void this.refetchIfStale();
+		return () => this.listeners.delete(listener);
+	}
+
+	trackProps(): (keyof QueryObserverResult<TSelected, TError>)[] {
+		return Object.keys(this.currentResult) as (keyof QueryObserverResult<
+			TSelected,
+			TError
+		>)[];
+	}
+
+	async fetch(): Promise<TData> {
+		return this.query.fetch(
+			this.options as QueryOptions<TData, TError, unknown>,
+		);
+	}
+
+	async refetch(): Promise<TData> {
+		return this.query.refetch();
+	}
+
+	willFetch(): boolean {
+		return this.options.enabled !== false && this.currentResult.isStale;
+	}
+
+	destroy(): void {
+		this.query.removeObserver(this as QueryObserver<TData, TError, unknown>);
+		this.listeners.clear();
+	}
+
+	private onQueryUpdate(): void {
+		this.updateResult();
+		for (const listener of this.listeners) {
+			listener(this.currentResult);
+		}
+	}
+
+	private updateResult(): void {
+		this.currentResult = createObserverResult(
+			this.query.getState(),
+			this.options,
+			this.query.clock(),
+		);
+	}
+
+	private async refetchIfStale(): Promise<void> {
+		if (this.options.enabled === false) return;
+		if (this.currentResult.isStale) {
+			try {
+				await this.query.fetch(
+					this.options as QueryOptions<TData, TError, unknown>,
+				);
+			} catch {
+				// errors are tracked in query state
+			}
+		}
+	}
+}

package/src/query/modules/query/domain/models/query-operations.ts

@@ -0,0 +1,76 @@
+import {
+	calculateRetryDelay,
+	shouldRetry,
+} from "#query/modules/query/domain/operations";
+import type {
+	QueryFunctionContext,
+	QueryOptions,
+} from "#query/modules/query/types";
+import type { Query } from "./query";
+
+export const runQuery = async <TData, TError = Error>(
+	query: Query<TData, TError>,
+	options: QueryOptions<TData, TError, unknown>,
+	controller: AbortController,
+	now: number,
+): Promise<TData> => {
+	const queryContext: QueryFunctionContext = {
+		signal: controller.signal,
+		queryKey: query.queryKey,
+	};
+	let failureCount = 0;
+
+	while (true) {
+		try {
+			const data = await options.queryFn(queryContext);
+			if (controller.signal.aborted) {
+				throw new Error(controller.signal.reason as string);
+			}
+
+			query.setState({
+				data,
+				dataUpdatedAt: now,
+				error: null,
+				errorUpdatedAt: 0,
+				failureCount: 0,
+				failureReason: null,
+				fetchStatus: "idle",
+				status: "success",
+			});
+			query.promise = null;
+			return data;
+		} catch (rawError) {
+			if (controller.signal.aborted) {
+				query.setState((prev) => ({ ...prev, fetchStatus: "idle" }));
+				query.promise = null;
+				throw rawError;
+			}
+
+			const error = rawError as TError;
+			failureCount += 1;
+
+			query.setState((prev) => ({
+				...prev,
+				error,
+				errorUpdatedAt: now,
+				failureCount,
+				failureReason: error,
+				fetchStatus: "idle",
+				status: "error",
+			}));
+
+			if (!shouldRetry(failureCount, error, options.retry ?? false)) {
+				query.promise = null;
+				throw error;
+			}
+
+			const delay = calculateRetryDelay(
+				failureCount,
+				error,
+				options.retryDelay ?? 1000,
+			);
+			await new Promise((resolve) => setTimeout(resolve, delay));
+			query.setState((prev) => ({ ...prev, fetchStatus: "fetching" }));
+		}
+	}
+};

package/src/query/modules/query/domain/models/query.ts

@@ -0,0 +1,239 @@
+import {
+	hashKey,
+	isStale,
+	resolveRefetchInterval,
+	resolveStaleTime,
+} from "#query/modules/query/domain/operations";
+import type {
+	FetchStatus,
+	QueryClock,
+	QueryKey,
+	QueryOptions,
+	QueryState,
+	QueryStatus,
+} from "#query/modules/query/types";
+import type { QueryCache } from "./query-cache";
+import { documentIsVisibleForMode, isOnlineForMode } from "./query-environment";
+import type { QueryObserver } from "./query-observer";
+import { runQuery } from "./query-operations";
+
+const createInitialState = <TData, TError = Error>(
+	clock: QueryClock,
+	initialData?: TData,
+): QueryState<TData, TError> => ({
+	data: initialData,
+	dataUpdatedAt: initialData !== undefined ? clock() : 0,
+	error: null,
+	errorUpdatedAt: 0,
+	failureCount: 0,
+	failureReason: null,
+	fetchStatus: "idle" as FetchStatus,
+	status:
+		initialData !== undefined
+			? ("success" as QueryStatus)
+			: ("pending" as QueryStatus),
+});
+
+export class Query<TData = unknown, TError = Error> {
+	readonly queryKey: QueryKey;
+	readonly queryHash: string;
+	options: QueryOptions<TData, TError, unknown>;
+	state: QueryState<TData, TError>;
+	private observers = new Set<QueryObserver<TData, TError, unknown>>();
+	private abortController: AbortController | null = null;
+	private refetchIntervalId: ReturnType<typeof setInterval> | null = null;
+	private gcTimeoutId: ReturnType<typeof setTimeout> | null = null;
+	private listeners = new Set<() => void>();
+	private cache: QueryCache;
+	readonly clock: QueryClock;
+	promise: Promise<TData> | null = null;
+
+	constructor(
+		options: QueryOptions<TData, TError, unknown>,
+		cache: QueryCache,
+		clock: QueryClock,
+	) {
+		this.queryKey = options.queryKey;
+		this.queryHash = hashKey(options.queryKey);
+		this.options = options;
+		this.cache = cache;
+		this.clock = clock;
+		this.state = createInitialState<TData, TError>(clock, options.initialData);
+		if (this.options.refetchInterval) {
+			this.startRefetchInterval();
+		}
+		if (
+			this.options.gcTime !== undefined &&
+			this.options.gcTime !== Number.POSITIVE_INFINITY
+		) {
+			this.scheduleGc();
+		}
+	}
+
+	getState(): QueryState<TData, TError> {
+		return this.state;
+	}
+
+	setState(
+		updater:
+			| QueryState<TData, TError>
+			| ((prev: QueryState<TData, TError>) => QueryState<TData, TError>),
+	): void {
+		const nextState =
+			typeof updater === "function" ? updater(this.state) : updater;
+		this.state = nextState;
+		this.notify();
+	}
+
+	subscribe(listener: () => void): () => void {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+
+	private notify(): void {
+		for (const listener of this.listeners) {
+			listener();
+		}
+	}
+
+	addObserver(observer: QueryObserver<TData, TError, unknown>): void {
+		this.observers.add(observer);
+		this.cancelGc();
+	}
+
+	removeObserver(observer: QueryObserver<TData, TError, unknown>): void {
+		this.observers.delete(observer);
+		if (this.observers.size === 0) {
+			this.scheduleGc();
+		}
+	}
+
+	getObserversCount(): number {
+		return this.observers.size;
+	}
+
+	setOptions(options: Partial<QueryOptions<TData, TError, unknown>>): void {
+		this.options = { ...this.options, ...options };
+		if (this.options.refetchInterval) {
+			this.startRefetchInterval();
+		} else {
+			this.stopRefetchInterval();
+		}
+	}
+
+	getOptions(): QueryOptions<TData, TError, unknown> {
+		return this.options;
+	}
+
+	isStale(now?: number): boolean {
+		const staleTime = resolveStaleTime(
+			this.options.staleTime,
+			this.state as QueryState<TData, unknown>,
+		);
+		return isStale(this.state, staleTime, now ?? this.clock());
+	}
+
+	async fetch(
+		options?: Partial<QueryOptions<TData, TError, unknown>>,
+	): Promise<TData> {
+		const now = this.clock();
+		const mergedOptions = options
+			? { ...this.options, ...options }
+			: this.options;
+		if (mergedOptions.enabled === false) {
+			this.setState((prev) => ({ ...prev, fetchStatus: "paused" }));
+			return this.state.data as TData;
+		}
+
+		if (this.promise) {
+			if (
+				mergedOptions.networkMode === "always" ||
+				isOnlineForMode(mergedOptions.networkMode)
+			) {
+				return this.promise;
+			}
+			this.cancel({ reason: "replaced" });
+		}
+
+		const staleTime = resolveStaleTime(mergedOptions.staleTime, this.state);
+		if (this.state.data !== undefined && !isStale(this.state, staleTime, now)) {
+			return this.state.data as TData;
+		}
+
+		this.setState((prev) => ({
+			...prev,
+			fetchStatus: "fetching",
+			status: prev.data === undefined ? "pending" : prev.status,
+		}));
+
+		const controller = new AbortController();
+		this.abortController = controller;
+
+		this.promise = runQuery(this, mergedOptions, controller, now);
+		return this.promise;
+	}
+
+	refetch(): Promise<TData> {
+		return this.fetch({ staleTime: 0 });
+	}
+
+	cancel({ reason }: { reason?: string } = {}): void {
+		if (this.abortController) {
+			this.abortController.abort(reason);
+			this.abortController = null;
+		}
+		this.promise = null;
+	}
+
+	invalidate(): void {
+		this.setState((prev) => ({
+			...prev,
+			dataUpdatedAt: 0,
+		}));
+	}
+
+	destroy(): void {
+		this.cancel();
+		this.stopRefetchInterval();
+		this.cache.remove(this as Query<unknown, unknown>);
+	}
+
+	private startRefetchInterval(): void {
+		this.stopRefetchInterval();
+		const interval = resolveRefetchInterval(
+			this.options.refetchInterval,
+			this.state as QueryState<TData, unknown>,
+		);
+		if (interval === false || interval <= 0) return;
+
+		this.refetchIntervalId = setInterval(() => {
+			if (documentIsVisibleForMode(this.options.refetchIntervalInBackground)) {
+				this.refetch().catch(() => undefined);
+			}
+		}, interval);
+	}
+
+	private stopRefetchInterval(): void {
+		if (this.refetchIntervalId) {
+			clearInterval(this.refetchIntervalId);
+			this.refetchIntervalId = null;
+		}
+	}
+
+	private scheduleGc(): void {
+		this.cancelGc();
+		const gcTime = this.options.gcTime;
+		if (gcTime === undefined || gcTime === Number.POSITIVE_INFINITY) return;
+
+		this.gcTimeoutId = setTimeout(() => {
+			this.cache.remove(this as Query<unknown, unknown>);
+		}, gcTime);
+	}
+
+	private cancelGc(): void {
+		if (this.gcTimeoutId) {
+			clearTimeout(this.gcTimeoutId);
+			this.gcTimeoutId = null;
+		}
+	}
+}

package/src/query/modules/query/domain/operations/index.ts

@@ -0,0 +1,76 @@
+import type {
+	QueryKey,
+	QueryState,
+	RetryDelayValue,
+	RetryValue,
+	StaleTimeValue,
+} from "#query/modules/query/types";
+import { hashKey } from "#query/shared";
+
+export { hashKey };
+
+export const DEFAULT_RETRY_DELAY = 1000;
+
+export const resolveStaleTime = <TData>(
+	value: StaleTimeValue<TData> | undefined,
+	state: QueryState<TData, unknown>,
+): number => {
+	if (typeof value === "number") return value;
+	if (typeof value === "function") return value(state);
+	return 0;
+};
+
+export const isStale = <TData, TError = Error>(
+	state: QueryState<TData, TError>,
+	staleTime: number,
+	now: number,
+): boolean => {
+	if (state.data === undefined) return true;
+	if (staleTime === Number.POSITIVE_INFINITY) return false;
+	return now - state.dataUpdatedAt >= staleTime;
+};
+
+export const resolveRefetchInterval = <TData>(
+	value:
+		| number
+		| false
+		| ((query: QueryState<TData, unknown>) => number | false | undefined)
+		| undefined,
+	state: QueryState<TData, unknown>,
+): number | false => {
+	if (typeof value === "number") return value;
+	if (typeof value === "function") {
+		const result = value(state);
+		return result === undefined ? false : result;
+	}
+	return false;
+};
+
+export const shouldRetry = <TError = Error>(
+	failureCount: number,
+	error: TError,
+	retry: RetryValue<TError>,
+): boolean => {
+	if (retry === false) return false;
+	if (retry === true) return true;
+	if (typeof retry === "number") return failureCount <= retry;
+	if (typeof retry === "function") return retry(failureCount, error);
+	return false;
+};
+
+export const calculateRetryDelay = <TError = Error>(
+	failureCount: number,
+	error: TError,
+	retryDelay: RetryDelayValue<TError>,
+): number => {
+	if (typeof retryDelay === "function") return retryDelay(failureCount, error);
+	return retryDelay ?? DEFAULT_RETRY_DELAY;
+};
+
+export const isQueryKeyEqual = (a: QueryKey, b: QueryKey): boolean =>
+	hashKey(a) === hashKey(b);
+
+export const isQueryKeyPrefix = (a: QueryKey, b: QueryKey): boolean => {
+	if (b.length > a.length) return false;
+	return a.slice(0, b.length).every((value, index) => value === b[index]);
+};

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

@@ -0,0 +1,9 @@
+export * from "./application/usecases/query-client";
+export * from "./domain/models/mutation";
+export * from "./domain/models/mutation-cache";
+export * from "./domain/models/query";
+export * from "./domain/models/query-cache";
+export * from "./domain/models/query-observer";
+export * from "./domain/operations";
+export * from "./ports";
+export * from "./types";

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

@@ -0,0 +1,53 @@
+import type { Mutation } from "#query/modules/query/domain/models/mutation";
+import type { Query } from "#query/modules/query/domain/models/query";
+import type { QueryKey } from "#query/modules/query/types";
+
+export type QueryPersistencePort = {
+	readonly name: string;
+	readonly getItem: <T>(
+		key: QueryKey,
+	) => T | undefined | Promise<T | undefined>;
+	readonly setItem: (key: QueryKey, value: unknown) => void | Promise<void>;
+	readonly removeItem?: (key: QueryKey) => void | Promise<void>;
+};
+
+export type QueryValidationResult<T = unknown> =
+	| { readonly success: true; readonly data: T }
+	| { readonly success: false; readonly errors: readonly string[] };
+
+export type QueryValidationPort<T = unknown> = {
+	readonly name: string;
+	readonly validate: (data: unknown) => QueryValidationResult<T>;
+};
+
+export type QueryNetworkPort = {
+	readonly name: string;
+	readonly isOnline: () => boolean;
+	readonly isVisible: () => boolean;
+	readonly onOnline: (listener: () => void) => () => void;
+	readonly onFocus: (listener: () => void) => () => void;
+	readonly onVisibilityChange: (listener: () => void) => () => void;
+};
+
+export type QueryDevtoolsPort = {
+	readonly name: string;
+	readonly onQueryAdded?: (query: Query<unknown, unknown>) => void;
+	readonly onQueryUpdated?: (query: Query<unknown, unknown>) => void;
+	readonly onQueryRemoved?: (query: Query<unknown, unknown>) => void;
+	readonly onMutationAdded?: (
+		mutation: Mutation<unknown, unknown, unknown, unknown>,
+	) => void;
+	readonly onMutationUpdated?: (
+		mutation: Mutation<unknown, unknown, unknown, unknown>,
+	) => void;
+	readonly onMutationRemoved?: (
+		mutation: Mutation<unknown, unknown, unknown, unknown>,
+	) => void;
+};
+
+export type QueryClientPorts = {
+	readonly network?: QueryNetworkPort;
+	readonly persistence?: QueryPersistencePort;
+	readonly validation?: QueryValidationPort<unknown>;
+	readonly devtools?: QueryDevtoolsPort;
+};