@kensio/pinyinjs 1.7.4 → 1.7.5

package/dist/search/match-scoring.d.ts

@@ -0,0 +1,146 @@
+/**
+ * What ranking a match costs, and what a match is made of.
+ *
+ * The weights, the shape of a partial match, and the one decode the ranking
+ * leans on. `match.ts` searches; this says how the searching is scored.
+ */
+import type { Dictionary } from "../dictionary/dictionary.js";
+import type { Syllable } from "../syllable/syllable.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 match scores for reading its characters the way the text reads them.
+ *
+ * The one thing this has that a reverse index cannot: every reading a character
+ * takes is matchable, so 行 is found by both `xing` and `hang` — and the decoder
+ * has already settled which of them the text in front of it means. So 银行 ranks
+ * `yh` above `yx`, and 长江 ranks `cj` above `zj`, without either being refused.
+ *
+ * Weighted by the share of the matched characters that agree, rather than by how
+ * many, so that a long match and a short one are scored on the same scale.
+ */
+export declare const CONTEXT_READING = 4;
+/**
+ * What a match scores for starting where a word starts.
+ *
+ * 大学 in 北京大学 is the second half of a word a reader thinks of as one thing;
+ * 大学 in 大学生 starts it. Both are matches and the second is the better one.
+ */
+export declare const WORD_START = 2;
+/**
+ * What a match at the very start of the haystack scores, decaying with position.
+ *
+ * A tie-break rather than a judgement, and deliberately smaller than
+ * {@link WORD_START}: it settles two matches that are otherwise alike, and never
+ * outranks starting a word.
+ */
+export declare const EARLINESS = 1;
+/**
+ * What one character scores for being written out in full rather than initialled.
+ *
+ * Only used to choose between the ways one query can be read over one haystack,
+ * never in the score a caller sees: `beij` over 北京大学 is 北 spelled out and 京
+ * initialled, and no other reading of it is on offer. Where two are — `xian` is
+ * both 西安 and 县 — the fuller spelling is the one the typist meant.
+ *
+ * Per character, which is what settles 这儿 against `zher`: read as 这 `zhèr` it
+ * spells two characters out at once, where 这 abbreviated to `zh` and 儿 as `er`
+ * spells one of them and initials the other.
+ */
+export declare const SPELLED_OUT = 1;
+/**
+ * What one step down a character's reading list costs, likeliest reading first.
+ *
+ * The dictionary's own order, applied before the decoder has been asked
+ * anything: it is what separates 行 `xíng` from 行 `hàng` when the query could
+ * be either and the surrounding text says nothing.
+ */
+export declare const RARE_READING = 2;
+/**
+ * What crossing one character with no reading costs.
+ *
+ * A separator inside a name is worth stepping over — 北京·大学 is one thing
+ * with a mark in the middle of it — and a query that steps over half a line of
+ * Latin to reach its second half has found something more tenuous.
+ */
+export declare const CROSSED = 0.5;
+/**
+ * One character on the way through a match.
+ *
+ * What the query wrote for it is held as the stretch of the query it took
+ * rather than as the reading it was taken by, because the question ranking asks
+ * later is whether the reading the text settles on could have taken that same
+ * stretch — and a character often offers two readings that would.
+ */
+export interface Step {
+    readonly at: number;
+    /** Whether the query spelled this character, rather than stepping over it. */
+    readonly isRead: boolean;
+    /** Where in the query this character's spelling starts. */
+    readonly from: number;
+    /** Where the query has been read up to once it is taken. */
+    readonly next: number;
+}
+/**
+ * One way of reading a query over a stretch of the haystack.
+ */
+export interface Path {
+    readonly steps: readonly Step[];
+    /** What choosing this way of reading it is worth; see {@link SPELLED_OUT}. */
+    readonly score: number;
+}
+/**
+ * The query having been read to its end, with nothing left to account for.
+ */
+export declare const COMPLETE: Path;
+/**
+ * One reading a character can be matched by, and how much it covers.
+ */
+export interface Candidate {
+    readonly reading: readonly Syllable[];
+    /** How far down the character's list of readings it is. */
+    readonly rank: number;
+    /** How many characters it reads: two only for 儿化. */
+    readonly characters: number;
+}
+/**
+ * What the decoder made of the haystack, for ranking rather than for matching.
+ */
+export interface Context {
+    /**
+     * The reading the decoder settled on for each character.
+     *
+     * A syllable covering two characters is recorded against both of them, which
+     * is what 儿化 is: 玩儿 is `wánr`, and that one syllable is how the decoder
+     * read the 玩 and the 儿 alike. Undefined where the alignment does not work
+     * out at all.
+     */
+    readonly preferred: readonly (Syllable | undefined)[];
+    /** Where each of the decoder's words starts, in code points. */
+    readonly wordStarts: ReadonlySet<number>;
+}
+/**
+ * The steps of a match, gathered into the stretches they cover.
+ */
+export declare function rangesOf(steps: readonly Step[]): readonly MatchRange[];
+/**
+ * Ask the decoder what the haystack says, for the two things ranking needs.
+ *
+ * Worked out once a match is known to exist rather than before, because this is
+ * a decode of the whole text and matching is not: a search box filtering a list
+ * asks the cheap question of every item and pays for this on the few that hit.
+ */
+export declare function contextOf(dictionary: Dictionary, haystack: string): Context;
+//# sourceMappingURL=match-scoring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"match-scoring.d.ts","sourceRoot":"","sources":["../../src/search/match-scoring.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD;;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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,MAAM,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,IAA8B,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,EAAE,CAAC;IACtD,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,UAAU,EAAE,CActE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CA0B3E"}

