@gukhanmun/types 0.3.1 → 0.4.0-dev.236

package/README.md

@@ -40,13 +40,15 @@ conventions and output format. `GukhanmunOptions` is the options bag passed to
 `load()`; it covers preset, rendering, segmentation, numerals, initial sound
 law, homophone window, first-occurrence window, recovery, directives, and HTML
 options. `Gukhanmun` is the converter interface returned by `load()`, with
-`convert()` and `convertStream()` methods. `GukhanmunError` is the structured
-error class with a typed `code` property and a `chain` array of causes.
-
-`DictionarySource` describes how to supply a dictionary: as a
-`{ format, bytes }` record pointing to already-loaded binary data. `Format` is
-the input format selector: `"text/plain"`, `"text/html"`, `"text/markdown"`, or
-a `{ format: "text/markdown", gfm: boolean }` object.
+`convert()` and `stream()` methods. `GukhanmunError` is the structured error
+class with a typed `code` property and a `chain` array of causes.
+
+`DictionarySource` describes how to supply a dictionary, either as a
+`FileDictionarySource` (`{ format, data }` pointing at FST or CDB bytes, a URL,
+or a path) or as a `MapDictionarySource` (`{ entries }` with hanja, reading,
+positional reading, preference, and mark fields) for readings computed at
+runtime. `Format` is the input format selector: `"text"`, `"html"`,
+`"markdown"`, or a `{ format: "markdown", gfm: boolean }` object.
 
 All TSDoc comments live in this package as the single source of truth for the
 JavaScript API. Refer to the declarations in `index.ts` for the full details.

package/dist/index.d.ts

