ochre-sdk 1.0.78 → 1.1.0

package/dist/parsers/languages.d.mts

@@ -0,0 +1,72 @@
+import { XMLMetadata } from "../xml/types.mjs";
+//#region src/parsers/languages.d.ts
+/**
+ * Validate language codes while preserving literal tuple inference
+ * @param languages - The language codes to validate
+ * @returns The same tuple, with its literal types intact
+ * @internal
+ */
+export declare function parseLanguages<const T extends ReadonlyArray<string>>(languages: T): T;
+/**
+ * Define a reusable languages tuple with validation and literal type inference
+ *
+ * Inline arrays can be passed directly to a fetcher
+ * (`fetchItem(uuid, { languages: ["eng", "spa"] })`); use this when the
+ * language set is stored separately.
+ * @param languages - The language codes to validate
+ * @returns The same tuple, with its literal types intact
+ */
+export declare function defineLanguages<const TLanguages extends ReadonlyArray<string>>(...languages: TLanguages): TLanguages;
+/**
+ * Validate an optional caller-supplied language tuple
+ * @param languages - The language codes to validate, or undefined
+ * @returns The validated codes, or an empty array when none were requested
+ * @internal
+ */
+export declare function parseRequestedLanguages(languages: ReadonlyArray<string> | undefined): ReadonlyArray<string>;
+/**
+ * Resolve which languages to parse from the content of a payload
+ *
+ * Requested languages win. Otherwise every `content/@xml:lang` found anywhere
+ * beneath the node is used, falling back to {@link DEFAULT_LANGUAGES} when the
+ * payload carries no tagged content at all.
+ * @param node - The payload node to walk
+ * @param requestedLanguages - The languages the caller asked for
+ * @returns The languages to parse
+ * @internal
+ */
+export declare function resolveContentLanguages(node: unknown, requestedLanguages: ReadonlyArray<string>): ReadonlyArray<string>;
+/**
+ * Read the languages a dataset declares in its metadata
+ * @param rawOchre - The raw OCHRE payload root
+ * @param rawOchre.metadata - The payload metadata declaring the languages
+ * @param rawOchre.languages - The semicolon-separated fallback language list
+ * @returns The declared languages, falling back to {@link DEFAULT_LANGUAGES}
+ * @internal
+ */
+export declare function parseMetadataLanguages(rawOchre: {
+  metadata: XMLMetadata;
+  languages?: string;
+}): Array<string>;
+/**
+ * Reconcile requested languages against the ones a dataset declares
+ * @param requestedLanguages - The languages the caller asked for
+ * @param metadataLanguages - The languages the dataset declares
+ * @returns The languages to parse
+ * @throws When a requested language is not offered by the dataset
+ * @internal
+ */
+export declare function resolveLanguages<T extends ReadonlyArray<string>>(requestedLanguages: T | undefined, metadataLanguages: Array<string>): T;
+/**
+ * Pick the language a dataset treats as its default
+ * @param rawOchre - The raw OCHRE payload root
+ * @param rawOchre.metadata - The payload metadata declaring the default
+ * @param languages - The languages being parsed
+ * @returns The default language
+ * @throws When `languages` is empty
+ * @internal
+ */
+export declare function resolveDefaultLanguage<T extends ReadonlyArray<string>>(rawOchre: {
+  metadata: XMLMetadata;
+}, languages: T): T[number];
+//#endregion

package/dist/parsers/languages.mjs