package/dist/search/match-scoring.js

@@ -0,0 +1,114 @@
+import { sourcesOf } from "../decode/convert.js";
+import { segment } from "../decode/segment.js";
+import { toCharacters } from "../script/characters.js";
+/**
+ * What a match scores for reading its characters the way the text reads them.
+ *
+ * The one thing this has that a reverse index cannot: every reading a character
+ * takes is matchable, so 行 is found by both `xing` and `hang` — and the decoder
+ * has already settled which of them the text in front of it means. So 银行 ranks
+ * `yh` above `yx`, and 长江 ranks `cj` above `zj`, without either being refused.
+ *
+ * Weighted by the share of the matched characters that agree, rather than by how
+ * many, so that a long match and a short one are scored on the same scale.
+ */
+export const CONTEXT_READING = 4;
+/**
+ * What a match scores for starting where a word starts.
+ *
+ * 大学 in 北京大学 is the second half of a word a reader thinks of as one thing;
+ * 大学 in 大学生 starts it. Both are matches and the second is the better one.
+ */
+export const WORD_START = 2;
+/**
+ * What a match at the very start of the haystack scores, decaying with position.
+ *
+ * A tie-break rather than a judgement, and deliberately smaller than
+ * {@link WORD_START}: it settles two matches that are otherwise alike, and never
+ * outranks starting a word.
+ */
+export const EARLINESS = 1;
+/**
+ * What one character scores for being written out in full rather than initialled.
+ *
+ * Only used to choose between the ways one query can be read over one haystack,
+ * never in the score a caller sees: `beij` over 北京大学 is 北 spelled out and 京
+ * initialled, and no other reading of it is on offer. Where two are — `xian` is
+ * both 西安 and 县 — the fuller spelling is the one the typist meant.
+ *
+ * Per character, which is what settles 这儿 against `zher`: read as 这 `zhèr` it
+ * spells two characters out at once, where 这 abbreviated to `zh` and 儿 as `er`
+ * spells one of them and initials the other.
+ */
+export const SPELLED_OUT = 1;
+/**
+ * What one step down a character's reading list costs, likeliest reading first.
+ *
+ * The dictionary's own order, applied before the decoder has been asked
+ * anything: it is what separates 行 `xíng` from 行 `hàng` when the query could
+ * be either and the surrounding text says nothing.
+ */
+export const RARE_READING = 2;
+/**
+ * What crossing one character with no reading costs.
+ *
+ * A separator inside a name is worth stepping over — 北京·大学 is one thing
+ * with a mark in the middle of it — and a query that steps over half a line of
+ * Latin to reach its second half has found something more tenuous.
+ */
+export const CROSSED = 0.5;
+/**
+ * The query having been read to its end, with nothing left to account for.
+ */
+export const COMPLETE = { steps: [], score: 0 };
+/**
+ * The steps of a match, gathered into the stretches they cover.
+ */
+export function rangesOf(steps) {
+    const ranges = [];
+    for (const step of steps) {
+        if (!step.isRead) {
+            continue;
+        }
+        const last = ranges.at(-1);
+        if (last !== undefined && last.at + last.length === step.at) {
+            ranges[ranges.length - 1] = { at: last.at, length: last.length + 1 };
+            continue;
+        }
+        ranges.push({ at: step.at, length: 1 });
+    }
+    return ranges;
+}
+/**
+ * Ask the decoder what the haystack says, for the two things ranking needs.
+ *
+ * Worked out once a match is known to exist rather than before, because this is
+ * a decode of the whole text and matching is not: a search box filtering a list
+ * asks the cheap question of every item and pays for this on the few that hit.
+ */
+export function contextOf(dictionary, haystack) {
+    const preferred = [];
+    const wordStarts = new Set();
+    for (const word of segment(dictionary, haystack)) {
+        if (word.reading.length === 0) {
+            continue;
+        }
+        wordStarts.add(word.at);
+        // `sourcesOf` is the decoder's own answer to which characters a syllable
+        // reads, 儿化 included. It names the whole word and then nothing where it
+        // cannot say, which is not an alignment and is dropped rather than guessed.
+        const sources = sourcesOf(word.text, word.reading).filter((source) => source !== undefined);
+        if (sources.length !== word.reading.length) {
+            continue;
+        }
+        let at = word.at;
+        for (const [index, source] of sources.entries()) {
+            for (const _ of toCharacters(source)) {
+                preferred[at] = word.reading[index];
+                at++;
+            }
+        }
+    }
+    return { preferred, wordStarts };
+}
+//# sourceMappingURL=match-scoring.js.map

