wikitongues-db 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,20 +1,66 @@
-import { L as LanguageData, S as SpeakerData, P as ProvenanceData, T as TranscriptionData, R as RawMetadataData, V as VideoData, F as FilterOptions, a as LanguageSummary, C as CountrySummary, b as SpeakerSummary, D as DatasetStats } from './dataset-jRTVzgZX.mjs';
-export { d as dataset } from './dataset-jRTVzgZX.mjs';
+import { R as ReferenceTables, a as ResolvedIso639_3, b as ResolvedGlottolog, c as ResolvedBcp47, S as StandardsData, d as ResolvedStandards, L as LanguageData, e as SpeakerData, P as ProvenanceData, T as TranscriptionData, f as RawMetadataData, V as VideoData, F as FilterOptions, g as LanguageSummary, C as CountrySummary, h as SpeakerSummary, D as DatasetStats } from './dataset-DNYcpFFZ.mjs';
+export { G as GlottologEntry, I as IanaLanguageEntry, i as IanaSubtagEntry, j as IanaVariantEntry, k as Iso639_3Entry, l as dataset } from './dataset-DNYcpFFZ.mjs';
+
+/**
+ * Deterministic hydration of the persisted ontological anchor keys
+ * (`standards: { iso639_3, glottocode, bcp47 }`) into fully resolved standard objects,
+ * joined against the bundled reference tables (src/generated/reference.json).
+ *
+ * Hydration is strict: any key that does not resolve, or that violates the curation rules
+ * (macrolanguage ISO code, Glottolog family node, malformed or unregistered BCP-47 tag),
+ * throws a HydrationError. A dataset that does not hydrate does not load.
+ */
+
+declare class HydrationError extends Error {
+    readonly recordId: string;
+    readonly field: keyof StandardsData;
+    readonly code: string;
+    constructor(recordId: string, field: keyof StandardsData, code: string, reason: string);
+}
+declare class ReferenceHydrator {
+    readonly tables: ReferenceTables;
+    constructor(tables?: ReferenceTables);
+    resolveIso(code: string, recordId?: string): ResolvedIso639_3;
+    resolveGlottolog(code: string, recordId?: string): ResolvedGlottolog;
+    /**
+     * Parse and validate a tag of the form `language[-script][-region][-variant]*` (RFC 5646 §2.1).
+     * The primary subtag must be the ISO 639-1 code of `iso` when one exists, else `iso` itself.
+     */
+    resolveBcp47(tag: string, iso: ResolvedIso639_3, recordId?: string): ResolvedBcp47;
+    hydrate(standards: StandardsData, recordId?: string): ResolvedStandards;
+}
 
 /**
  * Domain models for the high-level Wikitongues Database API.
  * Provides typed, immutable-friendly classes with rich helper methods.
  */
 
