@gukhanmun/wasm 0.3.1 → 0.4.0-dev.236

package/dist/index.d.ts

@@ -153,13 +153,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.
@@ -187,7 +213,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 {
   /**
@@ -208,16 +235,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
@@ -225,7 +295,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}.
@@ -447,6 +517,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[];
@@ -648,9 +722,10 @@ declare class GukhanmunError extends Error {
  * Creates a Gukhanmun converter with the given options.
  *
  * Initialises the WASM module on the first call (subsequent calls reuse the
- * cached module).  Dictionaries supplied via
- * `{@link GukhanmunOptions.dictionaries}` are fetched and passed to the Rust
- * engine as `FileDictionarySource` values.
+ * cached module).  Compiled dictionaries supplied via
+ * `{@link GukhanmunOptions.dictionaries}` are fetched, while
+ * `{@link MapDictionarySource}` entry lists are serialised and built in memory
+ * as Rust `MapDictionary` values.
  *
  * Note: unlike the Rust `ko-kr` preset, the JavaScript preset never includes a
  * bundled dictionary.  Pass `dictionaries: [await stdictFst()]` to include the
@@ -663,4 +738,4 @@ declare class GukhanmunError extends Error {
  */
 declare function load(options?: GukhanmunOptions): Promise<Gukhanmun>;
 //#endregion
-export { type ContextWindow, type CustomPunctuationProfile, type DelimiterStyle, type DictionaryEntry, type DictionarySource, type Directives, type ErrorCode, type FileDictionarySource, type Format, type Gukhanmun, GukhanmunError, type GukhanmunFactory, type GukhanmunOptions, type HanjaVariantSet, type HomophoneDetection, type HtmlOptions, type NumeralStrategy, type OriginalGloss, type Preset, type PunctuationPreset, type Recovery, type RenderMode, type ResolvedPunctuationProfile, type Segmentation, type SpaceAfter, type StopStyle, load };
+export { type ContextWindow, type CustomPunctuationProfile, type DelimiterStyle, type DictionaryEntry, type DictionarySource, type Directives, type ErrorCode, type FileDictionarySource, type Format, type Gukhanmun, GukhanmunError, type GukhanmunFactory, type GukhanmunOptions, type HanjaVariantSet, type HomophoneDetection, type HtmlOptions, type MapDictionarySource, type NumeralStrategy, type OriginalGloss, type Preset, type PunctuationPreset, type Recovery, type RenderMode, type ResolvedPunctuationProfile, type Segmentation, type SpaceAfter, type StopStyle, load };

package/dist/index.js

@@ -77,7 +77,54 @@ function ensureWasm() {
 	}
 	return wasmInit;
 }