package/dist/search/match-scoring.js.map

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

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

@@ -0,0 +1,28 @@
+/**
+ * Walking a query over a haystack.
+ *
+ * The search is a walk over two sequences at once — the haystack's characters
+ * and the query's letters — where each character may account for some of the
+ * query in more than one way. `match.ts` is the one call that starts it.
+ */
+import type { Dictionary } from "../dictionary/dictionary.js";
+import { type PinyinMatch } from "./match-ranking.js";
+export type { PinyinMatch } from "./match-ranking.js";
+/**
+ * One query being read over one haystack.
+ *
+ * The search is a walk over two sequences at once — the haystack's characters
+ * and the query's letters — where each character may account for some of the
+ * query in more than one way, since it may have more than one reading and each
+ * reading may be written out or abbreviated. Memoised on the pair of positions,
+ * which is what stops the ways of splitting a long query multiplying out.
+ */
+export declare class Search {
+    #private;
+    constructor(dictionary: Dictionary, haystack: string, query: string);
+    /**
+     * The best match, or undefined where the query matches nowhere.
+     */
+    best(): PinyinMatch | undefined;
+}
+//# sourceMappingURL=match-search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"match-search.d.ts","sourceRoot":"","sources":["../../src/search/match-search.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAWjE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,MAAM;;IAQjB,YAAY,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAMlE;IAgGD;;OAEG;IACH,IAAI,IAAI,WAAW,GAAG,SAAS,CAK9B;CACF"}

package/dist/search/match-search.js