@@ -152,13 +152,39 @@ type HomophoneDetection = "context-local" | "dictionary-wide";
  */
 type Recovery = "strict" | "lenient";
 /**
- * A single dictionary entry returned by a dictionary lookup.
+ * A single dictionary entry: a hanja key with one hangul reading.
+ *
+ * Callers pass these in {@link MapDictionarySource.entries} to build a
+ * dictionary at runtime.  Fields mirror the Rust `ReadingCandidate` type plus
+ * the hanja key.
  */
 interface DictionaryEntry {
-  /** The hanja form (key), e.g. `"漢字"`. */
+  /** The hanja form (dictionary key), e.g. `"漢字"`. */
   readonly hanja: string;
-  /** The hangul reading, e.g. `"한자"`. */
+  /** The word-initial hangul reading, e.g. `"한자"`. */
   readonly reading: string;
+  /**
+   * The reading used when the match is not word-initial, when it differs from
+   * {@link reading}.  For example a `年代` entry with `reading: "연대"` and
+   * `suffixReading: "년대"` reads `1990年代` as `1990년대` but `年代` alone as
+   * `연대`.
+   *
+   * Corresponds to Rust `ReadingCandidate::suffix_reading`.
+   */
+  readonly suffixReading?: string;
+  /**
+   * Relative default preference for this reading within its hanja key, a
+   * non-negative integer.  Larger values win, so an entry listed twice with
+   * different preferences keeps competing readings and uses the higher one by
+   * default.  Absent means `0`.
+   *
+   * List order never selects the default: when two readings share a preference
+   * the tie is broken by reading spelling.  Set distinct preferences to choose
+   * a default deliberately.
+   *
+   * Corresponds to Rust `ReadingCandidate::preference`.
+   */
+  readonly preference?: number;
   /**
    * When `true`, the renderer should always show the original hanja
    * alongside the hangul reading, regardless of ambiguity.
@@ -186,7 +212,8 @@ interface DictionaryEntry {
  *   Deno 2.0+, and Bun only.  Throws in browser environments.
  *
  * At runtime, a `FileDictionarySource` is distinguished from other values by
- * the presence of a `format` property (`"format" in source`).
+ * the absence of an `entries` property (`"entries" in source` selects a
+ * {@link MapDictionarySource}).
  */
 interface FileDictionarySource {
   /**
@@ -207,16 +234,59 @@ interface FileDictionarySource {
    *   or in-memory bytes; supported in Node-API and (with `from_bytes`) in
    *   WASM builds that include the `cdb` feature.
    *
-   * The `"tsv"` format is reserved for future use; passing it throws
-   * `GukhanmunError` with code `"unsupported-content-type"`.
+   * The `"tsv"` format is reserved and never accepted.  Pass entries in memory
+   * through {@link MapDictionarySource} instead of compiling a table.
    */
   readonly format: "fst" | "cdb";
 }
+/**
+ * A dictionary built from entries computed at runtime, such as per-document
+ * reading overrides.
+ *
+ * Use this instead of compiling a TSV file with `gukhanmun-mkdict` when the
+ * entries do not exist on disk, for example in a browser, an edge runtime, or a
+ * site generator that derives entries per document.
+ *
+ * A source is distinguished from a {@link FileDictionarySource} by the presence
+ * of an `entries` property.
+ *
+ * @example
+ * ```ts
+ * import { stdictFst } from "@gukhanmun/stdict-fst";
+ * const g = await load({
+ *   dictionaries: [
+ *     {
+ *       entries: [
+ *         { hanja: "高橋", reading: "다카하시" },
+ *         { hanja: "東京", reading: "도쿄", preference: 10 },
+ *         { hanja: "年代", reading: "연대", suffixReading: "년대" },
+ *       ],
+ *     },
+ *     await stdictFst(),
+ *   ],
+ * });
+ * ```
+ */
+interface MapDictionarySource {
+  /**
+   * The entries of this dictionary.
+   *
+   * Repeated `hanja` keys append competing readings instead of replacing each
+   * other, and {@link DictionaryEntry.preference} decides which reading is the
+   * context-free default.  Several readings for one key also let the engine
+   * pick a reading from a following particle (`東京을` versus `東京를`).
+   *
+   * An empty list contributes nothing, which is a convenient way to express
+   * "this document has no overrides".
+   */
+  readonly entries: readonly DictionaryEntry[];
+}
 /**
  * A dictionary source accepted by {@link GukhanmunOptions.dictionaries}.
  *
- * Currently only {@link FileDictionarySource} (binary file / URL / path) is
- * supported.  Sources are tried in array order; the first match wins.
+ * Sources are tried in array order; the first match for a hanja key wins, and
+ * every source listed before a compiled dictionary overrides that dictionary
+ * for the keys it carries.
  *
  * @example
  * ```ts
@@ -224,7 +294,7 @@ interface FileDictionarySource {
  * const g = await load({ dictionaries: [await stdictFst()] });
  * ```
  */
-type DictionarySource = FileDictionarySource;
+type DictionarySource = FileDictionarySource | MapDictionarySource;
 /**
  * Fine-grained HTML preservation rules passed in
  * {@link GukhanmunOptions.html}.
@@ -446,6 +516,10 @@ interface GukhanmunOptions {
    * `@gukhanmun/loanwords-fst` or `@gukhanmun/loanwords-cdb`. Put user
    * dictionaries first, then loanwords, then the preset dictionaries.
    *
+   * Entries computed at runtime need no package and no `gukhanmun-mkdict` run:
+   * pass {@link MapDictionarySource} (`{ entries: [...] }`) at the position
+   * where those overrides should take precedence.
+   *
    * @see {@link DictionarySource}
    */
   readonly dictionaries?: readonly DictionarySource[];
@@ -624,4 +698,4 @@ declare class GukhanmunError extends Error {
   }[];
 }
 //#endregion
-export { ContextWindow, CustomPunctuationProfile, DelimiterStyle, DictionaryEntry, DictionarySource, Directives, ErrorCode, FileDictionarySource, Format, Gukhanmun, GukhanmunError, GukhanmunFactory, GukhanmunOptions, HanjaVariantSet, HomophoneDetection, HtmlOptions, NumeralStrategy, OriginalGloss, Preset, PunctuationPreset, Recovery, RenderMode, ResolvedPunctuationProfile, Segmentation, SpaceAfter, StopStyle, load };
+export { ContextWindow, CustomPunctuationProfile, DelimiterStyle, DictionaryEntry, DictionarySource, Directives, ErrorCode, FileDictionarySource, Format, Gukhanmun, GukhanmunError, GukhanmunFactory, GukhanmunOptions, HanjaVariantSet, HomophoneDetection, HtmlOptions, MapDictionarySource, NumeralStrategy, OriginalGloss, Preset, PunctuationPreset, Recovery, RenderMode, ResolvedPunctuationProfile, Segmentation, SpaceAfter, StopStyle, load };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gukhanmun/types",
-  "version": "0.3.1",
+  "version": "0.4.0-dev.236",
   "description": "TypeScript API contract for Gukhanmun (type declarations only, no runtime code).",
   "type": "module",
   "exports": {