@kensio/pinyinjs 1.6.0 → 1.7.1

package/dist/search/candidates.js

@@ -0,0 +1,290 @@
+import { encodeReading } from "../dictionary/artifact.js";
+import { convertCharacters } from "../script/conversion.js";
+import { toCanonicalGlyphs } from "../script/glyphs.js";
+import { normaliseUmlaut, readSyllable, writeSyllable, } from "../syllable/syllable.js";
+import { applyToneMark, stripToneMarks } from "../tone/tone-mark.js";
+import { TONES } from "../tone/tone.js";
+import { readingKey } from "./reverse-index.js";
+/**
+ * What a query may write between syllables, all of which mean nothing here.
+ *
+ * The same set the matcher accepts, minus its meaning: `match` treats a written
+ * boundary as evidence, because a haystack it is filtering can be read more than
+ * one way. A reverse index is asked for one reading and answers with the words
+ * that have it, so `yin hang` and `yinhang` are the same question.
+ */
+const SEPARATORS = /[\s'’‘-]+/gu;
+/**
+ * A tone written as a digit, which is the last character of a syllable.
+ */
+const TONE_DIGIT = /^[0-5]$/u;
+/**
+ * Every tone a syllable that wrote none could be standing for.
+ */
+const TONE_DIGITS = ["1", "2", "3", "4", "5"];
+/**
+ * The umlaut the readings are written with, and the letter a keyboard has.
+ */
+const UMLAUT = "ü";
+const PLAIN_U = "u";
+/**
+ * The 儿化 suffix, which is the one letter a reading key keeps and a query may
+ * leave off.
+ */
+const ERHUA = "r";
+/**
+ * Put a typed query into both the forms a search needs.
+ *
+ * Case, spacing and the ways of writing ü are all noise on the way to the key,
+ * and the tone is noise there too — the index is keyed toneless. None of it is
+ * noise on the way to the *filter*, which is what honours a tone the query
+ * wrote, so the resolved spelling is kept alongside.
+ *
+ * A tone written as a mark counts here, unlike in `match`. The reason it cannot
+ * count there is that a mark says nothing about where its syllable ends and a
+ * half-typed query is exactly where that is unsettled; here the candidate's own
+ * reading says where every syllable ends, so the mark has somewhere to land.
+ */
+function readQuery(query) {
+    const written = normaliseUmlaut(query.normalize("NFC").toLowerCase()).replaceAll(SEPARATORS, "");
+    return { key: readingKey(stripToneMarks(written)), written };
+}
+/**
+ * Every way a typist may write one syllable of a stored reading.
+ *
+ * `shi4` is written `shi`, `shi4` or `shì`; `lü4` adds `lu` and `lu4`, since ü
+ * is not on the keyboard; and an 儿化 `wanr2` adds the whole set again with the
+ * r left off, because 玩儿 is `wanr` to one typist and `wan` to another.
+ *
+ * The r comes off only where the syllable really is 儿化. 儿 itself is `er2`,
+ * and letting that shed its r would answer `e` with 儿.
+ */
+function writingsOf(token) {
+    const digit = token.slice(-1);
+    const toned = TONE_DIGIT.test(digit);
+    const spelling = toned ? token.slice(0, -1) : token;
+    const syllable = readSyllable(token);
+    // A reading with no tone written cannot contradict one, so a query is free to
+    // write any. Every reading the shipped artifacts hold has a tone digit on it,
+    // so this is a case a hand-built dictionary reaches rather than a real one.
+    const tones = toned ? [digit] : TONE_DIGITS;
+    const written = new Set();
+    const add = (form) => {
+        const plain = form.replaceAll(UMLAUT, PLAIN_U);
+        written.add(form);
+        written.add(plain);
+        for (const tone of tones) {
+            written.add(`${form}${tone}`);
+            written.add(`${plain}${tone}`);
+        }
+        if (!toned) {
+            for (const tone of TONES) {
+                written.add(applyToneMark(form, tone));
+            }
+        }
+    };
+    add(spelling);
+    if (syllable !== undefined) {
+        written.add(writeSyllable(syllable, "marks"));
+        if (syllable.erhua === true) {
+            add(spelling.slice(0, -ERHUA.length));
+            written.add(writeSyllable({ ...syllable, erhua: false }, "marks"));
+        }
+    }
+    return [...written];
+}
+/**
+ * Whether a query spells a reading, syllable by syllable.
+ *
+ * Walked as a set of positions the query can have been read up to rather than
+ * one cursor, because a syllable can be written more than one way and the ways
+ * are different lengths: `wanr2` is `wan` or `wanr`, and only what follows says
+ * which was meant.
+ */
+function spells(query, reading, writings) {
+    let reached = new Set([0]);
+    for (const token of reading.split(" ")) {
+        let forms = writings.get(token);
+        if (forms === undefined) {
+            forms = writingsOf(token);
+            writings.set(token, forms);
+        }
+        const next = new Set();
+        for (const at of reached) {
+            for (const form of forms) {
+                if (query.startsWith(form, at)) {
+                    next.add(at + form.length);
+                }
+            }
+        }
+        if (next.size === 0) {
+            return false;
+        }
+        reached = next;
+    }
+    return reached.has(query.length);
+}
+/**
+ * The reading the dictionary itself reports for a word, in numbered spelling.
+ *
+ * Asked of the dictionary rather than re-derived, which is what makes the
+ * filter also the answer to the ghost keys: 校覈 is a key, `Dictionary.lookup`
+ * folds it to 校核 before it searches, and the reading that comes back is
+ * `jiao4 he2` rather than the `xiao4 he2` the raw key derives to. So a candidate
+ * the dictionary would disown does not survive being checked against it.
+ */
+function readingOf(index, word) {
+    const entry = index.dictionary.lookup(word);
+    /* c8 ignore next -- only asked of a canonical key, which always looks up */
+    return entry === undefined ? "" : encodeReading(entry.reading);
+}
+/**
+ * The positions in every group a query can reach, likeliest first.
+ *
+ * Two groups, not one: the query as typed, and the query with the 儿化 r on the
+ * end. `wan` has to reach 玩儿 as well as 玩, and the r is kept in the key so
+ * that `wanr` can still reach only 玩儿. Whatever the second group brings in is
+ * then made honest by the filter, which is what stops `e` answering with 儿.
+ */
+function rankedPositions(index, key) {
+    const found = [
+        ...index.positionsFor(key),
+        ...index.positionsFor(`${key}${ERHUA}`),
+    ];
+    // Both groups are already ranked, so this only has to interleave them. Sorted
+    // rather than merged because the comparison is one array read and the lists
+    // are short: the busiest reading in the full dictionary has 805 words in it.
+    return found.toSorted((left, right) => index.dictionary.frequencyAt(right) - index.dictionary.frequencyAt(left));
+}
+/**
+ * Keep one writing of a word where the group holds both scripts.
+ *
+ * Paired by 简体 form in both directions rather than by converting toward the
+ * preference, because simplification is many-to-one and so the 简体 form is the
+ * one both writings agree on. Going the other way needs a reading to tell 發
+ * from 髮, and a pair that failed to meet would simply be left as two.
+ *
+ * The kept writing takes the rank of the better-placed of the two, so
+ * collapsing a list never reorders what is left of it.
+ */
+function preferScript(words, script) {
+    /** Whether a candidate is the writing the caller asked for. */
+    const isWanted = (word, simplified) => script.prefer === "Hans" ? word === simplified : word !== simplified;
+    const chosen = new Map();
+    const order = [];
+    for (const word of words) {
+        const simplified = convertCharacters(script.tables.toSimplified, word);
+        const held = chosen.get(simplified);
+        if (held === undefined) {
+            chosen.set(simplified, word);
+            order.push(simplified);
+            continue;
+        }
+        if (!isWanted(held, simplified) && isWanted(word, simplified)) {
+            chosen.set(simplified, word);
+        }
+    }
+    /* c8 ignore next -- every entry in `order` was put in `chosen` beside it */
+    return order.map((simplified) => chosen.get(simplified) ?? simplified);
+}
+/**
+ * The words a pinyin query could be spelling, likeliest first.
+ *
+ * ```ts
+ * candidates(index, "shi"); // 是, 时, 事, 使, 市, …
+ * candidates(index, "shi4"); // narrowed by tone
+ * candidates(index, "shì"); // the same, written the other way
+ * candidates(index, "yinhang"); // 銀行, 银行, 引吭, 引航, 印航
+ * ```
+ *
+ * This is the half of search that has no haystack: `match` filters Chinese text
+ * you already hold, and this answers a query with nothing but the dictionary
+ * behind it — pinyin-only lookup, a homophone list, or an input method for
+ * somebody with no Chinese keyboard.
+ *
+ * **A query is a whole reading, not a prefix.** `yinhang` finds 银行 and `yinha`
+ * finds nothing, because a reading key is a key rather than a stem. What a query
+ * may leave out is the parts a keyboard makes awkward: the tones, the ü, the
+ * spaces between syllables, and the r of 儿化.
+ *
+ * Both scripts are dictionary keys, so 银行 and 銀行 both come back unless a
+ * {@link ScriptPreference} says which to keep.
+ */
+export function candidates(index, query, options = {}) {
+    const { key, written } = readQuery(query);
+    if (key === "") {
+        return [];
+    }
+    const writings = new Map();
+    const found = [];
+    for (const position of rankedPositions(index, key)) {
+        const word = index.dictionary.wordAt(position);
+        // A key whose glyphs are not the canonical ones can never be returned by
+        // `Dictionary.lookup`, which folds them before it searches, so offering it
+        // would be offering 中峯 beside the 中峰 that is already here. 281 of the
+        // full tier's keys are like that, and dropping them at the query rather
+        // than the build is what makes it free: filtering the whole key list with
+        // `toCanonicalGlyphs` costs 52.9 ms, and filtering one answer costs nothing.
+        if (toCanonicalGlyphs(word) !== word) {
+            continue;
+        }
+        if (spells(written, readingOf(index, word), writings)) {
+            found.push(word);
+        }
+    }
+    const preferred = options.script === undefined ? found : preferScript(found, options.script);
+    return options.limit === undefined
+        ? preferred
+        : preferred.slice(0, Math.max(0, options.limit));
+}
+/**
+ * The other words read exactly as this one is, likeliest first.
+ *
+ * ```ts
+ * homophonesOf(index, "长城"); // 長城, 長程, 长程, 常程 — everything read chángchéng
+ * ```
+ *
+ * A homophone list wants the tone, where a typist's query does not, and it gets
+ * one without a second index: the toneless group is narrowed to the words whose
+ * stored reading is the same string. Over the eight busiest readings in the full
+ * dictionary — 4,659 candidates — that narrowing costs 1.2 ms in total.
+ *
+ * The word itself is never in its own list. Neither is its other-script writing
+ * where a {@link ScriptPreference} is given, since 銀行 is not a homophone of
+ * 银行 but the same word spelled for a different reader.
+ *
+ * Returns nothing for a word the dictionary does not hold, since a word with no
+ * reading has no homophones rather than all of them.
+ */
+export function homophonesOf(index, word, options = {}) {
+    const entry = index.dictionary.lookup(word);
+    if (entry === undefined) {
+        return [];
+    }
+    const reading = encodeReading(entry.reading);
+    const same = new Set([word, entry.word]);
+    if (options.script !== undefined) {
+        same.add(convertCharacters(options.script.tables.toSimplified, word));
+    }
+    const found = [];
+    for (const position of rankedPositions(index, readingKey(reading))) {
+        const candidate = index.dictionary.wordAt(position);
+        if (toCanonicalGlyphs(candidate) !== candidate) {
+            continue;
+        }
+        const pairing = options.script === undefined
+            ? candidate
+            : convertCharacters(options.script.tables.toSimplified, candidate);
+        if (same.has(candidate) || same.has(pairing)) {
+            continue;
+        }
+        if (readingOf(index, candidate) === reading) {
+            found.push(candidate);
+        }
+    }
+    const preferred = options.script === undefined ? found : preferScript(found, options.script);
+    return options.limit === undefined
+        ? preferred
+        : preferred.slice(0, Math.max(0, options.limit));
+}
+//# sourceMappingURL=candidates.js.map

package/dist/search/candidates.js.map

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

package/dist/search/match.d.ts

@@ -0,0 +1,72 @@
+import type { Dictionary } from "../dictionary/dictionary.js";
+/**
+ * A stretch of the haystack the query spelled out.
+ */
+export interface MatchRange {
+    /**
+     * Where it starts, in code points from the start of the haystack.
+     *
+     * Code points rather than UTF-16 units, exactly as `Segment.at` is, so that a
+     * character outside the basic plane counts as the one character it is.
+     */
+    readonly at: number;
+    /** How many characters it covers. */
+    readonly length: number;
+}
+/**
+ * What a query matched, and how well.
+ */
+export interface PinyinMatch {
+    /**
+     * The stretches of the haystack the query spelled, in order.
+     *
+     * Usually one. There is more than one where the query ran over something
+     * with no reading of its own: 北京·大学 is matched by `bjdx` as two ranges
+     * with the separator between them left out, so that highlighting them marks
+     * what was matched rather than what lay between.
+     */
+    readonly ranges: readonly MatchRange[];
+    /**
+     * How good the match is, where higher is better.
+     *
+     * For ordering the haystacks one query matched — sort descending and the
+     * best is first. Comparable within a query and not across queries: what it
+     * weighs is described at {@link CONTEXT_READING}, and none of it is a
+     * probability.
+     */
+    readonly score: number;
+}
+/**
+ * Find where a pinyin query matches a Chinese text, for filtering and
+ * highlighting.
+ *
+ * ```ts
+ * match(dictionary, "北京大学", "bjdx")?.ranges; // [{ at: 0, length: 4 }]
+ * ```
+ *
+ * The query is what somebody types on a Latin keyboard with no Chinese input
+ * method in front of them: full syllables joined or spaced, `beijing` and
+ * `bei jing`; initials, `bj`; the two mixed, `beij` and `bjing`; tones as
+ * digits where they are worth writing, `bei3jing1`; and `v` or `u:` for ü.
+ * Returns undefined where none of it matches.
+ *
+ * **No index is built and none is needed.** The haystack is Chinese, so the
+ * query is tested as a path over each character's readings rather than the text
+ * being spelled out in advance and searched — which is what makes every reading
+ * of a polyphone matchable rather than whichever one a default table picked.
+ * 行 is found by `xing` and by `hang`, and 长江 by `cj` as well as by `zj`.
+ *
+ * The reading the decoder settles on in context is then what ranks them, so the
+ * one that reads correctly here sorts above the one that merely could:
+ *
+ * ```ts
+ * const scoreOf = (query: string) => match(dictionary, "银行", query)?.score;
+ * scoreOf("yh") > scoreOf("yx"); // true — 银行 is yínháng, not yínxíng
+ * ```
+ *
+ * Ranges rather than a boolean, so that a caller can mark what matched, in code
+ * points from the start of the text. Everything this needs is in the `core`
+ * dictionary, so a page that never loads a word list can still do it.
+ */
+export declare function match(dictionary: Dictionary, haystack: string, query: string): PinyinMatch | undefined;
+//# sourceMappingURL=match.d.ts.map

package/dist/search/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/search/match.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAe9D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AA+cD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,KAAK,CACnB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,WAAW,GAAG,SAAS,CAMzB"}