@farm.js/search 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,28 @@
+# `@farm.js/search`
+
+Build-time static page search for Farm.js applications, powered by Pagefind.
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { search } from "@farm.js/search";
+
+export default defineConfig({
+  plugins: [search({ include: ["/docs/**", "/blog/**"] })],
+});
+```
+
+Create a renderer-neutral browser client and query the generated index:
+
+```ts
+import { createSearch } from "@farm.js/search/client";
+
+const siteSearch = createSearch();
+const response = await siteSearch.search("server functions");
+```
+
+The plugin indexes only HTML emitted by static generation. It automatically respects Farm's
+`basePath`, writes a deployment-ready chunked index, and keeps dynamic or authenticated content out
+unless it was deliberately emitted as public static HTML.
+
+See the [Farm Search documentation](https://farmjs.dev/docs/plugins/search) for route selection,
+filters, result types, and production behavior.

package/dist/build.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedSearchOptions } from "./config.js";
+export interface SearchBuildInput {
+    outputDir: string;
+    publicDir?: string;
+    preset: string;
+    basePath: string;
+    options: ResolvedSearchOptions;
+}
+export interface SearchBuildResult {
+    bundlePath: string;
+    outputPath: string;
+    indexedRoutes: string[];
+    skippedRoutes: string[];
+}
+export declare function writeSearchIndex(input: SearchBuildInput): Promise<SearchBuildResult>;
+export declare function resolveSearchPublicDir(outputDir: string, preset: string): string;
+export declare function normalizeBasePath(value: string | undefined): string;
+export declare function withBasePath(route: string, basePath: string): string;
+export declare function stripBasePath(route: string, basePath: string): string;
+export declare function routeFromHtmlFile(file: string): string;
+export declare function matchesRoutePattern(route: string, pattern: string): boolean;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+E1F;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKhF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGnE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQpE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAoB3E"}

package/dist/build.js

@@ -0,0 +1,174 @@
+import { mkdir, readFile, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import * as pagefind from "pagefind";
+export async function writeSearchIndex(input) {
+    const publicDir = path.resolve(input.publicDir ?? resolveSearchPublicDir(input.outputDir, input.preset));
+    const basePath = normalizeBasePath(input.basePath);
+    const bundlePath = withBasePath(`/${input.options.output}`, basePath);
+    const outputPath = resolveOutputPath(publicDir, bundlePath);
+    const htmlFiles = await collectHtmlFiles(publicDir, outputPath);
+    const routes = htmlFiles
+        .map((file) => ({
+        file,
+        logicalRoute: stripBasePath(routeFromHtmlFile(path.relative(publicDir, file)), basePath),
+    }))
+        .sort((left, right) => left.logicalRoute.localeCompare(right.logicalRoute));
+    const selected = routes.filter(({ logicalRoute }) => shouldIndexRoute(logicalRoute, input.options));
+    const skippedRoutes = routes
+        .filter(({ logicalRoute }) => !shouldIndexRoute(logicalRoute, input.options))
+        .map(({ logicalRoute }) => withBasePath(logicalRoute, basePath));
+    if (selected.length === 0) {
+        throw new Error("[farm:search] No static HTML pages matched the configured routes. " +
+            "Mark searchable pages as static or update search include/exclude patterns.");
+    }
+    const created = await pagefind.createIndex({
+        ...(input.options.rootSelector ? { rootSelector: input.options.rootSelector } : {}),
+        ...(input.options.excludeSelectors.length
+            ? { excludeSelectors: input.options.excludeSelectors }
+            : {}),
+        ...(input.options.language ? { forceLanguage: input.options.language } : {}),
+        ...(input.options.includeCharacters
+            ? { includeCharacters: input.options.includeCharacters }
+            : {}),
+        keepIndexUrl: input.options.keepIndexUrl,
+        verbose: input.options.verbose,
+        writePlayground: false,
+    });
+    if (!created.index || created.errors.length) {
+        await pagefind.close();
+        throw pagefindError("could not create an index", created.errors);
+    }
+    const index = created.index;
+    const indexedRoutes = [];
+    try {
+        for (const { file, logicalRoute } of selected) {
+            const route = withBasePath(logicalRoute, basePath);
+            const result = await index.addHTMLFile({
+                url: route,
+                content: await readFile(file, "utf8"),
+            });
+            if (result.errors.length) {
+                throw pagefindError(`could not index ${route}`, result.errors);
+            }
+            indexedRoutes.push(route);
+        }
+        await rm(outputPath, { recursive: true, force: true });
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        const written = await index.writeFiles({ outputPath });
+        if (written.errors.length)
+            throw pagefindError("could not write the index", written.errors);
+    }
+    finally {
+        try {
+            await index.deleteIndex();
+        }
+        finally {
+            await pagefind.close();
+        }
+    }
+    return {
+        bundlePath: `${bundlePath}/`,
+        outputPath,
+        indexedRoutes,
+        skippedRoutes,
+    };
+}
+export function resolveSearchPublicDir(outputDir, preset) {
+    return path.join(outputDir, preset === "vercel" || preset === "vercel-edge" ? "static" : "public");
+}
+export function normalizeBasePath(value) {
+    if (!value || value === "/")
+        return "/";
+    return `/${value.replace(/^\/+|\/+$/g, "")}`;
+}
+export function withBasePath(route, basePath) {
+    const normalizedBase = normalizeBasePath(basePath);
+    const normalizedRoute = route === "/" ? "/" : `/${route.replace(/^\/+|\/+$/g, "")}`;
+    if (normalizedBase === "/")
+        return normalizedRoute;
+    if (normalizedRoute === normalizedBase || normalizedRoute.startsWith(`${normalizedBase}/`)) {
+        return normalizedRoute;
+    }
+    return normalizedRoute === "/" ? normalizedBase : `${normalizedBase}${normalizedRoute}`;
+}
+export function stripBasePath(route, basePath) {
+    const normalizedBase = normalizeBasePath(basePath);
+    if (normalizedBase === "/")
+        return route;
+    if (route === normalizedBase)
+        return "/";
+    return route.startsWith(`${normalizedBase}/`) ? route.slice(normalizedBase.length) || "/" : route;
+}
+export function routeFromHtmlFile(file) {
+    const normalized = file.replace(/\\/g, "/").replace(/^\/+/, "");
+    const withoutIndex = normalized.replace(/(?:^|\/)index\.html$/i, "");
+    const route = withoutIndex ? withoutIndex.replace(/\.html$/i, "").replace(/^\/+|\/+$/g, "") : "";
+    return route ? `/${route}` : "/";
+}
+export function matchesRoutePattern(route, pattern) {
+    if (pattern.endsWith("/**")) {
+        const parent = pattern.slice(0, -3) || "/";
+        return route === parent || route.startsWith(parent === "/" ? "/" : `${parent}/`);
+    }
+    let source = "";
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        if (character === "*" && pattern[index + 1] === "*") {
+            source += ".*";
+            index++;
+        }
+        else if (character === "*") {
+            source += "[^/]*";
+        }
+        else if (character === "?") {
+            source += "[^/]";
+        }
+        else {
+            source += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${source}/?$`).test(route);
+}
+function shouldIndexRoute(route, options) {
+    return (options.include.some((pattern) => matchesRoutePattern(route, pattern)) &&
+        !options.exclude.some((pattern) => matchesRoutePattern(route, pattern)));
+}
+async function collectHtmlFiles(root, ignoredDirectory) {
+    const files = [];
+    const pending = [root];
+    while (pending.length) {
+        const directory = pending.pop();
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        for (const entry of entries) {
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (absolute !== ignoredDirectory)
+                    pending.push(absolute);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".html")) {
+                files.push(absolute);
+            }
+        }
+    }
+    return files.sort();
+}
+function resolveOutputPath(publicDir, bundlePath) {
+    const outputPath = path.resolve(publicDir, `.${bundlePath}`);
+    const relative = path.relative(publicDir, outputPath);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("[farm:search] Search output must stay inside the public output directory");
+    }
+    return outputPath;
+}
+function pagefindError(action, errors) {
+    const details = errors.length ? `:\n${errors.map((error) => `  - ${error}`).join("\n")}` : "";
+    return new Error(`[farm:search] Pagefind ${action}${details}`);
+}

