ochre-sdk 1.0.25 → 1.0.27

package/dist/fetchers/item.d.mts

@@ -35,7 +35,7 @@ declare function withLanguages<const TLanguages extends ReadonlyArray<string>>(l
  * single category when it is known, or an array when the item may be any
  * category in that list.
  * @param options.containedItemCategory - The category of items inside the OCHRE item to fetch. Only valid for Trees and Sets. Tree accepts one category; Set accepts one category or an array.
- * @param options.shouldOmitEmbeddedItems - Whether to omit the embedded item hierarchy when fetching a recursive item category.
+ * @param options.shouldOmitEmbeddedItems - Whether to omit the embedded item hierarchy when fetching a recursive item category. Ignored when the fetched item does not expose recursive embedded items.
  * @param options.languages - Language codes to parse. Inline arrays preserve literal types automatically.
  * @param options.fetch - Custom fetch function to use instead of the default fetch
  * @returns An object containing the parsed item
@@ -49,7 +49,7 @@ declare function fetchItem<const TContainedItemCategory extends ContainedItemCat
   category?: undefined;
   containedItemCategory?: TContainedItemCategory;
   shouldOmitEmbeddedItems?: true;
-}): FetchItemResult<ItemWithoutEmbeddedItems<ItemCategoryWithEmbeddedItems, ContainedItemCategoryFromOption<ItemContainerCategory, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
+}): FetchItemResult<ItemWithoutEmbeddedItems<ItemCategoryWithEmbeddedItems, ContainedItemCategoryFromOption<ItemContainerCategory, TContainedItemCategory>, FetchLanguages<TLanguages>> | Item<Exclude<ItemCategory, ItemCategoryWithEmbeddedItems>, never, FetchLanguages<TLanguages>>>;
 declare function fetchItem<const TCategory extends ItemCategoryOption, const TContainedItemCategory extends ContainedItemCategoryOption<ItemCategoryFromOption<TCategory>> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchBaseOptions<TLanguages> & {
   category: TCategory;
   containedItemCategory?: TContainedItemCategory;
@@ -58,7 +58,7 @@ declare function fetchItem<const TCategory extends ItemCategoryOption, const TCo
 declare function fetchItem<const TCategory extends ItemCategoryOption, const TContainedItemCategory extends ContainedItemCategoryOption<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchBaseOptions<TLanguages> & {
   category: TCategory;
   containedItemCategory?: TContainedItemCategory;
-  shouldOmitEmbeddedItems: ItemCategoryFromOption<TCategory> extends ItemCategoryWithEmbeddedItems ? true : never;
-}): FetchItemResult<ItemWithoutEmbeddedItems<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>, ContainedItemCategoryFromOption<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
+  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 { defineLanguages, fetchItem, withLanguages };

package/dist/fetchers/item.mjs

@@ -23,11 +23,6 @@ function assertItemCategoryAllowed(category, containedItemCategory) {
 	for (const possibleCategory of categories) if (isItemContainerCategory(possibleCategory)) return;
 	throw new Error(`containedItemCategory can only be used when category is "tree" or "set"; received category "${categories.join(", ")}"`);
 }
