ochre-sdk 1.3.5 → 1.3.7

package/README.md

@@ -100,11 +100,14 @@ title.isEmpty();
 title.hasContent();
 title.hasLanguage("tur");
 title.hasAliases();
+title.isNonLinguistic();
 
 title.getAvailableLanguages(); // languages that carry content
 title.getSupportedLanguages(); // languages the string was built to hold
 ```
 
+OCHRE publishes `zxx` content in two senses, and the string tells them apart by the only thing that distinguishes them: whether another language stands beside it. Beside a field's languages, `zxx` content names the same thing again, so it is read as aliases (`getAliases()`). Standing alone, it is the text itself in no language, such as an identifier, so it is read as non-linguistic text: `isNonLinguistic()` is true, every language reads it through `getText`, and it has no aliases. Every string, however it is built or edited, follows the same rule, so adding a language to a non-linguistic string turns its text into aliases, as the same content would be read.
+
 Writes return a new string and never mutate the original.
 
 ```ts
@@ -129,6 +132,20 @@ const languages = defineLanguages("eng", "tur");
 const result = await fetchWebsite("uchicago-node", { languages });
 ```
 
+## Language Codes
+
+OCHRE publishes ISO 639-2 language codes in their bibliographic (B) form, the Library of Congress MARC convention, and every language the SDK reads or accepts uses them: `per` for Persian, not ISO 639-3 `fas`, and likewise `fre`, `chi` and `ger`. There are three exceptions: the ISO 639-3 identifier where ISO 639-2 has no code (`yua`, `lzh`), the terminology (T) form for Dutch (`nld`, not `dut`), and a few codes of OCHRE's own for transliterations and vocabularies (`ota-xlt`, `rel`), some of which collide with unrelated ISO 639-3 languages. Requests in any other code are rejected, with the OCHRE code to use when one exists.
+
+`OCHRE_LANGUAGES` maps every code OCHRE publishes to its name, what it tags (a `language`, a `transliteration`, a `vocabulary` or `non-linguistic` content), the standard the code itself is taken from (`iso639-2b`, or one of the exceptions: `iso639-3`, `iso639-2t`, `bcp47` or `ochre`), its ISO 639-3 identifier and the BCP 47 tag to give `Intl` or an HTML `lang` attribute. Either standard is `null` when none fits.
+
+```ts
+import { getOchreLanguage, getOchreLanguageCode } from "ochre-sdk";
+
+getOchreLanguage("per"); // { name: "Persian", kind: "language", standard: "iso639-2b", iso639_3: "fas", bcp47: "fa" }
+getOchreLanguage("ota-xlt")?.bcp47; // "ota-Latn-t-ota-arab"
+getOchreLanguageCode("fas"); // "per"
+```
+
 ## Set Queries
 
 Set fetchers accept a recursive `Query` tree. Leaf queries can target full text,

package/dist/index.d.mts

@@ -15,5 +15,6 @@ import { fetchWebsiteMetadata } from "./fetchers/website-metadata.mjs";
 import { fetchWebsite } from "./fetchers/website.mjs";
 import { PropertyOptions, PropertySelector, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
 import { flattenItemProperties } from "./helpers.mjs";
+import { OCHRE_LANGUAGES, OchreLanguage, OchreLanguageCode, OchreLanguageKind, OchreLanguageStandard, getOchreLanguage, getOchreLanguageCode, isOchreLanguageCode } from "./languages.mjs";
 import { defineLanguages } from "./parsers/languages.mjs";
-export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeFilterVariant, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemCategoryFromOption, type ItemCategoryOption, type ItemCategoryWithEmbeddedItems, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, type Observation, type OcrString, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, type PropertyOptions, type PropertyRelation, type PropertySelector, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type ProtectedWebsite, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type ResponsiveStyles, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemLocation, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetStyle, type SetStyleProperty, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebIiifViewer, type WebImage, type WebLoadingVariant, type WebOptions, type WebRelationVariant, type WebSectionDisplay, type WebSectionVariant, type WebSidebar, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePrivacy, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItemLocations, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };
+export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeFilterVariant, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemCategoryFromOption, type ItemCategoryOption, type ItemCategoryWithEmbeddedItems, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, OCHRE_LANGUAGES, type Observation, type OchreLanguage, type OchreLanguageCode, type OchreLanguageKind, type OchreLanguageStandard, type OcrString, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, type PropertyOptions, type PropertyRelation, type PropertySelector, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type ProtectedWebsite, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type ResponsiveStyles, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemLocation, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetStyle, type SetStyleProperty, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebIiifViewer, type WebImage, type WebLoadingVariant, type WebOptions, type WebRelationVariant, type WebSectionDisplay, type WebSectionVariant, type WebSidebar, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePrivacy, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItemLocations, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getOchreLanguage, getOchreLanguageCode, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isOchreLanguageCode, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/index.mjs

@@ -2,6 +2,7 @@ import { DEFAULT_PAGE_SIZE } from "./constants.mjs";
 import { getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
 import { flattenItemProperties } from "./helpers.mjs";
 import { MultilingualString } from "./parsers/multilingual.mjs";
+import { OCHRE_LANGUAGES, getOchreLanguage, getOchreLanguageCode, isOchreLanguageCode } from "./languages.mjs";
 import { defineLanguages } from "./parsers/languages.mjs";
 import { fetchGallery } from "./fetchers/gallery.mjs";
 import { fetchItemChildren } from "./fetchers/item-children.mjs";
@@ -14,4 +15,4 @@ import { fetchSetPropertyValues } from "./fetchers/set/property-values.mjs";
 import { fetchTreeItems } from "./fetchers/tree/items.mjs";
 import { fetchWebsiteMetadata } from "./fetchers/website-metadata.mjs";
 import { fetchWebsite } from "./fetchers/website.mjs";
-export { DEFAULT_PAGE_SIZE, MultilingualString, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItemLocations, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };
+export { DEFAULT_PAGE_SIZE, MultilingualString, OCHRE_LANGUAGES, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItemLocations, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getOchreLanguage, getOchreLanguageCode, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isOchreLanguageCode, isPropertyMatchingFilter, normalizePropertyVariableLabel };