wikitongues-db 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,394 @@
+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';
+
+/**
+ * Domain models for the high-level Wikitongues Database API.
+ * Provides typed, immutable-friendly classes with rich helper methods.
+ */
+
+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;
+    toDict(): LanguageData;
+}
+declare class Speaker {
+    readonly name: string;
+    readonly role: string;
+    readonly origin: string | null;
+    constructor(data: Partial<SpeakerData>);
+    static fromDict(data: Partial<SpeakerData>): Speaker;
+    toDict(): SpeakerData;
+}
+declare class Provenance {
+    readonly countryCode: string | null;
+    readonly countryName: string | null;
+    readonly region: string | null;
+    readonly city: string | null;
+    readonly recordedBy: string | null;
+    readonly recordingDate: string | null;
+    constructor(data?: Partial<ProvenanceData> | null);
+    static fromDict(data?: Partial<ProvenanceData> | null): Provenance;
+    toDict(): ProvenanceData;
+}
+declare class Transcription {
+    readonly hasSubtitles: boolean;
+    readonly availableSubtitles: string[];
+    readonly nativeText: string | null;
+    readonly englishTranslation: string | null;
+    constructor(data?: Partial<TranscriptionData> | null);
+    static fromDict(data?: Partial<TranscriptionData> | null): Transcription;
+    toDict(): TranscriptionData;
+}
+declare class RawMetadata {
+    readonly title: string;
+    readonly tags: string[];
+    constructor(data?: Partial<RawMetadataData> | null);
+    static fromDict(data?: Partial<RawMetadataData> | null): RawMetadata;
+    toDict(): RawMetadataData;
+}
+declare class Video {
+    readonly id: string;
+    readonly url: string;
+    readonly durationSeconds: number;
+    readonly uploadDate: string;
+    readonly license: string;
+    readonly contentType: string;
+    readonly primaryLanguage: Language;
+    readonly additionalLanguages: Language[];
+    readonly speakers: Speaker[];
+    readonly provenance: Provenance;
+    readonly transcription: Transcription;
+    readonly rawMetadata: RawMetadata;
+    constructor(data: Partial<VideoData>);
+    /**
+     * Returns the YouTube embed URL for iframe players.
+     */
+    get embedUrl(): string;
+    /**
+     * Returns video title.
+     */
+    get title(): string;
+    /**
+     * Returns raw metadata tags.
+     */
+    get tags(): string[];
+    /**
+     * Returns human-readable duration formatted as 'MM:SS' or 'HH:MM:SS'.
+     */
+    get durationFormatted(): string;
+    /**
+     * True if the video is licensed under any Creative Commons or Public Domain license.
+     */
+    get isCreativeCommons(): boolean;
+    /**
+     * Returns all languages (primary + additional).
+     */
+    get allLanguages(): Language[];
+    /**
+     * Returns all ISO 639-3 codes for this video.
+     */
+    get allIsoCodes(): Set<string>;
+    /**
+     * Returns all BCP 47 codes for this video.
+     */
+    get allBcp47Codes(): Set<string>;
+    /**
+     * Returns all Glottolog codes for this video.
+     */
+    get allGlottocodes(): Set<string>;
+    /**
+     * Returns list of speaker names (excluding 'unknown').
+     */
+    get speakerNames(): string[];
+    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.
+     */
+    hasLanguage(query: string): boolean;
+    /**
+     * Check if any speaker matches the name or role (case-insensitive substring match).
+     */
+    hasSpeaker(nameOrRole: string): boolean;
+    /**
+     * Check if provenance country matches country code or name (case-insensitive).
+     */
+    hasCountry(country: string): boolean;
+    /**
+     * Convert Video object into a standard dictionary.
+     */
+    toDict(): VideoData;
+    /**
+     * Serialize Video to JSON string.
+     */
+    toJSON(indent?: number): string;
+    static fromDict(data: Partial<VideoData>): Video;
+}
+
+/**
+ * VideoCollection container for rich query results, aggregations, and transformations.
+ */
+
+declare class VideoCollection implements Iterable<Video> {
+    protected readonly _videos: Video[];
+    constructor(videos?: Video[] | readonly Video[]);
+    [Symbol.iterator](): Iterator<Video>;
+    get length(): number;
+    get(index: number): Video | undefined;
+    at(index: number): Video | undefined;
+    toArray(): Video[];
+    slice(start?: number, end?: number): VideoCollection;
+    includes(item: Video | string): boolean;
+    get isEmpty(): boolean;
+    get ids(): string[];
+    get urls(): string[];
+    get embedUrls(): string[];
+    get titles(): string[];
+    get totalDurationSeconds(): number;
+    get totalDurationFormatted(): string;
+    get averageDurationSeconds(): number;
+    get isoCodes(): string[];
+    get bcp47Codes(): string[];
+    get languageNames(): string[];
+    get languages(): Language[];
+    get countries(): string[];
+    get speakers(): Speaker[];
+    get speakerNames(): string[];
+    first(): Video | null;
+    last(): Video | null;
+    sample(k?: number, seed?: number): VideoCollection;
+    filter(predicate: (video: Video, index: number) => boolean): VideoCollection;
+    sortBy(key: string | ((video: Video) => any), descending?: boolean): VideoCollection;
+    limit(n: number): VideoCollection;
+    offset(n: number): VideoCollection;
+    page(page?: number, pageSize?: number): VideoCollection;
+    groupBy(key: string | ((video: Video) => string)): Record<string, VideoCollection>;
+    toDicts(): VideoData[];
+    toJSON(indent?: number): string;
+    toJSONL(): string;
+    toCSV(): string;
+}
+
+/**
+ * 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)
+ * to matched language identifiers.
+ */
+declare function normalizeText(text?: string | null): string;
+/**
+ * Common international / multilingual aliases for popular and regional languages.
+ */
+declare const MULTILINGUAL_ALIASES: Record<string, string>;
+declare class LanguageResolver {
+    isoToName: Map<string, string>;
+    nameToIso: Map<string, string>;
+    glottoToIso: Map<string, string>;
+    isoToGlotto: Map<string, string>;
+    autonymToIso: Map<string, Set<string>>;
+    dialectToIso: Map<string, Set<string>>;
+    aliases: Map<string, string>;
+    constructor();
+    /**
+     * Dynamically register language metadata discovered from normalized records.
+     */
+    registerDatasetLanguage(iso639_3: string, bcp47: string, name: string, glottocode?: string | null, autonym?: string | null, dialect?: string | null): void;
+    /**
+     * Resolve a search string to matching ISO 639-3 codes (and direct identifiers).
+     * Returns a set of matching ISO codes (or Glottocodes).
+     */
+    resolve(query: string): Set<string>;
+}
+
+/**
+ * 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.
+ */
+
+declare class DatasetIndex {
+    readonly videos: Video[];
+    readonly byId: Map<string, Video>;
+    readonly byIso: Map<string, Video[]>;
+    readonly byIsoPrimary: Map<string, Video[]>;
+    readonly byBcp47: Map<string, Video[]>;
+    readonly byGlottocode: Map<string, Video[]>;
+    readonly byCountryCode: Map<string, Video[]>;
+    readonly byCountryName: Map<string, Video[]>;
+    readonly bySpeakerRole: Map<string, Video[]>;
+    readonly bySpeakerName: Map<string, Video[]>;
+    readonly byContentType: Map<string, Video[]>;
+    readonly byLicense: Map<string, Video[]>;
+    readonly withSubtitles: Video[];
+    constructor(videos: Video[]);
+    private appendToMap;
+    private buildIndices;
+}
+
+/**
+ * Full-Text Search Engine with multi-field scoring and relevance ranking for Wikitongues records.
+ */
+
+declare class SearchEngine {
+    readonly videos: readonly Video[];
+    readonly resolver?: LanguageResolver;
+    constructor(videos: readonly Video[], resolver?: LanguageResolver);
+    /**
+     * Execute full-text search across all video metadata and rank results by score.
+     */
+    search(query: string, limit?: number, minScore?: number): VideoCollection;
+    private scoreVideo;
+}
+
+/**
+ * Fluent QueryBuilder for Wikitongues Database.
+ * Enables expressive, composable, and chainable querying over Wikitongues records.
+ */
+
+declare class QueryBuilder {
+    private readonly _sourceVideos;
+    private readonly _resolver?;
+    private _filters;
+    private _sortKey;
+    private _sortDescending;
+    private _limitVal;
+    private _offsetVal;
+    constructor(videos: readonly Video[], resolver?: LanguageResolver);
+    clone(): QueryBuilder;
+    language(query: string, includeAdditional?: boolean): this;
+    iso(code: string, includeAdditional?: boolean): this;
+    bcp47(tag: string, exact?: boolean): this;
+    glottocode(code: string): this;
+    country(countryCodeOrName: string): this;
+    speaker(options: {
+        name?: string;
+        role?: string;
+        origin?: string;
+    }): this;
+    contentType(...types: string[]): this;
+    license(...licenses: string[]): this;
+    creativeCommonsOnly(): this;
+    withSubtitles(lang?: string): this;
+    withoutSubtitles(): this;
+    minDuration(seconds: number): this;
+    maxDuration(seconds: number): this;
+    durationBetween(minSeconds: number, maxSeconds: number): this;
+    uploadedAfter(dateStr: string): this;
+    uploadedBefore(dateStr: string): this;
+    uploadedBetween(startDate: string, endDate: string): this;
+    recordedBy(name: string): this;
+    filter(predicate: (video: Video) => boolean): this;
+    orderBy(key: string | ((video: Video) => any), descending?: boolean): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    page(page?: number, pageSize?: number): this;
+    all(): VideoCollection;
+    first(): Video | null;
+    last(): Video | null;
+    count(): number;
+    exists(): boolean;
+    random(n?: number, seed?: number): VideoCollection;
+}
+
+/**
+ * High-Level Client for the Wikitongues Database.
+ * Provides instant O(1) lookups, fluent querying, full-text search, discovery, and analytics.
+ */
+
+interface WikitonguesDBOptions {
+    data?: (VideoData | Video)[];
+    records?: (VideoData | Video)[];
+}
+declare class WikitonguesDB {
+    protected readonly _videos: Video[];
+    readonly resolver: LanguageResolver;
+    readonly index: DatasetIndex;
+    readonly searchEngine: SearchEngine;
+    constructor(options?: WikitonguesDBOptions);
+    get length(): number;
+    /**
+     * Create a WikitonguesDB instance directly from an in-memory list of dicts or Videos.
+     */
+    static fromRecords(records: (VideoData | Video)[]): WikitonguesDB;
+    /**
+     * Create a WikitonguesDB instance from a JSON string or JSON array.
+     */
+    static fromJSON(json: string | VideoData[]): WikitonguesDB;
+    /**
+     * Create a WikitonguesDB instance from a JSON or JSONL file path (Node.js environments).
+     */
+    static fromFile(filepath: string): WikitonguesDB;
+    /**
+     * Lookup a video by its YouTube ID in O(1) time.
+     */
+    get(videoId: string): Video | null;
+    /**
+     * Lookup videos matching a 3-letter SIL ISO 639-3 code in O(1) time.
+     */
+    getByIso(code: string): VideoCollection;
+    /**
+     * Lookup videos matching a BCP 47 language tag in O(1) time.
+     */
+    getByBcp47(tag: string): VideoCollection;
+    /**
+     * Lookup videos matching a Glottolog code in O(1) time.
+     */
+    getByGlottocode(glottocode: string): VideoCollection;
+    /**
+     * Lookup videos matching an ISO 3166-1 alpha-2 code or country name in O(1) time.
+     */
+    getByCountry(countryCodeOrName: string): VideoCollection;
+    /**
+     * Lookup videos for a given speaker name.
+     */
+    getBySpeaker(name: string): VideoCollection;
+    /**
+     * Intelligent language search: resolves natural names, multilingual aliases ('russe'),
+     * ISO 639-3 ('rus'), BCP 47 ('ru'), autonyms ('Русский'), and dialects.
+     */
+    findByLanguage(languageQuery: string, includeAdditional?: boolean): VideoCollection;
+    /**
+     * Shortcut method to filter videos by common criteria.
+     */
+    find(filters?: FilterOptions): VideoCollection;
+    /**
+     * Initialize a new fluent QueryBuilder.
+     */
+    query(): QueryBuilder;
+    /**
+     * Execute weighted full-text search across all metadata.
+     */
+    search(query: string, limit?: number): VideoCollection;
+    /**
+     * Return all videos as a VideoCollection.
+     */
+    all(): VideoCollection;
+    /**
+     * Return n random videos, optionally filtered by criteria.
+     */
+    random(n?: number, seed?: number, filters?: FilterOptions): VideoCollection;
+    /**
+     * Return a structured inventory of all represented languages with summary metrics.
+     */
+    languages(): LanguageSummary[];
+    /**
+     * Return a structured inventory of all represented countries with summary metrics.
+     */
+    countries(): CountrySummary[];
+    /**
+     * Return a structured inventory of all speakers in the dataset.
+     */
+    speakers(): SpeakerSummary[];
+    /**
+     * Compute aggregate dataset statistics.
+     */
+    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 };