@wrikka/solid-framework 0.0.0-stage → 0.15.0

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

@@ -0,0 +1,239 @@
+import type { MutationCache } from "#query/modules/query/domain/models/mutation-cache";
+import type { QueryCache } from "#query/modules/query/domain/models/query-cache";
+import type { QueryClientPorts } from "#query/modules/query/ports";
+
+export type QueryKey = readonly unknown[];
+
+export type QueryFunctionContext = {
+	readonly signal: AbortSignal;
+	readonly queryKey: QueryKey;
+	readonly pageParam?: unknown;
+};
+
+export type QueryFunction<TData = unknown> = (
+	context: QueryFunctionContext,
+) => Promise<TData> | TData;
+
+export type RetryValue<TError = Error> =
+	| number
+	| boolean
+	| ((failureCount: number, error: TError) => boolean);
+
+export type RetryDelayValue<TError = Error> =
+	| number
+	| ((retryAttempt: number, error: TError) => number);
+
+export type StaleTimeValue<TData = unknown> =
+	| number
+	| ((query: QueryState<TData, unknown>) => number);
+
+export type RefetchIntervalValue<TData = unknown> =
+	| number
+	| false
+	| ((query: QueryState<TData, unknown>) => number | false | undefined);
+
+export type PlaceholderDataValue<TData = unknown> =
+	| TData
+	| ((previousData: TData | undefined) => TData | undefined);
+
+export type QueryOptions<TData = unknown, TError = Error, TSelected = TData> = {
+	readonly queryKey: QueryKey;
+	readonly queryFn: QueryFunction<TData>;
+	readonly staleTime?: StaleTimeValue<TData>;
+	readonly gcTime?: number;
+	readonly retry?: RetryValue<TError>;
+	readonly retryDelay?: RetryDelayValue<TError>;
+	readonly refetchInterval?: RefetchIntervalValue<TData>;
+	readonly refetchIntervalInBackground?: boolean;
+	readonly refetchOnWindowFocus?: boolean | "always";
+	readonly refetchOnReconnect?: boolean;
+	readonly refetchOnMount?: boolean | "always";
+	readonly enabled?: boolean;
+	readonly networkMode?: "online" | "always" | "offlineFirst";
+	readonly placeholderData?: PlaceholderDataValue<TData>;
+	readonly initialData?: TData;
+	readonly select?: (data: TData) => TSelected;
+	readonly meta?: Record<string, unknown>;
+};
+
+export type QueryStatus = "pending" | "error" | "success";
+
+export type FetchStatus = "idle" | "fetching" | "paused";
+
+export type QueryState<TData = unknown, TError = Error> = {
+	readonly data: TData | undefined;
+	readonly dataUpdatedAt: number;
+	readonly error: TError | null;
+	readonly errorUpdatedAt: number;
+	readonly failureCount: number;
+	readonly failureReason: TError | null;
+	readonly fetchStatus: FetchStatus;
+	readonly status: QueryStatus;
+};
+
+export type QueryObserverResult<TData = unknown, TError = Error> = QueryState<
+	TData,
+	TError
+> & {
+	readonly isLoading: boolean;
+	readonly isFetching: boolean;
+	readonly isPending: boolean;
+	readonly isSuccess: boolean;
+	readonly isError: boolean;
+	readonly isInitialLoading: boolean;
+	readonly isStale: boolean;
+};
+
+export type QueryFilter = {
+	readonly queryKey?: QueryKey;
+	readonly exact?: boolean;
+	readonly predicate?: (queryKey: QueryKey) => boolean;
+	readonly type?: "all" | "active" | "inactive";
+	readonly stale?: boolean;
+};
+
+export type MutationStatus = "idle" | "pending" | "error" | "success";
+
+export type MutationOptions<
+	TData = unknown,
+	TError = Error,
+	TVariables = void,
+	TContext = unknown,
+> = {
+	readonly mutationFn: (variables: TVariables) => Promise<TData>;
+	readonly mutationKey?: QueryKey;
+	readonly retry?: RetryValue<TError>;
+	readonly retryDelay?: RetryDelayValue<TError>;
+	readonly networkMode?: "online" | "always" | "offlineFirst";
+	readonly onMutate?: (variables: TVariables) => Promise<TContext> | TContext;
+	readonly onError?: (
+		error: TError,
+		variables: TVariables,
+		context: TContext | undefined,
+	) => Promise<unknown> | unknown;
+	readonly onSuccess?: (
+		data: TData,
+		variables: TVariables,
+		context: TContext | undefined,
+	) => Promise<unknown> | unknown;
+	readonly onSettled?: (
+		data: TData | undefined,
+		error: TError | null,
+		variables: TVariables,
+		context: TContext | undefined,
+	) => Promise<unknown> | unknown;
+	readonly meta?: Record<string, unknown>;
+};
+
+export type MutationState<
+	TData = unknown,
+	TError = Error,
+	TVariables = void,
+> = {
+	readonly data: TData | undefined;
+	readonly error: TError | null;
+	readonly failureCount: number;
+	readonly failureReason: TError | null;
+	readonly isIdle: boolean;
+	readonly isPending: boolean;
+	readonly isPaused: boolean;
+	readonly isSuccess: boolean;
+	readonly isError: boolean;
+	readonly status: MutationStatus;
+	readonly submittedAt: number;
+	readonly variables: TVariables | undefined;
+};
+
+export type MutationResult<
+	TData = unknown,
+	TError = Error,
+	TVariables = void,
+> = MutationState<TData, TError, TVariables> & {
+	readonly mutate: (variables: TVariables) => void;
+	readonly mutateAsync: (variables: TVariables) => Promise<TData>;
+	readonly reset: () => void;
+};
+
+export type MutationFilter = {
+	readonly mutationKey?: QueryKey;
+	readonly exact?: boolean;
+	readonly predicate?: (mutationKey: QueryKey) => boolean;
+	readonly status?: MutationStatus;
+};
+
+export type InfiniteQueryPageParam<TData = unknown> = (
+	lastPage: TData,
+	allPages: TData[],
+) => unknown | undefined;
+
+export type InfiniteQueryOptions<
+	TData = unknown,
+	TError = Error,
+	TSelected = TData,
+> = Omit<
+	QueryOptions<InfiniteData<TData>, TError, InfiniteData<TSelected>>,
+	"queryFn"
+> & {
+	readonly queryFn: (
+		context: QueryFunctionContext & { pageParam: unknown },
+	) => Promise<TData>;
+	readonly getNextPageParam: InfiniteQueryPageParam<TData>;
+	readonly getPreviousPageParam?: InfiniteQueryPageParam<TData>;
+	readonly initialPageParam: unknown;
+	readonly maxPages?: number;
+};
+
+export type InfiniteData<TData = unknown> = {
+	readonly pages: TData[];
+	readonly pageParams: unknown[];
+};
+
+export type InfiniteQueryObserverResult<
+	TData = unknown,
+	TError = Error,
+	TSelected = TData,
+> = QueryObserverResult<InfiniteData<TSelected>, TError> & {
+	readonly hasNextPage: boolean;
+	readonly hasPreviousPage: boolean;
+	readonly isFetchingNextPage: boolean;
+	readonly isFetchingPreviousPage: boolean;
+	readonly fetchNextPage: () => Promise<void>;
+	readonly fetchPreviousPage: () => Promise<void>;
+	readonly refetch: () => Promise<void>;
+};
+
+export type QueryClock = () => number;
+
+export type QueryClientConfig = {
+	readonly defaultOptions?: DefaultOptions;
+	readonly queryCache?: QueryCache;
+	readonly mutationCache?: MutationCache;
+	readonly ports?: QueryClientPorts;
+	readonly clock?: QueryClock;
+};
+
+export type DefaultOptions = {
+	readonly queries?: Partial<QueryOptions>;
+	readonly mutations?: Partial<MutationOptions>;
+};
+
+export type MutationFunctionContext<
+	TVariables = unknown,
+	TContext = unknown,
+> = {
+	readonly variables: TVariables;
+	readonly context: TContext | undefined;
+};
+
+export type Updater<TInput, TOutput> = TOutput | ((input: TInput) => TOutput);
+
+export function queryOptions<
+	TData,
+	TError = Error,
+	TSelected = TData,
+	TKey extends QueryKey = QueryKey,
+>(
+	options: QueryOptions<TData, TError, TSelected> & { readonly queryKey: TKey },
+): QueryOptions<TData, TError, TSelected> & { readonly queryKey: TKey } {
+	return options;
+}

