@findlane/browser 0.15.0 → 0.16.1

package/dist/index.d.ts

@@ -285,6 +285,7 @@ export type BrowserClientOptions = {
 };
 export declare class SearchBrowserClient {
     private readonly url;
+    private readonly origin;
     private readonly fetcher;
     /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
     readonly events: BrowserEvents;
@@ -294,6 +295,9 @@ export declare class SearchBrowserClient {
     constructor(options: BrowserClientOptions);
     private post;
     private get;
+    /** Opens the connection to the API before the first search needs it, as a preconnect hint in the page
+     * would: call it when the shopper focuses a search box. Once per page; nothing outside a browser. */
+    warm(): void;
     search<T = Record<string, unknown>>(request: SearchRequest, options?: {
         signal?: AbortSignal;
     }): Promise<SearchResponse<T>>;

package/dist/index.js

@@ -156,8 +156,11 @@ function eventSender(url, fetcher, mode, ids) {
         flush,
     };
 }
+/** Origins this page has opened a connection to ahead of a search (warm). */
+const warmed = new Set();
 export class SearchBrowserClient {
     url;
+    origin;
     fetcher;
     /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
     events;
@@ -168,6 +171,7 @@ export class SearchBrowserClient {
         if (!/^pub_[a-f0-9]{32}$/.test(options.publicId))
             throw new Error("A valid public index ID (pub_…) is required");
         this.url = `${(options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "")}/api/public/indexes/${options.publicId}`;
+        this.origin = new URL(this.url).origin;
         this.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
         this.events = eventSender(options.eventsUrl ?? `${this.url}/events`, options.fetch, options.events ?? true, options.visitorIds ? deviceIds(options.publicId) : null);
         this.recentSearches = new RecentSearches(options.publicId);
@@ -195,6 +199,19 @@ export class SearchBrowserClient {
             throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
         return data;
     }
+    /** Opens the connection to the API before the first search needs it, as a preconnect hint in the page
+     * would: call it when the shopper focuses a search box. Once per page; nothing outside a browser. */
+    warm() {
+        if (typeof document === "undefined" || warmed.has(this.origin))
+            return;
+        warmed.add(this.origin);
+        const link = document.createElement("link");
+        link.rel = "preconnect";
+        link.href = this.origin;
+        // Searches are sent without credentials, so they use the connection a crossorigin hint opens.
+        link.crossOrigin = "anonymous";
+        document.head.append(link);
+    }
     search(request, options = {}) {
         return this.post("search", request, options.signal);
     }

package/dist/react/cache.d.ts

@@ -1,6 +1,8 @@
 import type { QuerySuggestion, RecommendationsRequest, RecommendationsResponse, SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
 /** Requests the API answers the same way share a key, as at the edge (workers/api/src/edge.ts):
- * the query's first eight lowercase words, defaults left out, and list order ignored. */
+ * the query's first eight lowercase words, defaults left out, and list order ignored. Words keep an
+ * apostrophe or period inside them (don't, 3.5), which the API matches as one word; the edge's exact
+ * rule needs lookbehind, which older Safari can't parse, so this keeps a little more apart than it. */
 export declare function searchKey(request: SearchRequest): string;
 /** A product's recommendations share a key when only defaults differ: the limit of 8 and empty filters. */
 export declare function recommendationsKey(objectID: string, request?: RecommendationsRequest): string;

package/dist/react/cache.js

@@ -6,11 +6,14 @@ const searches = store();
 const recommendations = store();
 const suggestions = store();
 /** Requests the API answers the same way share a key, as at the edge (workers/api/src/edge.ts):
- * the query's first eight lowercase words, defaults left out, and list order ignored. */
+ * the query's first eight lowercase words, defaults left out, and list order ignored. Words keep an
+ * apostrophe or period inside them (don't, 3.5), which the API matches as one word; the edge's exact
+ * rule needs lookbehind, which older Safari can't parse, so this keeps a little more apart than it. */
 export function searchKey(request) {
     const normal = { ...request };
     if (typeof normal.q === "string" && normal.q.length <= 200)
-        normal.q = normal.q.toLowerCase().match(/[\p{L}\p{N}]+/gu)?.slice(0, 8).join(" ") ?? "";
+        normal.q = (normal.q.toLowerCase().replace(/[’‘]/gu, "'").match(/[\p{L}\p{M}\p{N}_'.:·,;]+/gu) ?? [])
+            .map((word) => word.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "")).filter(Boolean).slice(0, 8).join(" ");
     const defaults = { q: "", limit: 20, offset: 0, countMode: "page", facetMode: "page" };
     for (const [key, value] of Object.entries(defaults))
         if (normal[key] === value)

package/dist/react/components.js

@@ -65,8 +65,8 @@ export function SearchBox({ placeholder, label = "Search", action, renderHit, em
 }
 /** The query input of the surrounding SearchProvider. */
 export function SearchInput({ placeholder, label = "Search", className, autoFocus }) {
-    const { query, setQuery } = useSearchBox();
-    return (_jsx("form", { role: "search", className: className, "data-findlane-search-input": "", onSubmit: (event) => event.preventDefault(), children: _jsx("input", { type: "search", value: query, onChange: (event) => setQuery(event.target.value), placeholder: placeholder, "aria-label": label, autoFocus: autoFocus, autoComplete: "off", spellCheck: false, maxLength: 200 }) }));
+    const { query, setQuery, warm } = useSearchBox();
+    return (_jsx("form", { role: "search", className: className, "data-findlane-search-input": "", onSubmit: (event) => event.preventDefault(), children: _jsx("input", { type: "search", value: query, onChange: (event) => setQuery(event.target.value), onFocus: warm, placeholder: placeholder, "aria-label": label, autoFocus: autoFocus, autoComplete: "off", spellCheck: false, maxLength: 200 }) }));
 }
 /** Whether a click was on a link inside the element that handled it, such as a hit's link. */
 export function onLink(event) {

package/dist/react/search-provider.d.ts

@@ -29,6 +29,8 @@ export declare function useSearchBox(): {
     setQuery: (q: string) => void;
     clear: () => void;
     isPending: boolean;
+    /** Opens the connection to the API ahead of the first search: call it when the box gets focus. */
+    warm: () => void;
 };
 export declare function useHits<T = Record<string, unknown>>(): {
     hits: import("./state.js").Hit<T>[];

package/dist/react/search-provider.js

@@ -73,7 +73,9 @@ export function useSearchState() {
 export function useSearchBox() {
     const [{ state, pending }, store] = useSnapshot();
     const setQuery = (q) => store.update((current) => ({ ...current, q, page: 0 }));
-    return { query: state.q, setQuery, clear: () => setQuery(""), isPending: pending };
+    return { query: state.q, setQuery, clear: () => setQuery(""), isPending: pending,
+        /** Opens the connection to the API ahead of the first search: call it when the box gets focus. */
+        warm: () => store.warm() };
 }
 export function useHits() {
     const [{ results, pending, error }, store] = useSnapshot();

package/dist/react/store.d.ts

@@ -38,16 +38,21 @@ export declare class SearchStore<T = unknown> {
     private config;
     private snapshot;
     private listeners;
-    private controller;
+    private controllers;
+    private waiting;
     private timer;
     private run;
+    private shown;
+    private cut;
+    private lastSent;
     /** Called after each change a visitor makes, not when the state is adopted from outside. */
     onChange: ((state: SearchState, change: StateChange) => void) | null;
     constructor(client: SearchBrowserClient, config: SearchConfig, state: SearchState, initial?: ServerResults<T>);
     subscribe: (listener: () => void) => () => void;
     getSnapshot: () => Snapshot<T>;
     private set;
-    /** A visitor's change. Changes to the query wait for a pause in typing; the others search at once.
+    /** A visitor's change. A keystroke soon after the last search waits briefly for the next (typing.ts);
+     * other changes search at once.
      * `push` overrides how it reaches the history, as a map's moves replace the entry. */
     update(change: (state: SearchState) => SearchState, push?: boolean): void;
     /** A state from outside, such as the URL after Back. */
@@ -55,13 +60,20 @@ export declare class SearchStore<T = unknown> {
     /** A new client or config, from changed props. */
     configure(client: SearchBrowserClient, config: SearchConfig): void;
     get settings(): SearchConfig;
+    /** Opens the connection to the API before the first search needs it (the client's warm). */
+    warm(): void;
     /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
     click(objectID: string): void;
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */
     start(state?: SearchState): void;
+    /** Stops and drops every search in flight. */
     stop(): void;
+    private unschedule;
     private resultsFor;
+    /** Searches for the current state. While typing, earlier searches keep going: their answers fill the
+     * cache (Backspace shows them at once) and show until a newer one's arrive, never after. Any other
+     * change drops them. */
     private search;
     /** A did-you-mean suggestion for a request that found nothing. */
     suggest(request: SearchRequest, signal: AbortSignal): Promise<DidYouMean | null>;

package/dist/react/store.js

@@ -1,15 +1,21 @@
 import { cachedSearch, peek } from "./cache.js";
 import { canonical, hasMoreAfter, planSearch } from "./state.js";
-const typingPause = 150;
+import { typingWait } from "./typing.js";
 export const planKey = (request) => canonical(request);
 export class SearchStore {
     client;
     config;
     snapshot;
     listeners = new Set();
-    controller = null;
+    // Searches in flight, and the one waiting for a pause in typing.
+    controllers = new Set();
+    waiting = null;
     timer;
+    // Each search's number; `shown` is the one whose results show, and searches up to `cut` are dropped.
     run = 0;
+    shown = 0;
+    cut = 0;
+    lastSent = -Infinity;
     /** Called after each change a visitor makes, not when the state is adopted from outside. */
     onChange = null;
     constructor(client, config, state, initial) {
@@ -30,7 +36,8 @@ export class SearchStore {
         for (const listener of this.listeners)
             listener();
     }
-    /** A visitor's change. Changes to the query wait for a pause in typing; the others search at once.
+    /** A visitor's change. A keystroke soon after the last search waits briefly for the next (typing.ts);
+     * other changes search at once.
      * `push` overrides how it reaches the history, as a map's moves replace the entry. */
     update(change, push) {
         const previous = this.snapshot.state;
@@ -58,6 +65,8 @@ export class SearchStore {
         this.search(false);
     }
     get settings() { return this.config; }
+    /** Opens the connection to the API before the first search needs it (the client's warm). */
+    warm() { this.client.warm(); }
     /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
     click(objectID) {
         const results = this.snapshot.results;
@@ -74,46 +83,69 @@ export class SearchStore {
         if (this.snapshot.results?.key !== key || this.snapshot.error)
             this.search(false);
     }
+    /** Stops and drops every search in flight. */
     stop() {
+        this.unschedule();
+        for (const controller of this.controllers)
+            controller.abort();
+        this.controllers.clear();
+        this.cut = ++this.run;
+    }
+    unschedule() {
         clearTimeout(this.timer);
-        this.controller?.abort();
-        this.controller = null;
-        this.run++;
+        if (this.waiting)
+            this.controllers.delete(this.waiting);
+        this.waiting = null;
     }
     resultsFor(request, response) {
         return { key: planKey(request), request, response, hits: response.hits, hasMore: hasMoreAfter(response, request.offset ?? 0) };
     }
-    search(debounce) {
-        this.stop();
-        const run = this.run;
+    /** Searches for the current state. While typing, earlier searches keep going: their answers fill the
+     * cache (Backspace shows them at once) and show until a newer one's arrive, never after. Any other
+     * change drops them. */
+    search(typing) {
+        if (typing)
+            this.unschedule();
+        else
+            this.stop();
+        const run = ++this.run;
         const client = this.client;
         const request = planSearch(this.config, this.snapshot.state);
         // Results already in memory show at once, without a loading state.
         const cached = peek(client, request);
         if (cached) {
+            this.shown = run;
             this.set({ results: this.resultsFor(request, cached), pending: false, error: null, loadingMore: false });
             return;
         }
         this.set({ pending: true, loadingMore: false });
         const controller = new AbortController();
-        this.controller = controller;
+        this.controllers.add(controller);
         const go = () => {
-            const started = performance.now();
+            if (this.waiting === controller)
+                this.waiting = null;
+            this.lastSent = performance.now();
+            const started = this.lastSent;
             cachedSearch(client, request, controller.signal).then((response) => {
-                if (run !== this.run)
+                this.controllers.delete(controller);
+                if (run <= this.cut || run < this.shown)
                     return;
+                this.shown = run;
                 const ms = Math.round(performance.now() - started);
-                this.set({ results: { ...this.resultsFor(request, response), ms }, pending: false, error: null });
+                this.set({ results: { ...this.resultsFor(request, response), ms }, pending: run !== this.run, error: null });
             }, (error) => {
-                if (run !== this.run)
+                this.controllers.delete(controller);
+                // Only the latest search's failure shows; an earlier one's answer is no longer wanted.
+                if (run !== this.run || run <= this.cut)
                     return;
                 this.set({ pending: false, error });
             });
         };
-        if (debounce)
-            this.timer = setTimeout(go, typingPause);
-        else
-            go();
+        const wait = typing ? typingWait(this.lastSent) : 0;
+        if (!wait)
+            return go();
+        this.waiting = controller;
+        this.timer = setTimeout(go, wait);
     }
     /** A did-you-mean suggestion for a request that found nothing. */
     suggest(request, signal) {

package/dist/react/typing.d.ts

@@ -0,0 +1,6 @@
+/** How long a keystroke that comes soon after the last search waits for the next, in milliseconds.
+ * People type a key every 240 to 330 ms on average, so after a pause this long a search goes out at
+ * once, and only quick bursts and pastes are merged. */
+export declare const typingPause = 50;
+/** How long a search for a keystroke waits: none when the last search went out at least `pause` ago. */
+export declare function typingWait(lastSent: number, pause?: number, now?: number): number;

package/dist/react/typing.js

@@ -0,0 +1,9 @@
+// When a search for what's typed goes out (docs/speed-and-cost-research-2026-10-16.md, phase 2).
+/** How long a keystroke that comes soon after the last search waits for the next, in milliseconds.
+ * People type a key every 240 to 330 ms on average, so after a pause this long a search goes out at
+ * once, and only quick bursts and pastes are merged. */
+export const typingPause = 50;
+/** How long a search for a keystroke waits: none when the last search went out at least `pause` ago. */
+export function typingWait(lastSent, pause = typingPause, now = performance.now()) {
+    return now - lastSent >= pause ? 0 : pause;
+}

package/dist/react/use-autocomplete.js

@@ -1,9 +1,10 @@
 "use client";
-import { useEffect, useId, useState, } from "react";
+import { useEffect, useId, useRef, useState, } from "react";
 import { valuesAt } from "./highlight.js";
 import { useSearch } from "./use-search.js";
 import { useClient } from "./client.js";
 import { cachedQuerySuggestions, peekQuerySuggestions } from "./cache.js";
+import { typingPause, typingWait } from "./typing.js";
 /** A hit's address from a template; links to other schemes, such as javascript:, are refused. */
 export function fillTemplate(template, hit) {
     const value = (field) => (field === "objectID" ? hit.id : valuesAt(hit.record, field)[0] ?? "");
@@ -46,10 +47,11 @@ export function useAutocomplete(options = {}) {
     const client = useClient({ publicId: options.publicId, baseUrl: options.baseUrl, client: options.client });
     const hits = search.data?.hits ?? [];
     const emptyBox = query.trim() === "";
-    // Query suggestions for what's typed, after the same pause as the search; the last ones stay while
+    // Query suggestions for what's typed, on the same schedule as the search; the last ones stay while
     // the next load. Popular searches are asked for on the first focus (the client keeps them), and recent
     // ones read from this browser on each.
     const [suggestions, setSuggestions] = useState(noSuggestions);
+    const lastSuggested = useRef(-Infinity);
     const typed = request && suggestionLimit ? query : null;
     useEffect(() => {
         if (typed === null)
@@ -60,10 +62,11 @@ export function useAutocomplete(options = {}) {
         let active = true;
         const controller = new AbortController();
         const timer = setTimeout(() => {
+            lastSuggested.current = performance.now();
             cachedQuerySuggestions(client, typed, suggestionLimit, controller.signal)
                 .then((items) => { if (active)
                 setSuggestions(items); }, () => undefined);
-        }, debounceMs ?? 150);
+        }, typingWait(lastSuggested.current, debounceMs ?? typingPause));
         return () => {
             active = false;
             clearTimeout(timer);
@@ -242,6 +245,8 @@ export function useAutocomplete(options = {}) {
             },
             onFocus: (event) => {
                 props.onFocus?.(event);
+                // Opens the connection now, so the first keystroke's search doesn't wait for it.
+                client.warm();
                 setFocused(true);
                 setDismissed(false);
             },

package/dist/react/use-search.d.ts

@@ -1,7 +1,8 @@
 import type { SearchRequest, SearchResponse } from "../index.js";
 import { type ClientOptions } from "./client.js";
 export type UseSearchOptions<T> = ClientOptions & {
-    /** How long to wait for a pause in typing, in milliseconds (default 150). */
+    /** How long a change that comes within this long of the last search waits for the next, in
+     * milliseconds (default 50). A change after a longer pause searches at once. */
     debounceMs?: number;
     /** Results for the first request, such as ones from the server. The hook doesn't search again
      * until the request changes. */
@@ -14,6 +15,7 @@ export type UseSearchResult<T> = {
     /** A search is waiting for a pause in typing or is in flight. */
     isPending: boolean;
 };
-/** Keeps one search current. A new request cancels the one in flight, and a slow response never
- * replaces a newer one. Pass `null` to not search (and clear the results). */
+/** Keeps one search current. Earlier searches still in flight keep going, so their answers fill the
+ * cache and show while a newer one loads; a slow response never replaces a newer one. Pass `null` to
+ * not search (and clear the results). */
 export declare function useSearch<T = Record<string, unknown>>(request: SearchRequest | null, { debounceMs, initialData, ...clientOptions }?: UseSearchOptions<T>): UseSearchResult<T>;

package/dist/react/use-search.js

@@ -2,10 +2,20 @@
 import { useEffect, useRef, useState } from "react";
 import { cachedSearch, peek, searchKey } from "./cache.js";
 import { useClient } from "./client.js";
-/** Keeps one search current. A new request cancels the one in flight, and a slow response never
- * replaces a newer one. Pass `null` to not search (and clear the results). */
-export function useSearch(request, { debounceMs = 150, initialData, ...clientOptions } = {}) {
+import { typingPause, typingWait } from "./typing.js";
+/** Keeps one search current. Earlier searches still in flight keep going, so their answers fill the
+ * cache and show while a newer one loads; a slow response never replaces a newer one. Pass `null` to
+ * not search (and clear the results). */
+export function useSearch(request, { debounceMs = typingPause, initialData, ...clientOptions } = {}) {
     const client = useClient(clientOptions);
+    // Each search's number: the latest, the one whose results show, and when the last went out.
+    const runs = useRef({ latest: 0, shown: 0, lastSent: -Infinity, client });
+    const inFlight = useRef(new Set());
+    useEffect(() => () => {
+        for (const controller of inFlight.current)
+            controller.abort();
+        inFlight.current.clear();
+    }, []);
     const key = request ? searchKey(request) : null;
     const [result, setResult] = useState(() => ({
         data: initialData ?? null,
@@ -14,7 +24,17 @@ export function useSearch(request, { debounceMs = 150, initialData, ...clientOpt
     }));
     const initialKey = useRef(initialData ? key : null);
     useEffect(() => {
+        const ours = runs.current;
+        // Another client's searches (another index) are dropped.
+        if (ours.client !== client) {
+            for (const controller of inFlight.current)
+                controller.abort();
+            inFlight.current.clear();
+            ours.client = client;
+        }
+        const run = ++ours.latest;
         if (!request) {
+            ours.shown = run;
             setResult((current) => (current.data || current.error || current.isPending ? { data: null, error: null, isPending: false } : current));
             return;
         }
@@ -23,22 +43,33 @@ export function useSearch(request, { debounceMs = 150, initialData, ...clientOpt
         initialKey.current = null;
         const cached = peek(client, request);
         if (cached) {
+            ours.shown = run;
             setResult({ data: cached, error: null, isPending: false });
             return;
         }
         setResult((current) => (current.isPending ? current : { ...current, isPending: true }));
-        let active = true;
-        const controller = new AbortController();
-        const timer = setTimeout(() => {
-            cachedSearch(client, request, controller.signal).then((data) => { if (active)
-                setResult({ data, error: null, isPending: false }); }, (error) => { if (active)
-                setResult((current) => ({ ...current, error, isPending: false })); });
-        }, debounceMs);
-        return () => {
-            active = false;
-            clearTimeout(timer);
-            controller.abort();
+        const go = () => {
+            const controller = new AbortController();
+            inFlight.current.add(controller);
+            ours.lastSent = performance.now();
+            cachedSearch(client, request, controller.signal).then((data) => {
+                inFlight.current.delete(controller);
+                if (run < ours.shown || ours.client !== client)
+                    return;
+                ours.shown = run;
+                setResult({ data, error: null, isPending: run !== ours.latest });
+            }, (error) => {
+                inFlight.current.delete(controller);
+                if (run === ours.latest && ours.client === client)
+                    setResult((current) => ({ ...current, error, isPending: false }));
+            });
         };
+        const wait = typingWait(ours.lastSent, debounceMs);
+        if (!wait)
+            return go();
+        const timer = setTimeout(go, wait);
+        // A search that hasn't gone out yet is replaced; one in flight keeps going.
+        return () => clearTimeout(timer);
         // The key stands for the request, so a new object with the same search doesn't search again.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [client, key, debounceMs]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/browser",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Findlane browser SDK: fast, typo-tolerant public search from the browser with an index's public ID, plus React hooks and components.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "instant search", "ecommerce search", "browser", "react", "autocomplete"],
   "license": "MIT",