@decocms/start 2.25.0 → 2.27.0

package/src/sdk/useSuggestions.test.ts

@@ -0,0 +1,230 @@
+/**
+ * Tests for the `createUseSuggestions` factory.
+ *
+ * The hook itself depends on React (useCallback). This file exercises
+ * the parts of the factory that don't need a React renderer:
+ *  - factory shape + isolation between calls
+ *  - the non-React `_internal.setQuery` flow which carries every bit
+ *    of behaviour the React hook delegates to (queue, cancel guard,
+ *    loading-flag invariants, error path)
+ *
+ * Hook-level integration is exercised by the site-level smoke (the
+ * factory has shipped to two production sites with the same shape).
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { createUseSuggestions } from "./useSuggestions";
+
+interface FakeSuggestion {
+	products: string[];
+}
+
+const FAKE_LOADER = {
+	__resolveType: "site/loaders/search/suggestions.ts",
+	limit: 5,
+} as unknown as FakeSuggestion;
+
+function makeOkFetch(payload: unknown, delayMs = 0): typeof fetch {
+	return ((_input: RequestInfo | URL, _init?: RequestInit) =>
+		new Promise((resolve) => {
+			setTimeout(
+				() =>
+					resolve(
+						new Response(JSON.stringify(payload), {
+							status: 200,
+							headers: { "Content-Type": "application/json" },
+						}),
+					),
+				delayMs,
+			);
+		})) as typeof fetch;
+}
+
+describe("createUseSuggestions — factory shape", () => {
+	it("returns useSuggestions + _internal", () => {
+		const f = createUseSuggestions<FakeSuggestion>();
+		expect(typeof f.useSuggestions).toBe("function");
+		expect(typeof f._internal.setQuery).toBe("function");
+		expect(typeof f._internal.drain).toBe("function");
+		expect(f._internal.payload.value).toBeNull();
+		expect(f._internal.loading.value).toBe(false);
+	});
+
+	it("two factory calls produce independent state + functions", () => {
+		const a = createUseSuggestions<FakeSuggestion>();
+		const b = createUseSuggestions<FakeSuggestion>();
+		expect(a.useSuggestions).not.toBe(b.useSuggestions);
+		expect(a._internal.payload).not.toBe(b._internal.payload);
+		expect(a._internal.loading).not.toBe(b._internal.loading);
+	});
+});
+
+describe("createUseSuggestions — fetch happy path", () => {
+	it("posts to /deco/invoke/<__resolveType> with the query + extra props", async () => {
+		const spy = vi.fn(makeOkFetch({ products: ["a", "b"] }));
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl: spy });
+		f._internal.setQuery("samsung", FAKE_LOADER);
+		await f._internal.drain();
+
+		expect(spy).toHaveBeenCalledTimes(1);
+		const [url, init] = spy.mock.calls[0];
+		expect(url).toBe("/deco/invoke/site/loaders/search/suggestions.ts");
+		expect(init?.method).toBe("POST");
+		expect(JSON.parse(init?.body as string)).toEqual({
+			query: "samsung",
+			limit: 5,
+		});
+	});
+
+	it("populates payload with the parsed response", async () => {
+		const f = createUseSuggestions<FakeSuggestion>({
+			fetchImpl: makeOkFetch({ products: ["a", "b"] }),
+		});
+		f._internal.setQuery("samsung", FAKE_LOADER);
+		await f._internal.drain();
+		expect(f._internal.payload.value).toEqual({ products: ["a", "b"] });
+	});
+
+	it("flips loading to true synchronously, back to false after fetch settles", async () => {
+		const f = createUseSuggestions<FakeSuggestion>({
+			fetchImpl: makeOkFetch({ products: [] }),
+		});
+		expect(f._internal.loading.value).toBe(false);
+		f._internal.setQuery("hi", FAKE_LOADER);
+		expect(f._internal.loading.value).toBe(true);
+		await f._internal.drain();
+		expect(f._internal.loading.value).toBe(false);
+	});
+});
+
+describe("createUseSuggestions — cancel + queue semantics", () => {
+	it("cancels older queries BEFORE they fetch — only the latest hits the network", async () => {
+		// Mock echoes the body's `query` field so we can tell which
+		// invocation actually reached the network.
+		const calls: string[] = [];
+		const fetchImpl: typeof fetch = ((_url, init) => {
+			const body = JSON.parse(init?.body as string) as { query: string };
+			calls.push(body.query);
+			return Promise.resolve(
+				new Response(JSON.stringify({ products: [body.query] }), {
+					status: 200,
+				}),
+			);
+		}) as typeof fetch;
+
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+		// Three queries kicked off back-to-back synchronously.
+		f._internal.setQuery("a", FAKE_LOADER);
+		f._internal.setQuery("b", FAKE_LOADER);
+		f._internal.setQuery("c", FAKE_LOADER);
+		await f._internal.drain();
+
+		// Only the latest query reaches the network — the cancel
+		// guard short-circuits the first two before they fetch.
+		expect(calls).toEqual(["c"]);
+		expect(f._internal.payload.value).toEqual({ products: ["c"] });
+	});
+
+	it("the latest-query guard prevents stale fetches from clearing loading prematurely", async () => {
+		// If the cancel guard ever regresses, this is the test that
+		// catches it: we kick off fetch #1, immediately call setQuery
+		// again, await drain, and expect the FINAL state to reflect
+		// the latest query — not an inconsistent "loading false but
+		// payload stale" mid-state.
+		const fetchImpl = makeOkFetch({ products: ["latest"] }, 5);
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+		f._internal.setQuery("a", FAKE_LOADER);
+		f._internal.setQuery("b", FAKE_LOADER);
+		f._internal.setQuery("c", FAKE_LOADER);
+		await f._internal.drain();
+		expect(f._internal.loading.value).toBe(false);
+		expect(f._internal.payload.value).toEqual({ products: ["latest"] });
+	});
+
+	it("queues serially — fetches don't run concurrently", async () => {
+		// Race detector: track whether the count of in-flight fetches
+		// ever exceeds 1.
+		let inflight = 0;
+		let maxInflight = 0;
+		const fetchImpl: typeof fetch = (() =>
+			new Promise<Response>((resolve) => {
+				inflight += 1;
+				maxInflight = Math.max(maxInflight, inflight);
+				setTimeout(() => {
+					inflight -= 1;
+					resolve(
+						new Response(JSON.stringify({ products: [] }), { status: 200 }),
+					);
+				}, 5);
+			})) as typeof fetch;
+
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+		f._internal.setQuery("a", FAKE_LOADER);
+		f._internal.setQuery("b", FAKE_LOADER);
+		f._internal.setQuery("c", FAKE_LOADER);
+		await f._internal.drain();
+		expect(maxInflight).toBe(1);
+	});
+});
+
+describe("createUseSuggestions — error path", () => {
+	it("forwards thrown errors to onError + console.error, does NOT update payload", async () => {
+		const onError = vi.fn();
+		const consoleError = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => {});
+
+		const fetchImpl = (() =>
+			Promise.reject(new Error("network down"))) as typeof fetch;
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl, onError });
+
+		f._internal.setQuery("samsung", FAKE_LOADER);
+		await f._internal.drain();
+
+		expect(onError).toHaveBeenCalledTimes(1);
+		const [err, query] = onError.mock.calls[0];
+		expect((err as Error).message).toBe("network down");
+		expect(query).toBe("samsung");
+		expect(consoleError).toHaveBeenCalled();
+		expect(f._internal.payload.value).toBeNull();
+		expect(f._internal.loading.value).toBe(false);
+
+		consoleError.mockRestore();
+	});
+
+	it("non-2xx responses surface as errors", async () => {
+		const onError = vi.fn();
+		const consoleError = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => {});
+		const fetchImpl = (() =>
+			Promise.resolve(
+				new Response("internal error", { status: 500 }),
+			)) as typeof fetch;
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl, onError });
+
+		f._internal.setQuery("x", FAKE_LOADER);
+		await f._internal.drain();
+
+		expect(onError).toHaveBeenCalledTimes(1);
+		expect((onError.mock.calls[0][0] as Error).message).toContain("500");
+		expect(f._internal.payload.value).toBeNull();
+		expect(f._internal.loading.value).toBe(false);
+
+		consoleError.mockRestore();
+	});
+
+	it("does NOT throw if onError is omitted (still console.errors)", async () => {
+		const consoleError = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => {});
+		const fetchImpl = (() =>
+			Promise.reject(new Error("boom"))) as typeof fetch;
+		const f = createUseSuggestions<FakeSuggestion>({ fetchImpl });
+
+		f._internal.setQuery("x", FAKE_LOADER);
+		await expect(f._internal.drain()).resolves.toBeUndefined();
+		expect(consoleError).toHaveBeenCalled();
+		consoleError.mockRestore();
+	});
+});

package/src/sdk/useSuggestions.ts

@@ -0,0 +1,188 @@
+/**
+ * Search-suggestions hook factory.
+ *
+ * Both casaevideo-storefront and baggagio-tanstack independently
+ * invented the same shape for autocomplete-style suggestions:
+ *
+ *  - module-level signal for the current payload + loading flag
+ *  - serial in-flight queue so older requests can't race past newer ones
+ *  - "is this still the latest query?" cancel guard
+ *  - posts to `/deco/invoke/<__resolveType>` with the loader's
+ *    extra props + the live `query` string
+ *
+ * This factory is the canonical version. Sites instantiate it once
+ * at module load with their concrete suggestion type and (optionally)
+ * an `onError` hook for observability (Sentry / OpenTelemetry / etc.).
+ *
+ * Why a factory and not a plain hook:
+ *  - Each call to `createUseSuggestions()` produces an isolated
+ *    `payload` / `loading` / queue. Keeps the door open for sites
+ *    with multiple independent suggestion streams (e.g. searchbar
+ *    *and* a category-jump suggester) without globally-shared state.
+ *  - Type narrowing happens at the factory boundary, not at hook
+ *    usage — the returned `useSuggestions` is already specialised
+ *    on `T` so callers don't need to re-pass generics.
+ *  - Mirrors the existing `createUseCart` / `createUseUser` /
+ *    `createUseWishlist` factory pattern from
+ *    `@decocms/apps/vtex/hooks/*`. See
+ *    `references/platform-hooks-factories.md`.
+ */
+
+import { useCallback } from "react";
+import type { Resolved } from "../types";
+import { signal, type ReactiveSignal } from "./signal";
+
+/**
+ * Optional dependencies the factory accepts at instantiation time.
+ *
+ * Most are pure observability hooks — the factory itself runs a
+ * `console.error()` after invoking `onError`, so callers don't have
+ * to remember to forward the error to the console themselves.
+ */
+export interface UseSuggestionsOptions {
+	/**
+	 * Called once per failed fetch with the original error and the
+	 * query that triggered it. Use for Sentry / OTEL captures.
+	 *
+	 * The factory still calls `console.error` after this returns so
+	 * sites that don't wire `onError` keep the same console output.
+	 */
+	onError?: (error: unknown, query: string) => void;
+
+	/**
+	 * Override the fetch implementation. Tests pass a stub here; the
+	 * default is the global `fetch`. Production sites have no reason
+	 * to set this.
+	 */
+	fetchImpl?: typeof fetch;
+}
+
+/**
+ * Shape returned by the hook produced by `createUseSuggestions`.
+ *
+ * `loading` and `payload` are reactive signals — subscribe with
+ * `useStore()` from `@tanstack/react-store` (or read `.value`
+ * directly inside an `useEffect`).
+ */
+export interface UseSuggestionsReturn<T> {
+	loading: ReactiveSignal<boolean>;
+	payload: ReactiveSignal<T | null>;
+	/**
+	 * Trigger a suggestion fetch for `query`. Calls coalesce through
+	 * a serial promise queue, and only the *latest* query's result
+	 * is allowed to flip `loading` back to `false` — so rapid keystrokes
+	 * don't leave the UI permanently in a stale loading state.
+	 */
+	setQuery: (query: string) => void;
+}
+
+/**
+ * Returned by {@link createUseSuggestions}.
+ *
+ * `useSuggestions` is the React hook bound to this factory's state.
+ * The `_internal` field exposes the underlying signals and a non-
+ * React `setQuery` for advanced cases (SSR pre-population, unit
+ * tests, server-side warmup). Sites almost never need it.
+ */
+export interface CreateUseSuggestionsReturn<T> {
+	useSuggestions: (loader: Resolved<T | null>) => UseSuggestionsReturn<T>;
+	_internal: {
+		readonly payload: ReactiveSignal<T | null>;
+		readonly loading: ReactiveSignal<boolean>;
+		/**
+		 * Same semantics as `useSuggestions(...).setQuery`, but pure JS —
+		 * no React hook context required. Useful in unit tests and for
+		 * SSR pre-fetch helpers.
+		 */
+		setQuery: (query: string, loader: Resolved<T | null>) => void;
+		/**
+		 * Promise that resolves once every queued fetch has settled.
+		 * Tests await this to assert post-cancellation state.
+		 */
+		readonly drain: () => Promise<unknown>;
+	};
+}
+
+/**
+ * Build a typed `useSuggestions` hook bound to a private
+ * `payload` / `loading` / queue tuple. Call once per stream at
+ * module load.
+ *
+ * @example
+ *   // site/src/sdk/useSuggestions.ts
+ *   import { createUseSuggestions } from "@decocms/start/sdk/useSuggestions";
+ *   import * as Sentry from "@sentry/react";
+ *   import type { Suggestion } from "@decocms/apps/commerce/types";
+ *
+ *   export const { useSuggestions } = createUseSuggestions<Suggestion>({
+ *     onError: (err) => Sentry.captureException(err),
+ *   });
+ */
+export function createUseSuggestions<T>(
+	options: UseSuggestionsOptions = {},
+): CreateUseSuggestionsReturn<T> {
+	const payload = signal<T | null>(null);
+	const loading = signal<boolean>(false);
+	let queue: Promise<unknown> = Promise.resolve();
+	let latestQuery = "";
+
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const onError = options.onError;
+
+	async function doFetch(
+		query: string,
+		resolved: Resolved<T | null>,
+	): Promise<void> {
+		if (latestQuery !== query) return;
+
+		const { __resolveType, ...extraProps } = resolved as {
+			__resolveType: string;
+			[k: string]: unknown;
+		};
+
+		try {
+			const response = await fetchImpl(`/deco/invoke/${__resolveType}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ query, ...extraProps }),
+			});
+			if (!response.ok) {
+				throw new Error(`Suggestions invoke failed: ${response.status}`);
+			}
+			payload.value = (await response.json()) as T | null;
+		} catch (error) {
+			onError?.(error, query);
+			console.error("[useSuggestions] fetch failed:", error);
+		} finally {
+			// Only the latest query is allowed to flip the loading flag —
+			// otherwise rapid keystrokes can leave the UI in a stale
+			// "still loading" state because an older fetch resolved last.
+			if (latestQuery === query) loading.value = false;
+		}
+	}
+
+	function setQueryImpl(query: string, loader: Resolved<T | null>): void {
+		loading.value = true;
+		latestQuery = query;
+		queue = queue.then(() => doFetch(query, loader));
+	}
+
+	function useSuggestions(loader: Resolved<T | null>): UseSuggestionsReturn<T> {
+		const setQuery = useCallback(
+			(query: string) => setQueryImpl(query, loader),
+			[loader],
+		);
+
+		return { loading, payload, setQuery };
+	}
+
+	return {
+		useSuggestions,
+		_internal: {
+			payload,
+			loading,
+			setQuery: setQueryImpl,
+			drain: () => queue,
+		},
+	};
+}