package/src/query/shared/index.ts

@@ -0,0 +1,48 @@
+import type { QueryNetworkPort } from "#query/modules/query/ports";
+import type { QueryKey } from "#query/modules/query/types";
+
+export const hashKey = (key: QueryKey): string => JSON.stringify(key);
+
+export const isPlainObject = (
+	value: unknown,
+): value is Record<string, unknown> =>
+	Object.prototype.toString.call(value) === "[object Object]";
+
+export const sleep = (ms: number): Promise<void> =>
+	new Promise((resolve) => setTimeout(resolve, ms));
+
+export const isOnline = (): boolean =>
+	typeof navigator !== "undefined" && navigator.onLine !== false;
+
+export const isVisible = (): boolean =>
+	typeof document !== "undefined" && document.visibilityState !== "hidden";
+
+export const defaultNetworkPort: QueryNetworkPort = {
+	name: "default",
+	isOnline,
+	isVisible,
+	onOnline(callback) {
+		if (typeof window === "undefined") return () => {};
+		const handler = () => {
+			if (isOnline()) callback();
+		};
+		window.addEventListener("online", handler);
+		return () => window.removeEventListener("online", handler);
+	},
+	onVisibilityChange(callback) {
+		if (typeof document === "undefined") return () => {};
+		const handler = () => {
+			if (isVisible()) callback();
+		};
+		document.addEventListener("visibilitychange", handler);
+		return () => document.removeEventListener("visibilitychange", handler);
+	},
+	onFocus(callback) {
+		if (typeof window === "undefined") return () => {};
+		const handler = () => {
+			if (isVisible()) callback();
+		};
+		window.addEventListener("focus", handler);
+		return () => window.removeEventListener("focus", handler);
+	},
+};