+/**
+ * A language as recorded in a video: three independently resolved institutional standards
+ * plus the speaker's own claim, Wikitongues' editorial label and the autonym.
+ * Shared by `Video.primaryLanguage` and every entry of `Video.additionalLanguages`.
+ */
 declare class Language {
-    readonly iso639_3: string;
-    readonly bcp47: string;
-    readonly name: string;
-    readonly glottocode: string | null;
-    readonly autonym: string | null;
-    readonly dialect: string | null;
-    constructor(data: Partial<LanguageData>);
-    static fromDict(data: Partial<LanguageData>): Language;
+    readonly standards: ResolvedStandards;
+    readonly speakerClaim: string | null;
+    readonly wikitonguesClassification: string;
+    readonly wikitonguesLineage: string | null;
+    readonly autonym: string;
+    constructor(data: LanguageData, hydrator: ReferenceHydrator, recordId?: string);
+    static hydrate(data: LanguageData, hydrator: ReferenceHydrator, recordId?: string): Language;
+    /** ISO 639-3 code, e.g. "por". */
+    get iso639_3(): string;
+    /** BCP-47 tag, e.g. "pt-BR". */
+    get bcp47(): string;
+    /** Glottocode, e.g. "braz1246". */
+    get glottocode(): string;
+    /** Human-readable label: Wikitongues' own classification. */
+    get name(): string;
+    /**
+     * Every label under which this language can be searched, in priority order:
+     * Wikitongues classification, Glottolog node name, ISO reference name, autonym, speaker claim.
+     */
+    get labels(): string[];
     toDict(): LanguageData;
 }
 declare class Speaker {
@@ -65,7 +111,7 @@ declare class Video {
     readonly provenance: Provenance;
     readonly transcription: Transcription;
     readonly rawMetadata: RawMetadata;
-    constructor(data: Partial<VideoData>);
+    constructor(data: VideoData, hydrator?: ReferenceHydrator);
     /**
      * Returns the YouTube embed URL for iframe players.
      */
@@ -109,8 +155,9 @@ declare class Video {
     get countryCode(): string | null;
     get countryName(): string | null;
     /**
-     * Check if video contains a language matching query (by ISO, BCP-47, Glottocode, Name, Autonym, or Dialect).
-     * Case-insensitive.
+     * Check if video contains a language matching query (by ISO 639-3, BCP-47, Glottocode —
+     * including the parent language of a dialect node — or any label: Wikitongues classification,
+     * Glottolog name, ISO name, autonym, speaker claim). Case-insensitive.
      */
     hasLanguage(query: string): boolean;
     /**
@@ -129,7 +176,7 @@ declare class Video {
      * Serialize Video to JSON string.
      */
     toJSON(indent?: number): string;
-    static fromDict(data: Partial<VideoData>): Video;
+    static fromDict(data: VideoData, hydrator?: ReferenceHydrator): Video;
 }
 
 /**
@@ -179,9 +226,10 @@ declare class VideoCollection implements Iterable<Video> {
 /**
  * Language Resolver module for Wikitongues Database.
  * Resolves natural language search queries (ISO 639-3, BCP 47, Glottocode, English canonical names,
- * multilingual common names like 'russe' / 'español', autonyms, and dialects)
+ * multilingual common names like 'russe' / 'español', autonyms, Glottolog / ISO names and speaker claims)
  * to matched language identifiers.
  */
+
 declare function normalizeText(text?: string | null): string;
 /**
  * Common international / multilingual aliases for popular and regional languages.
@@ -193,13 +241,16 @@ declare class LanguageResolver {
     glottoToIso: Map<string, string>;
     isoToGlotto: Map<string, string>;
     autonymToIso: Map<string, Set<string>>;
-    dialectToIso: Map<string, Set<string>>;
+    /** Secondary labels (Glottolog node names, ISO reference names, speaker claims) → ISO codes. */
+    labelToIso: Map<string, Set<string>>;
     aliases: Map<string, string>;
     constructor();
+    private addToSet;
     /**
-     * Dynamically register language metadata discovered from normalized records.
+     * Register a hydrated language from the dataset: its primary label (Wikitongues classification)
+     * goes to the name index; Glottolog / ISO names and the speaker claim to the secondary label index.
      */
-    registerDatasetLanguage(iso639_3: string, bcp47: string, name: string, glottocode?: string | null, autonym?: string | null, dialect?: string | null): void;
+    registerDatasetLanguage(lang: Language): void;
     /**
      * Resolve a search string to matching ISO 639-3 codes (and direct identifiers).
      * Returns a set of matching ISO codes (or Glottocodes).
@@ -209,7 +260,7 @@ declare class LanguageResolver {
 
 /**
  * In-memory Inverted Index engine for Wikitongues Database.
- * Provides O(1) indexed lookups by ID, ISO 639-3, BCP 47, Glottocode, Country, Speaker, License, etc.
+ * Provides O(1) indexed lookups by ID, ISO 639-3, BCP 47, Glottocode (incl. parent language of dialects), Country, Speaker, License, etc.
  */
 
 declare class DatasetIndex {
@@ -304,12 +355,22 @@ declare class QueryBuilder {
 interface WikitonguesDBOptions {
     data?: (VideoData | Video)[];
     records?: (VideoData | Video)[];
+    /**
+     * Reference tables used to hydrate `standards`. Defaults to the bundled pruned tables
+     * (src/generated/reference.json); pass full tables when loading records outside the dataset.
+     */
+    reference?: ReferenceTables;
 }
 declare class WikitonguesDB {
     protected readonly _videos: Video[];
+    readonly hydrator: ReferenceHydrator;
     readonly resolver: LanguageResolver;
     readonly index: DatasetIndex;
     readonly searchEngine: SearchEngine;
+    /**
+     * Loads and hydrates every record. Throws HydrationError on the first record whose
+     * standards do not resolve against the reference tables (see CLASSIFICATION_RULES.md §3.1.1).
+     */
     constructor(options?: WikitonguesDBOptions);
     get length(): number;
     /**
@@ -337,7 +398,8 @@ declare class WikitonguesDB {
      */
     getByBcp47(tag: string): VideoCollection;
     /**
-     * Lookup videos matching a Glottolog code in O(1) time.
+     * Lookup videos matching a Glottolog code in O(1) time. A language node also matches videos
+     * classified under one of its dialect nodes (e.g. `port1283` returns `braz1246` recordings).
      */
     getByGlottocode(glottocode: string): VideoCollection;
     /**
@@ -350,7 +412,8 @@ declare class WikitonguesDB {
     getBySpeaker(name: string): VideoCollection;
     /**
      * Intelligent language search: resolves natural names, multilingual aliases ('russe'),
-     * ISO 639-3 ('rus'), BCP 47 ('ru'), autonyms ('Русский'), and dialects.
+     * ISO 639-3 ('rus'), BCP 47 ('ru'), Glottocodes, autonyms ('Русский'), Wikitongues
+     * classifications, Glottolog / ISO names and speaker claims.
      */
     findByLanguage(languageQuery: string, includeAdditional?: boolean): VideoCollection;
     /**
@@ -391,4 +454,4 @@ declare class WikitonguesDB {
     stats(): DatasetStats;
 }
 
-export { CountrySummary, DatasetIndex, DatasetStats, FilterOptions, Language, LanguageData, LanguageResolver, LanguageSummary, MULTILINGUAL_ALIASES, Provenance, ProvenanceData, QueryBuilder, RawMetadata, RawMetadataData, SearchEngine, Speaker, SpeakerData, SpeakerSummary, Transcription, TranscriptionData, Video, VideoCollection, VideoData, WikitonguesDB, type WikitonguesDBOptions, normalizeText };
+export { CountrySummary, DatasetIndex, DatasetStats, FilterOptions, HydrationError, Language, LanguageData, LanguageResolver, LanguageSummary, MULTILINGUAL_ALIASES, Provenance, ProvenanceData, QueryBuilder, RawMetadata, RawMetadataData, ReferenceHydrator, ReferenceTables, ResolvedBcp47, ResolvedGlottolog, ResolvedIso639_3, ResolvedStandards, SearchEngine, Speaker, SpeakerData, SpeakerSummary, StandardsData, Transcription, TranscriptionData, Video, VideoCollection, VideoData, WikitonguesDB, type WikitonguesDBOptions, normalizeText };

package/dist/index.d.ts

@@ -1,20 +1,66 @@
-import { L as LanguageData, S as SpeakerData, P as ProvenanceData, T as TranscriptionData, R as RawMetadataData, V as VideoData, F as FilterOptions, a as LanguageSummary, C as CountrySummary, b as SpeakerSummary, D as DatasetStats } from './dataset-jRTVzgZX.js';
-export { d as dataset } from './dataset-jRTVzgZX.js';
+import { R as ReferenceTables, a as ResolvedIso639_3, b as ResolvedGlottolog, c as ResolvedBcp47, S as StandardsData, d as ResolvedStandards, L as LanguageData, e as SpeakerData, P as ProvenanceData, T as TranscriptionData, f as RawMetadataData, V as VideoData, F as FilterOptions, g as LanguageSummary, C as CountrySummary, h as SpeakerSummary, D as DatasetStats } from './dataset-DNYcpFFZ.js';
+export { G as GlottologEntry, I as IanaLanguageEntry, i as IanaSubtagEntry, j as IanaVariantEntry, k as Iso639_3Entry, l as dataset } from './dataset-DNYcpFFZ.js';
+
+/**
+ * Deterministic hydration of the persisted ontological anchor keys
+ * (`standards: { iso639_3, glottocode, bcp47 }`) into fully resolved standard objects,
+ * joined against the bundled reference tables (src/generated/reference.json).
+ *
+ * Hydration is strict: any key that does not resolve, or that violates the curation rules
+ * (macrolanguage ISO code, Glottolog family node, malformed or unregistered BCP-47 tag),
+ * throws a HydrationError. A dataset that does not hydrate does not load.
+ */
+
+declare class HydrationError extends Error {
+    readonly recordId: string;
+    readonly field: keyof StandardsData;
+    readonly code: string;
+    constructor(recordId: string, field: keyof StandardsData, code: string, reason: string);
+}
+declare class ReferenceHydrator {
+    readonly tables: ReferenceTables;
+    constructor(tables?: ReferenceTables);
+    resolveIso(code: string, recordId?: string): ResolvedIso639_3;
+    resolveGlottolog(code: string, recordId?: string): ResolvedGlottolog;
+    /**
+     * Parse and validate a tag of the form `language[-script][-region][-variant]*` (RFC 5646 §2.1).
+     * The primary subtag must be the ISO 639-1 code of `iso` when one exists, else `iso` itself.
+     */
+    resolveBcp47(tag: string, iso: ResolvedIso639_3, recordId?: string): ResolvedBcp47;
+    hydrate(standards: StandardsData, recordId?: string): ResolvedStandards;
+}
 
 /**
  * Domain models for the high-level Wikitongues Database API.
  * Provides typed, immutable-friendly classes with rich helper methods.
  */
 
+/**
+ * A language as recorded in a video: three independently resolved institutional standards
+ * plus the speaker's own claim, Wikitongues' editorial label and the autonym.
+ * Shared by `Video.primaryLanguage` and every entry of `Video.additionalLanguages`.
+ */
 declare class Language {
-    readonly iso639_3: string;
-    readonly bcp47: string;
-    readonly name: string;
-    readonly glottocode: string | null;
-    readonly autonym: string | null;
-    readonly dialect: string | null;
-    constructor(data: Partial<LanguageData>);
-    static fromDict(data: Partial<LanguageData>): Language;
+    readonly standards: ResolvedStandards;
+    readonly speakerClaim: string | null;
+    readonly wikitonguesClassification: string;
+    readonly wikitonguesLineage: string | null;
+    readonly autonym: string;
+    constructor(data: LanguageData, hydrator: ReferenceHydrator, recordId?: string);
+    static hydrate(data: LanguageData, hydrator: ReferenceHydrator, recordId?: string): Language;
+    /** ISO 639-3 code, e.g. "por". */
+    get iso639_3(): string;
+    /** BCP-47 tag, e.g. "pt-BR". */
+    get bcp47(): string;
+    /** Glottocode, e.g. "braz1246". */
+    get glottocode(): string;
+    /** Human-readable label: Wikitongues' own classification. */
+    get name(): string;
+    /**
+     * Every label under which this language can be searched, in priority order:
+     * Wikitongues classification, Glottolog node name, ISO reference name, autonym, speaker claim.
+     */
+    get labels(): string[];
     toDict(): LanguageData;
 }
 declare class Speaker {
@@ -65,7 +111,7 @@ declare class Video {
     readonly provenance: Provenance;
     readonly transcription: Transcription;
     readonly rawMetadata: RawMetadata;
-    constructor(data: Partial<VideoData>);
+    constructor(data: VideoData, hydrator?: ReferenceHydrator);
     /**
      * Returns the YouTube embed URL for iframe players.
      */
@@ -109,8 +155,9 @@ declare class Video {
     get countryCode(): string | null;
     get countryName(): string | null;
     /**
-     * Check if video contains a language matching query (by ISO, BCP-47, Glottocode, Name, Autonym, or Dialect).
-     * Case-insensitive.
+     * Check if video contains a language matching query (by ISO 639-3, BCP-47, Glottocode —
+     * including the parent language of a dialect node — or any label: Wikitongues classification,
+     * Glottolog name, ISO name, autonym, speaker claim). Case-insensitive.
      */
     hasLanguage(query: string): boolean;
     /**
@@ -129,7 +176,7 @@ declare class Video {
      * Serialize Video to JSON string.
      */
     toJSON(indent?: number): string;
-    static fromDict(data: Partial<VideoData>): Video;
+    static fromDict(data: VideoData, hydrator?: ReferenceHydrator): Video;
 }
 
 /**
@@ -179,9 +226,10 @@ declare class VideoCollection implements Iterable<Video> {
 /**
  * Language Resolver module for Wikitongues Database.
  * Resolves natural language search queries (ISO 639-3, BCP 47, Glottocode, English canonical names,
- * multilingual common names like 'russe' / 'español', autonyms, and dialects)
+ * multilingual common names like 'russe' / 'español', autonyms, Glottolog / ISO names and speaker claims)
  * to matched language identifiers.
  */
+
 declare function normalizeText(text?: string | null): string;
 /**
  * Common international / multilingual aliases for popular and regional languages.
@@ -193,13 +241,16 @@ declare class LanguageResolver {
     glottoToIso: Map<string, string>;
     isoToGlotto: Map<string, string>;
     autonymToIso: Map<string, Set<string>>;
-    dialectToIso: Map<string, Set<string>>;
+    /** Secondary labels (Glottolog node names, ISO reference names, speaker claims) → ISO codes. */
+    labelToIso: Map<string, Set<string>>;
     aliases: Map<string, string>;
     constructor();
+    private addToSet;
     /**
-     * Dynamically register language metadata discovered from normalized records.
+     * Register a hydrated language from the dataset: its primary label (Wikitongues classification)
+     * goes to the name index; Glottolog / ISO names and the speaker claim to the secondary label index.
      */
-    registerDatasetLanguage(iso639_3: string, bcp47: string, name: string, glottocode?: string | null, autonym?: string | null, dialect?: string | null): void;
+    registerDatasetLanguage(lang: Language): void;
     /**
      * Resolve a search string to matching ISO 639-3 codes (and direct identifiers).
      * Returns a set of matching ISO codes (or Glottocodes).
@@ -209,7 +260,7 @@ declare class LanguageResolver {
 
 /**
  * In-memory Inverted Index engine for Wikitongues Database.
- * Provides O(1) indexed lookups by ID, ISO 639-3, BCP 47, Glottocode, Country, Speaker, License, etc.
+ * Provides O(1) indexed lookups by ID, ISO 639-3, BCP 47, Glottocode (incl. parent language of dialects), Country, Speaker, License, etc.
  */
 
 declare class DatasetIndex {
@@ -304,12 +355,22 @@ declare class QueryBuilder {
 interface WikitonguesDBOptions {
     data?: (VideoData | Video)[];
     records?: (VideoData | Video)[];
+    /**
+     * Reference tables used to hydrate `standards`. Defaults to the bundled pruned tables
+     * (src/generated/reference.json); pass full tables when loading records outside the dataset.
+     */
+    reference?: ReferenceTables;
 }
 declare class WikitonguesDB {
     protected readonly _videos: Video[];
+    readonly hydrator: ReferenceHydrator;
     readonly resolver: LanguageResolver;
     readonly index: DatasetIndex;
     readonly searchEngine: SearchEngine;
+    /**
+     * Loads and hydrates every record. Throws HydrationError on the first record whose
+     * standards do not resolve against the reference tables (see CLASSIFICATION_RULES.md §3.1.1).
+     */
     constructor(options?: WikitonguesDBOptions);
     get length(): number;
     /**
@@ -337,7 +398,8 @@ declare class WikitonguesDB {
      */
     getByBcp47(tag: string): VideoCollection;
     /**
-     * Lookup videos matching a Glottolog code in O(1) time.
+     * Lookup videos matching a Glottolog code in O(1) time. A language node also matches videos
+     * classified under one of its dialect nodes (e.g. `port1283` returns `braz1246` recordings).
      */
     getByGlottocode(glottocode: string): VideoCollection;
     /**
@@ -350,7 +412,8 @@ declare class WikitonguesDB {
     getBySpeaker(name: string): VideoCollection;
     /**
      * Intelligent language search: resolves natural names, multilingual aliases ('russe'),
-     * ISO 639-3 ('rus'), BCP 47 ('ru'), autonyms ('Русский'), and dialects.
+     * ISO 639-3 ('rus'), BCP 47 ('ru'), Glottocodes, autonyms ('Русский'), Wikitongues
+     * classifications, Glottolog / ISO names and speaker claims.
      */
     findByLanguage(languageQuery: string, includeAdditional?: boolean): VideoCollection;
     /**
@@ -391,4 +454,4 @@ declare class WikitonguesDB {
     stats(): DatasetStats;
 }
 
-export { CountrySummary, DatasetIndex, DatasetStats, FilterOptions, Language, LanguageData, LanguageResolver, LanguageSummary, MULTILINGUAL_ALIASES, Provenance, ProvenanceData, QueryBuilder, RawMetadata, RawMetadataData, SearchEngine, Speaker, SpeakerData, SpeakerSummary, Transcription, TranscriptionData, Video, VideoCollection, VideoData, WikitonguesDB, type WikitonguesDBOptions, normalizeText };
+export { CountrySummary, DatasetIndex, DatasetStats, FilterOptions, HydrationError, Language, LanguageData, LanguageResolver, LanguageSummary, MULTILINGUAL_ALIASES, Provenance, ProvenanceData, QueryBuilder, RawMetadata, RawMetadataData, ReferenceHydrator, ReferenceTables, ResolvedBcp47, ResolvedGlottolog, ResolvedIso639_3, ResolvedStandards, SearchEngine, Speaker, SpeakerData, SpeakerSummary, StandardsData, Transcription, TranscriptionData, Video, VideoCollection, VideoData, WikitonguesDB, type WikitonguesDBOptions, normalizeText };