ochre-sdk 1.3.12 → 1.3.14

package/README.md

@@ -66,10 +66,7 @@ present and `error` is `null`; on failure, the parsed value is `null` and
   style, collection, and item-page configuration.
 - `fetchSetItems(params, containedItemCategories, options)` fetches paginated
   Set search results with typed query and sort support.
-- `fetchSetItemLocations(params, options)` fetches the identification,
-  coordinates and chosen property values of every Set item matching a query,
-  without paging, for drawing all results on a map while a list pages through
-  them.
+- `fetchItemLocations(params, options)` fetches the identification, coordinates, and chosen property values of every Set or Tree item matching a query without paging. You can pass `setScopeUuids`, `treeScopeUuids`, or both. Each item lists the scope Sets and Trees it belongs to; this allows a map to draw one layer per Set or Tree while a list pages through the same query.
 - `fetchTreeItems(params, containedItemCategories, options)` is the same for a
   Tree, and is how to read a Tree too large to fetch whole. Items nested under
   headings come back flat, in document order.

package/dist/categories.d.mts

@@ -1,5 +1,4 @@
 import { ContextItemCategory, HeadingItemCategory, ItemCategory, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLinkCategory, TreeItemCategory } from "./types/index.mjs";
-//#region src/categories.d.ts
 /**
  * Every category an item hierarchy entry can carry, including the
  * pseudo-category OCHRE uses to group entries
@@ -245,5 +244,4 @@ export declare function isHeadingItemCategory(category: TreeItemCategory): categ
  * @returns The canonical category, or null when the name is not one
  * @internal
  */
-export declare function normalizeItemCategory(category: string | undefined): ItemCategory | null;
-//#endregion
+export declare function normalizeItemCategory(category: string | undefined): ItemCategory | null;

package/dist/categories.mjs