package/src/render/adapters/index.ts

@@ -0,0 +1 @@
+export * from "./solid-web";

package/src/render/adapters/solid-web/hydration.ts

@@ -0,0 +1,35 @@
+/**
+ * Solid Web Hydration
+ * Client-side hydration and mount helpers
+ */
+
+import type { JSX } from "solid-js";
+import { hydrate, render } from "solid-js/web";
+import type { ClientHydratorPort } from "#render/modules/render/ports";
+import type { Renderable } from "#render/types";
+
+export const createSolidHydrator = (): ClientHydratorPort => ({
+	hydrate: (renderable: Renderable, element: Element) =>
+		hydrate(renderable, element),
+	mount: (renderable: () => JSX.Element, element: Element) =>
+		render(renderable, element),
+});
+
+export const hydrateApp = (
+	renderable: Renderable,
+	element: Element | null = typeof document !== "undefined"
+		? document.getElementById("app")
+		: null,
+): (() => void) => {
+	if (!element) {
+		throw new Error(
+			"[solid-framework] hydrateApp: mount element not found (expected #app)",
+		);
+	}
+	// CSR shells ship an empty mount — plain render() then
+	const html = element.innerHTML;
+	if (!html.includes("data-hk") && !html.includes("<!--!")) {
+		return render(renderable as () => JSX.Element, element);
+	}
+	return hydrate(renderable, element);
+};

package/src/render/adapters/solid-web/index.ts

@@ -0,0 +1,3 @@
+export { isServer } from "solid-js/web";
+export * from "./hydration";
+export * from "./renderer";