package/dist/client-runtime.d.ts

@@ -0,0 +1,53 @@
+import type { FarmSearchClient, FarmSearchPublicConfig, SearchClientOptions, SearchFilterCounts } from "./types.js";
+interface PagefindSearchFragment {
+    url: string;
+    content: string;
+    excerpt: string;
+    plain_excerpt: string;
+    word_count: number;
+    filters: Record<string, string[]>;
+    meta: Record<string, string>;
+    sub_results: Array<{
+        title: string;
+        url: string;
+        excerpt: string;
+        plain_excerpt: string;
+    }>;
+}
+interface PagefindResultHandle {
+    id: string;
+    score: number;
+    words: number[];
+    matchedMetaFields?: string[];
+    data(): Promise<PagefindSearchFragment>;
+}
+interface PagefindSearchResponse {
+    results: PagefindResultHandle[];
+    unfilteredResultCount: number;
+    filters: SearchFilterCounts;
+    totalFilters: SearchFilterCounts;
+    timings: {
+        preload: number;
+        search: number;
+        total: number;
+    } | Array<{
+        preload: number;
+        search: number;
+        total: number;
+    }>;
+}
+export interface PagefindBrowserApi {
+    options(options: Record<string, unknown>): Promise<void>;
+    init(): Promise<void>;
+    search(term: string | null, options?: Record<string, unknown>): Promise<PagefindSearchResponse>;
+    preload(term: string, options?: Record<string, unknown>): Promise<void>;
+    filters(): Promise<SearchFilterCounts>;
+    destroy(): Promise<void>;
+}
+export interface PagefindBrowserModule extends PagefindBrowserApi {
+    createInstance?(options?: Record<string, unknown>): PagefindBrowserApi | Promise<PagefindBrowserApi>;
+}
+export type PagefindModuleLoader = (url: string) => Promise<PagefindBrowserModule>;
+export declare function createSearchClient(resolveConfig: () => FarmSearchPublicConfig, options: SearchClientOptions, loadModule: PagefindModuleLoader): FarmSearchClient;
+export {};
+//# sourceMappingURL=client-runtime.d.ts.map