-function assertShouldOmitEmbeddedItemsAllowed(category, shouldOmitEmbeddedItems) {
-	if (!shouldOmitEmbeddedItems || category == null) return;
-	const categories = typeof category === "string" ? [category] : category;
-	for (const possibleCategory of categories) if (!isItemCategoryWithEmbeddedItems(possibleCategory)) throw new Error(`shouldOmitEmbeddedItems can only be used when the item category contains embedded items; received category "${possibleCategory}"`);
-}
 function buildOmitEmbeddedItemsXQuery(uuid, category) {
 	const collectionCategories = [];
 	const categories = category == null ? [
@@ -106,25 +101,39 @@ async function fetchItem(uuid, options) {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		assertItemCategoryAllowed(options?.category, options?.containedItemCategory);
 		const shouldOmitEmbeddedItems = options?.shouldOmitEmbeddedItems === true;
-		assertShouldOmitEmbeddedItemsAllowed(options?.category, shouldOmitEmbeddedItems);
+		let shouldFetchOmittedEmbeddedItems = shouldOmitEmbeddedItems;
 		let omitEmbeddedItemsCategory;
-		if (options?.category != null) if (typeof options.category === "string") {
-			if (isItemCategoryWithEmbeddedItems(options.category)) omitEmbeddedItemsCategory = options.category;
-		} else {
+		if (options?.category != null) if (typeof options.category === "string") if (isItemCategoryWithEmbeddedItems(options.category)) omitEmbeddedItemsCategory = options.category;
+		else shouldFetchOmittedEmbeddedItems = false;
+		else {
 			const categories = [];
 			for (const possibleCategory of options.category) if (isItemCategoryWithEmbeddedItems(possibleCategory)) categories.push(possibleCategory);
 			omitEmbeddedItemsCategory = categories;
+			shouldFetchOmittedEmbeddedItems = categories.length > 0;
 		}
 		const languages = options?.languages == null ? [] : parseLanguages(options.languages);
 		const fetcher = options?.fetch ?? fetch;
-		const response = shouldOmitEmbeddedItems ? await fetcher("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
+		const regularItemUrl = `https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&xsl=none&lang="*"`;
+		let response = shouldFetchOmittedEmbeddedItems ? await fetcher("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
 			method: "POST",
 			body: buildOmitEmbeddedItemsXQuery(parsedUuid, omitEmbeddedItemsCategory),
 			headers: { "Content-Type": "application/xquery" }
-		}) : await fetcher(`https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&xsl=none&lang="*"`);
+		}) : await fetcher(regularItemUrl);
 		if (!response.ok) throw new Error("Failed to fetch OCHRE data", { cause: response.statusText });
 		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
+		const parser = new XMLParser(XML_PARSER_OPTIONS);
+		let data = parser.parse(dataRaw);
+		if (shouldFetchOmittedEmbeddedItems && typeof data === "object" && data != null && "result" in data) {
+			const result = data.result;
+			if (typeof result === "object" && result != null && "ochre" in result) {
+				const ochre = result.ochre;
+				if (typeof ochre === "object" && ochre != null && (Object.keys(ochre).length === 0 || "payload" in ochre && ochre.payload === "" && Object.keys(ochre).length === 1)) {
+					response = await fetcher(regularItemUrl);
+					if (!response.ok) throw new Error("Failed to fetch OCHRE data", { cause: response.statusText });
+					data = parser.parse(await response.text());
+				}
+			}
+		}
 		const { success, issues, output } = v.safeParse(XMLData, data);
 		if (!success) throw createSchemaValidationError("Failed to parse OCHRE data", issues);
 		restoreXMLMetadata(output, data);
@@ -135,7 +144,6 @@ async function fetchItem(uuid, options) {
 			parseResourceView: (view, context) => parseWebpageView(view, { languages: context.metadata.languages }, context)
 		});
 		assertItemCategoryAllowed(parsedItem.category, options?.containedItemCategory);
-		assertShouldOmitEmbeddedItemsAllowed(parsedItem.category, shouldOmitEmbeddedItems);
 		return {
 			item: shouldOmitEmbeddedItems && isItemWithEmbeddedItems(parsedItem) ? omitEmbeddedItems(parsedItem) : parsedItem,
 			error: null,

package/dist/parsers/string.mjs

@@ -12,7 +12,7 @@ const ITEM_PAGE_TOKEN = "item-page";
 const ENTRY_PAGE_TOKEN = "entry-page";
 const VARIANT_TOKEN = "variant";
 const HEADING_LEVEL_TOKEN = "heading-level";
-const RAW_MDX_BLOCK_DELIMITER = "```***```";
+const RAW_MDX_BLOCK_DELIMITER = "``md``";
 const RAW_MDX_BLOCK_PLACEHOLDER_PREFIX = "\0raw-mdx-block:";
 const RAW_MDX_BLOCK_PLACEHOLDER_SUFFIX = "\0";
 const MDX_QUOTED_ATTRIBUTE_ESCAPE_REGEX = /[\n\r"]/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -67,7 +67,7 @@
     }
   },
   "dependencies": {
-    "date-fns": "^4.3.0",
+    "date-fns": "^4.4.0",
     "fast-equals": "^6.0.0",
     "fast-xml-parser": "^5.8.0",
     "valibot": "^1.4.1"
@@ -76,8 +76,8 @@
     "@antfu/eslint-config": "^9.0.0",
     "@types/node": "^24.12.4",
     "bumpp": "^11.1.0",
-    "eslint": "^10.4.0",
-    "knip": "^6.14.2",
+    "eslint": "^10.4.1",
+    "knip": "^6.15.0",
     "prettier": "^3.8.3",
     "tsdown": "^0.22.1",
     "typescript": "^6.0.3",