package/src/render/adapters/solid-web/renderer.ts

@@ -0,0 +1,20 @@
+/**
+ * Solid Web Server Renderer
+ * Adapter over solid-js/web SSR primitives
+ */
+
+import { renderToStream, renderToStringAsync } from "solid-js/web";
+import type { ServerRendererPort } from "#render/modules/render/ports";
+import type { Renderable } from "#render/types";
+
+export const createSolidServerRenderer = (): ServerRendererPort => ({
+	renderToString: (renderable: Renderable) => renderToStringAsync(renderable),
+
+	renderToStream: (renderable: Renderable): ReadableStream<Uint8Array> => {
+		const transform = new TransformStream<Uint8Array, Uint8Array>();
+		const solidStream = renderToStream(renderable);
+		// solid-js/web exposes pipeTo(WritableStream) for web streams
+		solidStream.pipeTo(transform.writable);
+		return transform.readable;
+	},
+});

package/src/render/index.ts

@@ -0,0 +1,7 @@
+// Public API - @wrikka/solid-framework/render
+
+export * from "./adapters";
+export * from "./modules/render";
+export * from "./presentation";
+export * from "./shared";
+export * from "./types";

package/src/render/modules/render/application/index.ts

@@ -0,0 +1 @@
+export * from "./usecases";

package/src/render/modules/render/application/usecases/index.ts

@@ -0,0 +1,4 @@
+export * from "./remote-island";
+export * from "./render-page";
+export * from "./render-shell";
+export * from "./stream-page";

package/src/render/modules/render/application/usecases/remote-island.ts

@@ -0,0 +1,46 @@
+/**
+ * Remote Island Endpoint
+ * `/_island/<name>?props=<json>` renders a registered island to an
+ * HTML fragment — the Nuxt `remoteIsland` equivalent. Pages on any
+ * origin (or a different framework app) can embed the fragment
+ * and hydrate it with hydrateIslands()
+ */
+
+import { renderToString } from "solid-js/web";
+import { getIsland } from "#render/presentation/Island";
+
+export const ISLAND_ENDPOINT = "/_island";
+
+export const isIslandRequest = (request: Request): boolean =>
+	new URL(request.url).pathname.startsWith(`${ISLAND_ENDPOINT}/`);
+
+export const createIslandHandler = (): ((
+	request: Request,
+) => Promise<Response | null>) => {
+	return async (request: Request): Promise<Response | null> => {
+		const url = new URL(request.url);
+		const name = decodeURIComponent(
+			url.pathname.slice(ISLAND_ENDPOINT.length + 1),
+		);
+		const component = getIsland(name);
+		if (!component) return null;
+
+		let props: Record<string, unknown> = {};
+		const raw = url.searchParams.get("props");
+		if (raw) {
+			try {
+				props = JSON.parse(raw) as Record<string, unknown>;
+			} catch {
+				return new Response("Invalid island props", { status: 400 });
+			}
+		}
+
+		const html = renderToString(() => component(props));
+		return new Response(html, {
+			headers: {
+				"Content-Type": "text/html; charset=utf-8",
+				"Cache-Control": "public, max-age=60",
+			},
+		});
+	};
+};

package/src/render/modules/render/application/usecases/render-page.ts

