ochre-sdk 1.0.72 → 1.0.74

package/dist/utilities.mjs

@@ -151,6 +151,46 @@ function stringLiteral(value) {
 	return `"${value.replaceAll("\"", "\"\"")}"`;
 }
 /**
+* XQuery prolog declaring `local:omit-supplemental`, which drops every element
+* carrying `supplemental="true"` from a node sequence, at any depth.
+*
+* Subtrees without a supplemental descendant are returned by reference, so
+* nodes are only copied along the path leading to an omitted element. The
+* lookahead walks the attribute axis (`//@supplemental`) rather than testing
+* every element, which measures around three times faster on large documents.
+*
+* Must be declared before any query body that calls {@link omitSupplemental}.
+*/
+const SUPPLEMENTAL_XQUERY_PROLOG = `declare function local:omit-supplemental($nodes as node()*) as node()* {
+  for $node in $nodes
+  return
+    if ($node instance of element())
+    then
+      if ($node/@supplemental = "true")
+      then ()
+      else if (empty($node//@supplemental[. = "true"]))
+      then $node
+      else element { node-name($node) } {
+        $node/@*,
+        local:omit-supplemental($node/node())
+      }
+    else $node
+};`;
+/**
+* Wrap an XQuery node expression so supplemental nodes are omitted from it
+* @param expression - The XQuery expression returning the nodes to filter
+* @returns The wrapped XQuery expression
+*/
+function omitSupplemental(expression) {
+	return `local:omit-supplemental(${expression})`;
+}
+/**
+* XQuery predicate keeping only nodes that are neither supplemental themselves
+* nor nested inside a supplemental node. Use it when aggregating over nodes
+* instead of returning them.
+*/
+const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
+/**
 * Flatten a properties array
 * @param properties - The properties to flatten
 * @returns The flattened properties
@@ -169,4 +209,4 @@ function flattenProperties(properties) {
 	return result;
 }
 //#endregion
-export { createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, stringLiteral };
+export { NOT_SUPPLEMENTAL_PREDICATE, SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, omitSupplemental, stringLiteral };

package/dist/xml/schemas.d.mts

@@ -1,11 +1,6 @@
-import { XMLData as XMLData$1, XMLDataItem as XMLDataItem$1, XMLGalleryData as XMLGalleryData$1, XMLItemLinksData as XMLItemLinksData$1, XMLLink as XMLLink$1, XMLOcrMatchesData as XMLOcrMatchesData$1, XMLSetItemsData as XMLSetItemsData$1, XMLWebsiteData as XMLWebsiteData$1 } from "./types.mjs";
+import { XMLData as XMLData$1, XMLDataItem as XMLDataItem$1, XMLGalleryData as XMLGalleryData$1, XMLItemLinksData as XMLItemLinksData$1, XMLLink as XMLLink$1, XMLSetItemsData as XMLSetItemsData$1, XMLWebsiteData as XMLWebsiteData$1 } from "./types.mjs";
 import * as v from "valibot";
 //#region src/xml/schemas.d.ts
-/**
- * Schema for validating OCR matches fetched from the OCHRE API
- * @internal
- */
-declare const XMLOcrMatchesData: v.GenericSchema<unknown, XMLOcrMatchesData$1>;
 declare const XMLLink: v.GenericSchema<unknown, XMLLink$1>;
 declare const XMLDataItem: v.GenericSchema<unknown, XMLDataItem$1>;
 declare const XMLItemLinksData: v.GenericSchema<unknown, XMLItemLinksData$1>;
@@ -14,4 +9,4 @@ declare const XMLSetItemsData: v.GenericSchema<unknown, XMLSetItemsData$1>;
 declare const XMLData: v.GenericSchema<unknown, XMLData$1>;
 declare const XMLWebsiteData: v.GenericSchema<unknown, XMLWebsiteData$1>;
 //#endregion