@@ -0,0 +1,132 @@
+import { DEFAULT_LANGUAGES } from "../constants.mjs";
+import { readArrayProperty, readEntries } from "../reflection.mjs";
+import { iso639_3Schema } from "../schemas.mjs";
+import { parseStringLike } from "./helpers.mjs";
+import * as v from "valibot";
+//#region src/parsers/languages.ts
+/**
+* A content entry carrying a language tag
+*
+* A schema rather than a hand-written predicate, because this is exactly a
+* shape check: `v.is` narrows only what it has verified, and an array or a
+* `Date` cannot pass because neither carries a string `lang`.
+*/
+const languageTaggedContentSchema = v.looseObject({ lang: v.string() });
+/**
+* The language tag OCHRE uses for content that has no language
+*/
+const UNTAGGED_LANGUAGE = "zxx";
+function collectContentLanguages(value, languages) {
+	if (Array.isArray(value)) {
+		for (const item of value) collectContentLanguages(item, languages);
+		return;
+	}
+	for (const contentItem of readArrayProperty(value, "content")) if (v.is(languageTaggedContentSchema, contentItem) && contentItem.lang !== UNTAGGED_LANGUAGE) languages.add(contentItem.lang);
+	for (const [, child] of readEntries(value)) collectContentLanguages(child, languages);
+}
+/**
+* Validate language codes while preserving literal tuple inference
+* @param languages - The language codes to validate
+* @returns The same tuple, with its literal types intact
+* @internal
+*/
+function parseLanguages(languages) {
+	for (const language of languages) v.parse(iso639_3Schema, language);
+	return languages;
+}
+/**
+* Define a reusable languages tuple with validation and literal type inference
+*
+* Inline arrays can be passed directly to a fetcher
+* (`fetchItem(uuid, { languages: ["eng", "spa"] })`); use this when the
+* language set is stored separately.
+* @param languages - The language codes to validate
+* @returns The same tuple, with its literal types intact
+*/
+function defineLanguages(...languages) {
+	return parseLanguages(languages);
+}
+/**
+* Validate an optional caller-supplied language tuple
+* @param languages - The language codes to validate, or undefined
+* @returns The validated codes, or an empty array when none were requested
+* @internal
+*/
+function parseRequestedLanguages(languages) {
+	return languages == null ? [] : parseLanguages(languages);
+}
+/**
+* Resolve which languages to parse from the content of a payload
+*
+* Requested languages win. Otherwise every `content/@xml:lang` found anywhere
+* beneath the node is used, falling back to {@link DEFAULT_LANGUAGES} when the
+* payload carries no tagged content at all.
+* @param node - The payload node to walk
+* @param requestedLanguages - The languages the caller asked for
+* @returns The languages to parse
+* @internal
+*/
+function resolveContentLanguages(node, requestedLanguages) {
+	if (requestedLanguages.length > 0) return requestedLanguages;
+	const languages = /* @__PURE__ */ new Set();
+	collectContentLanguages(node, languages);
+	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
+}
+/**
+* Read the languages a dataset declares in its metadata
+* @param rawOchre - The raw OCHRE payload root
+* @param rawOchre.metadata - The payload metadata declaring the languages
+* @param rawOchre.languages - The semicolon-separated fallback language list
+* @returns The declared languages, falling back to {@link DEFAULT_LANGUAGES}
+* @internal
+*/
+function parseMetadataLanguages(rawOchre) {
+	const languages = [];
+	const metadataLanguages = rawOchre.metadata.language ?? [];
+	for (const language of metadataLanguages) {
+		const parsedLanguage = parseStringLike(language);
+		if (parsedLanguage != null) languages.push(parsedLanguage);
+	}
+	if (languages.length > 0) return languages;
+	if (rawOchre.languages != null) {
+		for (const language of rawOchre.languages.split(";")) if (language !== "") languages.push(language);
+	}
+	return languages.length > 0 ? languages : [...DEFAULT_LANGUAGES];
+}
+/**
+* Reconcile requested languages against the ones a dataset declares
+* @param requestedLanguages - The languages the caller asked for
+* @param metadataLanguages - The languages the dataset declares
+* @returns The languages to parse
+* @throws When a requested language is not offered by the dataset
+* @internal
+*/
+function resolveLanguages(requestedLanguages, metadataLanguages) {
+	if (requestedLanguages == null || requestedLanguages.length === 0) return metadataLanguages;
+	const unsupportedLanguages = [];
+	for (const requestedLanguage of requestedLanguages) if (!metadataLanguages.some((metadataLanguage) => metadataLanguage.toLocaleLowerCase("en-US") === requestedLanguage.toLocaleLowerCase("en-US"))) unsupportedLanguages.push(requestedLanguage);
+	if (unsupportedLanguages.length > 0) throw new Error(`The following language(s) are not supported by the dataset: ${unsupportedLanguages.toSorted((a, b) => a.localeCompare(b, "en-US")).join(", ")}. Available languages: ${metadataLanguages.toSorted((a, b) => a.localeCompare(b, "en-US")).join(", ")}`, { cause: unsupportedLanguages });
+	return requestedLanguages;
+}
+/**
+* Pick the language a dataset treats as its default
+* @param rawOchre - The raw OCHRE payload root
+* @param rawOchre.metadata - The payload metadata declaring the default
+* @param languages - The languages being parsed
+* @returns The default language
+* @throws When `languages` is empty
+* @internal
+*/
+function resolveDefaultLanguage(rawOchre, languages) {
+	const metadataLanguages = rawOchre.metadata.language ?? [];
+	for (const language of metadataLanguages) {
+		const parsedLanguage = parseStringLike(language);
+		if (parsedLanguage != null && language.default === "true" && languages.includes(parsedLanguage)) return parsedLanguage;
+	}
+	for (const language of languages) if (language === DEFAULT_LANGUAGES[0]) return language;
+	const firstLanguage = languages[0];
+	if (firstLanguage == null) throw new Error("Default language not found", { cause: languages });
+	return firstLanguage;
+}
+//#endregion
+export { defineLanguages, parseLanguages, parseMetadataLanguages, parseRequestedLanguages, resolveContentLanguages, resolveDefaultLanguage, resolveLanguages };

