Upstream Pagefind/pagefind state of the touched files before f1eedafd11

wrappers/node/types/index.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Create a new Pagefind index that files can be added to
+ */
+export function createIndex(config?: PagefindServiceConfig): Promise<NewIndexResponse>;
+
+/**
+ * Close the Pagefind service and clean up, stopping the binary altogether.
+ * 
+ * Service _will_ be restarted if any new calls are made to any other function.
+ * 
+ * Calling functions on an existing index after calling close() is undefined behavior,
+ * as that index may map to a new index after the service has restarted.
+ */
+export function close(): Promise<null>;
+
+export interface PagefindServiceConfig {
+    /** 
+     * The element Pagefind should treat as the root of the document, defaults to `html`.
+     * Usually you will want to use the data-pagefind-body attribute instead.
+     * @example ".my-html-outer"
+     */
+    rootSelector?: string,
+    /** 
+     * Custom selectors that Pagefind should ignore when indexing.
+     * Usually you will want to use the data-pagefind-ignore attribute instead.
+     * @example ["svg", ".my-code-blocks"]
+     */
+    excludeSelectors?: string[],
+    /**
+     * Ignore any detected languages and index the whole site as a single language.
+     * Expects an ISO 639-1 code.
+     */
+    forceLanguage?: string,
+    /**
+     * Print verbose logging while indexing the site. Does not impact the web-facing search.
+     * When running as a service, only impacts the logfile (if present).
+     */
+    verbose?: boolean,
+    /**
+     * Path to a logfile to write to. Will replace the file on each run.
+     */
+    logfile?: string,
+    /**
+     * Keep `index.html` at the end of search result paths.
+     * Defaults to false, stripping `index.html`.
+     */
+    keepIndexUrl?: boolean,
+    /**
+     * When writing or outputting files, also write the Pagefind playground to /pagefind/playground/.
+     * Defaults to false, ensuring the playground isn't available on a live site.
+     */
+    writePlayground?: boolean,
+    /**
+     * Include these characters when indexing and searching words.
+     * Useful for sites documenting technical topics such as programming languages.
+     * @example "<>$"
+     */
+    includeCharacters?: string,
+}
+
+
+export interface NewIndexResponse {
+    errors: string[],
+    index?: PagefindIndex
+}
+
+/**
+ * A Pagefind index that exists in the backend service before being built
+ */
+export interface PagefindIndex {
+    addHTMLFile: typeof addHTMLFile,
+    addCustomRecord: typeof addCustomRecord,
+    addDirectory: typeof addDirectory,
+    writeFiles: typeof writeFiles,
+    getFiles: typeof getFiles,
+    deleteIndex: typeof deleteIndex,
+}
+
+/**
+ * Index an HTML file that isn't on disk
+ */
+declare function addHTMLFile(file: HTMLFile): Promise<NewFileResponse>;
+/**
+ * Index a custom record that isn't backed by an HTML file
+ */
+declare function addCustomRecord(record: CustomRecord): Promise<NewFileResponse>;
+/**
+ * Index a directory of HTML files from disk
+ */
+declare function addDirectory(path: SiteDirectory): Promise<IndexingResponse>;
+
+/**
+ * The data required for Pagefind to index an HTML file that isn't on disk
+ * @example
+ * {
+ *   sourcePath: "about/index.html",
+ *   content: "<html lang='en'><body><h1>Meet the team</h1></body></html>"
+ * }
+ */
+export interface HTMLFile {
+    /** 
+     * The source path of the HTML file if it were to exist on disk.
+     * Must be a relative path, or an absolute path within the current working directory.
+     * Pagefind will compute the result URL from this path.
+     * 
+     * If not supplied, url must be supplied.
+     * 
+     * @example "about/index.html"
+     * @example "/Users/user/Documents/site/about/index.html"
+     */
+    sourcePath?: string,
+    /** 
+     * An explicit URL to use, instead of having Pagefind
+     * compute the URL based on the sourcePath.
+     * 
+     * If not supplied, sourcePath must be supplied.
+     * 
+     * @example "/about/"
+     */
+    url?: string,
+    /** The source HTML content of the file to be parsed */
+    content: string
+}
+
+/**
+ * The data required for Pagefind to index a custom record that isn't backed by an HTML file
+ * @example
+ * {
+ *   url: "/about/",
+ *   content: "Meet the team",
+ *   language: "en"
+ * }
+ */
+export interface CustomRecord {
+    /** The output URL of this record. Pagefind will not alter this */
+    url: string,
+    /** The raw content of this record */
+    content: string,
+    /** What language is this record written in. Multiple languages will be split into separate indexes. Expects an ISO 639-1 code. */
+    language: string,
+    /** The metadata to attach to this record. Supplying a `title` is highly recommended */
+    meta?: Record<string, string>,
+    /** The filters to attach to this record */
+    filters?: Record<string, string[]>,
+    /** The sort keys to attach to this record */
+    sort?: Record<string, string>
+}
+
+/**
+ * The data required for Pagefind to index the files in a directory
+ * @example
+ * {
+ *   path: "public",
+ *   glob: "**\/*.{html}"
+ * }
+ */
+export interface SiteDirectory {
+    /**
+     * The path to the directory to index.
+     * If relative, is relative to the cwd.
+     */
+    path: string,
+    /** Optionally, a custom glob to evaluate for finding files. Default to all HTML files. */
+    glob?: string
+}
+
+export interface IndexingResponse {
+    errors: string[],
+    page_count: number
+}
+
+export interface NewFileResponse {
+    errors: string[],
+    file: NewFile
+}
+
+/**
+ * Details about a new file that has been successfully added to the Pagefind index
+ */
+export interface NewFile {
+    uniqueWords: number,
+    url: string,
+    meta: Record<string, string>
+}
+
+/**
+ * Write the index files to disk
+ */
+declare function writeFiles(options?: WriteOptions): Promise<WriteFilesResponse>;
+
+/**
+ * Options for writing a Pagefind index to disk
+ */
+export interface WriteOptions {
+    /** 
+     * The path of the pagefind bundle directory to write to disk.
+     * If relative, is relative to the cwd.
+     * @example "./public/pagefind"
+     */
+    outputPath: string
+}
+
+
+export interface WriteFilesResponse {
+    errors: string[],
+    outputPath: string
+}
+
+/**
+ * Get an in-memory copy of the built index files
+ */
+declare function getFiles(): Promise<GetFilesResponse>;
+
+export interface GetFilesResponse {
+    errors: string[],
+    files: IndexFile[]
+}
+
+export interface IndexFile {
+    path: string,
+    content: Uint8Array
+}
+
+/**
+ * Delete this index and clear it from memory
+ */
+declare function deleteIndex(): Promise<null>;