package/dist/client-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-runtime.d.ts","sourceRoot":"","sources":["../src/client-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAEpB,UAAU,sBAAsB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,WAAW,EAAE,KAAK,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;CACJ;AAED,UAAU,oBAAoB;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,IAAI,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzC;AAED,UAAU,sBAAsB;IAC9B,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EACH;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAClD,KAAK,CAAC;QACJ,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACR;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAChG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,cAAc,CAAC,CACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACrD;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAEnF,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,sBAAsB,EAC3C,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,oBAAoB,GAC/B,gBAAgB,CA0FlB"}

package/dist/client-runtime.js

@@ -0,0 +1,148 @@
+export function createSearchClient(resolveConfig, options, loadModule) {
+    let loaded;
+    const getApi = async () => {
+        const config = resolveConfig();
+        if (!config.available && !options.bundlePath) {
+            throw new Error("[farm:search] The search index is generated by production builds. " +
+                "Run farm build and serve the production output before searching.");
+        }
+        const bundlePath = normalizeBundlePath(options.bundlePath ?? config.bundlePath);
+        if (!loaded) {
+            const loading = loadModule(`${bundlePath}pagefind.js`)
+                .then(async (module) => {
+                const highlightParam = options.highlightParam === false
+                    ? undefined
+                    : (options.highlightParam ?? config.highlightParam);
+                const pagefindOptions = {
+                    basePath: bundlePath,
+                    excerptLength: normalizePositiveInteger(options.excerptLength ?? config.excerptLength, "excerptLength"),
+                    ...(highlightParam ? { highlightParam } : {}),
+                };
+                const api = module.createInstance ? await module.createInstance(pagefindOptions) : module;
+                if (!module.createInstance)
+                    await api.options(pagefindOptions);
+                await api.init();
+                return { api, bundlePath };
+            })
+                .catch((error) => {
+                loaded = undefined;
+                throw error;
+            });
+            loaded = loading;
+        }
+        const current = await loaded;
+        if (current.bundlePath !== bundlePath) {
+            await current.api.destroy();
+            loaded = undefined;
+            return getApi();
+        }
+        return current.api;
+    };
+    return {
+        async search(term, queryOptions = {}) {
+            if (term !== null && typeof term !== "string") {
+                throw new TypeError("Search term must be a string or null");
+            }
+            const limit = normalizePositiveInteger(queryOptions.limit ?? 20, "limit");
+            const offset = normalizeOffset(queryOptions.offset ?? 0);
+            const pagefindOptions = engineOptions(queryOptions);
+            const api = await getApi();
+            const response = await api.search(term, pagefindOptions);
+            const handles = response.results.slice(offset, offset + limit);
+            const results = await Promise.all(handles.map(loadResult));
+            return {
+                results,
+                total: response.results.length,
+                unfilteredTotal: response.unfilteredResultCount,
+                filters: response.filters,
+                totalFilters: response.totalFilters,
+                timings: combineTimings(response.timings),
+            };
+        },
+        async preload(term, queryOptions = {}) {
+            if (typeof term !== "string")
+                throw new TypeError("Search preload term must be a string");
+            const pagefindOptions = engineOptions(queryOptions);
+            const api = await getApi();
+            await api.preload(term, pagefindOptions);
+        },
+        async filters() {
+            const api = await getApi();
+            return api.filters();
+        },
+        async destroy() {
+            if (!loaded)
+                return;
+            const current = await loaded;
+            loaded = undefined;
+            await current.api.destroy();
+        },
+    };
+}
+function engineOptions(options) {
+    if (options.sort) {
+        const entries = Object.entries(options.sort);
+        if (entries.length !== 1) {
+            throw new TypeError("Search sort must contain exactly one field");
+        }
+        const [field, direction] = entries[0];
+        if (!field.trim() || (direction !== "asc" && direction !== "desc")) {
+            throw new TypeError("Search sort must use a non-empty field and asc or desc direction");
+        }
+    }
+    return {
+        ...(options.filters ? { filters: options.filters } : {}),
+        ...(options.sort ? { sort: options.sort } : {}),
+    };
+}
+async function loadResult(handle) {
+    const data = await handle.data();
+    return {
+        id: handle.id,
+        score: handle.score,
+        url: data.url,
+        title: data.meta.title || data.sub_results[0]?.title || data.url,
+        excerpt: data.excerpt,
+        plainExcerpt: data.plain_excerpt,
+        content: data.content,
+        wordCount: data.word_count,
+        words: handle.words,
+        matchedMetaFields: handle.matchedMetaFields ?? [],
+        meta: data.meta,
+        filters: data.filters,
+        subResults: data.sub_results.map((result) => ({
+            title: result.title,
+            url: result.url,
+            excerpt: result.excerpt,
+            plainExcerpt: result.plain_excerpt,
+        })),
+    };
+}
+function combineTimings(timings) {
+    if (!Array.isArray(timings))
+        return timings;
+    return timings.reduce((total, value) => ({
+        preload: total.preload + value.preload,
+        search: total.search + value.search,
+        total: total.total + value.total,
+    }), { preload: 0, search: 0, total: 0 });
+}
+function normalizeBundlePath(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new TypeError("Search bundlePath must be a non-empty URL path");
+    }
+    const normalized = value.trim();
+    return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+function normalizePositiveInteger(value, label) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new TypeError(`Search ${label} must be a positive integer`);
+    }
+    return value;
+}
+function normalizeOffset(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new TypeError("Search offset must be a non-negative integer");
+    }
+    return value;
+}

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+import type { FarmSearchClient, FarmSearchPublicConfig, SearchClientOptions } from "./types.js";
+export type { FarmSearchClient, SearchClientOptions, SearchFilterCounts, SearchFilterExpression, SearchFilterPrimitive, SearchFilters, SearchQueryOptions, SearchResponse, SearchResult, SearchSort, SearchSubResult, SearchTimings, } from "./types.js";
+/** @internal Configured by the Farm client plugin before hydration. */
+export declare function configureFarmSearch(config: FarmSearchPublicConfig): void;
+/** Create a lazy, renderer-neutral client for the generated static search index. */
+export declare function createSearch(options?: SearchClientOptions): FarmSearchClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEhG,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AAQpB,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAExE;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,gBAAgB,CAMhF"}