+/** Rejects a source that is not an object before any property is read. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/** The entry fields {@link DictionaryEntry} declares, in serialisation order. */
+const DICTIONARY_ENTRY_FIELDS = [
+	"hanja",
+	"reading",
+	"suffixReading",
+	"preference",
+	"requireHanja",
+	"requireHangul"
+];
+/**
+* Encodes runtime dictionary entries for the WASM boundary.
+*
+* Each entry is copied field by field, so a class instance exposing its
+* properties through getters serialises the same values it presents, and any
+* extra property a caller carries is dropped rather than rejected.  The copy
+* also keeps `NaN` and `±Infinity` preferences visible: `JSON.stringify` would
+* erase them to `null`, which the Rust side reads as "absent".
+*/
+function encodeEntries(entries) {
+	if (!Array.isArray(entries)) throw new GukhanmunError("invalid-input", "Dictionary 'entries' must be an array");
+	const records = [];
+	for (const [index, entry] of entries.entries()) {
+		if (!isRecord(entry)) {
+			records.push(entry);
+			continue;
+		}
+		const record = {};
+		for (const field of DICTIONARY_ENTRY_FIELDS) record[field] = entry[field];
+		const preference = record["preference"];
+		if (preference != null && !Number.isInteger(preference)) throw new GukhanmunError("invalid-input", `dictionary entry ${index} has a non-integer \`preference\`: ${String(preference)}`);
+		records.push(record);
+	}
+	try {
+		return JSON.stringify(records);
+	} catch (e) {
+		throw new GukhanmunError("invalid-input", `Dictionary entries are not serialisable: ${e instanceof Error ? e.message : String(e)}`);
+	}
+}
 async function resolveDictionary(source) {
+	if (typeof source !== "object" || source === null) throw new GukhanmunError("invalid-input", "Each dictionary must be an object");
+	if ("entries" in source) {
+		if ("format" in source || "data" in source) throw new GukhanmunError("invalid-input", "A dictionary must not combine 'entries' with 'format' or 'data'");
+		return { entriesJson: encodeEntries(source.entries) };
+	}
 	if (source.data instanceof ArrayBuffer) return {
 		format: source.format,
 		bytes: new Uint8Array(source.data)
@@ -223,9 +270,10 @@ function resolveOptions(opts = {}) {
 * Creates a Gukhanmun converter with the given options.
 *
 * Initialises the WASM module on the first call (subsequent calls reuse the
-* cached module).  Dictionaries supplied via
-* `{@link GukhanmunOptions.dictionaries}` are fetched and passed to the Rust
-* engine as `FileDictionarySource` values.
+* cached module).  Compiled dictionaries supplied via
+* `{@link GukhanmunOptions.dictionaries}` are fetched, while
+* `{@link MapDictionarySource}` entry lists are serialised and built in memory
+* as Rust `MapDictionary` values.
 *
 * Note: unlike the Rust `ko-kr` preset, the JavaScript preset never includes a
 * bundled dictionary.  Pass `dictionaries: [await stdictFst()]` to include the

package/dist/wasm/deno/gukhanmun_wasm.js

@@ -301,6 +301,10 @@ function __wbg_get_imports() {
             const ret = arg0[arg1];
             return ret;
         },
+        __wbg_has_73740b27f436fed3: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.has(arg0, arg1);
+            return ret;
+        }, arguments); },
         __wbg_instanceof_ArrayBuffer_8f49811467741499: function(arg0) {
             let result;
             try {

package/dist/wasm/nodejs/gukhanmun_wasm.js

@@ -303,6 +303,10 @@ function __wbg_get_imports() {
             const ret = arg0[arg1];
             return ret;
         },
+        __wbg_has_73740b27f436fed3: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.has(arg0, arg1);
+            return ret;
+        }, arguments); },
         __wbg_instanceof_ArrayBuffer_8f49811467741499: function(arg0) {
             let result;
             try {

package/dist/wasm/nodejs/package.json

@@ -4,7 +4,7 @@
     "Hong Minhe (洪 民憙) <hong@minhee.org>"
   ],
   "description": "WebAssembly binding for Gukhanmun via wasm-bindgen.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",

package/dist/wasm/web/gukhanmun_wasm.js

@@ -301,6 +301,10 @@ function __wbg_get_imports() {
             const ret = arg0[arg1];
             return ret;
         },
+        __wbg_has_73740b27f436fed3: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.has(arg0, arg1);
+            return ret;
+        }, arguments); },
         __wbg_instanceof_ArrayBuffer_8f49811467741499: function(arg0) {
             let result;
             try {

package/dist/wasm/web/package.json

@@ -5,7 +5,7 @@
     "Hong Minhe (洪 民憙) <hong@minhee.org>"
   ],
   "description": "WebAssembly binding for Gukhanmun via wasm-bindgen.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gukhanmun/wasm",
-  "version": "0.3.1",
+  "version": "0.4.0-dev.236",
   "description": "WebAssembly implementation of the Gukhanmun hanja-to-hangul converter.",
   "type": "module",
   "exports": {
@@ -54,7 +54,7 @@
     "@gukhanmun/types": "*"
   },
   "devDependencies": {
-    "@gukhanmun/types": "0.3.1"
+    "@gukhanmun/types": "0.4.0-dev.236+75afc34"
   },
   "scripts": {
     "build": "tsdown && node -e \"const fs=require('node:fs'),p=require('node:path');fs.cpSync('wasm','dist/wasm',{recursive:true,force:true,filter:(s)=>p.basename(s)!=='.gitignore'})\""