ochre-sdk 1.0.12 → 1.0.13

package/README.md

@@ -47,7 +47,9 @@ present and `error` is `null`; on failure, the parsed value is `null` and
 
 - `fetchItem(uuid, options)` fetches and parses a single OCHRE item. Passing
   `category` narrows the returned TypeScript type, and `containedItemCategory`
-  controls how nested Tree or Set contents are parsed.
+  controls how nested Tree or Set contents are parsed. For large Trees or Sets,
+  pass `shouldOmitEmbeddedItems: true` to fetch the top-level item without its
+  embedded `<items>` payload.
 - `fetchItemLinks(uuid, options)` fetches items linked from a source item and
   parses them as embedded OCHRE items.
 - `fetchGallery(params, options)` fetches paginated resource galleries with an

package/dist/index.d.mts

@@ -1129,6 +1129,10 @@ type ItemLink<U extends ItemLinkCategory = ItemLinkCategory, T extends LanguageC
  * An Item in OCHRE (can be a tree, set, bibliography, concept, spatial unit, period, person, property value, property variable, or resource)
  */
 type Item<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel"> = U extends ItemCategory ? U extends "tree" ? Tree<Extract<V, TreeItemCategory>, T, W> : U extends "set" ? Set<Extract<V, SetItemCategory>, T, W> : U extends "bibliography" ? Bibliography<T, W> : U extends "concept" ? Concept<T, W> : U extends "spatialUnit" ? SpatialUnit<T, W> : U extends "period" ? Period<T, W> : U extends "person" ? Person<T, W> : U extends "propertyVariable" ? PropertyVariable<T, W> : U extends "propertyValue" ? PropertyValue<T, W> : U extends "resource" ? Resource<T, W> : U extends "text" ? Text<T, W> : never : never;
+/**
+ * A Tree or Set fetched without its embedded item hierarchy.
+ */
+type ItemWithoutEmbeddedItems<U extends ItemContainerCategory = ItemContainerCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel"> = U extends ItemContainerCategory ? U extends "tree" ? Prettify<Omit<Tree<Extract<V, TreeItemCategory>, T, W>, "items">> : U extends "set" ? Prettify<Omit<Set<Extract<V, SetItemCategory>, T, W>, "items">> : never : never;
 type TopLevelItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, "topLevel">;
 type EmbeddedItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, "embedded">;
 type AnyItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, ItemPayloadKind>;
@@ -1585,7 +1589,21 @@ type FetchItemBaseOptions<TLanguages extends ReadonlyArray<string> | undefined =
   languages?: TLanguages;
   fetch?: FetchFunction$2;
 };
+type FetchItemNoOmitEmbeddedItemsOption = {
+  shouldOmitEmbeddedItems?: false;
+};
 type FetchItemLanguages<TLanguages extends ReadonlyArray<string> | undefined> = TLanguages extends readonly [] ? ReadonlyArray<string> : TLanguages extends ReadonlyArray<string> ? TLanguages : ReadonlyArray<string>;
+type FetchItemSuccess<TItem> = {
+  item: TItem;
+  error: null;
+  detailedError: null;
+};
+type FetchItemError = {
+  item: null;
+  error: string;
+  detailedError: string;
+};
+type FetchItemResult<TItem> = Promise<FetchItemSuccess<TItem> | FetchItemError>;
 /**
  * Defines a reusable languages tuple with validation and literal type inference.
  *
@@ -1608,46 +1626,33 @@ declare function withLanguages<const TLanguages extends ReadonlyArray<string>>(l
  * @param options - Required options object
  * @param options.category - The category of the OCHRE item to fetch
  * @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 `<items>` node when fetching a Tree or Set.
  * @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
  */
