ochre-sdk 1.0.78 → 1.1.0

package/dist/xml/schemas.mjs

@@ -1,4 +1,5 @@
-import { isPseudoUuid } from "../utilities.mjs";
+import { readArrayProperty } from "../reflection.mjs";
+import { isPseudoUuid } from "../schemas.mjs";
 import { parseDateTime } from "./dates.mjs";
 import * as v from "valibot";
 //#region src/xml/schemas.ts
@@ -47,13 +48,20 @@ const XMLRichTextEnvelope = {
 	properties: v.optional(v.object({ property: v.array(v.lazy(() => XMLProperty), "XMLRichTextEnvelope: properties is array of XMLProperty") })),
 	annotation: v.optional(v.string("XMLRichTextEnvelope: annotation is string and optional"))
 };
-const XMLString = v.lazy(() => v.object({
+/**
+* The entries every string-like OCHRE element carries
+*
+* Spread rather than re-listed by the shapes that embed a string envelope, so
+* a shape cannot declare the envelope in its type and forget to validate it.
+*/
+const XMLStringEntries = {
 	payload: v.optional(v.string("XMLString: payload is string and optional")),
 	rend: v.optional(v.string("XMLString: rend is string and optional")),
 	whitespace: v.optional(v.string("XMLString: whitespace is string and optional")),
 	...XMLRichTextEnvelope,
-	string: v.optional(v.array(XMLString, "XMLString: string is array of XMLString"))
-}, "XMLString: Shape error"));
+	string: v.optional(v.array(v.lazy(() => XMLString), "XMLString: string is array of XMLString"))
+};
+const XMLString = v.object(XMLStringEntries, "XMLString: Shape error");
 const XMLContent = v.object({ content: v.array(v.object({
 	string: v.array(XMLString),
 	title: v.optional(v.string("XMLContent: title is string and optional")),
@@ -110,6 +118,7 @@ const XMLMetadata = v.object({
 	}, "XMLMetadata: item is object with identification, category, type, and maxLength"))
 });
 const XMLLicense = v.object({
+	...XMLStringEntries,
 	payload: v.string("XMLLicense: payload is string and required"),
 	target: v.optional(v.pipe(v.string("XMLLicense: target is string and optional"), v.url("XMLLicense: target is not a valid URL")))
 }, "XMLLicense: Shape error");
@@ -225,10 +234,8 @@ const XMLImageMap = v.object({
 	height: XMLNumber
 }, "XMLImageMap: Shape error");
 const XMLNote = v.object({
+	...XMLStringEntries,
 	content: v.optional(XMLContent.entries.content),
-	payload: v.optional(v.string("XMLNote: payload is string and optional")),
-	rend: v.optional(v.string("XMLNote: rend is string and optional")),
-	whitespace: v.optional(v.string("XMLNote: whitespace is string and optional")),
 	noteNo: XMLOptionalNumber,
 	title: v.optional(v.string("XMLNote: title is string and optional")),
 	date: v.optional(customDateTime("XMLNote: date is not a valid datetime")),
@@ -263,34 +270,15 @@ const XMLProperty = v.lazy(() => v.object({
 	comment: v.optional(XMLContent),
 	property: v.optional(v.array(XMLProperty, "XMLProperty: property is array of XMLProperty"))
 }, "XMLProperty: Shape error"));
-const XMLSimplifiedProperty = v.lazy(() => v.object({
-	label: v.intersect([v.union([XMLContent, XMLString]), v.object({
-		uuid: v.union([v.literal(""), v.pipe(v.string("XMLSimplifiedProperty: uuid is string and required"), v.check(isPseudoUuid, "XMLSimplifiedProperty: uuid is not a valid pseudo-UUID"))], "XMLSimplifiedProperty: uuid is string and required"),
-		publicationDateTime: v.optional(customDateTime("XMLSimplifiedProperty: publicationDateTime is not a valid datetime")),
-		relation: v.optional(XMLPropertyRelation)
-	}, "XMLSimplifiedProperty: label is object with uuid")]),
-	value: v.optional(v.array(v.object({
-		...v.partial(XMLContent).entries,
-		i: XMLOptionalNumber,
-		inherited: v.optional(XMLBoolean),
-		uuid: v.optional(v.union([v.literal(""), v.pipe(v.string("XMLSimplifiedProperty: uuid is string and optional"), v.check(isPseudoUuid, "XMLSimplifiedProperty: uuid is not a valid pseudo-UUID"))])),
-		publicationDateTime: v.optional(customDateTime("XMLSimplifiedProperty: publicationDateTime is not a valid datetime")),
-		dataType: v.optional(v.string("XMLSimplifiedProperty: dataType is string and optional")),
-		category: v.optional(v.string("XMLSimplifiedProperty: category is string and optional")),
-		type: v.optional(v.string("XMLSimplifiedProperty: type is string and optional")),
-		slug: v.optional(v.string("XMLSimplifiedProperty: slug is string and optional")),
-		unit: v.optional(v.string("XMLSimplifiedProperty: unit is string and optional")),
-		height: XMLOptionalNumber,
-		width: XMLOptionalNumber,
-		fileSize: XMLOptionalNumber,
-		rawValue: v.optional(v.string("XMLSimplifiedProperty: rawValue is string and optional")),
-		isUncertain: v.optional(v.literal("true", "XMLSimplifiedProperty: isUncertain is true")),
-		href: v.optional(v.string("XMLSimplifiedProperty: href is string and optional")),
-		payload: v.optional(v.string("XMLSimplifiedProperty: payload is string"))
-	}), "XMLSimplifiedProperty: value is array of objects with payload")),
-	comment: v.optional(XMLContent),
-	property: v.optional(v.array(XMLSimplifiedProperty, "XMLSimplifiedProperty: property is array of XMLSimplifiedProperty"))
-}, "XMLSimplifiedProperty: Shape error"));
+/**
+* The raw shape of a simplified property
+*
+* Identical to {@link XMLProperty}: OCHRE serves one shape, and the
+* "simplified" distinction is a parsing choice, not a wire-format one. The
+* parser decides whether a label becomes a multilingual string or a plain
+* string; nothing about the XML differs.
+*/
+const XMLSimplifiedProperty = XMLProperty;
 const XMLBaseItem = v.object({
 	uuid: v.pipe(v.string("XMLBaseItem: uuid is string and required"), v.check(isPseudoUuid, "XMLBaseItem: uuid is not a valid pseudo-UUID")),
 	publicationDateTime: v.optional(customDateTime("XMLBaseItem: publicationDateTime is not a valid datetime")),
@@ -418,6 +406,7 @@ const XMLHeading = v.intersect([v.object({
 ])]);
 const XMLTree = v.object({
 	...XMLBaseItem.entries,
+	type: v.optional(v.string("XMLTree: type is string and optional")),
 	date: v.optional(v.union([customDateTime("XMLTree: date is not a valid datetime"), XMLString])),
 	links: v.optional(v.lazy(() => XMLLink)),
 	reverseLinks: v.optional(v.union([
@@ -532,6 +521,7 @@ const XMLInterpretation = v.object({
 }, "XMLInterpretation: Shape error");
 const XMLConcept = v.object({
 	...XMLBaseItem.entries,
+	status: v.optional(v.literal("live", "XMLConcept: status is live")),
 	image: v.optional(XMLImage),
 	interpretations: v.optional(v.object({ interpretation: v.array(XMLInterpretation) })),
 	interpretation: v.optional(v.array(XMLInterpretation)),
@@ -825,6 +815,11 @@ const XMLWebsiteTree = v.lazy(() => v.object({
 	type: v.optional(v.string("XMLWebsiteTree: type is string and optional")),
 	date: v.optional(v.union([customDateTime("XMLWebsiteTree: date is not a valid datetime"), XMLString])),
 	links: v.optional(v.lazy(() => XMLLink)),
+	reverseLinks: v.optional(v.union([
+		v.lazy(() => XMLLink),
+		v.lazy(() => XMLDataItem),
+		v.array(v.union([v.lazy(() => XMLLink), v.lazy(() => XMLDataItem)]))
+	])),
 	notes: v.optional(v.object({ note: v.array(XMLNote) })),
 	bibliographies: v.optional(v.object({ bibliography: v.array(v.lazy(() => XMLBibliography)) })),
 	options: v.optional(XMLWebsiteOptions),
@@ -847,20 +842,23 @@ const XMLDataItem = v.union([
 	v.object({ text: v.array(XMLText) }, "XMLDataItem: text is array of XMLText"),
 	v.object({ set: v.array(XMLSet) }, "XMLDataItem: set is array of XMLSet")
 ], "XMLDataItem: Shape error");
-function hasNestedRecursiveChildren(items, getChildren) {
-	for (const item of items) {
-		const children = getChildren(item) ?? [];
-		for (const child of children) if ((getChildren(child)?.length ?? 0) > 0) return true;
-	}
+/**
+* Whether any child of these items has children of its own
+*
+* Driven by the child element's name rather than an accessor, so the check does
+* not have to name a declared element type and cannot drift from one.
+*/
+function hasNestedRecursiveChildren(items, childKey) {
+	for (const item of items) for (const child of readArrayProperty(item, childKey)) if (readArrayProperty(child, childKey).length > 0) return true;
 	return false;
 }
 const XMLTopLevelDataItem = v.pipe(XMLDataItem, v.check((dataItem) => {
 	if ("tree" in dataItem) return true;
-	if ("bibliography" in dataItem && hasNestedRecursiveChildren(dataItem.bibliography, (item) => item.bibliography)) return false;
-	if ("concept" in dataItem && hasNestedRecursiveChildren(dataItem.concept, (item) => item.concept)) return false;
-	if ("spatialUnit" in dataItem && hasNestedRecursiveChildren(dataItem.spatialUnit, (item) => item.spatialUnit)) return false;
-	if ("period" in dataItem && hasNestedRecursiveChildren(dataItem.period, (item) => item.period)) return false;
-	if ("resource" in dataItem && hasNestedRecursiveChildren(dataItem.resource, (item) => item.resource)) return false;
+	if ("bibliography" in dataItem && hasNestedRecursiveChildren(dataItem.bibliography, "bibliography")) return false;
+	if ("concept" in dataItem && hasNestedRecursiveChildren(dataItem.concept, "concept")) return false;
+	if ("spatialUnit" in dataItem && hasNestedRecursiveChildren(dataItem.spatialUnit, "spatialUnit")) return false;
+	if ("period" in dataItem && hasNestedRecursiveChildren(dataItem.period, "period")) return false;
+	if ("resource" in dataItem && hasNestedRecursiveChildren(dataItem.resource, "resource")) return false;
 	return true;
 }, "XMLDataItem: standalone recursive item children cannot contain nested recursive children"));
 const XMLItemLinks = v.object({

package/dist/xml/types.d.mts

@@ -1,6 +1,7 @@
-//#region src/xml/types.d.ts
+declare namespace types_d_exports {
+  export { XMLBaseItem, XMLBibliography, XMLConcept, XMLContent, XMLContext, XMLContextGroup, XMLContextItem, XMLContextValue, XMLCoordinate, XMLCoordinates, XMLCoordinatesSource, XMLData, XMLDataItem, XMLDictionaryUnit, XMLEmptyContext, XMLEvent, XMLGallery, XMLGalleryData, XMLHeading, XMLIdentification, XMLImage, XMLImageMap, XMLImageMapArea, XMLInterpretation, XMLItemCategory, XMLItemLinks, XMLItemLinksData, XMLLicense, XMLLink, XMLLinkedBaseItem, XMLLinkedBibliography, XMLLinkedConcept, XMLLinkedPeriod, XMLLinkedPerson, XMLLinkedPropertyValue, XMLLinkedPropertyVariable, XMLLinkedResource, XMLLinkedSet, XMLLinkedSpatialUnit, XMLLinkedText, XMLLinkedTree, XMLMetadata, XMLNote, XMLObservation, XMLPeriod, XMLPerson, XMLProperty, XMLPropertyRelation, XMLPropertyValue, XMLPropertyVariable, XMLRecursiveItemCategory, XMLResource, XMLRichTextEnvelope, XMLSection, XMLSet, XMLSetItems, XMLSetItemsData, XMLSimplifiedProperty, XMLSpatialUnit, XMLString, XMLText, XMLTree, XMLWebsiteContext, XMLWebsiteContextItem, XMLWebsiteContextLevel, XMLWebsiteData, XMLWebsiteFilterContext, XMLWebsiteFilterContextItem, XMLWebsiteOptions, XMLWebsiteProperties, XMLWebsiteResource, XMLWebsiteResourceGroup, XMLWebsiteResourceItem, XMLWebsiteScope, XMLWebsiteSegment, XMLWebsiteStyle, XMLWebsiteTree };
+}
 export type XMLItemCategory = "tree" | "bibliography" | "spatialUnit" | "concept" | "period" | "person" | "propertyVariable" | "variable" | "propertyValue" | "value" | "text" | "resource" | "set";
-export type XMLHeadingItemCategory = Exclude<XMLItemCategory, "tree" | "bibliography" | "spatialUnit" | "concept" | "period">;
 export type XMLRecursiveItemCategory = Exclude<XMLItemCategory, "tree" | "person" | "propertyVariable" | "propertyValue" | "set">;
 /**
  * Rich text envelope shared by `<string>` and `<content>` nodes, carrying the
@@ -183,6 +184,7 @@ export type XMLImageMap = {
 export type XMLNote = Partial<XMLContent> & XMLString & {
   noteNo?: number;
   title?: string;
+  date?: Date;
   authors?: {
     author: Array<XMLPerson>;
   };
@@ -215,33 +217,13 @@ export type XMLProperty = {
   comment?: XMLContent;
   property?: Array<XMLProperty>;
 };
-export type XMLSimplifiedProperty = {
-  label: (XMLContent | XMLString) & {
-    uuid: string;
-    publicationDateTime?: Date;
-    relation?: XMLPropertyRelation;
-  };
-  value?: Array<Partial<XMLContent> & {
-    i?: number;
-    inherited?: boolean;
-    uuid?: string;
-    publicationDateTime?: Date;
-    dataType?: string;
-    category?: string;
-    type?: string;
-    slug?: string;
-    unit?: string;
-    height?: number;
-    width?: number;
-    fileSize?: number;
-    href?: string;
-    rawValue?: string;
-    isUncertain?: "true";
-    payload?: string;
-  }>;
-  comment?: XMLContent;
-  property?: Array<XMLSimplifiedProperty>;
-};
+/**
+ * The raw shape of a simplified property
+ *
+ * Identical to {@link XMLProperty}: the "simplified" distinction is a parsing
+ * choice, not a wire-format one.
+ */
+export type XMLSimplifiedProperty = XMLProperty;
 export type XMLBaseItem = {
   uuid: string;
   publicationDateTime?: Date;
@@ -919,4 +901,5 @@ export type XMLWebsiteData = {
     };
   };
 };
-//#endregion
+//#endregion
+export { types_d_exports };

package/dist/xquery.d.mts

@@ -0,0 +1,46 @@
+//#region src/xquery.d.ts
+/**
+ * Build a string literal for an XQuery string
+ * @param value - The string value to escape
+ * @returns The escaped string literal
+ * @internal
+ */
+export declare function stringLiteral(value: string): string;
+/**
+ * What a query body can ask the surrounding document for
+ *
+ * Handed to the body rather than imported by it, so a body cannot reference a
+ * prolog declaration the document did not emit.
+ */
+export type OchreQueryContext = {
+  /**
+   * Wrap a node expression so supplemental nodes are omitted from it
+   * @param expression - The XQuery expression returning the nodes to filter
+   * @returns The wrapped XQuery expression
+   */
+  omitSupplemental: (expression: string) => string;
+  /**
+   * An XQuery predicate keeping only nodes that are neither supplemental
+   * themselves nor nested inside a supplemental node. Use it when aggregating
+   * over nodes instead of returning them.
+   */
+  notSupplemental: string;
+};
+/**
+ * Compile a complete XQuery document for the OCHRE API
+ *
+ * Owns the version declaration, the prolog ordering, and the
+ * supplemental-stripping helper. The body receives what it is allowed to call,
+ * so the helper cannot be invoked without having been declared, and every
+ * fetcher stops restating the same preamble.
+ * @param parameters - The document parameters
+ * @param parameters.declarations - Prolog declarations, emitted in order before the supplemental helper
+ * @param parameters.body - Builds the query body
+ * @returns A complete XQuery document
+ * @internal
+ */
+export declare function compileOchreQuery(parameters: {
+  declarations?: ReadonlyArray<string>;
+  body: (context: OchreQueryContext) => string;
+}): string;
+//#endregion

package/dist/xquery.mjs

@@ -0,0 +1,66 @@
+//#region src/xquery.ts
+/**
+* Build a string literal for an XQuery string
+* @param value - The string value to escape
+* @returns The escaped string literal
+* @internal
+*/
+function stringLiteral(value) {
+	return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+/**
+* XQuery prolog declaring `local:omit-supplemental`, which drops every element
+* carrying `supplemental="true"` from a node sequence, at any depth.
+*
+* Subtrees without a supplemental descendant are returned by reference, so
+* nodes are only copied along the path leading to an omitted element. The
+* lookahead walks the attribute axis (`//@supplemental`) rather than testing
+* every element, which measures around three times faster on large documents.
+*
+* Private on purpose: it is only correct when it precedes a body that calls it,
+* and {@link compileOchreQuery} is the only thing that can guarantee that.
+*/
+const SUPPLEMENTAL_XQUERY_PROLOG = `declare function local:omit-supplemental($nodes as node()*) as node()* {
+  for $node in $nodes
+  return
+    if ($node instance of element())
+    then
+      if ($node/@supplemental = "true")
+      then ()
+      else if (empty($node//@supplemental[. = "true"]))
+      then $node
+      else element { node-name($node) } {
+        $node/@*,
+        local:omit-supplemental($node/node())
+      }
+    else $node
+};`;
+const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
+/**
+* Compile a complete XQuery document for the OCHRE API
+*
+* Owns the version declaration, the prolog ordering, and the
+* supplemental-stripping helper. The body receives what it is allowed to call,
+* so the helper cannot be invoked without having been declared, and every
+* fetcher stops restating the same preamble.
+* @param parameters - The document parameters
+* @param parameters.declarations - Prolog declarations, emitted in order before the supplemental helper
+* @param parameters.body - Builds the query body
+* @returns A complete XQuery document
+* @internal
+*/
+function compileOchreQuery(parameters) {
+	const { declarations = [], body } = parameters;
+	return `${[
+		"xquery version \"1.0-ml\";",
+		...declarations,
+		SUPPLEMENTAL_XQUERY_PROLOG
+	].join("\n\n")}
+
+${body({
+		omitSupplemental: (expression) => `local:omit-supplemental(${expression})`,
+		notSupplemental: NOT_SUPPLEMENTAL_PREDICATE
+	})}`;
+}
+//#endregion
+export { compileOchreQuery, stringLiteral };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.78",
+  "version": "1.1.0",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -66,8 +66,8 @@
   "scripts": {
     "dev": "tsdown src/index.ts --watch",
     "build": "tsdown",
-    "lint": "knip; eslint --concurrency auto .",
-    "lint:fix": "knip --fix; eslint --concurrency auto --fix .",
+    "lint": "knip && eslint --concurrency auto .",
+    "lint:fix": "knip --fix && eslint --concurrency auto --fix .",
     "format": "oxfmt --check",
     "format:fix": "oxfmt",
     "check-types": "tsc --noEmit",

package/dist/utilities.d.mts

@@ -1,54 +0,0 @@
-import { LanguageCodes, Property, SetItemProperty } from "./types/index.mjs";
-import * as v from "valibot";
-//#region src/utilities.d.ts
-type SchemaValidationIssue = v.BaseIssue<unknown>;
-export declare function getErrorOutput(error: unknown, fallbackMessage: string): {
-  error: string;
-  detailedError: string;
-};
-export declare function createSchemaValidationError(message: string, issues: ReadonlyArray<SchemaValidationIssue>): Error;
-/**
- * Validates a pseudo-UUID string
- * @param value - The string to validate
- * @returns True if the string is a valid pseudo-UUID, false otherwise
- * @internal
- */
-export declare function isPseudoUuid(value: string): boolean;
-/**
- * Build a string literal for an XQuery string
- * @param value - The string value to escape
- * @returns The escaped string literal
- */
-export declare function stringLiteral(value: string): string;
-/**
- * XQuery prolog declaring `local:omit-supplemental`, which drops every element
- * carrying `supplemental="true"` from a node sequence, at any depth.
- *
- * Subtrees without a supplemental descendant are returned by reference, so
- * nodes are only copied along the path leading to an omitted element. The
- * lookahead walks the attribute axis (`//@supplemental`) rather than testing
- * every element, which measures around three times faster on large documents.
- *
- * Must be declared before any query body that calls {@link omitSupplemental}.
- */
-export declare const SUPPLEMENTAL_XQUERY_PROLOG = "declare function local:omit-supplemental($nodes as node()*) as node()* {\n  for $node in $nodes\n  return\n    if ($node instance of element())\n    then\n      if ($node/@supplemental = \"true\")\n      then ()\n      else if (empty($node//@supplemental[. = \"true\"]))\n      then $node\n      else element { node-name($node) } {\n        $node/@*,\n        local:omit-supplemental($node/node())\n      }\n    else $node\n};";
-/**
- * Wrap an XQuery node expression so supplemental nodes are omitted from it
- * @param expression - The XQuery expression returning the nodes to filter
- * @returns The wrapped XQuery expression
- */
-export declare function omitSupplemental(expression: string): string;
-/**
- * XQuery predicate keeping only nodes that are neither supplemental themselves
- * nor nested inside a supplemental node. Use it when aggregating over nodes
- * instead of returning them.
- */
-export declare const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
-/**
- * Flatten a properties array
- * @param properties - The properties to flatten
- * @returns The flattened properties
- * @internal
- */
-export declare function flattenProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T> | SetItemProperty<T>>): Array<SetItemProperty<T>>;
-//#endregion