psyche is a fast, typo-tolerant, headless search for static and server-rendered sites.
Results are fuzzy matched in a web worker, using a search algorithm loosely based on fuzzysearch.
pnpm add github:dragonwocky/psyche#semver:^1.1.1The index is a JSON array of records, served by your site, each linked to its
page: { href, value: record }. A record's values are yours: the fields you
search, and anything else you want in results, which is passed through to them
untouched.
const entry = {
href: "/posts/kale/",
value: {
title: "Growing kale",
body: "Sow kale in late summer…", // the page's text
headings: [{ value: "After a frost", href: "#frost" }], // a match in one links to it
tags: ["Vegetables"],
date: "27 October 2026", // not searched: passed through as data
},
};A searched value is text, or a record, matched by the same fields (e.g. an
author's name). Either can be linked, { value, href }, with a link relative
to the link of the record it's in: a result whose best match is in a linked
value links to it, e.g. a heading's #id. A field's value is plain or linked,
or an array of them:
type Plain = string | Record<string, unknown>;
type Linked = { value: Plain; href: string }; // only these two keys
type Value = Plain | Linked | (Plain | Linked)[];
const post = {
title: "Growing kale",
authors: [{ value: { name: "Alice" }, href: "/authors/alice" }], // fields: [..., { key: "name", tier: 0 }]
};A record in a field scores its best value's match, without tiers, plus its
field's tier: an author's name matching outranks the body, as authors does,
whatever name's tier.
Matching runs in psyche's own worker, which the store starts the first time
search is used, and which fetches the index then. Vite, and other bundlers that
find a worker by new Worker(new URL("…", import.meta.url)), bundle it from
psyche for you. Otherwise, bundle psyche/worker yourself and pass its url as
worker:
// search.worker.ts, e.g. for esbuild
import "psyche/worker";For a small index, the store can match on the page instead: pass
worker: false. The matching is then loaded as a separate chunk, the first
time the search is used, and index can be a function that loads it.
createSearch makes the search's store. Fields, and their tiers, are always
yours: a record's score is its best value's match (0 to 1) plus its field's
tier, see matching.
// search.ts, shared by your components
import { createSearch } from "psyche";
const search = createSearch<Page>({
index: "/search.json", // relative to the page
fields: [
{ key: "title", tier: 3 },
{ key: "headings", tier: 2.5 },
{ key: "tags", tier: 2 },
{ key: "body", tier: 1 },
],
});Its options:
index(required): the index's url, relative to the page. Withworker: false, it can also be a function that loads the index's entries.fields(required): the fields searched,{ key, tier }[]. A record's score is its best value's match plus its field's tier.limit: the most results a search returns. Default:6.excerpt: the most characters an excerpt keeps of a text, with a quarter of its context before its match. Default:192.threshold: how tightly a query's characters must sit together to match, from 0 to 1: the share of the match's span they fill. Default:0.4.sitemap(result): whether a result is listed for an empty query. Default: every entry's.group: a record's key that results are grouped by, e.g."section". Groups are ordered by their best result.href(link, result, query): a result'shref, from the link of its best match (its best value's, e.g. a heading's#id, or its page's). Default: that link with?search=the query.navigate(href, { sourceElement }): follows a result's link, given the result's element. Default:location.assign(href). E.g. Astro'snavigate, for view transitions.onOpen(): called as the search opens, e.g. to close other menus.onLoad(page): called as each page loads, withpageas in the state:{ query }for its?search=query (""for none), and for a query, once the index has loaded,located, the entry it matched, before it's highlighted. Returntrueto highlight it yourself, see the landing page.loadEvent: the event a page has loaded by, on the window or the document, which its?search=query is handled on. Default:"load". With a client router, use its event after each navigation, e.g. Astro's"astro:page-load".root: the page content to highlight a?search=query's match in, a selector. Default:"article".worker: psyche's worker's url, if your bundler doesn't find it, orfalseto match on the page, see the worker.origin: loads the worker from the page's origin, not the script's, e.g. when scripts come from a dev server on another port that the page's server proxies.
Its state:
search.getState();
search.subscribe((state) => render(state)); // returns unsubscribe
// {
// open, query, loading, selected,
// results: [{ value, match?, matches, href, score }], // see below
// groups: [{ group?, results: [{ result, index }] }],
// page: { query, located? }, // the landing page's ?search= match
// }loading is whether a search is waiting on the worker, and selected is the
selected result's index. results are the best matches, or the sitemap for an
empty query, and groups are the same results grouped by group (a single
group without it), each with its results' indexes.
A result is its entry's match, as match returns it for a record: matches
has each field's match, { value, match?, href?, score } or an array of them,
with value excerpted around the match, and match is the best one's field
(and item), { key, index? }. Its href is the link to visit it by, its best
match's, see the href option, and its value has the record's other values:
the searched ones are left out, as their matches stand in for them.
Its actions:
open(): opens the search, fetches the index if it hasn't been, lists the sitemap if there's no query, callsonOpenand focuses the input.close(): closes the search and blurs the input.toggle(): opens the search if it's closed, and closes it if it's open.input(query): sets the query and searches. An empty query lists the sitemap.select(i): selects theith result, within the results.selectPrevious(),selectNext(): selects the previous or next result, scrolls it into view and focuses the input.visit(i?): follows theith result's link (default: the selected result's) withnavigate, then clears and closes the search.
search.connect() adds the open search's keyboard shortcuts (/, ↑ ↓,
Enter, Esc) and page handling (on loadEvent) to the document, and
returns a function that removes them. Call it once, from
your panel. Opening it is up to you, e.g. with isShortcut:
import { isShortcut, platformModifier } from "psyche";
document.addEventListener("keydown", (event) => {
if (!isShortcut(event, "k", { mod: true })) return;
event.preventDefault();
search.toggle();
});
// for a legend: `${platformModifier()} + K` to toggle searchRender from the state, and hand psyche your elements through refs. psyche
highlights matches in them, and moves focus and scroll:
search.refs.input($input);
search.refs.result(i)($a); // a result's link
search.refs.field(i, "title")($title); // a field shown in one element
search.refs.field(i, "tags", j)($tag); // each item of an array fieldRefs are cleared whenever results change, so register them as you render.
examples/lume renders a panel in plain DOM, bundled
with psyche's worker by Lume 4's @lumeland/plugin-esbuild:
// _config.ts
site.add("/main.ts");
site.add("/search.worker.ts");
site.use(esbuild());psyche has no framework adapters: subscribe to the store from your framework's own state. In Solid, for example:
import type { SearchState, SearchStore } from "psyche";
import { type Accessor, onCleanup } from "solid-js";
import { createStore } from "solid-js/store";
import { isServer } from "solid-js/web";
const useSearch = <T extends Record<string, unknown>>(
search: SearchStore<T>,
): Accessor<SearchState<T>> => {
if (isServer) return search.getState;
const [state, setState] = createStore({ ...search.getState() });
onCleanup(search.subscribe((next) => setState(next)));
return () => state;
};
function Search() {
const state = useSearch(search);
onMount(() => onCleanup(search.connect()));
return (
<For each={state().results}>
{(result, i) => (
<a ref={search.refs.result(i())} href={result.href}>
<h3 ref={search.refs.field(i(), "title")}>{result.matches.title?.value}</h3>
</a>
)}
</For>
);
}See examples/astro, whose panel is an island:
<Search client:only="solid-js" />.
When a page loads with ?search= in its url, psyche finds the entry it links
to: of the entries at its path, the one whose href has the most of the url's
query params, so an entry linked to by a param (e.g. a list's ?entry=) is
found before its page. It highlights its match in root, and scrolls to it.
A match in a value
linking within the page (e.g. #frost) is highlighted in the element it links
to. Other array items, like tags, are left to
your components, which read the store's page:
search.subscribe(({ page }) => {
// page.query: as the page loads ("" for none)
// page.located: the entry's match, with its record as value, once the index has loaded
});Matches are highlighted as ::highlight(psyche):
::highlight(psyche) {
background-color: #fde047;
color: #111;
}psyche exports what it highlights with, for your own
components. Highlighting is two steps: rangesOf selects a match's ranges in
the elements it's shown in, and highlight highlights them.
rangesOf(target, match) takes any of match's matches, with the elements
it's shown in:
rangesOf($title, match(query, title)); // a value's match, in its element
rangesOf($tags, match(query, tags)); // each value's match, in each item's element
rangesOf({ title: $title, tags: $tags }, match(query, record, { fields })); // each field's
rangesOf($article, match(query, record, { fields })); // within a page, as a landing page isTexts are found ignoring whitespace and curly quotes, so excerpts are found across element boundaries. Within a page, values linking within it are found in the element they link to, and other array items (e.g. tags) are left to your components.
highlight(ranges, name?) highlights ranges in ::highlight(name) (default:
psyche), and returns their removal, which removes only those ranges, so your
components, the results and the landing page never clear each other's:
createEffect(() => onCleanup(highlight(rangesOf($tags, match(query(), tags)))));match and rank are psyche's fuzzy matching, for your own components to match
by the same rules. match(query, input, options?) finds every match in a
value, values, a record or records, with their scores:
match(query, "Growing kale"); // { value, match?, score }, value excerpted around the match
match(query, ["Kale", { value: "Frost", href: "#frost" }]); // each value's, kept whole, with its href
match(query, record, { fields }); // { value: record, match?, matches, score }
match(query, records, { fields }); // each record's
match(query, { value: record, href: "/kale" }, { fields }); // a linked record's, with its hrefA text's score is 0 for no match, up to 1, and its match is the text it
matched. A record's matches has each field's match, its score is its best
value's plus its field's tier, and its match is that value's field (and
item), { key, index? }. A linked value's match has its href. Its options
are the worker's excerpt and threshold, and fields for records.
Match<V> is the match of any Value, as match returns it: a text's, a
record's, each with { href: string } if linked, and an array of them for an
array:
type Match<V extends Value> = V extends readonly (infer I)[]
? Match<I>[]
: V extends Linked<infer P>
? Match<P> & { href: string }
: V extends string
? { value: string; match?: string; score: number }
: { value: V; match?: { key; index? }; matches: { [field]?: Match }; score: number };rank(matches, limit?) orders matches by score, best first, without those
that didn't match, and keeps at most limit:
rank(match(query, records, { fields }), 6).map(({ value }) => value);isShortcut and platformModifier are what psyche's shortcuts are checked
with, for your own:
isShortcut(event, key, modifiers?): whether aKeyboardEventiskey(case-insensitive), pressed with exactly the given modifiers,{ mod?, shift?, alt? }, eachfalseby default.modis CTRL, or ⌘ on macs.platformModifier(): themodkey's label,"⌘"on macs and iOS and"CTRL"elsewhere, e.g. for a legend.
psyche exports its types, each generic over your record's type, T:
SearchOptions<T>,SearchState<T>andSearchStore<T>:createSearch's options, its state, and the store it returns.Result<T>: a result, see the store, andResultGroup<T>, a group of them,{ group?, results: { result, index }[] }.Fields<T>: the fields searched,{ key, tier }[].ValueandLinked: a field's value, and a linked one, see the index.Match<V>: the match of aValue, see matching.