ochre-sdk 1.0.79 → 1.1.1

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,178 @@ 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
+   * 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.
+   */
+  private resolveEntries;
+  private resolvePrimaryEntry;
+  /**
+   * Get text in a specific language, falling back when it has none
    */
   getText(language?: T[number]): string;
   /**
-   * Get rich text in a specific language with automatic fallback
+   * Get rich text in a specific language, falling back when it has none
    */
   getRichText(language?: T[number]): string;
   /**
-   * Get primary text in a specific language without fallback
+   * Get text in a specific language, with no fallback
    */
-  getExactText(language: T[number]): string | null;
+  getExactText(language: T[number]): string;
   /**
-   * Get primary rich text in a specific language without fallback
+   * Get rich text in a specific language, with no fallback
    */
-  getExactRichText(language: T[number]): string | null;
+  getExactRichText(language: T[number]): string;
   /**
-   * Get all text entries in a specific language without fallback
+   * Get every entry for a specific language, with no fallback
    */
-  getExactTexts(language: T[number]): Array<string>;
+  getExactEntries(language: T[number]): Array<MultilingualStringEntry>;
   /**
-   * Get all rich text entries in a specific language without fallback
+   * Get every entry for a language, falling back when it has none
+   *
+   * The multi-entry counterpart of {@link MultilingualString.getText}: OCHRE
+   * can carry several entries for one language, and this returns all of them
+   * rather than only the primary. Each entry carries both `text` and
+   * `richText`, so a caller rendering a rich field reads them from here.
+   * @param language - The language to read, or undefined for the default
+   * @returns The entries, or an empty array when no language has any
    */
-  getExactRichTexts(language: T[number]): Array<string>;
+  getEntries(language?: T[number]): Array<MultilingualStringEntry>;
   /**
-   * Get all text entries in a specific language with fallback
+   * Get the text of every entry for a language, falling back when it has none
+   * @param language - The language to read, or undefined for the default
+   * @returns The texts, or an empty array when no language has any
    */
   getTexts(language?: T[number]): Array<string>;
   /**
-   * Get all rich text entries in a specific language with fallback
+   * Get the text of every entry for a language, with no fallback
+   * @param language - The language to read
+   * @returns The texts, or an empty array when that language has none
    */
-  getRichTexts(language?: T[number]): Array<string>;
-  /**
-   * Get all entries in a specific language without fallback
-   */
-  getExactEntries(language: T[number]): Array<MultilingualStringEntry>;
-  /**
-   * Get all entries in a specific language with fallback
-   */
-  getEntries(language?: T[number]): Array<MultilingualStringEntry>;
+  getExactTexts(language: T[number]): Array<string>;
   /**
-   * 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
+   * Get the languages that actually carry content
    */
-  hasLanguage(language: T[number]): boolean;
+  getAvailableLanguages(): Array<T[number]>;
   /**
-   * Check if aliases exist
+   * Get the language reads fall back to before trying the rest
    */
-  hasAliases(): boolean;
-  /**
-   * Get all available languages
-   */
-  getAvailableLanguages(): ReadonlyArray<T[number]>;
+  getDefaultLanguage(): T[number];
   /**
-   * Get all supported languages (the full language array passed to constructor)
+   * Get every language this string was built to hold
+   *
+   * The configured language list, which is not the same question as
+   * {@link MultilingualString.getAvailableLanguages}: that one answers which
+   * languages actually carry content, and is a subset of this.
+   * @returns The supported languages
    */
-  getSupportedLanguages(): T;
+  getSupportedLanguages(): Array<T[number]>;
   /**
-   * Check if the multilingual string is empty (no content in any language)
+   * Whether any language carries an entry
+   *
+   * Answers the structural question. A language whose only entry is blank
+   * still counts here; {@link MultilingualString.hasContent} is the question
+   * about text. Aliases are not entries, so a string carrying only aliases is
+   * empty by this measure and {@link MultilingualString.hasAliases} is true.
+   * @returns True when no language carries an entry
    */
   isEmpty(): boolean;
   /**
-   * Check if the multilingual string has any content
+   * Whether any entry in any language carries text that is not whitespace
+   *
+   * Deliberately not the negation of {@link MultilingualString.isEmpty}, which
+   * only asks whether entries exist. OCHRE does serve fields holding a single
+   * whitespace entry, so a caller deciding whether to render something wants
+   * this one, and it looks at every entry rather than only the primary.
+   * @returns True when some entry has non-whitespace text
    */
   hasContent(): boolean;
   /**
-   * Get the default language
+   * Whether a specific language carries an entry, with no fallback
+   * @param language - The language to test
+   * @returns True when that language carries at least one entry
    */
-  getDefaultLanguage(): T[number];
-  /**
-   * Add or update the primary text for a language (returns new instance)
-   */
-  withText(language: T[number], text: MultilingualStringInput): MultilingualString<T>;
+  hasLanguage(language: T[number]): boolean;
   /**
-   * Add another text entry for a language (returns new instance)
+   * Whether OCHRE carried any `zxx` alias values for this string
+   * @returns True when there is at least one alias
    */
-  withEntry(language: T[number], text: MultilingualStringInput): MultilingualString<T>;
+  hasAliases(): boolean;
   /**
-   * Replace aliases (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
+   */
+  with(language: T[number], text: MultilingualStringInput, options?: {
+    shouldAppend?: boolean;
+  }): MultilingualString<T>;
+  /**
+   * 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
+   */
+  without(language: T[number]): MultilingualString<T>;
+  /**
+   * Replace the alias values
+   *
+   * Aliases are the `zxx` content OCHRE carries alongside a field's languages,
+   * so they are set as a whole rather than per language. Empty strings are
+   * dropped, matching how they are read from a payload.
+   * @param aliases - The aliases to carry
+   * @returns A new multilingual string
    */
   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)
-   */
-  map(function_: (text: string, language: T[number]) => string): MultilingualString<T>;
-  /**
-   * Filter languages based on predicate (returns new instance)
-   */
-  filter(shouldInclude: (text: string, language: T[number]) => boolean): MultilingualString<T>;
-  /**
-   * Get the string representation (uses default language)
+   * Transform the text of every entry in every language
+   *
+   * Replaces the old `map`, which corrupted rich text: it wrote the
+   * transformed plain text and left the entry's `richText` to be re-derived,
+   * so a transform such as uppercasing turned `<InternalLink uuid="abc">` into
+   * markup OCHRE never wrote. The transform here runs against plain text only,
+   * and the entry's rich text is rebuilt from the result, so the two can never
+   * disagree.
+   *
+   * A transform that needs to keep or rewrite markup returns
+   * `{ text, richText }` instead of a string, and both are used verbatim.
+   * @param transform - Produces the new text for one entry
+   * @returns A new multilingual string
+   */
+  mapText(transform: (text: string, language: T[number]) => MultilingualStringInput): MultilingualString<T>;
+  /**
+   * Keep only the entries a predicate accepts
+   *
+   * The callback receives the whole entry rather than just its text, so it
+   * can also test `richText` and `isPrimary`. Dropping every entry of a
+   * language removes that language, and when that was the default the default
+   * moves to the first language that still has content, so reads keep
+   * resolving.
+   * @param shouldKeep - Whether to keep one entry
+   * @returns A new multilingual string
+   */
+  filterEntries(shouldKeep: (entry: MultilingualStringEntry, language: T[number]) => boolean): MultilingualString<T>;
+  /**
+   * 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>;
 }