package/dist/client.js

@@ -0,0 +1,14 @@
+import { createSearchClient } from "./client-runtime.js";
+let configuredSearch = {
+    available: false,
+    bundlePath: "/_farm/search/",
+    excerptLength: 30,
+};
+/** @internal Configured by the Farm client plugin before hydration. */
+export function configureFarmSearch(config) {
+    configuredSearch = { ...config };
+}
+/** Create a lazy, renderer-neutral client for the generated static search index. */
+export function createSearch(options = {}) {
+    return createSearchClient(() => configuredSearch, options, (url) => import(/* @vite-ignore */ url));
+}

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+export interface SearchOptions {
+    /** URL patterns to index. Patterns are matched without Farm's basePath. */
+    include?: string[];
+    /** URL patterns to omit. Patterns are matched without Farm's basePath. */
+    exclude?: string[];
+    /** Static bundle directory, relative to Farm's basePath. */
+    output?: string;
+    /** Restrict indexed document content to one CSS selector. */
+    rootSelector?: string;
+    /** Additional CSS selectors Pagefind should ignore. */
+    excludeSelectors?: string[];
+    /** Force every page into one ISO 639-1 language index. */
+    language?: string;
+    /** Characters Pagefind should preserve inside indexed words. */
+    includeCharacters?: string;
+    /** Keep index.html in result URLs. */
+    keepIndexUrl?: boolean;
+    /** Number of words in generated result excerpts. */
+    excerptLength?: number;
+    /** Query parameter used by Pagefind's optional result highlighting. */
+    highlightParam?: string | false;
+    /** Print Pagefind's detailed build diagnostics. */
+    verbose?: boolean;
+}
+export interface ResolvedSearchOptions {
+    include: string[];
+    exclude: string[];
+    output: string;
+    rootSelector?: string;
+    excludeSelectors: string[];
+    language?: string;
+    includeCharacters?: string;
+    keepIndexUrl: boolean;
+    excerptLength: number;
+    highlightParam?: string;
+    verbose: boolean;
+}
+export declare function resolveSearchOptions(options?: SearchOptions): ResolvedSearchOptions;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sCAAsC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC,mDAAmD;IACnD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,qBAAqB,CAuBvF"}

