ochre-sdk 0.20.29 → 0.21.0

package/dist/index.d.mts

@@ -671,9 +671,9 @@ type SetItemsSort = {
   language?: string;
 };
 /**
- * Represents a query for Set items
+ * Represents a leaf query for Set items
  */
-type Query = {
+type QueryLeaf = {
   target: "property";
   propertyVariables?: Array<string>;
   dataType: Exclude<Exclude<PropertyValueContentType, "coordinate">, "date" | "dateTime">;
@@ -683,7 +683,6 @@ type Query = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
-  operator?: "AND" | "OR";
   isNegated?: boolean;
 } | {
   target: "property";
@@ -695,7 +694,6 @@ type Query = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
-  operator?: "AND" | "OR";
   isNegated?: boolean;
 } | {
   target: "property";
@@ -707,7 +705,6 @@ type Query = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
-  operator?: "AND" | "OR";
   isNegated?: boolean;
 } | {
   target: "string";
@@ -715,7 +712,6 @@ type Query = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
-  operator?: "AND" | "OR";
   isNegated?: boolean;
 } | {
   target: "title" | "description" | "image" | "periods" | "bibliography";
@@ -723,9 +719,20 @@ type Query = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
-  operator?: "AND" | "OR";
   isNegated?: boolean;
 };
+/**
+ * Represents a boolean query group for Set items
+ */
+type QueryGroup = {
+  and: Array<Query>;
+} | {
+  or: Array<Query>;
+};
+/**
+ * Represents a query for Set items
+ */
+type Query = QueryLeaf | QueryGroup;
 //#endregion
 //#region src/types/website.d.ts
 /**
@@ -1234,7 +1241,7 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
  *
  * @param params - The parameters for the fetch
  * @param params.setScopeUuids - The Set scope UUIDs to filter by
- * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+ * @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)
@@ -1247,7 +1254,7 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
  */
 declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategory>>(params: {
   setScopeUuids: Array<string>;
-  queries: Array<Query>;
+  queries?: Query | null;
   sort?: SetItemsSort;
   page: number;
   pageSize?: number;
@@ -1274,7 +1281,7 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
  *
  * @param params - The parameters for the fetch
  * @param params.setScopeUuids - An array of set scope UUIDs to filter by
- * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+ * @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
@@ -1287,7 +1294,7 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
  */
 declare function fetchSetPropertyValues(params: {
   setScopeUuids: Array<string>;
-  queries?: Array<Query>;
+  queries?: Query | null;
   attributes?: {
     bibliographies: boolean;
     periods: boolean;
@@ -1470,4 +1477,4 @@ declare const DEFAULT_PAGE_SIZE = 48;
  */
 declare function flattenItemProperties<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(item: Item<T, U>): Item<T, U>;
 //#endregion
-export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, PropertyVariable, Query, Resource, Scope, Section, Set, SetAttributeValueQueryItem, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsiteType, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, PropertyVariable, Query, QueryGroup, QueryLeaf, Resource, Scope, Section, Set, SetAttributeValueQueryItem, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsiteType, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -756,7 +756,7 @@ const boundsSchema = z.string().transform((str, ctx) => {
 * Shared schema for Set queries
 * @internal
 */
-const setQuerySchema = z.union([
+const setQueryLeafSchema = z.union([
 	z.object({
 		target: z.literal("property"),
 		propertyVariables: z.array(uuidSchema).default([]),
@@ -772,7 +772,6 @@ const setQuerySchema = z.union([
 		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().superRefine((value, ctx) => {
 		if (value.propertyVariables.length === 0 && value.propertyValues == null) ctx.addIssue({
@@ -789,7 +788,6 @@ const setQuerySchema = z.union([
 		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({
@@ -801,7 +799,6 @@ const setQuerySchema = z.union([
 		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({
@@ -810,7 +807,6 @@ const setQuerySchema = z.union([
 		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({
@@ -825,11 +821,15 @@ const setQuerySchema = z.union([
 		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([]);
+const setQuerySchema = z.lazy(() => z.union([
+	setQueryLeafSchema,
+	z.object({ and: z.array(setQuerySchema).min(1, "AND groups must contain at least one query") }).strict(),
+	z.object({ or: z.array(setQuerySchema).min(1, "OR groups must contain at least one query") }).strict()
+]));
+const setQueriesSchema = setQuerySchema.nullable().default(null);
 const setItemsSortSchema = z.discriminatedUnion("target", [
 	z.object({ target: z.literal("none") }).strict(),
 	z.object({
@@ -854,16 +854,12 @@ const setItemsSortSchema = z.discriminatedUnion("target", [
 		language: z.string().default("eng")
 	}).strict()
 ]).default({ target: "none" });
-function validateSetQueriesOperators(queries, ctx) {
-	for (const [index, query] of queries.entries()) if (index > 0 && query.operator == null) ctx.addIssue({
-		code: "custom",
-		path: [
-			"queries",
-			index,
-			"operator"
-		],
-		message: "Query rules after the first must include an operator"
-	});
+function hasPropertyQueryWithPropertyVariables(query) {
+	if (query == null) return false;
+	if ("target" in query) return query.target === "property" && (query.propertyVariables?.length ?? 0) > 0;
+	const groupQueries = "and" in query ? query.and : query.or;
+	for (const groupQuery of groupQueries) if (hasPropertyQueryWithPropertyVariables(groupQuery)) return true;
+	return false;
 }
 /**
 * Schema for validating the parameters for the Set property values fetching function
@@ -882,8 +878,7 @@ const setPropertyValuesParamsSchema = z.object({
 	}),
 	isLimitedToLeafPropertyValues: z.boolean().default(false)
 }).superRefine((value, ctx) => {
-	validateSetQueriesOperators(value.queries, ctx);
-	if (!value.queries.some((query) => query.target === "property" && query.propertyVariables.length > 0)) ctx.addIssue({
+	if (!hasPropertyQueryWithPropertyVariables(value.queries)) ctx.addIssue({
 		code: "custom",
 		path: ["queries"],
 		message: "At least one property query with propertyVariables is required"
@@ -896,8 +891,6 @@ const setItemsParamsSchema = z.object({
 	sort: setItemsSortSchema,
 	page: z.number().min(1, "Page must be positive").default(1),
 	pageSize: z.number().min(1, "Page size must be positive").default(48)
-}).superRefine((value, ctx) => {
-	validateSetQueriesOperators(value.queries, ctx);
 });
 //#endregion
 //#region src/utils/parse/index.ts
@@ -2409,6 +2402,15 @@ function buildOrCtsQueryExpression(queries) {
 	if (queries.length === 1) return queries[0] ?? "cts:false-query()";
 	return `cts:or-query((${queries.join(", ")}))`;
 }
+function isQueryLeaf(query) {
+	return "target" in query;
+}
+function getQueryGroupChildren(query) {
+	return "and" in query ? query.and : query.or;
+}
+function getQueryGroupOperator(query) {
+	return "and" in query ? "and" : "or";
+}
 function buildContentTargetCandidateBranch(params) {
 	const { containerElementName, termExpression, isCaseSensitive, language } = params;
 	return `cts:element-query(xs:QName("${containerElementName}"),
@@ -2561,31 +2563,32 @@ function buildIncludesGroupMember(query) {
 		case "property": return buildPropertyStringIncludesGroupMember(query);
 	}
 }
-function findCompatibleIncludesGroup(params) {
-	const { queries, startIndex, version } = params;
-	const startQuery = queries[startIndex];
-	if (startQuery == null) return null;
-	const groupValue = getGroupableIncludesValue(startQuery);
+function getCompatibleIncludesGroupLeaves(params) {
+	const { query, version } = params;
+	if (!("or" in query) || query.or.length <= 1) return null;
+	const leafQueries = [];
+	for (const childQuery of query.or) {
+		if (!isQueryLeaf(childQuery)) return null;
+		leafQueries.push(childQuery);
+	}
+	const firstQuery = leafQueries[0];
+	if (firstQuery == null) return null;
+	const groupValue = getGroupableIncludesValue(firstQuery);
 	if (groupValue == null || !isCompatibleIncludesGroupQuery({
-		query: startQuery,
+		query: firstQuery,
 		value: groupValue,
-		isCaseSensitive: startQuery.isCaseSensitive,
-		language: startQuery.language,
+		isCaseSensitive: firstQuery.isCaseSensitive,
+		language: firstQuery.language,
 		version
-	}) || startIndex > 0 && queries[startIndex]?.operator === "AND") return null;
-	const groupedQueries = [startQuery];
-	for (let index = startIndex + 1; index < queries.length; index += 1) {
-		const query = queries[index];
-		if (query?.operator !== "OR" || !isCompatibleIncludesGroupQuery({
-			query,
-			value: groupValue,
-			isCaseSensitive: startQuery.isCaseSensitive,
-			language: startQuery.language,
-			version
-		})) break;
-		groupedQueries.push(query);
-	}
-	return groupedQueries.length > 1 ? groupedQueries : null;
+	})) return null;
+	for (const leafQuery of leafQueries.slice(1)) if (!isCompatibleIncludesGroupQuery({
+		query: leafQuery,
+		value: groupValue,
+		isCaseSensitive: firstQuery.isCaseSensitive,
+		language: firstQuery.language,
+		version
+	})) return null;
+	return leafQueries;
 }
 function buildIncludesGroupClause(params) {
 	const { queries, queryKey } = params;
@@ -2843,7 +2846,7 @@ function buildQueryClause(params) {
 /**
 * Build a boolean query clause for an XQuery string.
 */
-function buildBooleanQueryClause(params) {
+function buildBooleanQueryNode(params) {
 	const { query, version, queryKey } = params;
 	const compiledQueryClause = buildQueryClause({
 		query,
@@ -2854,45 +2857,79 @@ function buildBooleanQueryClause(params) {
 	return {
 		declarations: compiledQueryClause.declarations,
 		predicate: query.isNegated ? `not(${baseClause})` : baseClause,
-		candidateQueryVar: query.isNegated ? null : compiledQueryClause.candidateQueryVar
+		candidateQueryVars: query.isNegated || compiledQueryClause.candidateQueryVar == null ? [] : [compiledQueryClause.candidateQueryVar]
 	};
 }
-function buildQueryPlan(params) {
-	const { queries, version, baseItemsExpression } = params;
+function buildQueryNode(params) {
+	const { query, version, queryKey } = params;
+	if (isQueryLeaf(query)) return buildBooleanQueryNode({
+		query,
+		version,
+		queryKey
+	});
+	const groupQueries = getQueryGroupChildren(query);
+	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves({
+		query,
+		version
+	});
+	if (groupQueries.length === 1) {
+		const onlyQuery = groupQueries[0];
+		if (onlyQuery == null) return {
+			declarations: [],
+			predicate: "",
+			candidateQueryVars: []
+		};
+		return buildQueryNode({
+			query: onlyQuery,
+			version,
+			queryKey
+		});
+	}
+	if (optimizedIncludesGroupQueries != null) {
+		const compiledClause = buildIncludesGroupClause({
+			queries: optimizedIncludesGroupQueries,
+			queryKey
+		});
+		return {
+			declarations: compiledClause.declarations,
+			predicate: compiledClause.predicate,
+			candidateQueryVars: compiledClause.candidateQueryVar == null ? [] : [compiledClause.candidateQueryVar]
+		};
+	}
 	const declarations = [];
-	const predicateParts = [];
+	const predicates = [];
 	const candidateQueryVars = [];
-	let hasCtsIncludesClauses = false;
-	for (let index = 0; index < queries.length;) {
-		const groupedQueries = findCompatibleIncludesGroup({
-			queries,
-			startIndex: index,
-			version
+	for (const [groupIndex, groupQuery] of groupQueries.entries()) {
+		const compiledQueryNode = buildQueryNode({
+			query: groupQuery,
+			version,
+			queryKey: `${queryKey}_${groupIndex + 1}`
 		});
-		const query = queries[index];
-		if (query == null) break;
-		const compiledClause = groupedQueries != null ? buildIncludesGroupClause({
-			queries: groupedQueries,
-			queryKey: `${index + 1}`
-		}) : buildBooleanQueryClause({
-			query,
+		declarations.push(...compiledQueryNode.declarations);
+		predicates.push(compiledQueryNode.predicate);
+		candidateQueryVars.push(...compiledQueryNode.candidateQueryVars);
+	}
+	return {
+		declarations,
+		predicate: getQueryGroupOperator(query) === "and" ? buildAndPredicate(predicates) : buildOrPredicate(predicates),
+		candidateQueryVars
+	};
+}
+function buildQueryPlan(params) {
+	const { queries, version, baseItemsExpression } = params;
+	const declarations = [];
+	let predicate = "";
+	let candidateQueryVars = [];
+	if (queries != null) {
+		const compiledQueryNode = buildQueryNode({
+			query: queries,
 			version,
-			queryKey: `${index + 1}`
+			queryKey: "1"
 		});
-		if (compiledClause.declarations.length > 0) {
-			hasCtsIncludesClauses = true;
-			declarations.push(...compiledClause.declarations);
-		}
-		if (compiledClause.candidateQueryVar != null) candidateQueryVars.push(compiledClause.candidateQueryVar);
-		if (index === 0) {
-			predicateParts.push(compiledClause.predicate);
-			index += groupedQueries?.length ?? 1;
-			continue;
-		}
-		predicateParts.push(`${query.operator === "AND" ? "and" : "or"} ${compiledClause.predicate}`);
-		index += groupedQueries?.length ?? 1;
+		if (compiledQueryNode.declarations.length > 0) declarations.push(`let ${CTS_INCLUDES_STOP_WORDS_VAR} := (${CTS_INCLUDES_STOP_WORDS.map((stopWord) => stringLiteral(stopWord)).join(", ")})`, ...compiledQueryNode.declarations);
+		predicate = compiledQueryNode.predicate;
+		candidateQueryVars = compiledQueryNode.candidateQueryVars;
 	}
-	if (hasCtsIncludesClauses) declarations.unshift(`let ${CTS_INCLUDES_STOP_WORDS_VAR} := (${CTS_INCLUDES_STOP_WORDS.map((stopWord) => stringLiteral(stopWord)).join(", ")})`);
 	let itemsExpression = `(${baseItemsExpression})`;
 	if (candidateQueryVars.length > 0) {
 		const candidateQueriesExpression = `(${candidateQueryVars.join(", ")})`;
@@ -2910,7 +2947,7 @@ function buildQueryPlan(params) {
 	return {
 		declarations,
 		itemsExpression,
-		predicate: predicateParts.join(" ")
+		predicate
 	};
 }
 //#endregion
@@ -2990,7 +3027,7 @@ function buildOrderedItemsClause(sort) {
 * @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 - Ordered queries to combine with AND/OR and optional NOT via negation
+* @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)
@@ -3036,7 +3073,7 @@ function buildXQuery$1(params, options) {
 *
 * @param params - The parameters for the fetch
 * @param params.setScopeUuids - The Set scope UUIDs to filter by
-* @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+* @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)
@@ -3215,9 +3252,15 @@ function aggregateAttributeValues(values) {
 }
 function getPropertyVariableUuidsFromQueries(queries) {
 	const propertyVariableUuids = /* @__PURE__ */ new Set();
-	for (const query of queries) {
-		if (query.target !== "property") continue;
-		for (const propertyVariableUuid of query.propertyVariables ?? []) propertyVariableUuids.add(propertyVariableUuid);
+	if (queries == null) return [];
+	const pendingQueries = [queries];
+	for (const query of pendingQueries) {
+		if ("target" in query) {
+			if (query.target !== "property") continue;
+			for (const propertyVariableUuid of query.propertyVariables ?? []) propertyVariableUuids.add(propertyVariableUuid);
+			continue;
+		}
+		pendingQueries.push(..."and" in query ? query.and : query.or);
 	}
 	return [...propertyVariableUuids];
 }
@@ -3289,7 +3332,7 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 * @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 - Ordered queries to combine with AND/OR and optional NOT via negation
+* @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
@@ -3357,7 +3400,7 @@ return (${returnedSequences.join(", ")})`}}</ochre>`;
 *
 * @param params - The parameters for the fetch
 * @param params.setScopeUuids - An array of set scope UUIDs to filter by
-* @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+* @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "0.20.29",
+  "version": "0.21.0",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -52,7 +52,7 @@
     "eslint": "^10.1.0",
     "prettier": "^3.8.1",
     "tsdown": "^0.21.4",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.2"
   },
   "scripts": {
     "dev": "tsdown src/index.ts --watch",