@@ -1,4 +1,4 @@
-//#region src/categories.ts
+// src/categories.ts
 /**
 * The one table describing the OCHRE item categories
 * @internal
@@ -255,5 +255,4 @@ function normalizeItemCategory(category) {
 	const normalizedCategory = ITEM_CATEGORY_BY_ALIAS.get(category);
 	return normalizedCategory != null && ITEM_CATEGORY_FACTS[normalizedCategory].isSetItem ? normalizedCategory : null;
 }
-//#endregion
 export { CONTEXT_CATEGORY_ALIASES, HEADING_ITEM_CATEGORIES, ITEM_CATEGORIES_WITH_EMBEDDED_ITEMS, ITEM_CATEGORY_ALIASES, ITEM_CATEGORY_BY_ALIAS, ITEM_CATEGORY_FACTS, ITEM_CONTAINER_CATEGORIES, OCHRE_COLLECTION_CATEGORIES, SET_ITEM_CATEGORIES, TREE_ITEM_CATEGORIES, isHeadingItemCategory, isItemCategoryWithEmbeddedItems, isItemContainerCategory, normalizeItemCategory };

package/dist/constants.d.mts

@@ -1,5 +1,4 @@
 import { X2jOptions } from "fast-xml-parser";
-//#region src/constants.d.ts
 export declare const XML_ARRAY_TAGS: ReadonlyArray<string>;
 export declare const XML_PARSER_OPTIONS: X2jOptions;
 export declare const DEFAULT_LANGUAGES: readonly ["eng"];
@@ -25,5 +24,4 @@ export declare const TEXT_ANNOTATION_ITEM_PAGE_VARIANT_UUID = "bf4476ab-6bc8-40d
 export declare const TEXT_ANNOTATION_ENTRY_PAGE_VARIANT_UUID = "9d52db95-a9cf-45f7-a0bf-fc9ba9f0aae0";
 export declare const TEXT_ANNOTATION_TEXT_STYLING_UUID = "3e6f86ab-df81-45ae-8257-e2867357df56";
 export declare const TEXT_ANNOTATION_TEXT_STYLING_VARIANT_UUID = "e1647bef-d801-4100-bdde-d081c422f763";
-export declare const TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID = "d4266f0b-3f8d-4b32-8c15-4b229c8bb11e";
-//#endregion
+export declare const TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID = "d4266f0b-3f8d-4b32-8c15-4b229c8bb11e";

package/dist/constants.mjs

@@ -1,4 +1,5 @@
-//#region src/constants.ts
+import { COMMON_HTML, CURRENCY, ENTITY_ACTION, EntityDecoder } from "@nodable/entities";
+// src/constants.ts
 const XML_ARRAY_TAGS = [
 	"string",
 	"content",
@@ -40,7 +41,10 @@ const XML_ARRAY_TAGS = [
 	"scope",
 	"level",
 	"style",
+	"styleLabel",
 	"itemLocation",
+	"mapSource",
+	"mapLayer",
 	"flattenContexts",
 	"suppressContexts",
 	"filterContexts",
@@ -48,7 +52,8 @@ const XML_ARRAY_TAGS = [
 	"detailContexts",
 	"downloadContexts",
 	"labelContexts",
-	"prominentContexts"
+	"prominentContexts",
+	"option"
 ];
 const XML_PARSER_OPTIONS = {
 	alwaysCreateTextNode: true,
@@ -62,7 +67,13 @@ const XML_PARSER_OPTIONS = {
 	attributeNamePrefix: "",
 	textNodeName: "payload",
 	stopNodes: ["*.referenceFormatDiv", "*.citationFormatSpan"],
-	htmlEntities: true,
+	entityDecoder: new EntityDecoder({
+		namedEntities: {
+			...COMMON_HTML,
+			...CURRENCY
+		},
+		onInputEntity: () => ENTITY_ACTION.BLOCK
+	}),
 	isArray(tagName, _, __, isAttribute) {
 		if (isAttribute) return false;
 		return XML_ARRAY_TAGS.includes(tagName);
@@ -99,5 +110,4 @@ const TEXT_ANNOTATION_ENTRY_PAGE_VARIANT_UUID = "9d52db95-a9cf-45f7-a0bf-fc9ba9f
 const TEXT_ANNOTATION_TEXT_STYLING_UUID = "3e6f86ab-df81-45ae-8257-e2867357df56";
 const TEXT_ANNOTATION_TEXT_STYLING_VARIANT_UUID = "e1647bef-d801-4100-bdde-d081c422f763";
 const TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID = "d4266f0b-3f8d-4b32-8c15-4b229c8bb11e";
-//#endregion
 export { BELONGS_TO_COLLECTION_UUID, DEFAULT_LANGUAGES, DEFAULT_PAGE_SIZE, OCHRE_ENDPOINT, PERMANENT_IDENTIFICATION_URL_PREFIX, PRESENTATION_ITEM_UUID, TEXT_ANNOTATION_ENTRY_PAGE_VARIANT_UUID, TEXT_ANNOTATION_HOVER_CARD_UUID, TEXT_ANNOTATION_ITEM_PAGE_VARIANT_UUID, TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID, TEXT_ANNOTATION_TEXT_STYLING_UUID, TEXT_ANNOTATION_TEXT_STYLING_VARIANT_UUID, TEXT_ANNOTATION_UUID, XML_ARRAY_TAGS, XML_PARSER_OPTIONS, getOchreItemUrl };

package/dist/errors.d.mts

@@ -1,5 +1,4 @@
 import * as v from "valibot";
-//#region src/errors.d.ts
 type SchemaValidationIssue = v.BaseIssue<unknown>;
 /**
  * Render an error as a short message and a fully detailed report
@@ -20,5 +19,4 @@ export declare function getErrorOutput(error: unknown, fallbackMessage: string):
  * @internal
  */
 export declare function createSchemaValidationError(message: string, issues: ReadonlyArray<SchemaValidationIssue>): Error;
-//#endregion
 export {};

package/dist/errors.mjs

@@ -1,6 +1,6 @@
 import { isObject, readEntries } from "./reflection.mjs";
 import * as v from "valibot";
-//#region src/errors.ts
+// src/errors.ts
 /**
 * The shape a valibot issue has to have for this module to render it
 *
@@ -160,5 +160,4 @@ function createSchemaValidationError(message, issues) {
 * @returns True if the string is a valid pseudo-UUID, false otherwise
 * @internal
 */
-//#endregion
 export { createSchemaValidationError, getErrorOutput };

