lyric-romanizer 0.2.0 → 0.3.0

package/dist/romanizer.js

@@ -1,137 +1,195 @@
-import Kuroshiro from '@sglkc/kuroshiro';
-import KuromojiAnalyzer from '@sglkc/kuroshiro-analyzer-kuromoji';
-import { pinyin } from 'pinyin-pro';
-import CyrillicToTranslit from 'cyrillic-to-translit-js';
-import Sanscript from '@indic-transliteration/sanscript';
-import { romanize as romanizeKorean } from '@romanize/korean';
-import romanizeThai from '@dehoist/romanize-thai';
-import { romanize as romanizeTamil } from 'tamil-romanizer';
-import { transliterate } from 'transliteration';
-import { detectScript } from './detector.js';
+import { NON_LATIN_SCRIPT_RE, detectScript } from './detector.js';
 import { UnsupportedRomanizationError } from './types.js';
 const DEFAULT_JAPANESE_DICT_PATH = 'https://cdn.jsdelivr.net/npm/kuromoji/dict';
-const EXTERNAL_ROMANIZATION_SCRIPTS = new Set([
-    'malayalam',
-    'bengali',
-    'arabic',
-    'hebrew',
-    'other',
-]);
-const cyrillicTranslitRu = CyrillicToTranslit({ preset: 'ru' });
-const cyrillicTranslitUk = CyrillicToTranslit({ preset: 'uk' });
-const SANSCRIPT_SCHEME = {
-    devanagari: 'devanagari',
-    gujarati: 'gujarati',
-    gurmukhi: 'gurmukhi',
-    telugu: 'telugu',
-    kannada: 'kannada',
-    odia: 'oriya',
-};
-export function requiresExternalRomanization(script) {
-    return EXTERNAL_ROMANIZATION_SCRIPTS.has(script);
+const HAS_LETTER_RE = /\p{L}/u;
+const ASCII_LETTER_RE = /[A-Za-z]/;
+/**
+ * Memoizes an async load; a failed load clears the cache so the next call
+ * retries instead of caching the rejection.
+ */
+function lazy(load) {
+    let cached = null;
+    return () => {
+        if (!cached) {
+            cached = load().catch((error) => {
+                cached = null;
+                throw error;
+            });
+        }
+        return cached;
+    };
+}
+/** Rejects the load when interop resolution finds nothing callable. */
+function resolved(value, what) {
+    if (value === undefined)
+        throw new Error(`Failed to resolve ${what} from its module.`);
+    return value;
+}
+// Every engine loads on first use so that importing this module costs nothing
+// until a line of the matching script is romanized. The `?? default` chains
+// bridge module shapes: bundlers surface these CJS packages' named exports,
+// while plain Node ESM surfaces them only on `default`.
+const loadPinyin = lazy(async () => {
+    const mod = await import('pinyin-pro');
+    return resolved(mod.pinyin ?? mod.default?.pinyin, 'pinyin');
+});
+const loadJyutping = lazy(() => import('to-jyutping'));
+const loadKorean = lazy(async () => {
+    const mod = await import('@romanize/korean');
+    return resolved(mod.romanize ?? mod.default?.romanize, 'korean romanize');
+});
+const loadThai = lazy(async () => {
+    const mod = await import('@dehoist/romanize-thai');
+    return resolved(mod.default ?? mod.romanize, 'thai romanize');
+});
+const loadTamil = lazy(async () => {
+    const mod = await import('tamil-romanizer');
+    return resolved(mod.romanize ?? mod.default?.romanize, 'tamil romanize');
+});
+const loadSanscript = lazy(async () => {
+    const mod = await import('@indic-transliteration/sanscript');
+    return resolved(mod.default ?? mod.Sanscript, 'Sanscript');
+});
+const loadTransliterate = lazy(async () => {
+    const mod = await import('transliteration');
+    return resolved(mod.transliterate ?? mod.default?.transliterate, 'transliterate');
+});
+const loadCyrillicTranslit = lazy(async () => {
+    const mod = await import('cyrillic-to-translit-js');
+    const factory = resolved(mod.default ?? mod, 'CyrillicToTranslit');
+    return { ru: factory({ preset: 'ru' }), uk: factory({ preset: 'uk' }) };
+});
+/**
+ * Ukrainian-specific characters pick the Ukrainian preset; all other Cyrillic
+ * romanizes as Russian. Applied per line, so a mixed-language song switches
+ * preset line by line.
+ */
+export function selectCyrillicPreset(line) {
+    return /[іїєґ]/i.test(line) ? 'uk' : 'ru';
 }
 class DefaultRomanizer {
     japaneseDictPath;
-    kuroshiroReady = null;
-    jyutpingReady = null;
+    engines;
+    loadKuroshiro = lazy(async () => {
+        const [kuroshiroModule, analyzerModule] = await Promise.all([
+            import('@sglkc/kuroshiro'),
+            import('@sglkc/kuroshiro-analyzer-kuromoji'),
+        ]);
+        const KuroshiroCtor = kuroshiroModule.default ?? kuroshiroModule;
+        const KuromojiAnalyzer = analyzerModule.default ?? analyzerModule;
+        const instance = new KuroshiroCtor();
+        await instance.init(new KuromojiAnalyzer({ dictPath: this.japaneseDictPath }));
+        return instance;
+    });
     constructor(options) {
         this.japaneseDictPath = options?.japaneseDictPath ?? DEFAULT_JAPANESE_DICT_PATH;
+        // Null-prototype: an out-of-contract script name from an untyped caller
+        // (e.g. 'toString') must miss the lookup rather than resolve to an
+        // inherited Object.prototype method and be invoked as an engine.
+        const engines = Object.assign(Object.create(null), this.buildDefaultEngines());
+        for (const [script, engine] of Object.entries(options?.engines ?? {})) {
+            if (engine)
+                engines[script] = engine;
+        }
+        this.engines = engines;
     }
     async romanizeLine(line, options) {
-        if (!line.trim() || !/\p{L}/u.test(line))
-            return line;
-        const script = options?.script ?? detectScript([line]);
-        if (script === 'latin')
-            return line;
-        if (requiresExternalRomanization(script)) {
-            throw new UnsupportedRomanizationError(script);
-        }
-        try {
-            switch (script) {
-                case 'japanese': {
-                    const k = await this.getKuroshiro();
-                    return k.convert(line, { to: 'romaji', mode: 'spaced' });
-                }
-                case 'chinese': {
-                    if (options?.dialect === 'cantonese') {
-                        try {
-                            const jyutping = await this.getJyutpingModule();
-                            const result = jyutping.getJyutpingText(line);
-                            if (result)
-                                return result;
-                        }
-                        catch {
-                            // fall through to pinyin
-                        }
-                    }
-                    return pinyin(line, { toneType: 'symbol', type: 'string' });
-                }
-                case 'korean':
-                    return romanizeKorean(line);
-                case 'cyrillic':
-                    return /[іїєґ]/i.test(line)
-                        ? cyrillicTranslitUk.transform(line)
-                        : cyrillicTranslitRu.transform(line);
-                case 'devanagari':
-                case 'gujarati':
-                case 'gurmukhi':
-                case 'telugu':
-                case 'kannada':
-                case 'odia': {
-                    const scheme = SANSCRIPT_SCHEME[script];
-                    if (!scheme)
-                        throw new Error(`Missing Sanscript scheme mapping for '${script}'.`);
-                    if (!Sanscript.schemes?.[scheme]) {
-                        throw new Error(`Sanscript does not support scheme '${scheme}' for '${script}'.`);
-                    }
-                    return Sanscript.t(line, scheme, 'iast');
-                }
-                case 'tamil':
-                    return romanizeTamil(line);
-                case 'thai':
-                    return romanizeThai(line);
-                default:
-                    return transliterate(line);
-            }
-        }
-        catch {
-            return transliterate(line);
-        }
+        const { text } = await this.resolveLine(line, options?.script, options);
+        return text;
     }
     async romanizeLines(lines, options) {
         const script = options?.script ?? detectScript(lines);
-        if (requiresExternalRomanization(script)) {
+        if (script !== 'latin' && !this.engines[script]) {
             throw new UnsupportedRomanizationError(script);
         }
         if (script === 'latin') {
-            return { script, lines: [...lines] };
+            return { script, lines: [...lines], fallbacks: lines.map(() => false) };
         }
-        const romanized = await Promise.all(lines.map((line) => this.romanizeLine(line, { script, dialect: options?.dialect })));
-        return { script, lines: romanized };
+        const resolved = await Promise.all(lines.map((line) => this.resolveLine(line, script, options)));
+        return {
+            script,
+            lines: resolved.map((r) => r.text),
+            fallbacks: resolved.map((r) => r.fallback),
+        };
     }
-    async getKuroshiro() {
-        if (!this.kuroshiroReady) {
-            this.kuroshiroReady = (async () => {
-                const instance = new Kuroshiro();
-                await instance.init(new KuromojiAnalyzer({
-                    dictPath: this.japaneseDictPath,
-                }));
-                return instance;
-            })().catch((error) => {
-                this.kuroshiroReady = null;
-                throw error;
-            });
+    async resolveLine(line, script, options) {
+        if (!line.trim() || !HAS_LETTER_RE.test(line))
+            return { text: line, fallback: false };
+        const resolved = script ?? detectScript([line]);
+        if (resolved === 'latin')
+            return { text: line, fallback: false };
+        // Checked before the latin guard below so that a script with no engine
+        // throws regardless of what the line contains — matching romanizeLines,
+        // which rejects such a script before looking at any line.
+        const engine = this.engines[resolved];
+        if (!engine)
+            throw new UnsupportedRomanizationError(resolved);
+        // A pinned script (romanizeLines, or an explicit option) skips per-line
+        // detection, so re-apply the latin no-op here: a line with ASCII letters
+        // and no character of any detectable script has nothing the pinned engine
+        // could romanize — without this, engines mangle it (pinyin-pro spaces
+        // "Hello" into "H e l l o").
+        if (ASCII_LETTER_RE.test(line) && !NON_LATIN_SCRIPT_RE.test(line)) {
+            return { text: line, fallback: false };
         }
-        return this.kuroshiroReady;
-    }
-    async getJyutpingModule() {
-        if (!this.jyutpingReady) {
-            this.jyutpingReady = import('to-jyutping').catch((e) => {
-                this.jyutpingReady = null;
-                throw e;
-            });
+        const context = { dialect: options?.dialect ?? 'mandarin' };
+        try {
+            return { text: await engine(line, context), fallback: false };
         }
-        return this.jyutpingReady;
+        catch {
+            // Universal-fallback policy: a failed engine (or engine load) must not
+            // keep lyrics from rendering. Degrade to plain transliteration and
+            // report it via RomanizeResult.fallbacks.
+            try {
+                const transliterate = await loadTransliterate();
+                return { text: transliterate(line), fallback: true };
+            }
+            catch {
+                // Even the universal engine is unavailable. Render the line as-is
+                // rather than failing the whole batch; the flag reports the degradation.
+                return { text: line, fallback: true };
+            }
+        }
+    }
+    // Total over EngineScript: adding a local script to ScriptType (or
+    // reclassifying one in SCRIPT_METADATA) is a compile error here until the
+    // engine row exists — there is no default arm to fall through silently.
+    buildDefaultEngines() {
+        const sanscriptEngine = (scheme) => async (line) => (await loadSanscript()).t(line, scheme, 'iast');
+        return {
+            japanese: async (line) => {
+                const kuroshiro = await this.loadKuroshiro();
+                return kuroshiro.convert(line, { to: 'romaji', mode: 'spaced' });
+            },
+            chinese: async (line, context) => {
+                if (context.dialect === 'cantonese') {
+                    try {
+                        const jyutping = await loadJyutping();
+                        const result = jyutping.getJyutpingText(line);
+                        if (result)
+                            return result;
+                    }
+                    catch {
+                        // fall through to pinyin
+                    }
+                }
+                const pinyin = await loadPinyin();
+                return pinyin(line, { toneType: 'symbol', type: 'string' });
+            },
+            korean: async (line) => (await loadKorean())(line),
+            cyrillic: async (line) => {
+                const translit = await loadCyrillicTranslit();
+                return translit[selectCyrillicPreset(line)].transform(line);
+            },
+            devanagari: sanscriptEngine('devanagari'),
+            gujarati: sanscriptEngine('gujarati'),
+            gurmukhi: sanscriptEngine('gurmukhi'),
+            telugu: sanscriptEngine('telugu'),
+            kannada: sanscriptEngine('kannada'),
+            odia: sanscriptEngine('oriya'),
+            tamil: async (line) => (await loadTamil())(line),
+            thai: async (line) => (await loadThai())(line),
+        };
     }
 }
 export function createRomanizer(options) {

package/dist/romanizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"romanizer.js","sourceRoot":"","sources":["../src/romanizer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"romanizer.js","sourceRoot":"","sources":["../src/romanizer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,14 +1,39 @@
 export type ScriptType = 'japanese' | 'chinese' | 'korean' | 'cyrillic' | 'devanagari' | 'gujarati' | 'gurmukhi' | 'telugu' | 'kannada' | 'odia' | 'tamil' | 'malayalam' | 'bengali' | 'arabic' | 'hebrew' | 'thai' | 'latin' | 'other';
+export type RomanizeEngineContext = {
+    /** Chinese romanization system. Every other built-in engine ignores it. */
+    dialect: 'mandarin' | 'cantonese';
+};
+/**
+ * An engine adapter: romanizes one line of its script. May be synchronous or
+ * asynchronous. Throwing (or rejecting) triggers the universal transliteration
+ * fallback, reported per line via `RomanizeResult.fallbacks`.
+ */
+export type RomanizeEngine = (line: string, context: RomanizeEngineContext) => string | Promise<string>;
 export type RomanizerOptions = {
     japaneseDictPath?: string;
+    /**
+     * Override the built-in engine for a script, or plug an engine for a script
+     * that has none built in (arabic, hebrew, malayalam, bengali, other).
+     * Scripts without an engine — built-in or injected — throw
+     * `UnsupportedRomanizationError`. Entries with an `undefined` value are
+     * ignored, as is a `latin` entry: latin text is always returned unchanged.
+     */
+    engines?: Partial<Record<ScriptType, RomanizeEngine>>;
 };
 export type RomanizeOptions = {
     script?: ScriptType;
+    /** Only honored for `chinese`; every other script ignores it. */
     dialect?: 'mandarin' | 'cantonese';
 };
 export type RomanizeResult = {
     script: ScriptType;
     lines: string[];
+    /**
+     * Aligned with `lines`: `true` where the script engine failed and the line
+     * was universally transliterated as a last resort. Always populated by this
+     * library; optional so existing code constructing results keeps compiling.
+     */
+    fallbacks?: boolean[];
 };
 export interface Romanizer {
     romanizeLine(line: string, options?: RomanizeOptions): Promise<string>;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,SAAS,GACT,QAAQ,GACR,UAAU,GACV,YAAY,GACZ,UAAU,GACV,UAAU,GACV,QAAQ,GACR,SAAS,GACT,MAAM,GACN,OAAO,GACP,WAAW,GACX,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,aAAa,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC7F;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,MAAM,EAAE,UAAU,CAAC;gBAEvB,MAAM,EAAE,UAAU;CAK/B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,SAAS,GACT,QAAQ,GACR,UAAU,GACV,YAAY,GACZ,UAAU,GACV,UAAU,GACV,QAAQ,GACR,SAAS,GACT,MAAM,GACN,OAAO,GACP,WAAW,GACX,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEZ,MAAM,MAAM,qBAAqB,GAAG;IAClC,2EAA2E;IAC3E,OAAO,EAAE,UAAU,GAAG,WAAW,CAAC;CACnC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAExG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,iEAAiE;IACjE,OAAO,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,aAAa,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC7F;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,MAAM,EAAE,UAAU,CAAC;IAEnC,YAAY,MAAM,EAAE,UAAU,EAI7B;CACF"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAuCA,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrC,MAAM,CAAa;IAEnC,YAAY,MAAkB;QAC5B,KAAK,CAAC,WAAW,MAAM,mCAAmC,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAkEA,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrC,MAAM,CAAa;IAEnC,YAAY,MAAkB;QAC5B,KAAK,CAAC,WAAW,MAAM,mCAAmC,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}