ochre-sdk 0.20.7 → 0.20.10

package/dist/index.d.mts

@@ -951,7 +951,7 @@ type WebElementComponent = {
     isResultsBarDisplayed: boolean;
     isMapDisplayed: boolean;
     isInputDisplayed: boolean;
-    isLimitedToTitleQuery: boolean;
+    isLimitedToInputFilter: boolean;
     isLimitedToLeafPropertyValues: boolean;
     sidebarSort: "default" | "alphabetical";
   };
@@ -1231,12 +1231,6 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
 }>;
 //#endregion
 //#region src/utils/fetchers/set/property-values-by-property-variables.d.ts
-type SetPropertyValuesByPropertyVariablesTitleQueryInput = {
-  value: string;
-  matchMode: "includes" | "exact";
-  isCaseSensitive: boolean;
-  language?: string;
-};
 /**
  * Fetches and parses Set property values by property variables from the OCHRE API
  *
@@ -1244,7 +1238,7 @@ type SetPropertyValuesByPropertyVariablesTitleQueryInput = {
  * @param params.setScopeUuids - An array of set scope UUIDs to filter by
  * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
  * @param params.propertyVariableUuids - The property variable UUIDs to query by
- * @param params.titleQuery - Title query to filter returned items by item title
+ * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
  * @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
@@ -1255,7 +1249,7 @@ declare function fetchSetPropertyValuesByPropertyVariables(params: {
   setScopeUuids: Array<string>;
   belongsToCollectionScopeUuids: Array<string>;
   propertyVariableUuids: Array<string>;
-  titleQuery?: SetPropertyValuesByPropertyVariablesTitleQueryInput;
+  queries?: Array<Query>;
   isLimitedToLeafPropertyValues?: boolean;
 }, options?: {
   fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;

package/dist/index.mjs

@@ -760,87 +760,70 @@ const boundsSchema = z.string().transform((str, ctx) => {
 	}
 }).pipe(z.tuple([z.tuple([z.number(), z.number()]), z.tuple([z.number(), z.number()])], { message: "Must contain exactly 2 coordinate pairs" }));
 /**
-* Schema for validating the parameters for the Set property values by property variables fetching function
+* Shared schema for Set queries
 * @internal
 */