package/dist/fetchers/container-items.d.mts

@@ -1,7 +1,6 @@
 import { ItemCategory, Query, SetItem, SetItemsSort } from "../types/index.mjs";
 import { XMLSetItems } from "../xml/types.mjs";
 import { FetchRuntimeOptions } from "../parsers/helpers.mjs";
-//#region src/fetchers/container-items.d.ts
 /**
  * Whether a container payload carries any item of a category
  * @param items - The parsed `<items>` payload
@@ -48,5 +47,4 @@ export declare function fetchContainerItems(parameters: {
   page: number;
   pageSize: number;
   items: Array<SetItem<ItemCategory, ReadonlyArray<string>>>;
-}>;
-//#endregion
+}>;

package/dist/fetchers/container-items.mjs

@@ -4,7 +4,7 @@ import { parseSetItems } from "../parsers/index.mjs";
 import { XMLSetItemsData } from "../xml/schemas.mjs";
 import { getContentLanguage, stringLiteral } from "../xquery.mjs";
 import { compileContainerItemsQuery } from "../query.mjs";
-//#region src/fetchers/container-items.ts
+// src/fetchers/container-items.ts
 function hasArray(items) {
 	return items != null && items.length > 0;
 }
@@ -180,5 +180,4 @@ async function fetchContainerItems(parameters) {
 		items: itemsByUuid.values().toArray()
 	};
 }
-//#endregion
 export { fetchContainerItems, hasItemsCategory };

package/dist/fetchers/gallery.d.mts

@@ -1,6 +1,5 @@
 import { Gallery } from "../types/index.mjs";
 import { FetchBaseOptions, FetchLanguages } from "../parsers/helpers.mjs";
-//#region src/fetchers/gallery.d.ts
 /**
  * Fetches and parses a gallery from the OCHRE API
  *
@@ -27,5 +26,4 @@ export declare function fetchGallery<const TLanguages extends ReadonlyArray<stri
   gallery: null;
   error: string;
   detailedError: string;
-}>;
-//#endregion
+}>;

package/dist/fetchers/gallery.mjs

@@ -6,7 +6,7 @@ import { parseGallery } from "../parsers/index.mjs";
 import { XMLGalleryData } from "../xml/schemas.mjs";
 import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
-//#region src/fetchers/gallery.ts
+// src/fetchers/gallery.ts
 function buildXQuery(parameters) {
 	const { uuid, filter, page, perPage, contentLanguage } = parameters;
 	const start = (page - 1) * perPage + 1;
@@ -61,5 +61,4 @@ async function fetchGallery(parameters, options) {
 		};
 	}
 }
-//#endregion
 export { fetchGallery };

package/dist/fetchers/item-children.d.mts

@@ -1,6 +1,5 @@
 import { ContainedItemCategoryFromOption, ContainedItemCategoryOption, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemContainerCategory, SetItemCategory, TreeItemCategory } from "../types/index.mjs";
 import { FetchBaseOptions, FetchLanguages } from "../parsers/helpers.mjs";
-//#region src/fetchers/item-children.d.ts
 type FetchItemChildrenResult<TItems> = Promise<{
   items: TItems;
   error: null;
@@ -32,5 +31,4 @@ export declare function fetchItemChildren<const TCategory extends ItemCategoryOp
   category: TCategory;
   containedItemCategory?: TContainedItemCategory;
 }): FetchItemChildrenResult<Array<Item<TChildCategory, ContainedItemCategoryFromOption<TChildCategory, TContainedItemCategory>, FetchLanguages<TLanguages>, ItemChildrenPayloadKind<ItemCategoryFromOption<TCategory>>>>>;
-//#endregion
 export {};

package/dist/fetchers/item-children.mjs

@@ -7,7 +7,7 @@ import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
 import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
-//#region src/fetchers/item-children.ts
+// src/fetchers/item-children.ts
 function buildXQuery(uuid, category, contentLanguage) {
 	const categories = category == null ? OCHRE_COLLECTION_CATEGORIES : typeof category === "string" ? [category] : category;
 	const collectionQueries = Array.from(categories, (possibleCategory) => `cts:search(fn:collection("ochre/${possibleCategory}")/ochre, $uuid-query)`);
@@ -81,5 +81,4 @@ async function fetchItemChildren(uuid, options) {
 		};
 	}
 }
-//#endregion
 export { fetchItemChildren };

package/dist/fetchers/item-links.d.mts

@@ -1,6 +1,5 @@
 import { ContainedItemCategoryFromOption, ContainedItemCategoryOption, Item, ItemCategory, ItemContainerCategory } from "../types/index.mjs";
 import { FetchBaseOptions, FetchLanguages } from "../parsers/helpers.mjs";
-//#region src/fetchers/item-links.d.ts
 /**
  * Fetches linked OCHRE items by source-item UUID.
  *
@@ -21,5 +20,4 @@ export declare function fetchItemLinks<const TContainedItemCategory extends Cont
   items: null;
   error: string;
   detailedError: string;
-}>;
-//#endregion
+}>;

package/dist/fetchers/item-links.mjs

@@ -7,7 +7,7 @@ import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
 import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
-//#region src/fetchers/item-links.ts
+// src/fetchers/item-links.ts
 /**
 * Build an XQuery string to fetch linked items from the OCHRE API.
 *
@@ -70,5 +70,4 @@ async function fetchItemLinks(uuid, options) {
 		};
 	}
 }
-//#endregion
 export { fetchItemLinks };

package/dist/fetchers/item-locations.d.mts

@@ -0,0 +1,39 @@
+import { ItemLocation, Query } from "../types/index.mjs";
+import { FetchBaseOptions, FetchLanguages } from "../parsers/helpers.mjs";
+/**
+ * Fetches the location of every Set or Tree item that matches a query, without paging
+ *
+ * Each item carries only its identification, the scope Sets and Trees it
+ * belongs to, its publication date, its coordinates, optionally its map
+ * polygons, and the values of the requested property variables (inherited
+ * values included), which is what a map needs to draw, color and group every
+ * match into layers while a list pages through the same query with
+ * {@link fetchSetItems} or {@link fetchTreeItems}.
+ *
+ * @param parameters - The parameters for the fetch
+ * @param parameters.setScopeUuids - The Set scope UUIDs to search within
+ * @param parameters.treeScopeUuids - The Tree scope UUIDs to search within
+ * @param parameters.queries - Recursive query tree used to filter matching items
+ * @param parameters.propertyVariableUuids - The property variables whose values each item should carry
+ * @param parameters.isMapDataIncluded - Whether each item should carry its map polygons
+ * @param options - Options for the fetch
+ * @param options.fetch - The fetch function to use
+ * @returns The item locations, or an error if the fetch/parse fails
+ */
+export declare function fetchItemLocations<const TLanguages extends ReadonlyArray<string> | undefined = undefined>(parameters: {
+  setScopeUuids?: Array<string>;
+  treeScopeUuids?: Array<string>;
+  queries?: Query | null;
+  propertyVariableUuids?: Array<string>;
+  isMapDataIncluded?: boolean;
+}, options?: FetchBaseOptions<TLanguages>): Promise<{
+  totalCount: number;
+  items: Array<ItemLocation<FetchLanguages<TLanguages>>>;
+  error: null;
+  detailedError: null;
+} | {
+  totalCount: null;
+  items: null;
+  error: string;
+  detailedError: string;
+}>;

