ochre-sdk 1.0.12 → 1.0.14

package/dist/fetchers/set/items.d.mts

@@ -0,0 +1,48 @@
+import { Query, SetItem, SetItemCategory, SetItemsSort } from "../../types/index.mjs";
+
+//#region src/fetchers/set/items.d.ts
+type FetchFunction = (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+type FetchSetItemsBaseOptions<TLanguages extends ReadonlyArray<string> | undefined = undefined> = {
+  languages?: TLanguages;
+  fetch?: FetchFunction;
+};
+type FetchSetItemsLanguages<TLanguages extends ReadonlyArray<string> | undefined> = TLanguages extends readonly [] ? ReadonlyArray<string> : TLanguages extends ReadonlyArray<string> ? TLanguages : ReadonlyArray<string>;
+type FetchSetItemsCategory<TContainedItemCategories extends ReadonlyArray<SetItemCategory> | undefined> = TContainedItemCategories extends ReadonlyArray<infer U> ? Extract<U, SetItemCategory> : SetItemCategory;
+/**
+ * Fetches and parses Set items from the OCHRE API
+ *
+ * @param params - The parameters for the fetch
+ * @param params.setScopeUuids - The Set scope UUIDs to filter by
+ * @param params.queries - Recursive query tree used to filter matching items
+ * @param params.sort - Optional sorting configuration applied before pagination.
+ * For propertyValue sorting, dataType is required and the sort key uses the first valid leaf value (value[not(@i)]).
+ * @param params.page - The page number (1-indexed)
+ * @param params.pageSize - The number of items per page
+ * @param containedItemCategories - The categories of the items to fetch
+ * @param options - Options for the fetch
+ * @param options.fetch - The fetch function to use
+ * @returns The parsed Set items or null if the fetch/parse fails
+ */
+declare function fetchSetItems<const TContainedItemCategories extends ReadonlyArray<SetItemCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(params: {
+  setScopeUuids: Array<string>;
+  queries?: Query | null;
+  sort?: SetItemsSort;
+  page: number;
+  pageSize?: number;
+}, containedItemCategories?: TContainedItemCategories, options?: FetchSetItemsBaseOptions<TLanguages>): Promise<{
+  totalCount: number;
+  page: number;
+  pageSize: number;
+  items: Array<SetItem<FetchSetItemsCategory<TContainedItemCategories>, FetchSetItemsLanguages<TLanguages>>>;
+  error: null;
+  detailedError: null;
+} | {
+  totalCount: null;
+  page: null;
+  pageSize: null;
+  items: null;
+  error: string;
+  detailedError: string;
+}>;
+//#endregion
+export { fetchSetItems };

package/dist/fetchers/set/items.mjs

@@ -0,0 +1,268 @@
+import { BELONGS_TO_COLLECTION_UUID, DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../../constants.mjs";
+import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../../utils.mjs";
+import { iso639_3Schema, setItemsParamsSchema } from "../../schemas.mjs";
+import { restoreXMLMetadata } from "../../xml/metadata.mjs";
+import { parseSetItems } from "../../parsers/index.mjs";
+import { XMLSetItemsData } from "../../xml/schemas.mjs";
+import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
+import * as v from "valibot";
+import { XMLParser } from "fast-xml-parser";
+//#region src/fetchers/set/items.ts
+function parseLanguages(languages) {
+	const parsedLanguages = [];
+	for (const language of languages) parsedLanguages.push(v.parse(iso639_3Schema, language));
+	return parsedLanguages;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function collectContentLanguages(value, languages) {
+	if (Array.isArray(value)) {
+		for (const item of value) collectContentLanguages(item, languages);
+		return;
+	}
+	if (!isRecord(value)) return;
+	const content = value.content;
+	if (Array.isArray(content)) for (const contentItem of content) {
+		if (!isRecord(contentItem)) continue;
+		const language = contentItem.lang;
+		if (typeof language === "string" && language !== "zxx") languages.add(language);
+	}
+	for (const child of Object.values(value)) collectContentLanguages(child, languages);
+}
+function resolveSetItemsLanguages(data, requestedLanguages) {
+	if (requestedLanguages.length > 0) return requestedLanguages;
+	const languages = /* @__PURE__ */ new Set();
+	collectContentLanguages(data.result.ochre.items, languages);
+	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
+}
+function hasArray(items) {
+	return items != null && items.length > 0;
+}
+function hasSetItemsCategory(items, category) {
+	switch (category) {
+		case "tree": return hasArray(items.tree);
+		case "bibliography": return hasArray(items.bibliography);
+		case "concept": return hasArray(items.concept);
+		case "spatialUnit": return hasArray(items.spatialUnit);
+		case "period": return hasArray(items.period);
+		case "person": return hasArray(items.person);
+		case "propertyVariable": return hasArray(items.propertyVariable) || hasArray(items.variable);
+		case "propertyValue": return hasArray(items.propertyValue) || hasArray(items.value);
+		case "resource": return hasArray(items.resource);
+		case "text": return hasArray(items.text);
+		case "set": return hasArray(items.set);
+	}
+}
+function mapSortDirectionToXQuery(direction) {
+	return direction === "desc" ? "descending" : "ascending";
+}
+function buildStringOrderByClause(direction) {
+	return `($sortKey = "") ascending, lower-case($sortKey) ${direction}, $position ascending`;
+}
+function buildTypedOrderByClause(direction) {
+	return `empty($sortKey) ascending, $sortKey ${direction}, $position ascending`;
+}
+function buildPropertyValueValuePath(sort) {
+	return `$item//properties//property[label/@uuid=${stringLiteral(sort.propertyVariableUuid)}]/value[not(@i)]`;
+}
+function buildPropertyValueStringSortKeyExpression(sort) {
+	const languageLiteral = stringLiteral(sort.language ?? "eng");
+	return `string((for $v in ${buildPropertyValueValuePath(sort)}
+        let $candidate := string-join($v/content[@xml:lang=${languageLiteral}]/string, "")
+        where string-length($candidate) gt 0
+        return $candidate)[1])`;
+}
+function buildPropertyValueTypedSortKeyExpression(params) {
+	const { sort, dataType } = params;
+	const propertyValuePath = buildPropertyValueValuePath(sort);
+	switch (dataType) {
+		case "integer": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:integer
+        return xs:integer($candidate))[1]`;
+		case "decimal":
+		case "time": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:decimal
+        return xs:decimal($candidate))[1]`;
+		case "boolean": return `(for $v in ${propertyValuePath}
+        let $candidate := lower-case(normalize-space(string($v/@rawValue)))
+        where $candidate = ("true", "false", "1", "0")
+        return if ($candidate = ("true", "1")) then 1 else 0)[1]`;
+		case "date": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:date
+        return xs:date($candidate))[1]`;
+		case "dateTime": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:dateTime
+        return xs:dateTime($candidate))[1]`;
+	}
+}
+function buildPropertyValueOrderByClause(params) {
+	const { dataType, direction } = params;
+	return dataType === "string" || dataType === "IDREF" ? buildStringOrderByClause(direction) : buildTypedOrderByClause(direction);
+}
+function buildOrderedItemsClause(sort) {
+	if (sort.target === "none") return "let $orderedItems := $items";
+	const direction = mapSortDirectionToXQuery(sort.direction);
+	if (sort.target === "title") return `let $orderedItems :=
+    for $item at $position in $items
+      let $sortKey := ${`string-join($item/identification/label/content[@xml:lang=${stringLiteral(sort.language ?? "eng")}]/string, "")`}
+      stable order by ${buildStringOrderByClause(direction)}
+      return $item`;
+	return `let $orderedItems :=
+    for $item at $position in $items
+      let $sortKey := ${sort.dataType === "string" || sort.dataType === "IDREF" ? buildPropertyValueStringSortKeyExpression(sort) : buildPropertyValueTypedSortKeyExpression({
+		sort,
+		dataType: sort.dataType
+	})}
+      stable order by ${buildPropertyValueOrderByClause({
+		dataType: sort.dataType,
+		direction
+	})}
+      return $item`;
+}
+function isExactStringPropertyQuery(query) {
+	return "target" in query && query.target === "property" && query.dataType === "string" && query.value != null && query.matchMode === "exact" && query.isNegated !== true;
+}
+function getCtsQueriesWithoutExactStringPropertyQueries(queries) {
+	if (queries == null) return null;
+	if ("target" in queries) return isExactStringPropertyQuery(queries) ? null : queries;
+	if ("or" in queries) return queries;
+	const filteredChildren = [];
+	for (const childQuery of queries.and) {
+		const filteredChildQuery = getCtsQueriesWithoutExactStringPropertyQueries(childQuery);
+		if (filteredChildQuery != null) filteredChildren.push(filteredChildQuery);
+	}
+	if (filteredChildren.length === 0) return null;
+	return filteredChildren.length === 1 ? filteredChildren[0] ?? null : { and: filteredChildren };
+}
+function buildExactStringPropertyPredicate(query) {
+	const propertyPredicates = [];
+	const value = stringLiteral(query.value);
+	if (query.propertyVariable != null) propertyPredicates.push(`label/@uuid = ${stringLiteral(query.propertyVariable)}`);
+	propertyPredicates.push(`value[
+    not(@inherited = "true")
+    and (
+      content[@xml:lang = ${stringLiteral(query.language)}]/string = ${value}
+      or @rawValue = ${value}
+      or (not(content) and text() = ${value})
+    )
+  ]`);
+	return `.//properties/property[${propertyPredicates.join(" and ")}]`;
+}
+function buildExactStringPropertyXPathFilterExpression(queries) {
+	if (queries == null) return null;
+	if ("target" in queries) return isExactStringPropertyQuery(queries) ? buildExactStringPropertyPredicate(queries) : null;
+	if ("or" in queries) return null;
+	const childExpressions = [];
+	for (const childQuery of queries.and) {
+		const childExpression = buildExactStringPropertyXPathFilterExpression(childQuery);
+		if (childExpression != null) childExpressions.push(childExpression);
+	}
+	if (childExpressions.length === 0) return null;
+	return childExpressions.join(" and ");
+}
+/**
+* Build an XQuery string to fetch Set items from the OCHRE API
+* @param params - The parameters for the fetch
+* @param params.setScopeUuids - An array of Set scope UUIDs to filter by
+* @param params.belongsToCollectionScopeUuids - An array of collection scope UUIDs to filter by
+* @param params.queries - Recursive query tree used to filter matching items
+* @param params.sort - Optional sorting configuration applied before pagination.
+* For propertyValue sorting, dataType is required and the sort key uses the first valid leaf value (value[not(@i)]).
+* @param params.page - The page number (1-indexed)
+* @param params.pageSize - The number of items per page
+* @returns An XQuery string
+*/
+function buildXQuery(params) {
+	const { queries, sort, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = params;
+	const startPosition = (page - 1) * pageSize + 1;
+	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
+	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
+	const ctsQueries = getCtsQueriesWithoutExactStringPropertyQueries(queries);
+	const exactStringPropertyXPathFilterExpression = buildExactStringPropertyXPathFilterExpression(queries);
+	const compiledQueryPlan = buildQueryPlan({ queries: ctsQueries });
+	const itemsQueryExpressions = [];
+	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
+	if (compiledQueryPlan.queryExpression != null) itemsQueryExpressions.push(compiledQueryPlan.queryExpression);
+	if (belongsToCollectionQueryExpression != null) itemsQueryExpressions.push(belongsToCollectionQueryExpression);
+	const itemsQueryExpression = buildAndCtsQueryExpression(itemsQueryExpressions);
+	const orderedItemsClause = buildOrderedItemsClause(sort);
+	const xqueryDeclarations = ["xquery version \"1.0-ml\";", setScopeDeclaration];
+	if (compiledQueryPlan.prolog !== "") xqueryDeclarations.push(compiledQueryPlan.prolog);
+	const searchedItemsClause = itemsQueryExpression == null ? `let $searchedItems := ${baseItemsExpression}` : `let $query := ${itemsQueryExpression}
+  let $searchedItems := cts:search(${baseItemsExpression}, $query)`;
+	const itemsClause = exactStringPropertyXPathFilterExpression == null ? `${searchedItemsClause}
+  let $items := $searchedItems` : `${searchedItemsClause}
+  let $items := $searchedItems[${exactStringPropertyXPathFilterExpression}]`;
+	return `${xqueryDeclarations.join("\n\n")}
+
+<ochre>{
+${itemsClause}
+  let $totalCount := count($items)
+  ${orderedItemsClause}
+  let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})
+
+  return <items totalCount="{$totalCount}" page="${page}" pageSize="${pageSize}">{
+    $pagedItems
+  }</items>
+}</ochre>`;
+}
+async function fetchSetItems(params, containedItemCategories, options) {
+	try {
+		const { setScopeUuids, belongsToCollectionScopeUuids, queries, sort, page, pageSize } = v.parse(setItemsParamsSchema, params);
+		const requestedLanguages = options?.languages == null ? [] : parseLanguages(options.languages);
+		const xquery = buildXQuery({
+			setScopeUuids,
+			belongsToCollectionScopeUuids,
+			queries,
+			sort,
+			page,
+			pageSize
+		});
+		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
+			method: "POST",
+			body: xquery,
+			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(XMLSetItemsData, data);
+		if (!success) throw createSchemaValidationError("Failed to parse OCHRE Set items", issues);
+		restoreXMLMetadata(output, data);
+		if (containedItemCategories != null) {
+			const missingCategories = containedItemCategories.filter((category) => !hasSetItemsCategory(output.result.ochre.items, category));
+			if (missingCategories.length > 0) throw new Error(`No Set items found for item categories: ${missingCategories.join(", ")}`, { cause: missingCategories });
+		}
+		const languages = resolveSetItemsLanguages(output, requestedLanguages);
+		const items = parseSetItems(output.result.ochre.items, {
+			containedItemCategories,
+			languages
+		});
+		const itemsByUuid = /* @__PURE__ */ new Map();
+		for (const item of items) if (!itemsByUuid.has(item.uuid)) itemsByUuid.set(item.uuid, item);
+		const uniqueItems = [...itemsByUuid.values()];
+		return {
+			totalCount: output.result.ochre.items.totalCount,
+			page: output.result.ochre.items.page,
+			pageSize: output.result.ochre.items.pageSize,
+			items: uniqueItems,
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			totalCount: null,
+			page: null,
+			pageSize: null,
+			items: null,
+			...getErrorOutput(error, "Failed to fetch Set items")
+		};
+	}
+}
+//#endregion
+export { fetchSetItems };

package/dist/fetchers/set/property-values.d.mts

@@ -0,0 +1,46 @@
+import { PropertyValueQueryItem, Query, SetAttributeValueQueryItem } from "../../types/index.mjs";
+
+//#region src/fetchers/set/property-values.d.ts
+/**
+ * Fetches and parses Set property values from the OCHRE API
+ *
+ * @param params - The parameters for the fetch
+ * @param params.setScopeUuids - An array of set scope UUIDs to filter by
+ * @param params.queries - Recursive query tree used to filter matching items
+ * @param params.attributes - Whether to return values for bibliographies and periods
+ * @param params.attributes.bibliographies - Whether to return values for bibliographies
+ * @param params.attributes.periods - Whether to return values for periods
+ * @param params.isLimitedToLeafPropertyValues - Whether to limit the property values to leaf property values
+ * @param options - Options for the fetch
+ * @param options.fetch - The fetch function to use
+ * @returns Parsed Set property values and requested attribute values.
+ * Returns empty arrays/objects when no matches are found, and null outputs on fetch/parse errors.
+ */
+declare function fetchSetPropertyValues(params: {
+  setScopeUuids: Array<string>;
+  queries?: Query | null;
+  attributes?: {
+    bibliographies: boolean;
+    periods: boolean;
+  };
+  isLimitedToLeafPropertyValues?: boolean;
+}, options?: {
+  fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+}): Promise<{
+  propertyValues: Array<PropertyValueQueryItem>;
+  propertyValuesByPropertyVariableUuid: Record<string, Array<PropertyValueQueryItem>>;
+  attributeValues: {
+    bibliographies: Array<SetAttributeValueQueryItem> | null;
+    periods: Array<SetAttributeValueQueryItem> | null;
+  };
+  error: null;
+  detailedError: null;
+} | {
+  propertyValues: null;
+  propertyValuesByPropertyVariableUuid: null;
+  attributeValues: null;
+  error: string;
+  detailedError: string;
+}>;
+//#endregion
+export { fetchSetPropertyValues };