-export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLOcrMatchesData, XMLSetItemsData, XMLWebsiteData };
+export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLSetItemsData, XMLWebsiteData };

package/dist/xml/schemas.mjs

@@ -224,42 +224,6 @@ const XMLImageMap = v.object({
 	width: XMLNumber,
 	height: XMLNumber
 }, "XMLImageMap: Shape error");
-const XMLOcrString = v.object({
-	HPOS: XMLNumber,
-	VPOS: XMLNumber,
-	WIDTH: XMLNumber,
-	HEIGHT: XMLNumber,
-	CONTENT: v.string("XMLOcrString: CONTENT is string and required"),
-	VERTICES: v.optional(v.string("XMLOcrString: VERTICES is string and optional"))
-}, "XMLOcrString: Shape error");
-const XMLOcrTextLine = v.object({ string: v.optional(v.array(XMLOcrString, "XMLOcrTextLine: string is array of XMLOcrString")) }, "XMLOcrTextLine: Shape error");
-const XMLOcrTextBlock = v.object({ TextLine: v.optional(v.array(XMLOcrTextLine, "XMLOcrTextBlock: TextLine is array of XMLOcrTextLine")) }, "XMLOcrTextBlock: Shape error");
-const XMLOcrPage = v.object({
-	n: XMLOptionalNumber,
-	fileName: v.optional(v.string("XMLOcrPage: fileName is string and optional")),
-	WIDTH: XMLOptionalNumber,
-	HEIGHT: XMLOptionalNumber,
-	TextBlock: v.optional(v.array(XMLOcrTextBlock, "XMLOcrPage: TextBlock is array of XMLOcrTextBlock"))
-}, "XMLOcrPage: Shape error");
-const XMLOcr = v.object({ Page: v.optional(v.array(XMLOcrPage, "XMLOcr: Page is array of XMLOcrPage")) }, "XMLOcr: Shape error");
-const XMLOcrMatch = v.object({
-	resourceUuid: v.optional(v.string("XMLOcrMatch: resourceUuid is string and optional")),
-	n: XMLOptionalNumber,
-	fileName: v.optional(v.string("XMLOcrMatch: fileName is string and optional")),
-	WIDTH: XMLOptionalNumber,
-	HEIGHT: XMLOptionalNumber,
-	string: v.optional(v.array(XMLOcrString, "XMLOcrMatch: string is array of XMLOcrString"))
-}, "XMLOcrMatch: Shape error");
-const XMLOcrMatchItem = v.object({
-	uuid: v.pipe(v.string("XMLOcrMatchItem: uuid is string and required"), v.check(isPseudoUuid, "XMLOcrMatchItem: uuid is not a valid pseudo-UUID")),
-	matchCount: XMLNumber,
-	ocrMatch: v.optional(v.array(XMLOcrMatch, "XMLOcrMatchItem: ocrMatch is array of XMLOcrMatch"))
-}, "XMLOcrMatchItem: Shape error");
-/**
-* Schema for validating OCR matches fetched from the OCHRE API
-* @internal
-*/
-const XMLOcrMatchesData = v.object({ result: v.object({ ochre: v.object({ ocrMatches: v.optional(v.object({ ocrItem: v.optional(v.array(XMLOcrMatchItem, "XMLOcrMatchesData: ocrItem is array of XMLOcrMatchItem")) })) }) }) }, "XMLOcrMatchesData: Shape error");
 const XMLNote = v.object({
 	content: v.optional(XMLContent.entries.content),
 	payload: v.optional(v.string("XMLNote: payload is string and optional")),
@@ -680,7 +644,6 @@ const XMLResource = v.object({
 	width: XMLOptionalNumber,
 	image: v.optional(XMLImage),
 	imagemap: v.optional(XMLImageMap),
-	ocr: v.optional(XMLOcr),
 	document: v.optional(XMLContent),
 	coordinates: v.optional(XMLCoordinates),
 	periods: v.optional(v.object({ period: v.array(XMLPeriod) })),
@@ -832,7 +795,6 @@ const XMLWebsiteResource = v.lazy(() => v.object({
 	width: XMLOptionalNumber,
 	image: v.optional(XMLImage),
 	imagemap: v.optional(XMLImageMap),
-	ocr: v.optional(XMLOcr),
 	document: v.optional(XMLContent),
 	coordinates: v.optional(XMLCoordinates),
 	periods: v.optional(v.object({ period: v.array(XMLPeriod) })),
@@ -966,4 +928,4 @@ const XMLWebsiteData = v.object({ result: v.object({ ochre: v.object({
 	tree: v.array(XMLWebsiteTree)
 }, "XMLWebsiteData: ochre is object with website tree") }, "XMLWebsiteData: result is object with ochre") }, "XMLWebsiteData: Shape error");
 //#endregion
-export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLOcrMatchesData, XMLSetItemsData, XMLWebsiteData };
+export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLSetItemsData, XMLWebsiteData };

package/dist/xml/types.d.mts

@@ -182,48 +182,6 @@ type XMLImageMap = {
   width: XMLNumber;
   height: XMLNumber;
 };
-type XMLOcrString = {
-  HPOS: XMLNumber;
-  VPOS: XMLNumber;
-  WIDTH: XMLNumber;
-  HEIGHT: XMLNumber;
-  CONTENT: string;
-  VERTICES?: string;
-};
-type XMLOcrTextLine = {
-  string?: Array<XMLOcrString>;
-};
-type XMLOcrTextBlock = {
-  TextLine?: Array<XMLOcrTextLine>;
-};
-type XMLOcrPage = {
-  n?: XMLNumber;
-  fileName?: string;
-  WIDTH?: XMLNumber;
-  HEIGHT?: XMLNumber;
-  TextBlock?: Array<XMLOcrTextBlock>;
-};
-type XMLOcr = {
-  Page?: Array<XMLOcrPage>;
-};
-type XMLOcrMatch = Omit<XMLOcrPage, "TextBlock"> & {
-  resourceUuid?: string;
-  string?: Array<XMLOcrString>;
-};
-type XMLOcrMatchItem = {
-  uuid: string;
-  matchCount: XMLNumber;
-  ocrMatch?: Array<XMLOcrMatch>;
-};
-type XMLOcrMatchesData = {
-  result: {
-    ochre: {
-      ocrMatches?: {
-        ocrItem?: Array<XMLOcrMatchItem>;
-      };
-    };
-  };
-};
 type XMLNote = Partial<XMLContent> & XMLString & {
   noteNo?: XMLNumber;
   title?: string;
@@ -605,7 +563,6 @@ type XMLResource = XMLBaseItem & {
   width?: XMLNumber;
   image?: XMLImage;
   imagemap?: XMLImageMap;
-  ocr?: XMLOcr;
   document?: XMLContent;
   coordinates?: XMLCoordinates;
   periods?: {
@@ -963,4 +920,4 @@ type XMLWebsiteData = {
   };
 };
 //#endregion
-export { XMLBaseItem, XMLBibliography, XMLBoolean, XMLConcept, XMLContent, XMLContext, XMLContextGroup, XMLContextItem, XMLContextValue, XMLCoordinate, XMLCoordinates, XMLCoordinatesSource, XMLData, XMLDataItem, XMLDictionaryUnit, XMLEmptyContext, XMLEvent, XMLGallery, XMLGalleryData, XMLHeading, XMLHeadingItemCategory, XMLIdentification, XMLImage, XMLImageMap, XMLImageMapArea, XMLInterpretation, XMLItemCategory, XMLItemLinks, XMLItemLinksData, XMLLicense, XMLLink, XMLLinkedBaseItem, XMLLinkedBibliography, XMLLinkedConcept, XMLLinkedPeriod, XMLLinkedPerson, XMLLinkedPropertyValue, XMLLinkedPropertyVariable, XMLLinkedResource, XMLLinkedSet, XMLLinkedSpatialUnit, XMLLinkedText, XMLLinkedTree, XMLMetadata, XMLNote, XMLNumber, XMLObservation, XMLOcr, XMLOcrMatch, XMLOcrMatchItem, XMLOcrMatchesData, XMLOcrPage, XMLOcrString, XMLOcrTextBlock, XMLOcrTextLine, XMLPeriod, XMLPerson, XMLProperty, XMLPropertyRelation, XMLPropertyValue, XMLPropertyVariable, XMLRecursiveItemCategory, XMLResource, XMLRichTextEnvelope, XMLSection, XMLSet, XMLSetItems, XMLSetItemsData, XMLSimplifiedProperty, XMLSpatialUnit, XMLString, XMLText, XMLTree, XMLWebsiteContext, XMLWebsiteContextItem, XMLWebsiteContextLevel, XMLWebsiteData, XMLWebsiteFilterContext, XMLWebsiteFilterContextItem, XMLWebsiteOptions, XMLWebsiteProperties, XMLWebsiteResource, XMLWebsiteResourceGroup, XMLWebsiteResourceItem, XMLWebsiteScope, XMLWebsiteSegment, XMLWebsiteStyle, XMLWebsiteTree };
+export { XMLBaseItem, XMLBibliography, XMLBoolean, XMLConcept, XMLContent, XMLContext, XMLContextGroup, XMLContextItem, XMLContextValue, XMLCoordinate, XMLCoordinates, XMLCoordinatesSource, XMLData, XMLDataItem, XMLDictionaryUnit, XMLEmptyContext, XMLEvent, XMLGallery, XMLGalleryData, XMLHeading, XMLHeadingItemCategory, XMLIdentification, XMLImage, XMLImageMap, XMLImageMapArea, XMLInterpretation, XMLItemCategory, XMLItemLinks, XMLItemLinksData, XMLLicense, XMLLink, XMLLinkedBaseItem, XMLLinkedBibliography, XMLLinkedConcept, XMLLinkedPeriod, XMLLinkedPerson, XMLLinkedPropertyValue, XMLLinkedPropertyVariable, XMLLinkedResource, XMLLinkedSet, XMLLinkedSpatialUnit, XMLLinkedText, XMLLinkedTree, XMLMetadata, XMLNote, XMLNumber, XMLObservation, XMLPeriod, XMLPerson, XMLProperty, XMLPropertyRelation, XMLPropertyValue, XMLPropertyVariable, XMLRecursiveItemCategory, XMLResource, XMLRichTextEnvelope, XMLSection, XMLSet, XMLSetItems, XMLSetItemsData, XMLSimplifiedProperty, XMLSpatialUnit, XMLString, XMLText, XMLTree, XMLWebsiteContext, XMLWebsiteContextItem, XMLWebsiteContextLevel, XMLWebsiteData, XMLWebsiteFilterContext, XMLWebsiteFilterContextItem, XMLWebsiteOptions, XMLWebsiteProperties, XMLWebsiteResource, XMLWebsiteResourceGroup, XMLWebsiteResourceItem, XMLWebsiteScope, XMLWebsiteSegment, XMLWebsiteStyle, XMLWebsiteTree };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.72",
+  "version": "1.0.74",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -51,11 +51,12 @@
     "valibot": "^1.4.2"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.2.0",
+    "@antfu/eslint-config": "^9.3.0",
     "@types/node": "^24.13.3",
-    "bumpp": "^12.1.1",
+    "bumpp": "^12.2.0",
     "eslint": "^10.8.0",
-    "knip": "^6.31.0",
+    "eslint-plugin-erasable-syntax-only": "^0.4.2",
+    "knip": "^6.32.0",
     "oxfmt": "^0.62.0",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",

package/dist/fetchers/ocr-matches.d.mts

@@ -1,44 +0,0 @@
-import { OcrMatch } from "../types/index.mjs";
-import { FetchFunction } from "../parsers/helpers.mjs";
-//#region src/fetchers/ocr-matches.d.ts
-/**
- * Fetches the locations of OCR text matches within OCHRE resources
- *
- * Matching mirrors the `ocr` Set item query target, so the same value and match
- * mode that selected an item will locate its hits. `matchCountsByUuid` reports
- * the untruncated count, which can exceed the returned matches when
- * `maxMatchesPerItem` caps them.
- *
- * @param parameters - The parameters for the fetch
- * @param parameters.uuids - The resource UUIDs to search, typically from a filtered Set item fetch
- * @param parameters.value - The search value
- * @param parameters.matchMode - Whether to match loosely (stemming and wildcards) or on whole OCR words, defaults to "includes"
- * @param parameters.isCaseSensitive - Whether matching is case sensitive, defaults to false
- * @param parameters.maxMatchesPerItem - The cap on returned matches per requested UUID, defaults to 50
- * @param options - Options for the fetch
- * @param options.fetch - The fetch function to use
- * @returns The OCR matches, or null if the fetch/parse fails
- */
-declare function fetchOcrMatches(parameters: {
-  uuids: Array<string>;
-  value: string;
-  matchMode?: "includes" | "exact";
-  isCaseSensitive?: boolean;
-  maxMatchesPerItem?: number;
-}, options?: {
-  fetch?: FetchFunction;
-}): Promise<{
-  matches: Array<OcrMatch>;
-  matchesByUuid: Record<string, Array<OcrMatch>>;
-  matchCountsByUuid: Record<string, number>;
-  error: null;
-  detailedError: null;
-} | {
-  matches: null;
-  matchesByUuid: null;
-  matchCountsByUuid: null;
-  error: string;
-  detailedError: string;
-}>;
-//#endregion
-export { fetchOcrMatches };

package/dist/fetchers/ocr-matches.mjs

@@ -1,134 +0,0 @@
-import { XML_PARSER_OPTIONS } from "../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utilities.mjs";
-import { buildOcrTermQueryExpressions } from "../query.mjs";
-import { ocrMatchesParametersSchema } from "../schemas.mjs";
-import { restoreXMLMetadata } from "../xml/metadata.mjs";
-import { parseOcrMatches } from "../parsers/index.mjs";
-import { XMLOcrMatchesData } from "../xml/schemas.mjs";
-import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
-//#region src/fetchers/ocr-matches.ts
-/**
-* Build an XQuery string to fetch OCR match locations from the OCHRE API
-*
-* Each OCR word is matched with `cts:contains` against the same per-term CTS
-* queries the Set item filter compiles, so hit locations always agree with what
-* the filter matched — including stemming and wildcards, which cannot be
-* reproduced outside MarkLogic.
-*
-* @param parameters - The parameters for the fetch
-* @param parameters.uuids - The resource UUIDs to search
-* @param parameters.termQueryExpressions - One CTS query expression per search term, in word order
-* @param parameters.maxMatchesPerItem - The cap on returned matches per requested UUID
-* @returns An XQuery string
-*/
-function buildXQuery(parameters) {
-	const { uuids, termQueryExpressions, maxMatchesPerItem } = parameters;
-	return `xquery version "1.0-ml";
-
-declare variable $uuids := (${Array.from(uuids, (uuid) => stringLiteral(uuid)).join(", ")});
-
-declare variable $termQueries := (
-  ${termQueryExpressions.join(",\n  ")}
-);
-
-declare variable $termCount := ${termQueryExpressions.length};
-
-<ochre>{
-  <ocrMatches>{
-    for $uuid in $uuids
-    let $matches :=
-      for $page in doc($uuid)//ocr/Page
-      let $words := $page//TextLine/string
-      let $wordCount := count($words)
-      let $resourceUuid := string($page/ancestor::resource[1]/@uuid)
-      for $word at $index in $words
-      where $index + $termCount - 1 le $wordCount
-        and (every $offset in (1 to $termCount)
-             satisfies cts:contains($words[$index + $offset - 1], $termQueries[$offset]))
-      return <ocrMatch resourceUuid="{$resourceUuid}">{
-        $page/@n, $page/@fileName, $page/@WIDTH, $page/@HEIGHT,
-        subsequence($words, $index, $termCount)
-      }</ocrMatch>
-    return <ocrItem uuid="{$uuid}" matchCount="{count($matches)}">{
-      subsequence($matches, 1, ${maxMatchesPerItem})
-    }</ocrItem>
-  }</ocrMatches>
-}</ochre>`;
-}
-/**
-* Fetches the locations of OCR text matches within OCHRE resources
-*
-* Matching mirrors the `ocr` Set item query target, so the same value and match
-* mode that selected an item will locate its hits. `matchCountsByUuid` reports
-* the untruncated count, which can exceed the returned matches when
-* `maxMatchesPerItem` caps them.
-*
-* @param parameters - The parameters for the fetch
-* @param parameters.uuids - The resource UUIDs to search, typically from a filtered Set item fetch
-* @param parameters.value - The search value
-* @param parameters.matchMode - Whether to match loosely (stemming and wildcards) or on whole OCR words, defaults to "includes"
-* @param parameters.isCaseSensitive - Whether matching is case sensitive, defaults to false
-* @param parameters.maxMatchesPerItem - The cap on returned matches per requested UUID, defaults to 50
-* @param options - Options for the fetch
-* @param options.fetch - The fetch function to use
-* @returns The OCR matches, or null if the fetch/parse fails
-*/
-async function fetchOcrMatches(parameters, options) {
-	try {
-		const { uuids, value, matchMode, isCaseSensitive, maxMatchesPerItem } = v.parse(ocrMatchesParametersSchema, parameters);
-		const termQueryExpressions = buildOcrTermQueryExpressions({
-			value,
-			matchMode,
-			isCaseSensitive
-		});
-		if (termQueryExpressions.length === 0) return {
-			matches: [],
-			matchesByUuid: {},
-			matchCountsByUuid: {},
-			error: null,
-			detailedError: null
-		};
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: buildXQuery({
-				uuids,
-				termQueryExpressions,
-				maxMatchesPerItem
-			}),
-			headers: { "Content-Type": "application/xquery" }
-		});
-		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`, { cause: response.statusText });
-		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
-		const { success, issues, output } = v.safeParse(XMLOcrMatchesData, data);
-		if (!success) throw createSchemaValidationError("Failed to parse OCHRE OCR matches", issues);
-		restoreXMLMetadata(output, data);
-		const rawOcrItems = output.result.ochre.ocrMatches?.ocrItem ?? [];
-		const matches = parseOcrMatches(rawOcrItems);
-		const matchesByUuid = {};
-		const matchCountsByUuid = {};
-		for (const uuid of uuids) {
-			matchesByUuid[uuid] = [];
-			matchCountsByUuid[uuid] = 0;
-		}
-		for (const rawOcrItem of rawOcrItems) matchCountsByUuid[rawOcrItem.uuid] = rawOcrItem.matchCount;
-		for (const match of matches) matchesByUuid[match.uuid]?.push(match);
-		return {
-			matches,
-			matchesByUuid,
-			matchCountsByUuid,
-			error: null,
-			detailedError: null
-		};
-	} catch (error) {
-		return {
-			matches: null,
-			matchesByUuid: null,
-			matchCountsByUuid: null,
-			...getErrorOutput(error, "Unknown error")
-		};
-	}
-}
-//#endregion
-export { fetchOcrMatches };