-const setPropertyValuesByPropertyVariablesParamsSchema = z.object({
-	setScopeUuids: z.array(uuidSchema).min(1, "At least one set scope UUID is required"),
-	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
-	propertyVariableUuids: z.array(uuidSchema).min(1, "At least one property variable UUID is required"),
-	titleQuery: z.object({
+const setQuerySchema = z.union([
+	z.object({
+		target: z.literal("propertyValue"),
+		dataType: z.enum([
+			"string",
+			"integer",
+			"decimal",
+			"boolean",
+			"time",
+			"IDREF"
+		]),
 		value: z.string(),
 		matchMode: z.enum(["includes", "exact"]),
 		isCaseSensitive: z.boolean(),
-		language: z.string().default("eng")
-	}).strict().optional(),
-	isLimitedToLeafPropertyValues: z.boolean().default(false)
-});
-const setItemsParamsSchema = z.object({
-	setScopeUuids: z.array(uuidSchema).min(1, "At least one set scope UUID is required"),
-	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
-	propertyVariableUuids: z.array(uuidSchema).default([]),
-	queries: z.array(z.union([
-		z.object({
-			target: z.literal("propertyValue"),
-			dataType: z.enum([
-				"string",
-				"integer",
-				"decimal",
-				"boolean",
-				"time",
-				"IDREF"
-			]),
-			value: z.string(),
-			matchMode: z.enum(["includes", "exact"]),
-			isCaseSensitive: z.boolean(),
-			language: z.string().default("eng"),
-			operator: z.enum(["AND", "OR"]).optional(),
-			isNegated: z.boolean().optional().default(false)
-		}).strict(),
-		z.object({
-			target: z.literal("propertyValue"),
-			dataType: z.enum(["date", "dateTime"]),
-			value: z.string(),
-			from: z.string(),
-			to: z.string().optional(),
-			matchMode: z.enum(["includes", "exact"]),
-			isCaseSensitive: z.boolean(),
-			language: z.string().default("eng"),
-			operator: z.enum(["AND", "OR"]).optional(),
-			isNegated: z.boolean().optional().default(false)
-		}).strict(),
-		z.object({
-			target: z.literal("propertyValue"),
-			dataType: z.enum(["date", "dateTime"]),
-			value: z.string(),
-			from: z.string().optional(),
-			to: z.string(),
-			matchMode: z.enum(["includes", "exact"]),
-			isCaseSensitive: z.boolean(),
-			language: z.string().default("eng"),
-			operator: z.enum(["AND", "OR"]).optional(),
-			isNegated: z.boolean().optional().default(false)
-		}).strict(),
-		z.object({
-			target: z.enum([
-				"title",
-				"description",
-				"image",
-				"periods",
-				"bibliography"
-			]),
-			value: z.string(),
-			matchMode: z.enum(["includes", "exact"]),
-			isCaseSensitive: z.boolean(),
-			language: z.string().default("eng"),
-			operator: z.enum(["AND", "OR"]).optional(),
-			isNegated: z.boolean().optional().default(false)
-		}).strict()
-	])).default([]),
-	page: z.number().min(1, "Page must be positive").default(1),
-	pageSize: z.number().min(1, "Page size must be positive").default(DEFAULT_PAGE_SIZE)
-}).superRefine((value, ctx) => {
-	for (const [index, query] of value.queries.entries()) {
+		language: z.string().default("eng"),
+		operator: z.enum(["AND", "OR"]).optional(),
+		isNegated: z.boolean().optional().default(false)
+	}).strict(),
+	z.object({
+		target: z.literal("propertyValue"),
+		dataType: z.enum(["date", "dateTime"]),
+		value: z.string(),
+		from: z.string(),
+		to: z.string().optional(),
+		matchMode: z.enum(["includes", "exact"]),
+		isCaseSensitive: z.boolean(),
+		language: z.string().default("eng"),
+		operator: z.enum(["AND", "OR"]).optional(),
+		isNegated: z.boolean().optional().default(false)
+	}).strict(),
+	z.object({
+		target: z.literal("propertyValue"),
+		dataType: z.enum(["date", "dateTime"]),
+		value: z.string(),
+		from: z.string().optional(),
+		to: z.string(),
+		matchMode: z.enum(["includes", "exact"]),
+		isCaseSensitive: z.boolean(),
+		language: z.string().default("eng"),
+		operator: z.enum(["AND", "OR"]).optional(),
+		isNegated: z.boolean().optional().default(false)
+	}).strict(),
+	z.object({
+		target: z.enum([
+			"title",
+			"description",
+			"image",
+			"periods",
+			"bibliography"
+		]),
+		value: z.string(),
+		matchMode: z.enum(["includes", "exact"]),
+		isCaseSensitive: z.boolean(),
+		language: z.string().default("eng"),
+		operator: z.enum(["AND", "OR"]).optional(),
+		isNegated: z.boolean().optional().default(false)
+	}).strict()
+]);
+const setQueriesSchema = z.array(setQuerySchema).default([]);
+function validateSetQueriesOperators(queries, ctx) {
+	for (const [index, query] of queries.entries()) {
 		if (index === 0 && query.operator != null) ctx.addIssue({
 			code: "custom",
 			path: [
@@ -860,6 +843,29 @@ const setItemsParamsSchema = z.object({
 			message: "Query rules after the first must include an operator"
 		});
 	}
+}
+/**
+* Schema for validating the parameters for the Set property values by property variables fetching function
+* @internal
+*/
+const setPropertyValuesByPropertyVariablesParamsSchema = z.object({
+	setScopeUuids: z.array(uuidSchema).min(1, "At least one set scope UUID is required"),
+	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
+	propertyVariableUuids: z.array(uuidSchema).min(1, "At least one property variable UUID is required"),
+	queries: setQueriesSchema,
+	isLimitedToLeafPropertyValues: z.boolean().default(false)
+}).superRefine((value, ctx) => {
+	validateSetQueriesOperators(value.queries, ctx);
+});
+const setItemsParamsSchema = z.object({
+	setScopeUuids: z.array(uuidSchema).min(1, "At least one set scope UUID is required"),
+	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
+	propertyVariableUuids: z.array(uuidSchema).default([]),
+	queries: setQueriesSchema,
+	page: z.number().min(1, "Page must be positive").default(1),
+	pageSize: z.number().min(1, "Page size must be positive").default(DEFAULT_PAGE_SIZE)
+}).superRefine((value, ctx) => {
+	validateSetQueriesOperators(value.queries, ctx);
 });
 
 //#endregion
@@ -2105,17 +2111,11 @@ async function fetchItem(uuid, category, itemCategories, options) {
 }
 
 //#endregion
-//#region src/utils/fetchers/set/items.ts
+//#region src/utils/fetchers/set/query-helpers.ts
 /**
 * Build a string match predicate for an XQuery string
-* @param params - The parameters for the predicate
-* @param params.path - The path to the string
-* @param params.value - The value to match
-* @param params.matchMode - The match mode (includes or exact)
-* @param params.isCaseSensitive - Whether to match case-sensitively
-* @returns The string match predicate
-*/
-function buildStringMatchPredicate$1(params) {
+*/
+function buildStringMatchPredicate(params) {
 	const { path, value, matchMode, isCaseSensitive } = params;
 	const comparedPath = isCaseSensitive ? path : `lower-case(${path})`;
 	const comparedValueLiteral = stringLiteral(isCaseSensitive ? value : value.toLowerCase());
@@ -2134,8 +2134,6 @@ function buildDateRangePredicate(params) {
 }
 /**
 * Build a property value predicate for an XQuery string
-* @param query - The propertyValue query
-* @returns The property value predicate
 */
 function buildPropertyValuePredicate(query) {
 	if (query.dataType === "IDREF") return `.//properties//property[value[@uuid=${stringLiteral(query.value)}]]`;
@@ -2144,7 +2142,7 @@ function buildPropertyValuePredicate(query) {
 		to: query.to
 	})}]`;
 	if (query.dataType === "time" || query.dataType === "integer" || query.dataType === "decimal" || query.dataType === "boolean") return `.//properties//property[value[@rawValue=${stringLiteral(query.value)}]]`;
-	return `.//properties//property[${buildStringMatchPredicate$1({
+	return `.//properties//property[${buildStringMatchPredicate({
 		path: `string-join(value/content[@xml:lang="${query.language}"]/string, "")`,
 		value: query.value,
 		matchMode: query.matchMode,
@@ -2153,36 +2151,34 @@ function buildPropertyValuePredicate(query) {
 }
 /**
 * Build a query predicate for an XQuery string
-* @param query - The query to build the predicate for
-* @returns The query predicate
 */
 function buildQueryPredicate(query) {
 	switch (query.target) {
-		case "title": return buildStringMatchPredicate$1({
+		case "title": return buildStringMatchPredicate({
 			path: `string-join(identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "description": return buildStringMatchPredicate$1({
+		case "description": return buildStringMatchPredicate({
 			path: `string-join(description/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "periods": return buildStringMatchPredicate$1({
+		case "periods": return buildStringMatchPredicate({
 			path: `string-join(periods/period/identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "bibliography": return buildStringMatchPredicate$1({
+		case "bibliography": return buildStringMatchPredicate({
 			path: `string-join(bibliographies/bibliography/identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "image": return buildStringMatchPredicate$1({
+		case "image": return buildStringMatchPredicate({
 			path: `string-join(image/identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
@@ -2199,6 +2195,19 @@ function buildBooleanQueryClause(query) {
 	return query.isNegated ? `not(${baseClause})` : baseClause;
 }
 /**
+* Build query filters for an XQuery string.
+*/
+function buildQueryFilters(queries) {
+	return queries.map((query, index) => {
+		const clause = buildBooleanQueryClause(query);
+		if (index === 0) return clause;
+		return `${query.operator === "OR" ? "or" : "and"} ${clause}`;
+	}).join(" ");
+}
+
+//#endregion
+//#region src/utils/fetchers/set/items.ts
+/**
 * 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
@@ -2217,11 +2226,7 @@ function buildXQuery$1(params, options) {
 	const startPosition = (page - 1) * pageSize + 1;
 	const endPosition = page * pageSize;
 	const setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`;
-	const queryFilters = queries.map((query, index) => {
-		const clause = buildBooleanQueryClause(query);
-		if (index === 0) return clause;
-		return `${query.operator === "OR" ? "or" : "and"} ${clause}`;
-	}).join(" ");
+	const queryFilters = buildQueryFilters(queries);
 	const filterPredicates = [];
 	if (belongsToCollectionScopeUuids.length > 0) {
 		const belongsToCollectionScopeValues = belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
@@ -2397,35 +2402,6 @@ function aggregatePropertyValues(values) {
 	});
 }
 /**
-* Build a string match predicate for an XQuery string
-* @param params - The parameters for the predicate
-* @param params.path - The path to the string
-* @param params.value - The value to match
-* @param params.matchMode - The match mode (includes or exact)
-* @param params.isCaseSensitive - Whether to match case-sensitively
-* @returns The string match predicate
-*/
-function buildStringMatchPredicate(params) {
-	const { path, value, matchMode, isCaseSensitive } = params;
-	const comparedPath = isCaseSensitive ? path : `lower-case(${path})`;
-	const comparedValueLiteral = stringLiteral(isCaseSensitive ? value : value.toLowerCase());
-	if (matchMode === "includes") return `contains(${comparedPath}, ${comparedValueLiteral})`;
-	return `${comparedPath} = ${comparedValueLiteral}`;
-}
-/**
-* Build a title predicate for an XQuery string
-* @param titleQuery - The title query
-* @returns The title predicate
-*/
-function buildTitlePredicate(titleQuery) {
-	return buildStringMatchPredicate({
-		path: `string-join(identification/label/content[@xml:lang="${titleQuery.language}"]/string, "")`,
-		value: titleQuery.value,
-		matchMode: titleQuery.matchMode,
-		isCaseSensitive: titleQuery.isCaseSensitive
-	});
-}
-/**
 * Schema for a single property value query item in the OCHRE API response
 */
 const propertyValueQueryItemSchema = z.object({
@@ -2482,7 +2458,7 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 * @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.propertyVariableUuids - An array of property variable UUIDs to fetch
-* @param params.titleQuery - Title query to filter returned items by item title
+* @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
 * @param params.isLimitedToLeafPropertyValues - Whether to limit the property values to leaf property values
 * @param options - Options for the fetch
 * @param options.version - The version of the OCHRE API to use
@@ -2490,16 +2466,17 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 */
 function buildXQuery(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
-	const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, titleQuery, isLimitedToLeafPropertyValues } = params;
+	const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, queries, isLimitedToLeafPropertyValues } = params;
 	let setScopeFilter = "/set/items/*";
 	if (setScopeUuids.length > 0) setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`;
 	const propertyVariableFilters = propertyVariableUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
+	const queryFilters = buildQueryFilters(queries);
 	const filterPredicates = [];
 	if (belongsToCollectionScopeUuids.length > 0) {
 		const belongsToCollectionScopeValues = belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 		filterPredicates.push(`.//properties[property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}" and value/(${belongsToCollectionScopeValues})]]`);
 	}
-	if (titleQuery != null) filterPredicates.push(buildTitlePredicate(titleQuery));
+	if (queryFilters.length > 0) filterPredicates.push(`(${queryFilters})`);
 	const itemFilters = filterPredicates.length > 0 ? `[${filterPredicates.join(" and ")}]` : "";
 	return `<ochre>{${`let $items := ${version === 2 ? "doc()" : "input()"}/ochre
       ${setScopeFilter}
@@ -2522,7 +2499,7 @@ function buildXQuery(params, options) {
 * @param params.setScopeUuids - An array of set scope UUIDs to filter by
 * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
 * @param params.propertyVariableUuids - The property variable UUIDs to query by
-* @param params.titleQuery - Title query to filter returned items by item title
+* @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
 * @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
@@ -2532,12 +2509,12 @@ function buildXQuery(params, options) {
 async function fetchSetPropertyValuesByPropertyVariables(params, options) {
 	try {
 		const version = options?.version ?? DEFAULT_API_VERSION;
-		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, titleQuery, isLimitedToLeafPropertyValues } = setPropertyValuesByPropertyVariablesParamsSchema.parse(params);
+		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, queries, isLimitedToLeafPropertyValues } = setPropertyValuesByPropertyVariablesParamsSchema.parse(params);
 		const xquery = buildXQuery({
 			setScopeUuids,
 			belongsToCollectionScopeUuids,
 			propertyVariableUuids,
-			titleQuery,
+			queries,
 			isLimitedToLeafPropertyValues
 		}, { version });
 		const response = await (options?.fetch ?? fetch)(version === 2 ? `https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery=${encodeURIComponent(xquery)}&format=json&lang="*"` : `https://ochre.lib.uchicago.edu/ochre?xquery=${encodeURIComponent(xquery)}&format=json&lang="*"`);
@@ -3071,8 +3048,8 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			isFilterMapDisplayed ??= false;
 			let isFilterInputDisplayed = getPropertyValueByLabel(componentProperty.properties, "filter-input-displayed");
 			isFilterInputDisplayed ??= false;
-			let isFilterLimitedToTitleQuery = getPropertyValueByLabel(componentProperty.properties, "filter-limit-to-title-query");
-			isFilterLimitedToTitleQuery ??= false;
+			let isFilterLimitedToInputFilter = getPropertyValueByLabel(componentProperty.properties, "filter-limit-to-input-filter");
+			isFilterLimitedToInputFilter ??= false;
 			let isFilterLimitedToLeafPropertyValues = getPropertyValueByLabel(componentProperty.properties, "filter-limit-to-leaf-property-values");
 			isFilterLimitedToLeafPropertyValues ??= false;
 			let isSortDisplayed = getPropertyValueByLabel(componentProperty.properties, "sort-displayed");
@@ -3122,7 +3099,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 					isResultsBarDisplayed: isFilterResultsBarDisplayed,
 					isMapDisplayed: isFilterMapDisplayed,
 					isInputDisplayed: isFilterInputDisplayed,
-					isLimitedToTitleQuery: isFilterLimitedToTitleQuery,
+					isLimitedToInputFilter: isFilterLimitedToInputFilter,
 					isLimitedToLeafPropertyValues: isFilterLimitedToLeafPropertyValues,
 					sidebarSort: filterSidebarSort
 				},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "0.20.7",
+  "version": "0.20.10",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -47,7 +47,7 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^7.6.1",
-    "@types/node": "^24.10.14",
+    "@types/node": "^24.10.15",
     "bumpp": "^10.4.1",
     "eslint": "^10.0.2",
     "prettier": "^3.8.1",