@@ -0,0 +1,86 @@
+/**
+ * Render Page Use Case
+ * Produce a complete HTML document string for one request
+ */
+
+import {
+	createDocumentModel,
+	hydrationScriptTag,
+	renderAssetTags,
+	renderHeadHtml,
+} from "#render/modules/render/domain";
+import type { ServerRendererPort } from "#render/modules/render/ports";
+import type {
+	HydrationPayload,
+	Renderable,
+	RenderOptions,
+	RenderResult,
+} from "#render/types";
+
+export interface RenderPageInput {
+	renderable: Renderable;
+	options?: RenderOptions;
+	headTags?: string[];
+	/** Head HTML collected after the render pass (e.g. HeadProvider sink) */
+	collectHead?: () => string;
+	title?: string;
+	lang?: string;
+	/** Client entry script url emitted at the end of body */
+	entry?: string;
+	/** CSP nonce applied to the hydration + entry scripts */
+	nonce?: string;
+}
+
+/**
+ * Render a Solid tree to a full HTML document (non-streaming).
+ * The document shell is assembled from the document model; the rendered
+ * app markup is injected into the mount point.
+ */
+export const renderPage = async (
+	renderer: ServerRendererPort,
+	input: RenderPageInput,
+): Promise<RenderResult> => {
+	const context = input.options?.context;
+	const hydration = context?.hydration ?? { loaders: {}, stores: {} };
+
+	const appHtml = await renderer.renderToString(input.renderable);
+
+	// Deferred loader values — resolve all before serializing hydration
+	// so the client materializes them synchronously
+	const deferred = (
+		hydration as HydrationPayload & {
+			__deferred?: Map<string, Promise<unknown>>;
+		}
+	).__deferred;
+	if (deferred?.size) {
+		const resolved: Record<string, unknown> = {};
+		for (const [key, promise] of deferred) {
+			resolved[key] = await promise;
+		}
+		hydration.deferred = resolved;
+	}
+
+	const headFromContext = context?.head?.renderToString();
+	const collected = input.collectHead?.();
+	const model = createDocumentModel({
+		lang: input.lang,
+		title: input.title,
+		headTags: [
+			...(input.headTags ?? []),
+			...(collected ? [collected] : []),
+			...(headFromContext ? [headFromContext] : []),
+		],
+		assets: { entry: input.entry },
+		hydrationScript: hydrationScriptTag(hydration, input.nonce),
+	});
+
+	const html = [
+		"<!doctype html>",
+		`<html lang="${model.lang}">`,
+		`<head>${renderHeadHtml(model)}${model.hydrationScript ?? ""}</head>`,
+		`<body><div id="app">${appHtml}</div>${renderAssetTags(model)}</body>`,
+		"</html>",
+	].join("");
+
+	return { html, hydration };
+};

package/src/render/modules/render/application/usecases/render-shell.ts

@@ -0,0 +1,56 @@
+/**
+ * Render Shell Use Case
+ * Produce the document shell without rendering the app — CSR mode
+ */
+
+import {
+	createDocumentModel,
+	hydrationScriptTag,
+	renderAssetTags,
+	renderHeadHtml,
+} from "#render/modules/render/domain";
+import type { HydrationPayload } from "#render/types";
+
+export interface RenderShellInput {
+	title?: string;
+	lang?: string;
+	headTags?: string[];
+	hydration?: HydrationPayload;
+	/** Client entry script url — emitted as the boot module */
+	entry?: string;
+	/** CSP nonce applied to the hydration script */
+	nonce?: string;
+}
+
+/**
+ * Build a client-side-rendered document: full head, empty mount point,
+ * hydration payload and the client entry script.
+ */
+export const renderShell = (input: RenderShellInput = {}): string => {
+	const hydration = input.hydration ?? { loaders: {}, stores: {} };
+	const model = createDocumentModel({
+		lang: input.lang,
+		title: input.title,
+		headTags: input.headTags ?? [],
+		assets: { entry: input.entry },
+	});
+
+	return [
+		"<!doctype html>",
+		`<html lang="${model.lang}">`,
+		`<head>${renderHeadHtml(model)}${hydrationScriptTag(hydration, input.nonce)}</head>`,
+		`<body><div id="app"></div>${renderAssetTags(model)}</body>`,
+		"</html>",
+	].join("");
+};
+
+export const renderShellResponse = (
+	input: RenderShellInput = {},
+	headers?: HeadersInit,
+): Response => {
+	const responseHeaders = new Headers(headers);
+	if (!responseHeaders.has("Content-Type")) {
+		responseHeaders.set("Content-Type", "text/html; charset=utf-8");
+	}
+	return new Response(renderShell(input), { headers: responseHeaders });
+};