@opencraw/core 0.1.3 → 0.1.4

package/dist/record-diff/record-diff.algorithm.d.ts

@@ -0,0 +1,82 @@
+import type { OutputRecipe } from '../recipe-schema/index.js';
+/** A record as a JSON Lines file holds it: the data, plus the sink's `_source` (and `_key` in append mode). */
+export type StoredRecord = Record<string, unknown>;
+/** One field whose value changed; nested objects are compared field by field (`price.amount`). */
+export interface FieldChange {
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+export type RecordChange = {
+    change: 'added';
+    key: string;
+    after: StoredRecord;
+} | {
+    change: 'removed';
+    key: string;
+    before: StoredRecord;
+} | {
+    change: 'changed';
+    key: string;
+    before: StoredRecord;
+    after: StoredRecord;
+    fields: FieldChange[];
+};
+/** How two runs differ, by record key. */
+export interface RecordDiff {
+    added: number;
+    removed: number;
+    changed: number;
+    unchanged: number;
+    /** Every change, removed first, then changed, then added, each in file order. */
+    changes: RecordChange[];
+    /** Records on either side the key cannot tell apart from an earlier one: only the first counts. */
+    repeated: number;
+    /** How many records each side holds. */
+    counts: {
+        previous: number;
+        current: number;
+    };
+    /** Set when the current run holds far fewer records: the usual sign a site changed and a recipe broke quietly. */
+    shrunk?: {
+        previous: number;
+        current: number;
+    };
+}
+export interface DiffOptions {
+    /** The fields that identify a record. Default: the `_key` each line carries (a sink in append mode writes it). */
+    key?: readonly string[];
+    /** Fields not compared (their dotted paths match nested ones too). `_source` and `_key` never are. */
+    ignore?: readonly string[];
+    /** The share of records a run may lose before `shrunk` is set; default 0.5 (half). */
+    shrink?: number;
+}
+/**
+ * Compares two runs' records by key: what was added, what was removed, and
+ * for the records in both, which fields changed, before and after. Like a
+ * `git diff` of a price list, but row by row instead of line by line, so a
+ * reordered file is not a change.
+ *
+ * @param previous - The earlier run's records.
+ * @param current - The later run's records.
+ * @param options - The key fields, the fields to ignore, the shrink threshold.
+ * @returns The differences.
+ * @throws Error when records carry no key: without `key`, every line needs `_key`.
+ */
+export declare function diffRecords(previous: readonly StoredRecord[], current: readonly StoredRecord[], options?: DiffOptions): RecordDiff;
+/**
+ * The diff options an output recipe implies: its key fields, and its fields
+ * the engine fills differently every run (`generated: now`, `uuid`).
+ *
+ * @param output - The output recipe.
+ * @returns The key and the fields to ignore.
+ */
+export declare function diffOptionsFor(output: OutputRecipe): Required<Pick<DiffOptions, 'key' | 'ignore'>>;
+/**
+ * A key as people read it: the key fields' values joined (`Pandina · 1.0 Hybrid`).
+ *
+ * @param key - A record key (a JSON array of the key values).
+ * @returns The readable form.
+ */
+export declare function readableKey(key: string): string;
+//# sourceMappingURL=record-diff.algorithm.d.ts.map

package/dist/record-diff/records-file.repository.d.ts

@@ -0,0 +1,10 @@
+import type { StoredRecord } from './record-diff.algorithm.js';
+/**
+ * The records of a JSON Lines file, as a sink wrote them.
+ *
+ * @param path - The file.
+ * @returns One record per non-empty line.
+ * @throws Error naming the file and the line that is not a JSON object.
+ */
+export declare function readRecordsFile(path: string): Promise<StoredRecord[]>;
+//# sourceMappingURL=records-file.repository.d.ts.map

package/dist/record-sink/dedupe.policy.d.ts

@@ -0,0 +1,29 @@
+import type { OutputRecord } from '../output-mapping/index.js';
+/** How far de-duplication reaches: the whole run, one input recipe, or not at all. */
+export type DedupeScope = 'run' | 'recipe' | 'off';
+/** One input recipe's view of de-duplication: whether a record repeats a key already seen. */
+export interface RecipeDedupe {
+    /**
+     * @param record - A validated record.
+     * @returns `true` when the record repeats an earlier key and must be dropped.
+     */
+    isDuplicate: (record: OutputRecord) => boolean;
+}
+/**
+ * Drops records whose key was already seen. First record wins; keyless
+ * records always pass. Recipes running in parallel each get their own view:
+ * under `recipe` scope they never see each other's keys, under `run` scope
+ * they share them (and whichever emits a key first keeps it).
+ */
+export declare class DedupePolicy {
+    readonly scope: DedupeScope;
+    private readonly shared;
+    constructor(scope?: DedupeScope);
+    /**
+     * The de-duplication one input recipe run uses.
+     *
+     * @returns Its view: keys shared with the run, its own, or none checked.
+     */
+    forRecipe(): RecipeDedupe;
+}
+//# sourceMappingURL=dedupe.policy.d.ts.map

package/dist/record-sink/index.d.ts

@@ -0,0 +1,9 @@
+export type { RecordSink, SinkSummary } from './record-sink.contract.js';
+export { memorySink } from './memory-sink.repository.js';
+export type { MemorySink } from './memory-sink.repository.js';
+export { jsonLinesSink } from './json-lines-sink.repository.js';
+export type { JsonLinesSinkOptions } from './json-lines-sink.repository.js';
+export { DedupePolicy } from './dedupe.policy.js';
+export type { RecipeDedupe } from './dedupe.policy.js';
+export type { DedupeScope } from './dedupe.policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/record-sink/json-lines-sink.repository.d.ts

@@ -0,0 +1,19 @@
+import type { RecordSink } from './record-sink.contract.js';
+export interface JsonLinesSinkOptions {
+    /**
+     * Keep what the file holds and add to it. Each line then carries the record
+     * key as `_key`, and `open` reads the keys already there so a resumed run
+     * (`CrawlOptions.resume`) can skip them.
+     */
+    append?: boolean;
+}
+/**
+ * A sink that writes one JSON object per line to a file (JSON Lines). Each line
+ * is the record's `data` plus a `_source` member (and `_key` in append mode).
+ *
+ * @param path - The file to write; created with its directories, truncated on open unless `append`.
+ * @param options - Append mode.
+ * @returns The sink.
+ */
+export declare function jsonLinesSink(path: string, options?: JsonLinesSinkOptions): RecordSink;
+//# sourceMappingURL=json-lines-sink.repository.d.ts.map

package/dist/record-sink/memory-sink.repository.d.ts

@@ -0,0 +1,9 @@
+import type { OutputRecord } from '../output-mapping/index.js';
+import type { RecordSink } from './record-sink.contract.js';
+/** A sink that keeps records in memory; `records` is readable at any time. */
+export interface MemorySink extends RecordSink {
+    readonly records: OutputRecord[];
+}
+/** @returns A new in-memory sink. */
+export declare function memorySink(): MemorySink;
+//# sourceMappingURL=memory-sink.repository.d.ts.map

package/dist/record-sink/record-sink.contract.d.ts

@@ -0,0 +1,17 @@
+import type { OutputRecord } from '../output-mapping/index.js';
+import type { OutputRecipe } from '../recipe-schema/index.js';
+/** What a sink reports when closed. */
+export interface SinkSummary {
+    written: number;
+    /** Where the records went, when the sink has a location. */
+    location?: string;
+}
+/** Where validated records go. Opened once per run, written per record, closed once. */
+export interface RecordSink {
+    open: (output: OutputRecipe) => Promise<void>;
+    write: (record: OutputRecord) => Promise<void>;
+    close: () => Promise<SinkSummary>;
+    /** Whether a record with this key is already there; what a resumed run asks before writing. */
+    has?: (key: string) => Promise<boolean>;
+}
+//# sourceMappingURL=record-sink.contract.d.ts.map

package/dist/selection/html-selector.algorithm.d.ts

@@ -0,0 +1,19 @@
+import type { Cheerio, CheerioAPI } from 'cheerio';
+import type { AnyNode } from 'domhandler';
+/** A matched HTML element together with the document it belongs to. */
+export interface HtmlMatch {
+    api: CheerioAPI;
+    element: Cheerio<AnyNode>;
+}
+/**
+ * Runs a CSS selector on static HTML. A whole document is parsed as one; anything
+ * else (a table row, a list item taken with `take: "html"`) is parsed as a
+ * fragment, so cells and rows outside a table survive instead of being dropped.
+ *
+ * @param html - The markup (a whole document or a fragment).
+ * @param selector - A CSS selector.
+ * @param xml - Read the markup as XML: names keep their case, `take: "html"` gives XML.
+ * @returns Every match, in document order.
+ */
+export declare function selectHtml(html: string, selector: string, xml?: boolean): HtmlMatch[];
+//# sourceMappingURL=html-selector.algorithm.d.ts.map

package/dist/selection/index.d.ts

@@ -0,0 +1,8 @@
+export { selectJson } from './json-path.algorithm.js';
+export { selectRegex } from './regex.algorithm.js';
+export { selectHtml } from './html-selector.algorithm.js';
+export type { HtmlMatch } from './html-selector.algorithm.js';
+export { takeFromHtml, takeFromJson, collapse } from './take-value.mapper.js';
+export type { Take } from './take-value.mapper.js';
+export { tryParseJson, parseJsonText, dataItemsOf, parseJsonLike, parseJsonLines } from './json-text.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/selection/json-path.algorithm.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Evaluates a JSONPath expression on a decoded JSON document.
+ *
+ * @param document - The JSON value.
+ * @param path - A JSONPath such as `$.items[*].url`.
+ * @returns Every match, in document order.
+ */
+export declare function selectJson(document: unknown, path: string): unknown[];
+//# sourceMappingURL=json-path.algorithm.d.ts.map

package/dist/selection/json-text.algorithm.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON that arrives as text: a `<script type="application/ld+json">` body, a
+ * `data-*` attribute, a fetched document read as text. Sites wrap JSON in
+ * things that are not JSON: comment guards around inline JSON-LD, prefixes
+ * that stop a page from loading an API as a script, a JSONP callback, an
+ * assignment in an inline script. Those wrappers are removed, but only after
+ * the text failed to parse as it is, and what is left must still be strict
+ * JSON: nothing is evaluated.
+ */
+/**
+ * Parses text as JSON, or as JSON inside one of the wrappers sites put around
+ * it: comment guards, an anti-hijacking prefix, a JSONP call, an assignment.
+ * Valid JSON is always read as it is; a wrapper is only removed when that
+ * fails.
+ *
+ * @param text - The text.
+ * @returns The value, or the error the text as it is gave.
+ */
+export declare function parseJsonLike(text: string): {
+    value: unknown;
+} | {
+    error: Error;
+};
+/**
+ * Parses JSON Lines (NDJSON): one JSON value per non-blank line.
+ *
+ * @param text - The text.
+ * @param source - Where it came from, for the error.
+ * @returns The values, in order.
+ * @throws Error naming the source and the line that does not parse.
+ */
+export declare function parseJsonLines(text: string, source: string): unknown[];
+/**
+ * Parses text as JSON, wrappers removed (see {@link parseJsonLike}).
+ *
+ * @param text - The text.
+ * @returns The value, or `undefined` when it is not JSON.
+ */
+export declare function tryParseJson(text: string): unknown;
+/**
+ * Parses text that must be JSON.
+ *
+ * @param text - The text.
+ * @param id - What the text is, for the error.
+ * @returns The value.
+ * @throws Error when it is not JSON.
+ */
+export declare function parseJsonText(text: string, id: string): unknown;
+/**
+ * The data a value holds, whatever shape it arrived in: JSON text is parsed, a
+ * list of texts becomes the list of its parsable entries, and an entry that
+ * parses to a list is spliced in. Data that is not text is kept as is.
+ *
+ * @param value - A bound value: data, text, or a list of either.
+ * @returns A list of items.
+ */
+export declare function dataItemsOf(value: unknown): unknown[];
+//# sourceMappingURL=json-text.algorithm.d.ts.map

package/dist/selection/regex.algorithm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Evaluates a regular expression on text: the extract kind for values that
+ * live in inline scripts, attributes or prose rather than in elements or JSON.
+ *
+ * @param text - The document text.
+ * @param pattern - A regular expression source; group 1 is returned when the
+ * pattern has a capturing group, else the whole match.
+ * @returns Every match, in document order.
+ * @throws When the pattern is not a valid regular expression.
+ */
+export declare function selectRegex(text: string, pattern: string): string[];
+//# sourceMappingURL=regex.algorithm.d.ts.map

package/dist/selection/take-value.mapper.d.ts

@@ -0,0 +1,27 @@
+import type { HtmlMatch } from './html-selector.algorithm.js';
+/** What `extract` takes from a match: text, inner HTML, an attribute, an input's value, or the node as data. */
+export type Take = 'text' | 'html' | 'value' | 'json' | `attr:${string}`;
+/**
+ * The value of an HTML match.
+ *
+ * @param match - A selected element.
+ * @param take - What to take; `text` collapses whitespace.
+ * @returns The value; `undefined` for a missing attribute.
+ */
+export declare function takeFromHtml(match: HtmlMatch, take: Take): unknown;
+/**
+ * The value of a JSON match.
+ *
+ * @param node - A JSONPath result.
+ * @param take - `json` keeps the node; `text` stringifies scalars.
+ * @returns The value.
+ */
+export declare function takeFromJson(node: unknown, take: Take): unknown;
+/**
+ * Text as a human reads it: runs of whitespace collapsed, ends trimmed.
+ *
+ * @param text - Raw text content.
+ * @returns The collapsed text.
+ */
+export declare function collapse(text: string): string;
+//# sourceMappingURL=take-value.mapper.d.ts.map

package/dist/src/api-steps/extract-from-document.use-case.d.ts

@@ -2,11 +2,11 @@ import type { ExtractionScope, ScopeDocument } from '../extraction-scope/index.j
 import type { ExtractStep } from '../recipe-schema/index.js';
 /**
  * Runs an `extract` step against a static document: the value bound under
- * `from`, else the scope's current document. `css` reads HTML, `jsonpath`
- * reads JSON (or a read PDF, workbook or deck as data), `table` reads the
- * tables of a PDF, a workbook (a spreadsheet, a CSV), a deck (a presentation)
- * or HTML (its `<table>`s), `regex` reads any document as text; `xpath` needs
- * a live page and is refused here.
+ * `from`, else the scope's current document. `css` reads HTML (or XML),
+ * `xpath` reads XML (a feed, a sitemap) or HTML parsed as a browser parses
+ * it, `jsonpath` reads JSON (or a read PDF, workbook or deck as data), `table`
+ * reads the tables of a PDF, a workbook (a spreadsheet, a CSV), a deck (a
+ * presentation) or HTML (its `<table>`s), `regex` reads any document as text.
  *
  * A `jsonpath` extract whose `from` is text parses that text as JSON, and a
  * list of texts (every `<script type="application/ld+json">` of a page) becomes

package/dist/src/docx-document/index.d.ts

@@ -0,0 +1,2 @@
+export { readDocxHtml } from './read-docx-html.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/docx-document/read-docx-html.client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reads a `.docx` Word document into HTML, through `@opencraw/office-reader`,
+ * so every selector that reads a page reads a Word document too:
+ *
+ * - headings become `<h1>`…`<h6>` inside `<section data-heading="…">`, as in
+ *   rendered Markdown;
+ * - list items become nested `<ul>` / `<ol>`;
+ * - tables become `<table>`s with their merged cells as `colspan` / `rowspan`,
+ *   so a `table` extract reads them like any HTML table;
+ * - a paragraph keeps its style as `data-style` and its links as `<a href>`;
+ * - headers, footers and notes follow the body, in `<header>`, `<footer>`
+ *   and `<aside data-part="notes">`; the title goes to `<title>`.
+ *
+ * The reader is imported on first use.
+ *
+ * @param bytes - The file.
+ * @param source - Where it came from, for messages.
+ * @returns The HTML document.
+ * @throws Error naming the source, and saying what to do, for a file that is
+ * not a readable Word document (a legacy `.doc`, a password-protected file, an `.odt`…).
+ */
+export declare function readDocxHtml(bytes: Uint8Array, source: string): Promise<string>;
+//# sourceMappingURL=read-docx-html.client.d.ts.map

package/dist/src/extraction-scope/extraction-scope.model.d.ts

@@ -7,11 +7,12 @@
  * Page state (the current URL, page number and the document `extract` reads by
  * default) is scope state too, bound in the innermost scope that navigated.
  */
+import type { XmlDocument } from '../xml-document/index.js';
 import type { DeckDocument } from '../deck-document/index.js';
 import type { PdfDocument } from '../pdf-document/index.js';
 import type { WorkbookDocument } from '../workbook-document/index.js';
 /** A fetched or rendered document a later `extract` can read. */
-export type ScopeDocument = PdfDocument | WorkbookDocument | DeckDocument | {
+export type ScopeDocument = PdfDocument | WorkbookDocument | DeckDocument | XmlDocument | {
     kind: 'json';
     data: unknown;
 } | {

package/dist/src/http-session/http-response.contract.d.ts

@@ -1,6 +1,7 @@
 import type { DeckDocument } from '../deck-document/index.js';
 import type { PdfDocument } from '../pdf-document/index.js';
 import type { WorkbookDocument } from '../workbook-document/index.js';
+import type { XmlDocument } from '../xml-document/index.js';
 import type { BodyKind, HttpMethod } from '../recipe-schema/index.js';
 /** One HTTP request as the api runner sends it, templates already rendered. */
 export interface HttpRequest {
@@ -20,7 +21,7 @@ export interface HttpRequest {
     timeoutMs?: number;
 }
 /** A parsed response body. Structurally the same as a scope document, on purpose. */
-export type HttpBody = PdfDocument | WorkbookDocument | DeckDocument | {
+export type HttpBody = PdfDocument | WorkbookDocument | DeckDocument | XmlDocument | {
     kind: 'json';
     data: unknown;
 } | {

package/dist/src/index.d.ts

@@ -24,12 +24,16 @@ export type { PdfDocument, PdfPage, PdfRow, PdfCell, PdfTable, TableQuery, Table
 export { parseCsv, detectDelimiter, csvWorkbook, findGridTables, fillDown, workbookText, isWorkbookDocument, htmlTableSheets } from './workbook-document/index.js';
 export { readMarkdown } from './markdown-document/index.js';
 export { readYaml } from './yaml-document/index.js';
+export { parseXml, selectXpath, takeFromXml, isXmlDocument } from './xml-document/index.js';
+export type { XmlDocument, XpathOptions, XpathValue } from './xml-document/index.js';
 export { findDeckTables, deckText, isDeckDocument } from './deck-document/index.js';
 export type { DeckDocument, DeckSlide, DeckShape, DeckChart, DeckTable, DeckTableQuery } from './deck-document/index.js';
 export type { WorkbookDocument, WorkbookCell, Sheet, CsvFormat, GridTable, GridTableQuery } from './workbook-document/index.js';
 export { StepFailure, HostThrottle, DEFAULT_RETRY_RULE } from './step-flow/index.js';
 export type { ThrottleConfig, HostRule } from './step-flow/index.js';
 export { TransformError } from './transformation/index.js';
+export { diffRecords, diffOptionsFor, readableKey, readRecordsFile } from './record-diff/index.js';
+export type { RecordDiff, RecordChange, FieldChange, DiffOptions, StoredRecord } from './record-diff/index.js';
 export { CaptchaError, DEFAULT_CAPTCHA_SELECTOR, detectChallenge } from './captcha/index.js';
 export type { CaptchaSolver, CaptchaChallenge, CaptchaContext, CaptchaOutcome, CaptchaKind, CaptchaLog } from './captcha/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/markdown-document/index.d.ts

@@ -1,3 +1,3 @@
-export { readMarkdown } from './read-markdown.client.js';
+export { readMarkdown, sectioned } from './read-markdown.client.js';
 export type { MarkdownRead } from './read-markdown.client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/markdown-document/read-markdown.client.d.ts

@@ -26,4 +26,14 @@ export interface MarkdownRead {
  * @throws Error naming the source when the front matter is not YAML.
  */
 export declare function readMarkdown(text: string, source: string): Promise<MarkdownRead>;
+/**
+ * Wraps each heading and what follows it, up to the next heading of the same
+ * or a higher level, in `<section data-heading="…" data-level="…">`, sections
+ * nesting; headings get slug ids. Rendered Markdown and Word documents both go
+ * through it, so one selector finds "the table under *Prezzi*" in either.
+ *
+ * @param html - Top-level HTML: headings among paragraphs, lists, tables.
+ * @returns The same content, sectioned.
+ */
+export declare function sectioned(html: string): string;
 //# sourceMappingURL=read-markdown.client.d.ts.map

package/dist/src/recipe-schema/recipe-kind.enum.d.ts

@@ -4,7 +4,7 @@ export declare const CRAWL_MODES: readonly ["web", "api"];
 export declare const SELECTOR_KINDS: readonly ["css", "xpath", "jsonpath", "regex", "table"];
 /** `take` also accepts `attr:<name>`, which is validated by pattern rather than listed. */
 export declare const TAKE_KINDS: readonly ["text", "html", "value", "json"];
-export declare const BODY_KINDS: readonly ["json", "jsonl", "html", "text", "pdf", "csv", "xlsx", "pptx", "yaml", "markdown"];
+export declare const BODY_KINDS: readonly ["json", "jsonl", "html", "text", "pdf", "csv", "xlsx", "pptx", "yaml", "markdown", "xml", "docx"];
 export declare const YAML_SCALARS: readonly ["typed", "text"];
 /** How a PDF table aligns a row's values against a cell wrapped over several lines. */
 export declare const TABLE_ALIGNS: readonly ["auto", "top", "center", "bottom"];

package/dist/src/recipe-schema/step.contract.d.ts

@@ -119,6 +119,10 @@ export interface ExtractStep extends StepBaseFields {
     slide?: string;
     /** `table` only: read text boxes laid out as a table instead of native tables (deck). */
     shapes?: boolean;
+    /** `xpath` on XML only: prefix to namespace URI (`{ "atom": "http://www.w3.org/2005/Atom" }`). Prefixes the root declares are known already. */
+    namespaces?: Record<string, string>;
+    /** `xpath` on XML only: drop the document's namespaces, so `//entry/title` matches `<entry xmlns="…">`. */
+    ignoreNamespaces?: boolean;
 }
 export interface SetStep extends StepBaseFields {
     type: 'set';

package/dist/src/record-diff/index.d.ts

@@ -0,0 +1,4 @@
+export { diffRecords, diffOptionsFor, readableKey } from './record-diff.algorithm.js';
+export type { RecordDiff, RecordChange, FieldChange, DiffOptions, StoredRecord } from './record-diff.algorithm.js';
+export { readRecordsFile } from './records-file.repository.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/record-diff/record-diff.algorithm.d.ts

@@ -0,0 +1,82 @@
+import type { OutputRecipe } from '../recipe-schema/index.js';
+/** A record as a JSON Lines file holds it: the data, plus the sink's `_source` (and `_key` in append mode). */
+export type StoredRecord = Record<string, unknown>;
+/** One field whose value changed; nested objects are compared field by field (`price.amount`). */
+export interface FieldChange {
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+export type RecordChange = {
+    change: 'added';
+    key: string;
+    after: StoredRecord;
+} | {
+    change: 'removed';
+    key: string;
+    before: StoredRecord;
+} | {
+    change: 'changed';
+    key: string;
+    before: StoredRecord;
+    after: StoredRecord;
+    fields: FieldChange[];
+};
+/** How two runs differ, by record key. */
+export interface RecordDiff {
+    added: number;
+    removed: number;
+    changed: number;
+    unchanged: number;
+    /** Every change, removed first, then changed, then added, each in file order. */
+    changes: RecordChange[];
+    /** Records on either side the key cannot tell apart from an earlier one: only the first counts. */
+    repeated: number;
+    /** How many records each side holds. */
+    counts: {
+        previous: number;
+        current: number;
+    };
+    /** Set when the current run holds far fewer records: the usual sign a site changed and a recipe broke quietly. */
+    shrunk?: {
+        previous: number;
+        current: number;
+    };
+}
+export interface DiffOptions {
+    /** The fields that identify a record. Default: the `_key` each line carries (a sink in append mode writes it). */
+    key?: readonly string[];
+    /** Fields not compared (their dotted paths match nested ones too). `_source` and `_key` never are. */
+    ignore?: readonly string[];
+    /** The share of records a run may lose before `shrunk` is set; default 0.5 (half). */
+    shrink?: number;
+}
+/**
+ * Compares two runs' records by key: what was added, what was removed, and
+ * for the records in both, which fields changed, before and after. Like a
+ * `git diff` of a price list, but row by row instead of line by line, so a
+ * reordered file is not a change.
+ *
+ * @param previous - The earlier run's records.
+ * @param current - The later run's records.
+ * @param options - The key fields, the fields to ignore, the shrink threshold.
+ * @returns The differences.
+ * @throws Error when records carry no key: without `key`, every line needs `_key`.
+ */
+export declare function diffRecords(previous: readonly StoredRecord[], current: readonly StoredRecord[], options?: DiffOptions): RecordDiff;
+/**
+ * The diff options an output recipe implies: its key fields, and its fields
+ * the engine fills differently every run (`generated: now`, `uuid`).
+ *
+ * @param output - The output recipe.
+ * @returns The key and the fields to ignore.
+ */
+export declare function diffOptionsFor(output: OutputRecipe): Required<Pick<DiffOptions, 'key' | 'ignore'>>;
+/**
+ * A key as people read it: the key fields' values joined (`Pandina · 1.0 Hybrid`).
+ *
+ * @param key - A record key (a JSON array of the key values).
+ * @returns The readable form.
+ */
+export declare function readableKey(key: string): string;
+//# sourceMappingURL=record-diff.algorithm.d.ts.map

package/dist/src/record-diff/records-file.repository.d.ts

@@ -0,0 +1,10 @@
+import type { StoredRecord } from './record-diff.algorithm.js';
+/**
+ * The records of a JSON Lines file, as a sink wrote them.
+ *
+ * @param path - The file.
+ * @returns One record per non-empty line.
+ * @throws Error naming the file and the line that is not a JSON object.
+ */
+export declare function readRecordsFile(path: string): Promise<StoredRecord[]>;
+//# sourceMappingURL=records-file.repository.d.ts.map

package/dist/src/selection/html-selector.algorithm.d.ts

@@ -12,7 +12,8 @@ export interface HtmlMatch {
  *
  * @param html - The markup (a whole document or a fragment).
  * @param selector - A CSS selector.
+ * @param xml - Read the markup as XML: names keep their case, `take: "html"` gives XML.
  * @returns Every match, in document order.
  */
-export declare function selectHtml(html: string, selector: string): HtmlMatch[];
+export declare function selectHtml(html: string, selector: string, xml?: boolean): HtmlMatch[];
 //# sourceMappingURL=html-selector.algorithm.d.ts.map

package/dist/src/xml-document/index.d.ts

@@ -0,0 +1,6 @@
+export type { XmlDocument } from './xml-document.model.js';
+export { isXmlDocument } from './xml-document.model.js';
+export { parseXml, htmlAsXml, withoutNamespaces, serializeXml, gunzipIfNeeded } from './xml-parser.client.js';
+export { selectXpath, takeFromXml } from './xpath.algorithm.js';
+export type { XpathValue, XpathOptions } from './xpath.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/xml-document/xml-document.model.d.ts

@@ -0,0 +1,13 @@
+/** A fetched XML document: a feed, a sitemap, an open-data export. Kept as text; queries parse it once. */
+export interface XmlDocument {
+    kind: 'xml';
+    xml: string;
+}
+/**
+ * Whether a value is a read XML document.
+ *
+ * @param value - Anything bound in a scope.
+ * @returns `true` for an `XmlDocument`.
+ */
+export declare function isXmlDocument(value: unknown): value is XmlDocument;
+//# sourceMappingURL=xml-document.model.d.ts.map