package/dist/config.js

@@ -0,0 +1,83 @@
+const DEFAULT_OUTPUT = "_farm/search";
+export function resolveSearchOptions(options = {}) {
+    if ("enabled" in options) {
+        throw new TypeError("Search does not accept enabled; remove search() from plugins to disable it");
+    }
+    return {
+        include: normalizePatterns(options.include ?? ["/**"], "include"),
+        exclude: normalizePatterns(options.exclude ?? [], "exclude"),
+        output: normalizeOutput(options.output ?? DEFAULT_OUTPUT),
+        rootSelector: normalizeOptionalString(options.rootSelector, "rootSelector"),
+        excludeSelectors: normalizeStrings(options.excludeSelectors ?? [], "excludeSelectors"),
+        language: normalizeLanguage(options.language),
+        includeCharacters: normalizeOptionalString(options.includeCharacters, "includeCharacters"),
+        keepIndexUrl: normalizeBoolean(options.keepIndexUrl, "keepIndexUrl") ?? false,
+        excerptLength: normalizeExcerptLength(options.excerptLength ?? 30),
+        highlightParam: options.highlightParam === false
+            ? undefined
+            : normalizeOptionalString(options.highlightParam, "highlightParam"),
+        verbose: normalizeBoolean(options.verbose, "verbose") ?? false,
+    };
+}
+function normalizePatterns(values, label) {
+    const patterns = normalizeStrings(values, label).map((value) => {
+        const normalized = value === "/" ? "/" : `/${value.replace(/^\/+|\/+$/g, "")}`;
+        if (normalized.includes("\\")) {
+            throw new TypeError(`Search ${label} patterns must use URL separators`);
+        }
+        return normalized;
+    });
+    return [...new Set(patterns)];
+}
+function normalizeStrings(values, label) {
+    if (!Array.isArray(values))
+        throw new TypeError(`Search ${label} must be an array of strings`);
+    return values.map((value) => {
+        if (typeof value !== "string" || !value.trim()) {
+            throw new TypeError(`Search ${label} must contain non-empty strings`);
+        }
+        return value.trim();
+    });
+}
+function normalizeOptionalString(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new TypeError(`Search ${label} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function normalizeOutput(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new TypeError("Search output must be a non-empty relative URL path");
+    }
+    const normalized = value.trim().replace(/^\/+|\/+$/g, "");
+    const segments = normalized.split("/");
+    if (!normalized ||
+        value.includes("\\") ||
+        value.includes("?") ||
+        value.includes("#") ||
+        segments.some((segment) => segment === "." || segment === ".." || !segment)) {
+        throw new TypeError("Search output must stay inside the public output directory");
+    }
+    return normalized;
+}
+function normalizeLanguage(value) {
+    const normalized = normalizeOptionalString(value, "language")?.toLowerCase();
+    if (normalized && !/^[a-z]{2}$/.test(normalized)) {
+        throw new TypeError("Search language must be a two-letter ISO 639-1 code");
+    }
+    return normalized;
+}
+function normalizeExcerptLength(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 1_000) {
+        throw new TypeError("Search excerptLength must be an integer from 1 to 1000");
+    }
+    return value;
+}
+function normalizeBoolean(value, label) {
+    if (value !== undefined && typeof value !== "boolean") {
+        throw new TypeError(`Search ${label} must be a boolean`);
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type SearchOptions } from "./config.js";
+export type { ResolvedSearchOptions, SearchOptions } from "./config.js";
+export type { FarmSearchClient, SearchClientOptions, SearchFilterCounts, SearchFilterExpression, SearchFilterPrimitive, SearchFilters, SearchQueryOptions, SearchResponse, SearchResult, SearchSort, SearchSubResult, SearchTimings, } from "./types.js";
+/** Build a static Pagefind index from Farm's emitted HTML pages. */
+export declare function search(options?: SearchOptions): import("@farm.js/core/plugin").FarmPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGvE,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,oEAAoE;AACpE,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,6CAuFjD"}

package/dist/index.js

@@ -0,0 +1,84 @@
+import { definePlugin } from "@farm.js/core/plugin";
+import { normalizeBasePath, withBasePath, writeSearchIndex } from "./build.js";
+import { resolveSearchOptions } from "./config.js";
+/** Build a static Pagefind index from Farm's emitted HTML pages. */
+export function search(options = {}) {
+    const resolved = resolveSearchOptions(options);
+    let configuredBasePath = "/";
+    let generated = false;
+    const publicConfig = {
+        available: false,
+        bundlePath: `/${resolved.output}/`,
+        excerptLength: resolved.excerptLength,
+        ...(resolved.highlightParam ? { highlightParam: resolved.highlightParam } : {}),
+    };
+    return definePlugin({
+        name: "farm:search",
+        enforce: "post",
+        configure(config) {
+            if ((config.plugins ?? []).filter((candidate) => candidate.name === "farm:search").length > 1) {
+                throw new Error("[farm:search] Configure search in one search() plugin instance");
+            }
+            configuredBasePath = normalizeBasePath(config.basePath);
+            publicConfig.bundlePath = `${withBasePath(`/${resolved.output}`, configuredBasePath)}/`;
+        },
+        build: {
+            before() {
+                generated = false;
+            },
+            configure(nitroConfig) {
+                const hooks = nitroConfig.hooks ?? {};
+                const previousPrerenderDone = hooks["prerender:done"];
+                const generate = async () => {
+                    if (generated)
+                        return;
+                    const result = await writeSearchIndex({
+                        outputDir: nitroConfig.output?.dir ?? ".farm/.output",
+                        publicDir: nitroConfig.output?.publicDir,
+                        preset: nitroConfig.preset ?? "node-server",
+                        basePath: configuredBasePath,
+                        options: resolved,
+                    });
+                    generated = true;
+                    console.info(`[farm:search] Indexed ${result.indexedRoutes.length} static page${result.indexedRoutes.length === 1 ? "" : "s"} at ${result.bundlePath}`);
+                };
+                return {
+                    ...nitroConfig,
+                    hooks: {
+                        ...hooks,
+                        "prerender:done": async (...args) => {
+                            await callConfiguredHooks(previousPrerenderDone, args);
+                            await generate();
+                        },
+                    },
+                };
+            },
+            async after(result) {
+                if (!result.success || generated)
+                    return;
+                const built = await writeSearchIndex({
+                    outputDir: result.outputDir ?? `${result.root}/.farm/.output`,
+                    preset: result.preset,
+                    basePath: configuredBasePath,
+                    options: resolved,
+                });
+                generated = true;
+                console.info(`[farm:search] Indexed ${built.indexedRoutes.length} static page${built.indexedRoutes.length === 1 ? "" : "s"} at ${built.bundlePath}`);
+            },
+        },
+        client: {
+            public: publicConfig,
+            async setup({ public: config, isProd }) {
+                const runtime = await import("@farm.js/search/client");
+                runtime.configureFarmSearch({ ...config, available: isProd });
+            },
+        },
+    });
+}
+async function callConfiguredHooks(value, args) {
+    const hooks = Array.isArray(value) ? value : [value];
+    for (const hook of hooks) {
+        if (typeof hook === "function")
+            await hook(...args);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+export type SearchFilterPrimitive = string | number | boolean;
+export type SearchFilterExpression = SearchFilterPrimitive | SearchFilterPrimitive[] | {
+    [key: string]: SearchFilterExpression | SearchFilterExpression[];
+};
+export type SearchFilters = Record<string, SearchFilterExpression | SearchFilterExpression[]>;
+export type SearchSort = Record<string, "asc" | "desc">;
+export type SearchFilterCounts = Record<string, Record<string, number>>;
+export interface SearchQueryOptions {
+    /** Pagefind filter expression. */
+    filters?: SearchFilters;
+    /** One Pagefind sort key and direction. Sorting replaces relevance order. */
+    sort?: SearchSort;
+    /** Number of fully loaded results. Defaults to 20. */
+    limit?: number;
+    /** Number of result handles to skip before loading. Defaults to 0. */
+    offset?: number;
+}
+export interface SearchClientOptions {
+    /** Override the generated search bundle URL. */
+    bundlePath?: string;
+    /** Override the configured result excerpt length. */
+    excerptLength?: number;
+    /** Add the query to result links through this parameter. */
+    highlightParam?: string | false;
+}
+export interface SearchSubResult {
+    title: string;
+    url: string;
+    excerpt: string;
+    plainExcerpt: string;
+}
+export interface SearchResult {
+    id: string;
+    score: number;
+    url: string;
+    title: string;
+    excerpt: string;
+    /** Excerpt without Pagefind's mark elements. Safe to render as ordinary text. */
+    plainExcerpt: string;
+    content: string;
+    wordCount: number;
+    words: number[];
+    matchedMetaFields: string[];
+    meta: Record<string, string>;
+    filters: Record<string, string[]>;
+    subResults: SearchSubResult[];
+}
+export interface SearchTimings {
+    preload: number;
+    search: number;
+    total: number;
+}
+export interface SearchResponse {
+    results: SearchResult[];
+    /** Number of matching results after filters, before offset and limit. */
+    total: number;
+    /** Number of results that matched the term before filters. */
+    unfilteredTotal: number;
+    filters: SearchFilterCounts;
+    totalFilters: SearchFilterCounts;
+    timings: SearchTimings;
+}
+export interface FarmSearchClient {
+    search(term: string | null, options?: SearchQueryOptions): Promise<SearchResponse>;
+    preload(term: string, options?: Pick<SearchQueryOptions, "filters" | "sort">): Promise<void>;
+    filters(): Promise<SearchFilterCounts>;
+    destroy(): Promise<void>;
+}
+export interface FarmSearchPublicConfig {
+    available: boolean;
+    bundlePath: string;
+    excerptLength: number;
+    highlightParam?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,MAAM,MAAM,sBAAsB,GAC9B,qBAAqB,GACrB,qBAAqB,EAAE,GACvB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,GAAG,sBAAsB,EAAE,CAAA;CAAE,CAAC;AAEzE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,EAAE,CAAC,CAAC;AAC9F,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;AACxD,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAExE,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACnF,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@farm.js/search",
+  "version": "0.1.0-beta.0",
+  "description": "Build-time static page search for Farm.js applications",
+  "keywords": [
+    "farm.js",
+    "pagefind",
+    "search",
+    "static-site",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-search"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "pagefind": "^1.5.2",
+    "@farm.js/core": "0.1.0-beta.92"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}