-declare function fetchItem<const TContainedItemCategory extends ContainedItemCategoryOption<ItemContainerCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options?: FetchItemBaseOptions<TLanguages> & {
+declare function fetchItem<const TContainedItemCategory extends ContainedItemCategoryOption<ItemContainerCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options?: FetchItemBaseOptions<TLanguages> & FetchItemNoOmitEmbeddedItemsOption & {
   category?: undefined;
   containedItemCategory?: TContainedItemCategory;
-}): Promise<{
-  item: Item<ItemCategory, ContainedItemCategoryFromOption<ItemCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>;
-  error: null;
-  detailedError: null;
-} | {
-  item: null;
-  error: string;
-  detailedError: string;
-}>;
+}): FetchItemResult<Item<ItemCategory, ContainedItemCategoryFromOption<ItemCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>>;
+declare function fetchItem<const TContainedItemCategory extends ContainedItemCategoryOption<ItemContainerCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & {
+  category?: undefined;
+  containedItemCategory?: TContainedItemCategory;
+  shouldOmitEmbeddedItems: true;
+}): FetchItemResult<ItemWithoutEmbeddedItems<ItemContainerCategory, ContainedItemCategoryFromOption<ItemContainerCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>>;
+declare function fetchItem<const TCategory extends ItemContainerCategory, const TContainedItemCategory extends ContainedItemCategoryOption<TCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & FetchItemNoOmitEmbeddedItemsOption & {
+  category: TCategory;
+  containedItemCategory?: TContainedItemCategory;
+}): FetchItemResult<Item<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>>;
 declare function fetchItem<const TCategory extends ItemContainerCategory, const TContainedItemCategory extends ContainedItemCategoryOption<TCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & {
   category: TCategory;
   containedItemCategory?: TContainedItemCategory;
-}): Promise<{
-  item: Item<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>;
-  error: null;
-  detailedError: null;
-} | {
-  item: null;
-  error: string;
-  detailedError: string;
-}>;
-declare function fetchItem<const TCategory extends ItemCategory, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & {
+  shouldOmitEmbeddedItems: true;
+}): FetchItemResult<ItemWithoutEmbeddedItems<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>>;
+declare function fetchItem<const TCategory extends ItemCategory, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & FetchItemNoOmitEmbeddedItemsOption & {
   category: TCategory;
   containedItemCategory?: never;
-}): Promise<{
-  item: Item<TCategory, ContainedItemCategory<TCategory>, FetchItemLanguages<TLanguages>>;
-  error: null;
-  detailedError: null;
-} | {
-  item: null;
-  error: string;
-  detailedError: string;
-}>;
+}): FetchItemResult<Item<TCategory, ContainedItemCategory<TCategory>, FetchItemLanguages<TLanguages>>>;
 //#endregion
 //#region src/fetchers/set/items.d.ts
 type FetchFunction$1 = (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
@@ -1963,4 +1968,4 @@ declare const DEFAULT_PAGE_SIZE = 48;
  */
 declare function flattenItemProperties<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel">(item: Item<U, V, T, W>): FlattenedItem<Item<U, V, T, W>, T>;
 //#endregion
-export { AccordionWebBlock, AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, ContextTree, ContextTreeFilterLevel, ContextTreeLevel, ContextTreeLevelItem, Coordinates, CoordinatesSource, DEFAULT_PAGE_SIZE, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, LanguageCodes, License, Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, Note, Observation, Period, PeriodItemLink, Person, PersonItemLink, Property, PropertyLike, PropertyOptions, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Scope, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Style, StylesheetCategory, StylesheetItem, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink, WebBlock, WebBlockByLayout, WebBlockLayout, WebElement, WebElementComponent, WebElementComponentName, WebElementComponentOf, WebElementOf, WebImage, WebTitle, Webpage, Website, WebsitePropertyQuery, WebsitePropertyQueryNode, WebsiteSegment, WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemLinks, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels, withLanguages };
+export { AccordionWebBlock, AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, ContextTree, ContextTreeFilterLevel, ContextTreeLevel, ContextTreeLevelItem, Coordinates, CoordinatesSource, DEFAULT_PAGE_SIZE, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, Note, Observation, Period, PeriodItemLink, Person, PersonItemLink, Property, PropertyLike, PropertyOptions, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Scope, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Style, StylesheetCategory, StylesheetItem, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink, WebBlock, WebBlockByLayout, WebBlockLayout, WebElement, WebElementComponent, WebElementComponentName, WebElementComponentOf, WebElementOf, WebImage, WebTitle, Webpage, Website, WebsitePropertyQuery, WebsitePropertyQueryNode, WebsiteSegment, WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemLinks, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels, withLanguages };

package/dist/index.mjs

@@ -5484,10 +5484,17 @@ function parseWebsite(data, options) {
 function isItemContainerCategory(category) {
 	return category === "tree" || category === "set";
 }
+function isItemContainer(item) {
+	return isItemContainerCategory(item.category);
+}
 function assertItemCategoryAllowed(category, containedItemCategory) {
 	if (category == null || containedItemCategory == null || isItemContainerCategory(category)) return;
 	throw new Error(`containedItemCategory can only be used when category is "tree" or "set"; received category "${category}"`);
 }
+function assertShouldOmitEmbeddedItemsAllowed(category, shouldOmitEmbeddedItems) {
+	if (!shouldOmitEmbeddedItems || category == null || isItemContainerCategory(category)) return;
+	throw new Error(`shouldOmitEmbeddedItems can only be used when category is "tree" or "set"; received category "${category}"`);
+}
 function normalizeFetchedCategory(category) {
 	switch (category) {
 		case "tree":
@@ -5522,6 +5529,25 @@ function inferFetchItemCategory(rawOchre) {
 	if ("set" in rawOchre) return "set";
 	throw new Error("Could not infer OCHRE item category", { cause: rawOchre });
 }
+function buildOmitEmbeddedItemsXQuery(uuid) {
+	return `xquery version "1.0-ml";
+
+let $ochre := doc()/ochre[@uuid=${stringLiteral(uuid)}][1]
+return
+  if (empty($ochre)) then ()
+  else element ochre {
+    $ochre/@*,
+    for $node in $ochre/node()
+    return
+      if (local-name($node) = ("tree", "set"))
+      then element { node-name($node) } { $node/@*, $node/node()[not(self::items)] }
+      else $node
+  }`;
+}
+function omitEmbeddedItems(item) {
+	const { items: _items, ...itemWithoutEmbeddedItems } = item;
+	return itemWithoutEmbeddedItems;
+}
 /**
 * Validate language codes while preserving literal tuple inference.
 */
@@ -5553,8 +5579,15 @@ async function fetchItem(uuid, options) {
 	try {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		assertItemCategoryAllowed(options?.category, options?.containedItemCategory);
+		const shouldOmitEmbeddedItems = options?.shouldOmitEmbeddedItems === true;
+		assertShouldOmitEmbeddedItemsAllowed(options?.category, shouldOmitEmbeddedItems);
 		const languages = options?.languages == null ? [] : parseLanguages$1(options.languages);
-		const response = await (options?.fetch ?? fetch)(`https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&xsl=none&lang="*"`);
+		const fetcher = options?.fetch ?? fetch;
+		const response = shouldOmitEmbeddedItems ? await fetcher("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
+			method: "POST",
+			body: buildOmitEmbeddedItemsXQuery(parsedUuid),
+			headers: { "Content-Type": "application/xquery" }
+		}) : await fetcher(`https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&xsl=none&lang="*"`);
 		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);
@@ -5563,13 +5596,15 @@ async function fetchItem(uuid, options) {
 		restoreXMLMetadata(output, data);
 		const category = options?.category ?? inferFetchItemCategory(output.result.ochre);
 		assertItemCategoryAllowed(category, options?.containedItemCategory);
+		assertShouldOmitEmbeddedItemsAllowed(category, shouldOmitEmbeddedItems);
+		const parsedItem = parseItem(output, {
+			category,
+			containedItemCategory: options?.containedItemCategory,
+			languages,
+			parseResourceView: (view, context) => parseWebpageView(view, { languages: context.metadata.languages }, context)
+		});
 		return {
-			item: parseItem(output, {
-				category,
-				containedItemCategory: options?.containedItemCategory,
-				languages,
-				parseResourceView: (view, context) => parseWebpageView(view, { languages: context.metadata.languages }, context)
-			}),
+			item: shouldOmitEmbeddedItems && isItemContainer(parsedItem) ? omitEmbeddedItems(parsedItem) : parsedItem,
 			error: null,
 			detailedError: null
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",