package/dist/fetchers/item-locations.mjs

@@ -0,0 +1,98 @@
+import { normalizeItemCategory } from "../categories.mjs";
+import { getErrorOutput } from "../errors.mjs";
+import { requestOchre } from "./request.mjs";
+import { itemLocationsParametersSchema } from "../schemas.mjs";
+import { parseRequiredContentLike } from "../parsers/helpers.mjs";
+import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
+import { parseCoordinates, parseIdentification, parseSpatialUnitMapData } from "../parsers/index.mjs";
+import { XMLItemLocationsData } from "../xml/schemas.mjs";
+import { getContentLanguage, stringLiteral } from "../xquery.mjs";
+import { compileContainerItemsQuery } from "../query.mjs";
+import * as v from "valibot";
+// src/fetchers/item-locations.ts
+async function fetchItemLocations(parameters, options) {
+	try {
+		const { setScopeUuids, treeScopeUuids, belongsToCollectionScopeUuids, queries, propertyVariableUuids, isMapDataIncluded } = v.parse(itemLocationsParametersSchema, parameters);
+		const scopes = [{
+			container: "set",
+			scopeUuids: setScopeUuids
+		}, {
+			container: "tree",
+			scopeUuids: treeScopeUuids
+		}].filter(({ scopeUuids }) => scopeUuids.length > 0);
+		const outputs = await Promise.all(scopes.map(async ({ container, scopeUuids }) => requestOchre({
+			xquery: compileContainerItemsQuery({
+				container,
+				scopeUuids,
+				belongsToCollectionScopeUuids,
+				queries,
+				contentLanguage: getContentLanguage(options),
+				body: ({ items }) => `  let $propertyVariableUuids := (${Array.from(propertyVariableUuids, (uuid) => stringLiteral(uuid)).join(", ")})
+
+  return <items totalCount="{count(${items})}">{
+    for $item in ${items}
+    return <itemLocation uuid="{$item/@uuid}" category="{local-name($item)}" scopeUuid="{$item/ancestor::${container}[1]/@uuid}">{
+      ${container === "tree" ? "($item/@publicationDateTime, $item/ancestor::tree[1]/@publicationDateTime)[1]" : "$item/@publicationDateTime"},
+      $item/identification,
+      $item/coordinates,${isMapDataIncluded ? "\n      $item/mapData," : ""}
+      for $value in $item//properties//property[label/@uuid = $propertyVariableUuids]/value[@uuid]
+      return <value variable="{$value/../label/@uuid}" uuid="{$value/@uuid}">{$value/content}</value>
+    }</itemLocation>
+  }</items>`
+			}),
+			schema: XMLItemLocationsData,
+			label: `OCHRE ${container === "set" ? "Set" : "Tree"} item locations`,
+			options
+		})));
+		const languages = resolveContentLanguages(outputs.map((output) => output.result.ochre.items), parseRequestedLanguages(options?.languages));
+		let totalCount = 0;
+		for (const output of outputs) totalCount += output.result.ochre.items.totalCount;
+		const itemsByUuid = /* @__PURE__ */ new Map();
+		const itemLocations = outputs.flatMap((output) => output.result.ochre.items.itemLocation ?? []);
+		for (const itemLocation of itemLocations) {
+			const category = normalizeItemCategory(itemLocation.category);
+			const existing = itemsByUuid.get(itemLocation.uuid);
+			if (existing != null) {
+				if (!existing.scopeUuids.includes(itemLocation.scopeUuid)) existing.scopeUuids.push(itemLocation.scopeUuid);
+				continue;
+			}
+			if (category == null) continue;
+			const propertyValues = [];
+			const seenPropertyValues = /* @__PURE__ */ new Set();
+			const values = itemLocation.value ?? [];
+			for (const value of values) {
+				const key = `${value.variable}:${value.uuid}`;
+				if (seenPropertyValues.has(key)) continue;
+				seenPropertyValues.add(key);
+				propertyValues.push({
+					variableUuid: value.variable,
+					valueUuid: value.uuid,
+					label: parseRequiredContentLike(value, { languages })
+				});
+			}
+			itemsByUuid.set(itemLocation.uuid, {
+				uuid: itemLocation.uuid,
+				category,
+				scopeUuids: [itemLocation.scopeUuid],
+				publicationDateTime: itemLocation.publicationDateTime ?? null,
+				identification: parseIdentification(itemLocation.identification, { languages }),
+				coordinates: parseCoordinates(itemLocation.coordinates, { languages }),
+				mapData: parseSpatialUnitMapData(itemLocation.mapData),
+				propertyValues
+			});
+		}
+		return {
+			totalCount,
+			items: itemsByUuid.values().toArray(),
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			totalCount: null,
+			items: null,
+			...getErrorOutput(error, "Failed to fetch item locations")
+		};
+	}
+}
+export { fetchItemLocations };