package/dist/parsers/multilingual.d.mts

@@ -19,6 +19,13 @@ export type MultilingualStringInput = string | {
 export type MultilingualStringJSON<T extends ReadonlyArray<string> = ReadonlyArray<string>> = {
   content: Partial<Record<T[number], Array<MultilingualStringEntry>>>;
   aliases: Array<string>;
+  /**
+   * The language reads fall back to first
+   *
+   * Optional so payloads written before it existed still parse; when absent the
+   * first available language is used, which is what the old shape implied.
+   */
+  defaultLanguage?: string;
 };
 export type MultilingualStringObject<T extends ReadonlyArray<string> = ReadonlyArray<string>> = Partial<Record<T[number], MultilingualStringInput>>;
 export type MultilingualStringEntries<T extends ReadonlyArray<string> = ReadonlyArray<string>> = Partial<Record<T[number], ReadonlyArray<MultilingualStringInput>>>;
@@ -90,109 +97,77 @@ export declare class MultilingualString<T extends ReadonlyArray<string> = Readon
   constructor(init: MultilingualStringInternalInit<T>);
   constructor(content: MultilingualStringObject<T>, languages: T, options?: MultilingualOptions);
   constructor(content?: Partial<Record<string, MultilingualStringInput>>, languages?: undefined, options?: MultilingualOptions);
-  private getPrimaryEntry;
-  /**
-   * Get text in a specific language with automatic fallback
-   */
-  getText(language?: T[number]): string;
-  /**
-   * Get rich text in a specific language with automatic fallback
-   */
-  getRichText(language?: T[number]): string;
   /**
-   * Get primary text in a specific language without fallback
+   * Resolve the entries to read for a language
+   *
+   * The fallback order is requested language, then the dataset's default
+   * language, then the first language that has any content. This is the only
+   * place that order is written down; every reader below is a projection of it.
    */
-  getExactText(language: T[number]): string | null;
+  private resolveEntries;
+  private resolvePrimaryEntry;
   /**
-   * Get primary rich text in a specific language without fallback
+   * Get text in a specific language, falling back when it has none
    */
-  getExactRichText(language: T[number]): string | null;
-  /**
-   * Get all text entries in a specific language without fallback
-   */
-  getExactTexts(language: T[number]): Array<string>;
+  getText(language?: T[number]): string;
   /**
-   * Get all rich text entries in a specific language without fallback
+   * Get rich text in a specific language, falling back when it has none
    */
-  getExactRichTexts(language: T[number]): Array<string>;
+  getRichText(language?: T[number]): string;
   /**
-   * Get all text entries in a specific language with fallback
+   * Get text in a specific language, with no fallback
    */
-  getTexts(language?: T[number]): Array<string>;
+  getExactText(language: T[number]): string;
   /**
-   * Get all rich text entries in a specific language with fallback
+   * Get rich text in a specific language, with no fallback
    */
-  getRichTexts(language?: T[number]): Array<string>;
+  getExactRichText(language: T[number]): string;
   /**
-   * Get all entries in a specific language without fallback
+   * Get every entry for a specific language, with no fallback
    */
   getExactEntries(language: T[number]): Array<MultilingualStringEntry>;
   /**
-   * Get all entries in a specific language with fallback
-   */
-  getEntries(language?: T[number]): Array<MultilingualStringEntry>;
-  /**
-   * Get aliases carried by OCHRE as zxx content
+   * Get the alias values OCHRE carries as `zxx` content
    */
   getAliases(): Array<string>;
   /**
-   * Check if text exists for a specific language
-   */
-  hasLanguage(language: T[number]): boolean;
-  /**
-   * Check if aliases exist
+   * Get the languages that actually carry content
    */
-  hasAliases(): boolean;
+  getAvailableLanguages(): Array<T[number]>;
   /**
-   * Get all available languages
-   */
-  getAvailableLanguages(): ReadonlyArray<T[number]>;
-  /**
-   * Get all supported languages (the full language array passed to constructor)
-   */
-  getSupportedLanguages(): T;
-  /**
-   * Check if the multilingual string is empty (no content in any language)
-   */
-  isEmpty(): boolean;
-  /**
-   * Check if the multilingual string has any content
-   */
-  hasContent(): boolean;
-  /**
-   * Get the default language
+   * Get the language reads fall back to before trying the rest
    */
   getDefaultLanguage(): T[number];
   /**
-   * Add or update the primary text for a language (returns new instance)
-   */
-  withText(language: T[number], text: MultilingualStringInput): MultilingualString<T>;
-  /**
-   * Add another text entry for a language (returns new instance)
-   */
-  withEntry(language: T[number], text: MultilingualStringInput): MultilingualString<T>;
-  /**
-   * Replace aliases (returns new instance)
-   */
-  withAliases(aliases: ReadonlyArray<string>): MultilingualString<T>;
-  /**
-   * Remove text for a language (returns new instance)
-   */
-  withoutLanguage(language: T[number]): MultilingualString<T>;
-  /**
-   * Transform all language versions (returns new instance)
+   * Set the text for a language, or append another entry to it
+   * @param language - The language to write
+   * @param text - The text to write
+   * @param options - Write options
+   * @param options.shouldAppend - Append as an additional entry instead of replacing
+   * @returns A new multilingual string
    */
-  map(function_: (text: string, language: T[number]) => string): MultilingualString<T>;
+  with(language: T[number], text: MultilingualStringInput, options?: {
+    shouldAppend?: boolean;
+  }): MultilingualString<T>;
   /**
-   * Filter languages based on predicate (returns new instance)
+   * Remove the content for a language
+   *
+   * When the removed language was the default, the default moves to the first
+   * language that still has content, so reads keep resolving.
+   * @param language - The language to remove
+   * @returns A new multilingual string
    */
-  filter(shouldInclude: (text: string, language: T[number]) => boolean): MultilingualString<T>;
+  without(language: T[number]): MultilingualString<T>;
   /**
-   * Get the string representation (uses default language)
+   * Get the string representation, using the default language
    */
   toString(): string;
   /**
-   * Get JSON representation
+   * Get the JSON representation
+   *
+   * Carries `defaultLanguage`, because it is not derivable from the content:
+   * without it {@link MultilingualString.fromJSON} would fall back to the first
+   * available language and `getText()` would resolve differently.
    */
   toJSON(): MultilingualStringJSON<T>;
 }