macotron.spotlight
Find files and folders by name with the Spotlight index, and complete paths as the user types them. It needs no setup, but each search takes most of a second.
const hits = await macotron.spotlight.search("invoice", { folder: "~/Documents", kind: "pdf" });
if (hits.length) macotron.url.open("file://" + encodeURI(hits[0].path));Searching
search(query: string, opts?: { folder?: string; kind?: string }): Promise<Array<{ path, name, kind }>>
Returns up to 50 matches, best first. Each result has the absolute path, the name, and kind, the file extension without the dot ("" for most folders). An empty query returns [].
A plain query matches names that start with it, or that have a word starting with it: budget finds Q3 Budget.pdf. Case does not matter. Shallow paths rank first, so downloads finds ~/Downloads before a downloads folder deep in a project. Paths under hidden folders such as .git, and paths outside home and /Applications, rank lower.
When there is no folder and no kind, a query of three or more letters also matches folder paths in home up to three levels deep, so letters from a parent and a child folder find the child: docpro can find ~/Documents/Projects. These matches come after the name matches. ~/Library and node_modules are not searched this way.
| Option | What it does |
|---|---|
folder | Only search inside this folder. ~ expands. |
kind | A file extension, such as "pdf", with or without the dot. |
Path completion
A query that contains /, or is just ~, is a path being typed. Each segment matches one folder level, with fuzzy matching, so a few letters per level are enough: ~/dc/inv can reach ~/Documents/Invoices.
~/starts at home and/at the root of the disk. Any other start is relative tofolder, or to home.- A trailing
/lists the children of the folders matched so far. .and..work as in the shell.- Hidden names show only when the segment starts with a dot.
Spotlight never returns the top level of home, such as ~/Desktop. Macotron adds those top-level folders itself by reading home, /Applications and / directly. For faster results in folders you choose, use macotron.files.
See also
- macotron.files for an in-memory index that answers in milliseconds.
- macotron.launcher to show results as the user types.
- The
file-search.jsplugin, which uses this module for path queries and when the file index is unavailable.