package/dist/fetchers/item-ocr-data.d.mts

@@ -1,6 +1,5 @@
 import { OcrString } from "../types/index.mjs";
 import { OchreRequestOptions } from "./request.mjs";
-//#region src/fetchers/item-ocr-data.d.ts
 /**
  * Fetches and parses the OCR strings of an OCHRE item that match a search value
  *
@@ -35,5 +34,4 @@ export declare function fetchItemOcrData(uuid: string, value: string, options?:
   ocrStrings: null;
   error: string;
   detailedError: string;
-}>;
-//#endregion
+}>;

package/dist/fetchers/item-ocr-data.mjs

@@ -4,7 +4,7 @@ import { itemOcrDataParametersSchema } from "../schemas.mjs";
 import { OCHRE_RESPONSE_PADDING, stringLiteral } from "../xquery.mjs";
 import { buildOcrWordPath } from "../ocr.mjs";
 import * as v from "valibot";
-//#region src/fetchers/item-ocr-data.ts
+// src/fetchers/item-ocr-data.ts
 const OCR_STRING_VERTEX_REGEX = /\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)/g;
 /**
 * Schema for a single matched OCR string in the OCHRE API response
@@ -164,5 +164,4 @@ async function fetchItemOcrData(uuid, value, options) {
 		};
 	}
 }
-//#endregion
 export { fetchItemOcrData };

package/dist/fetchers/item.d.mts

@@ -1,6 +1,5 @@
 import { ContainedItemCategoryFromOption, ContainedItemCategoryOption, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemWithoutEmbeddedItems } from "../types/index.mjs";
 import { FetchBaseOptions, FetchLanguages } from "../parsers/helpers.mjs";
-//#region src/fetchers/item.d.ts
 type FetchItemResult<TItem> = Promise<{
   item: TItem;
   error: null;
@@ -44,5 +43,4 @@ export declare function fetchItem<const TCategory extends ItemCategoryOption, co
   containedItemCategory?: TContainedItemCategory;
   shouldOmitEmbeddedItems: true;
 }): FetchItemResult<ItemWithoutEmbeddedItems<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>, ContainedItemCategoryFromOption<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>, TContainedItemCategory>, FetchLanguages<TLanguages>> | Item<Exclude<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>, never, FetchLanguages<TLanguages>>>;
-//#endregion
 export {};

package/dist/fetchers/item.mjs

@@ -8,7 +8,7 @@ import { XMLData } from "../xml/schemas.mjs";
 import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import { parseWebpageView } from "../parsers/website/index.mjs";
 import * as v from "valibot";
-//#region src/fetchers/item.ts
+// src/fetchers/item.ts
 function isItemWithEmbeddedItems(item) {
 	return isItemCategoryWithEmbeddedItems(item.category);
 }
@@ -100,5 +100,4 @@ async function fetchItem(uuid, options) {
 		};
 	}
 }
-//#endregion
 export { fetchItem };

package/dist/fetchers/map-layers.d.mts

@@ -0,0 +1,28 @@
+import { MapLayer } from "../types/index.mjs";
+import { FetchBaseOptions, FetchLanguages } from "../parsers/helpers.mjs";
+/**
+ * Fetches the layers a map draws from the Sets and Trees it links to
+ *
+ * A linked Set holding only Sets, Trees and Resources is a layer list: each
+ * linked Set or Tree becomes an OCHRE layer and each webpage Resource whose
+ * href points at a geospatial web service becomes a service layer. Any other
+ * linked Set or Tree is drawn as one OCHRE layer itself. The variant is
+ * `"arcgis"` when any service layer is present, else `"maplibre-gl"`.
+ *
+ * @param uuids - The UUIDs of the Sets and Trees the map links to, in order
+ * @param options - Options for the fetch
+ * @param options.languages - Language codes to parse
+ * @param options.fetch - The fetch function to use
+ * @returns The map variant and layers, or an error if the fetch/parse fails
+ */
+export declare function fetchMapLayers<const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuids: Array<string>, options?: FetchBaseOptions<TLanguages>): Promise<{
+  variant: "maplibre-gl" | "arcgis";
+  layers: Array<MapLayer<FetchLanguages<TLanguages>>>;
+  error: null;
+  detailedError: null;
+} | {
+  variant: null;
+  layers: null;
+  error: string;
+  detailedError: string;
+}>;