@@ -0,0 +1,128 @@
+import { toCharacters } from "../script/characters.js";
+import { chunksFor } from "./match-chunks.js";
+import { bestMatch } from "./match-ranking.js";
+import { CharacterReadings } from "./match-readings.js";
+import { skipSeparators } from "./query.js";
+import { COMPLETE, CROSSED, RARE_READING, SPELLED_OUT, } from "./match-scoring.js";
+/**
+ * One query being read over one haystack.
+ *
+ * The search is a walk over two sequences at once — the haystack's characters
+ * and the query's letters — where each character may account for some of the
+ * query in more than one way, since it may have more than one reading and each
+ * reading may be written out or abbreviated. Memoised on the pair of positions,
+ * which is what stops the ways of splitting a long query multiplying out.
+ */
+export class Search {
+    #dictionary;
+    #haystack;
+    #characters;
+    #query;
+    #readings;
+    #paths = new Map();
+    constructor(dictionary, haystack, query) {
+        this.#dictionary = dictionary;
+        this.#haystack = haystack;
+        this.#characters = toCharacters(haystack);
+        this.#readings = new CharacterReadings(dictionary, this.#characters);
+        this.#query = query;
+    }
+    /**
+     * The best way of reading the rest of the query from a character, or nothing.
+     */
+    #from(at, offset) {
+        const start = skipSeparators(this.#query, offset);
+        if (start === this.#query.length) {
+            return COMPLETE;
+        }
+        if (at >= this.#characters.length) {
+            return undefined;
+        }
+        const key = `${String(at)}:${String(start)}`;
+        const held = this.#paths.get(key);
+        if (held !== undefined || this.#paths.has(key)) {
+            return held;
+        }
+        const found = this.#read(at, start);
+        this.#paths.set(key, found);
+        return found;
+    }
+    /**
+     * Read one character, every way it can be read, and keep the best.
+     */
+    #read(at, start) {
+        const candidates = this.#readings.candidatesAt(at);
+        if (candidates.length === 0) {
+            return this.#cross(at, start);
+        }
+        let best;
+        for (const candidate of candidates) {
+            for (const chunk of chunksFor(this.#query, start, candidate.reading)) {
+                const rest = this.#from(at + candidate.characters, chunk.next);
+                if (rest === undefined) {
+                    continue;
+                }
+                const score = rest.score +
+                    (chunk.isFull ? SPELLED_OUT * candidate.characters : 0) -
+                    candidate.rank * RARE_READING;
+                if (best === undefined || score > best.score) {
+                    best = {
+                        steps: [
+                            ...Array.from({ length: candidate.characters }, (_, covered) => ({
+                                at: at + covered,
+                                isRead: true,
+                                from: start,
+                                next: chunk.next,
+                            })),
+                            ...rest.steps,
+                        ],
+                        score,
+                    };
+                }
+            }
+        }
+        return best;
+    }
+    /**
+     * Step over a character with no reading, which a match may span but not end
+     * on: the query is checked for having been read to its end first.
+     */
+    #cross(at, start) {
+        const rest = this.#from(at + 1, start);
+        return rest === undefined
+            ? undefined
+            : {
+                steps: [
+                    { at, isRead: false, from: start, next: start },
+                    ...rest.steps,
+                ],
+                score: rest.score - CROSSED,
+            };
+    }
+    /**
+     * Where the query matches at all, and how it reads at each of those places.
+     */
+    #everyMatch() {
+        const found = [];
+        for (const [at] of this.#characters.entries()) {
+            if (this.#readings.at(at).length === 0) {
+                continue;
+            }
+            const path = this.#from(at, 0);
+            if (path !== undefined) {
+                found.push(path);
+            }
+        }
+        return found;
+    }
+    /**
+     * The best match, or undefined where the query matches nowhere.
+     */
+    best() {
+        const found = this.#everyMatch();
+        return found.length === 0
+            ? undefined
+            : bestMatch(this.#dictionary, this.#haystack, this.#query, found);
+    }
+}
+//# sourceMappingURL=match-search.js.map

package/dist/search/match-search.js.map

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

package/dist/search/match.d.ts

@@ -1,41 +1,10 @@
-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.
+ * Finding where a pinyin query occurs in a Chinese text.
  */
-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;
-}
+import type { Dictionary } from "../dictionary/dictionary.js";
+import { type PinyinMatch } from "./match-search.js";
+export type { MatchRange } from "./match-scoring.js";
+export type { PinyinMatch } from "./match-search.js";
 /**
  * Find where a pinyin query matches a Chinese text, for filtering and
  * highlighting.

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

@@ -1 +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"}
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/search/match.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,KAAK,WAAW,EAAU,MAAM,mBAAmB,CAAC;AAE7D,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,KAAK,CACnB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,WAAW,GAAG,SAAS,CAMzB"}