wrappers/node/types/internal.d.ts

@@ -0,0 +1,154 @@
+// Requests to the backend.
+
+/**
+ * The raw object passed to the backend binary
+ */
+export interface InternalServiceRequest {
+    message_id?: number,
+    payload: InternalRequestPayload
+}
+
+/**
+ * The payload describing an action to the backend binary
+ */
+export type InternalRequestPayload =
+  | InternalNewIndexRequest
+  | InternalAddFileRequest
+  | InternalAddRecordRequest
+  | InternalAddDirRequest
+  | InternalWriteFilesRequest
+  | InternalGetFilesRequest
+  | InternalDeleteIndexRequest;
+
+export interface InternalNewIndexRequest {
+    type: 'NewIndex',
+    config?: InternalPagefindServiceConfig
+}
+
+export interface InternalPagefindServiceConfig {
+    root_selector?: string,
+    exclude_selectors?: string[],
+    force_language?: string,
+    verbose?: boolean,
+    logfile?: string,
+    keep_index_url?: boolean,
+    write_playground?: boolean,
+    include_characters?: string,
+}
+
+export interface InternalAddFileRequest {
+    type: 'AddFile',
+    index_id: number,
+    file_path?: string,
+    url?: string,
+    file_contents: string
+}
+
+export interface InternalAddRecordRequest {
+    type: 'AddRecord',
+    index_id: number,
+    url: string,
+    content: string,
+    language: string,
+    meta?: Record<string, string>,
+    filters?: Record<string, string[]>,
+    sort?: Record<string, string>
+}
+
+export interface InternalAddDirRequest {
+    type: 'AddDir',
+    index_id: number,
+    path: string,
+    glob?: string
+}
+
+export interface InternalWriteFilesRequest {
+    type: 'WriteFiles',
+    index_id: number,
+    output_path?: string
+}
+
+export interface InternalGetFilesRequest {
+    type: 'GetFiles',
+    index_id: number
+}
+
+export interface InternalDeleteIndexRequest {
+    type: 'DeleteIndex',
+    index_id: number
+}
+
+// Responses from the backend.
+
+/**
+ * The raw object returned from the backend binary
+ */
+export interface InternalServiceResponse {
+    message_id: number,
+    payload: InternalResponsePayload | InternalResponseError
+}
+
+/**
+ * The response payload in the case of an error
+ */
+export interface InternalResponseError {
+    type: 'Error',
+    original_message?: string,
+    message: string
+}
+
+/**
+ * The response payload in the case of a success
+ */
+export type InternalResponsePayload = 
+  | InternalNewIndexResponse
+  | InternalIndexedFileResponse
+  | InternalIndexedDirResponse
+  | InternalWriteFilesResponse
+  | InternalGetFilesResponse
+  | InternalDeleteIndexResponse;
+
+export interface InternalNewIndexResponse {
+    type: 'NewIndex',
+    index_id: number
+}
+
+export interface InternalIndexedFileResponse {
+    type: 'IndexedFile',
+    page_word_count: number,
+    page_url: string,
+    page_meta: Record<string, string>
+}
+
+export interface InternalIndexedDirResponse {
+    type: 'IndexedDir',
+    page_count: number
+}
+
+export interface InternalWriteFilesResponse {
+    type: 'WriteFiles',
+    output_path: string,
+}
+
+export interface InternalGetFilesResponse {
+    type: 'GetFiles',
+    files: InternalSyntheticFile[],
+}
+
+export interface InternalSyntheticFile {
+    path: string,
+    content: string
+}
+
+export interface InternalDeleteIndexResponse {
+    type: 'DeleteIndex'
+}
+
+/**
+ * What the service returns to the wrapping javascript detailing a response
+ */
+export interface InternalResponseCallback {
+    exception: Error | null,
+    err: InternalResponseError | null,
+    result: InternalResponsePayload | null
+}