package/dist/fetchers/map-layers.mjs

@@ -0,0 +1,160 @@
+import { getErrorOutput } from "../errors.mjs";
+import { requestOchre } from "./request.mjs";
+import { uuidSchema } from "../schemas.mjs";
+import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
+import { parseIdentification } from "../parsers/index.mjs";
+import { XMLMapSourcesData } from "../xml/schemas.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
+import * as v from "valibot";
+// src/fetchers/map-layers.ts
+const REGEX_TILE_TEMPLATE_LEVEL = /\{(?:level|z)\}/i;
+const REGEX_TILE_TEMPLATE_ROW = /\{(?:row|y)\}/i;
+const REGEX_TILE_TEMPLATE_COLUMN = /\{(?:col|x)\}/i;
+const REGEX_UNSUPPORTED_HOST = /(?:^|\.)google\.[a-z.]+$/i;
+const REGEX_PORTAL_ITEM_PATH = /\/home\/(?:item|webmap\/viewer)\.html$/i;
+const REGEX_PORTAL_ITEM_ID = /^[\da-f]{32}$/i;
+const REGEX_WMTS_CAPABILITIES = /\/WMTSCapabilities\.xml$/i;
+const REGEX_WMS_PATH = /\/wms(?:\/|$)/i;
+const REGEX_FEATURE_SERVER = /\/FeatureServer(?:\/\d+)?\/?$/i;
+const REGEX_MAP_SERVER = /\/MapServer(?:\/\d+)?\/?$/i;
+const REGEX_IMAGE_SERVER = /\/ImageServer\/?$/i;
+const REGEX_TRAILING_SLASH = /\/$/;
+const REGEX_ARCGIS_SOAP_SERVICES = /\/arcgis\/services\//i;
+/**
+* Classify the href of a webpage Resource as a geospatial web service
+* @param href - The Resource href
+* @returns The service layer, or null when the href names no supported service
+*/
+function parseServiceLayer(href) {
+	const trimmedHref = href.trim();
+	const url = URL.parse(trimmedHref);
+	if (url == null || REGEX_UNSUPPORTED_HOST.test(url.hostname)) return null;
+	if (REGEX_TILE_TEMPLATE_LEVEL.test(trimmedHref) && REGEX_TILE_TEMPLATE_ROW.test(trimmedHref) && REGEX_TILE_TEMPLATE_COLUMN.test(trimmedHref)) return {
+		type: "web-tile",
+		url: trimmedHref
+	};
+	let service = null;
+	for (const [key, value] of url.searchParams) if (key.toLowerCase() === "service") service = value.toLowerCase();
+	const itemId = url.searchParams.get("webmap") ?? (REGEX_PORTAL_ITEM_PATH.test(url.pathname) ? url.searchParams.get("id") : null);
+	if (itemId != null && REGEX_PORTAL_ITEM_ID.test(itemId)) return {
+		type: "arcgis-item",
+		itemId,
+		portalUrl: url.origin
+	};
+	const baseUrl = `${url.origin}${url.pathname.replace(REGEX_TRAILING_SLASH, "")}`;
+	const restUrl = baseUrl.replace(REGEX_ARCGIS_SOAP_SERVICES, "/arcgis/rest/services/");
+	if (service === "wmts") return {
+		type: "wmts",
+		url: baseUrl
+	};
+	if (REGEX_WMTS_CAPABILITIES.test(url.pathname)) return {
+		type: "wmts",
+		url: trimmedHref
+	};
+	if (service === "wms" || REGEX_WMS_PATH.test(url.pathname)) return {
+		type: "wms",
+		url: baseUrl
+	};
+	if (REGEX_FEATURE_SERVER.test(url.pathname)) return {
+		type: "arcgis-feature",
+		url: restUrl
+	};
+	if (REGEX_MAP_SERVER.test(url.pathname)) return {
+		type: "arcgis-map",
+		url: restUrl
+	};
+	if (REGEX_IMAGE_SERVER.test(url.pathname)) return {
+		type: "arcgis-image",
+		url: restUrl
+	};
+	return null;
+}
+/**
+* Build the layer a Set, Tree or Resource of a map's layer list stands for
+* @param member - The linked Set, Tree or Resource
+* @param languages - The languages to parse
+* @returns The layer, or null when a Resource names no supported service
+*/
+function parseMapLayer(member, languages) {
+	const { label } = parseIdentification(member.identification, { languages });
+	if (member.category === "set" || member.category === "tree") return {
+		type: member.category === "set" ? "ochre-set" : "ochre-tree",
+		uuid: member.uuid,
+		label,
+		wkid: member.WKID ?? null
+	};
+	const service = "href" in member && member.href != null ? parseServiceLayer(member.href) : null;
+	return service == null ? null : {
+		...service,
+		uuid: member.uuid,
+		label
+	};
+}
+async function fetchMapLayers(uuids, options) {
+	try {
+		const parsedUuids = v.parse(v.pipe(v.array(uuidSchema), v.minLength(1, "At least one map link UUID is required")), uuids);
+		const output = await requestOchre({
+			xquery: compileOchreQuery({
+				contentLanguage: getContentLanguage(options),
+				body: () => `<ochre>${OCHRE_RESPONSE_PADDING}<mapSources>{
+  for $uuid in (${parsedUuids.map((uuid) => stringLiteral(uuid)).join(", ")})
+  let $set := fn:collection("ochre/set")/ochre[@uuid = $uuid]/set
+  let $source := if (exists($set)) then $set else fn:collection("ochre/tree")/ochre[@uuid = $uuid]/tree
+  let $members := $set/items/*
+  let $layers := $members[self::set or self::tree or self::resource]
+  where exists($source)
+  return <mapSource uuid="{$uuid}" category="{local-name($source[1])}">{
+    $source[1]/@WKID,
+    $source[1]/identification,
+    if (exists($members) and count($layers) = count($members))
+    then
+      for $layer in $layers
+      let $layerUuid := $layer/@uuid/string()
+      return <mapLayer uuid="{$layerUuid}" category="{local-name($layer)}">{
+        $layer/@type,
+        $layer/@href,
+        if (local-name($layer) = "set")
+        then fn:collection("ochre/set")/ochre[@uuid = $layerUuid]/set[1]/@WKID
+        else (),
+        $layer/identification
+      }</mapLayer>
+    else ()
+  }</mapSource>
+}</mapSources></ochre>`
+			}),
+			schema: XMLMapSourcesData,
+			label: "OCHRE map layers",
+			options
+		});
+		const languages = resolveContentLanguages(output.result.ochre.mapSources, parseRequestedLanguages(options?.languages));
+		const layers = [];
+		const layerUuids = /* @__PURE__ */ new Set();
+		const sources = output.result.ochre.mapSources.mapSource ?? [];
+		for (const source of sources) {
+			const sourceLayers = [];
+			const members = source.mapLayer ?? [source];
+			for (const member of members) {
+				const layer = parseMapLayer(member, languages);
+				if (layer != null) sourceLayers.push(layer);
+			}
+			const mapServerUrls = sourceLayers.flatMap((layer) => layer.type === "arcgis-map" ? [`${layer.url}/`] : []);
+			for (const layer of sourceLayers) if (!(layer.type === "wmts" && mapServerUrls.some((url) => layer.url.startsWith(url))) && !layerUuids.has(layer.uuid)) {
+				layerUuids.add(layer.uuid);
+				layers.push(layer);
+			}
+		}
+		return {
+			variant: layers.some((layer) => layer.type !== "ochre-set" && layer.type !== "ochre-tree") ? "arcgis" : "maplibre-gl",
+			layers,
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			variant: null,
+			layers: null,
+			...getErrorOutput(error, "Failed to fetch map layers")
+		};
+	}
+}
+export { fetchMapLayers };

package/dist/fetchers/request.d.mts

@@ -1,6 +1,5 @@
 import { FetchFunction } from "../parsers/helpers.mjs";
 import * as v from "valibot";
-//#region src/fetchers/request.d.ts
 export type OchreRequestOptions = {
   fetch?: FetchFunction;
   signal?: AbortSignal;
@@ -66,5 +65,4 @@ export declare function isOchreJsonAccepted(parameters: {
   body: unknown;
   label: string;
   options?: OchreRequestOptions;
-}): Promise<boolean>;
-//#endregion
+}): Promise<boolean>;