@gukhanmun/napi 0.4.0-dev.235 → 0.4.0-dev.236

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -153,13 +153,39 @@ type HomophoneDetection = "context-local" | "dictionary-wide";
153
153
  */
154
154
  type Recovery = "strict" | "lenient";
155
155
  /**
156
- * A single dictionary entry returned by a dictionary lookup.
156
+ * A single dictionary entry: a hanja key with one hangul reading.
157
+ *
158
+ * Callers pass these in {@link MapDictionarySource.entries} to build a
159
+ * dictionary at runtime. Fields mirror the Rust `ReadingCandidate` type plus
160
+ * the hanja key.
157
161
  */
158
162
  interface DictionaryEntry {
159
- /** The hanja form (key), e.g. `"漢字"`. */
163
+ /** The hanja form (dictionary key), e.g. `"漢字"`. */
160
164
  readonly hanja: string;
161
- /** The hangul reading, e.g. `"한자"`. */
165
+ /** The word-initial hangul reading, e.g. `"한자"`. */
162
166
  readonly reading: string;
167
+ /**
168
+ * The reading used when the match is not word-initial, when it differs from
169
+ * {@link reading}. For example a `年代` entry with `reading: "연대"` and
170
+ * `suffixReading: "년대"` reads `1990年代` as `1990년대` but `年代` alone as
171
+ * `연대`.
172
+ *
173
+ * Corresponds to Rust `ReadingCandidate::suffix_reading`.
174
+ */
175
+ readonly suffixReading?: string;
176
+ /**
177
+ * Relative default preference for this reading within its hanja key, a
178
+ * non-negative integer. Larger values win, so an entry listed twice with
179
+ * different preferences keeps competing readings and uses the higher one by
180
+ * default. Absent means `0`.
181
+ *
182
+ * List order never selects the default: when two readings share a preference
183
+ * the tie is broken by reading spelling. Set distinct preferences to choose
184
+ * a default deliberately.
185
+ *
186
+ * Corresponds to Rust `ReadingCandidate::preference`.
187
+ */
188
+ readonly preference?: number;
163
189
  /**
164
190
  * When `true`, the renderer should always show the original hanja
165
191
  * alongside the hangul reading, regardless of ambiguity.
@@ -187,7 +213,8 @@ interface DictionaryEntry {
187
213
  * Deno 2.0+, and Bun only. Throws in browser environments.
188
214
  *
189
215
  * At runtime, a `FileDictionarySource` is distinguished from other values by
190
- * the presence of a `format` property (`"format" in source`).
216
+ * the absence of an `entries` property (`"entries" in source` selects a
217
+ * {@link MapDictionarySource}).
191
218
  */
192
219
  interface FileDictionarySource {
193
220
  /**
@@ -208,16 +235,59 @@ interface FileDictionarySource {
208
235
  * or in-memory bytes; supported in Node-API and (with `from_bytes`) in
209
236
  * WASM builds that include the `cdb` feature.
210
237
  *
211
- * The `"tsv"` format is reserved for future use; passing it throws
212
- * `GukhanmunError` with code `"unsupported-content-type"`.
238
+ * The `"tsv"` format is reserved and never accepted. Pass entries in memory
239
+ * through {@link MapDictionarySource} instead of compiling a table.
213
240
  */
214
241
  readonly format: "fst" | "cdb";
215
242
  }
243
+ /**
244
+ * A dictionary built from entries computed at runtime, such as per-document
245
+ * reading overrides.
246
+ *
247
+ * Use this instead of compiling a TSV file with `gukhanmun-mkdict` when the
248
+ * entries do not exist on disk, for example in a browser, an edge runtime, or a
249
+ * site generator that derives entries per document.
250
+ *
251
+ * A source is distinguished from a {@link FileDictionarySource} by the presence
252
+ * of an `entries` property.
253
+ *
254
+ * @example
255
+ * ```ts
256
+ * import { stdictFst } from "@gukhanmun/stdict-fst";
257
+ * const g = await load({
258
+ * dictionaries: [
259
+ * {
260
+ * entries: [
261
+ * { hanja: "高橋", reading: "다카하시" },
262
+ * { hanja: "東京", reading: "도쿄", preference: 10 },
263
+ * { hanja: "年代", reading: "연대", suffixReading: "년대" },
264
+ * ],
265
+ * },
266
+ * await stdictFst(),
267
+ * ],
268
+ * });
269
+ * ```
270
+ */
271
+ interface MapDictionarySource {
272
+ /**
273
+ * The entries of this dictionary.
274
+ *
275
+ * Repeated `hanja` keys append competing readings instead of replacing each
276
+ * other, and {@link DictionaryEntry.preference} decides which reading is the
277
+ * context-free default. Several readings for one key also let the engine
278
+ * pick a reading from a following particle (`東京을` versus `東京를`).
279
+ *
280
+ * An empty list contributes nothing, which is a convenient way to express
281
+ * "this document has no overrides".
282
+ */
283
+ readonly entries: readonly DictionaryEntry[];
284
+ }
216
285
  /**
217
286
  * A dictionary source accepted by {@link GukhanmunOptions.dictionaries}.
218
287
  *
219
- * Currently only {@link FileDictionarySource} (binary file / URL / path) is
220
- * supported. Sources are tried in array order; the first match wins.
288
+ * Sources are tried in array order; the first match for a hanja key wins, and
289
+ * every source listed before a compiled dictionary overrides that dictionary
290
+ * for the keys it carries.
221
291
  *
222
292
  * @example
223
293
  * ```ts
@@ -225,7 +295,7 @@ interface FileDictionarySource {
225
295
  * const g = await load({ dictionaries: [await stdictFst()] });
226
296
  * ```
227
297
  */
228
- type DictionarySource = FileDictionarySource;
298
+ type DictionarySource = FileDictionarySource | MapDictionarySource;
229
299
  /**
230
300
  * Fine-grained HTML preservation rules passed in
231
301
  * {@link GukhanmunOptions.html}.
@@ -447,6 +517,10 @@ interface GukhanmunOptions {
447
517
  * `@gukhanmun/loanwords-fst` or `@gukhanmun/loanwords-cdb`. Put user
448
518
  * dictionaries first, then loanwords, then the preset dictionaries.
449
519
  *
520
+ * Entries computed at runtime need no package and no `gukhanmun-mkdict` run:
521
+ * pass {@link MapDictionarySource} (`{ entries: [...] }`) at the position
522
+ * where those overrides should take precedence.
523
+ *
450
524
  * @see {@link DictionarySource}
451
525
  */
452
526
  readonly dictionaries?: readonly DictionarySource[];
@@ -647,9 +721,10 @@ declare class GukhanmunError extends Error {
647
721
  /**
648
722
  * Creates a Gukhanmun converter with the given options.
649
723
  *
650
- * The native addon is synchronously ready; dictionaries supplied via
651
- * `{@link GukhanmunOptions.dictionaries}` are fetched or read from disk and
652
- * passed to the Rust engine as `FileDictionarySource` values.
724
+ * The native addon is synchronously ready; compiled dictionaries supplied via
725
+ * `{@link GukhanmunOptions.dictionaries}` are fetched or read from disk, while
726
+ * `{@link MapDictionarySource}` entry lists are serialised and built in memory
727
+ * as Rust `MapDictionary` values.
653
728
  *
654
729
  * Note: unlike the Rust `ko-kr` preset, the JavaScript preset never includes a
655
730
  * bundled dictionary. Pass `dictionaries: [await stdictFst()]` to include the
@@ -662,4 +737,4 @@ declare class GukhanmunError extends Error {
662
737
  */
663
738
  declare function load(options?: GukhanmunOptions): Promise<Gukhanmun>;
664
739
  //#endregion
665
- 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 };
740
+ 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 CHANGED
@@ -113,7 +113,54 @@ function liftNapiError(raw) {
113
113
  } catch {}
114
114
  return new GukhanmunError("internal", String(raw));
115
115
  }
116
+ /** Rejects a source that is not an object before any property is read. */
117
+ function isRecord(value) {
118
+ return typeof value === "object" && value !== null;
119
+ }
120
+ /** The entry fields {@link DictionaryEntry} declares, in serialisation order. */
121
+ const DICTIONARY_ENTRY_FIELDS = [
122
+ "hanja",
123
+ "reading",
124
+ "suffixReading",
125
+ "preference",
126
+ "requireHanja",
127
+ "requireHangul"
128
+ ];
129
+ /**
130
+ * Encodes runtime dictionary entries for the native addon.
131
+ *
132
+ * Each entry is copied field by field, so a class instance exposing its
133
+ * properties through getters serialises the same values it presents, and any
134
+ * extra property a caller carries is dropped rather than rejected. The copy
135
+ * also keeps `NaN` and `±Infinity` preferences visible: `JSON.stringify` would
136
+ * erase them to `null`, which the Rust side reads as "absent".
137
+ */
138
+ function encodeEntries(entries) {
139
+ if (!Array.isArray(entries)) throw new GukhanmunError("invalid-input", "Dictionary 'entries' must be an array");
140
+ const records = [];
141
+ for (const [index, entry] of entries.entries()) {
142
+ if (!isRecord(entry)) {
143
+ records.push(entry);
144
+ continue;
145
+ }
146
+ const record = {};
147
+ for (const field of DICTIONARY_ENTRY_FIELDS) record[field] = entry[field];
148
+ const preference = record["preference"];
149
+ if (preference != null && !Number.isInteger(preference)) throw new GukhanmunError("invalid-input", `dictionary entry ${index} has a non-integer \`preference\`: ${String(preference)}`);
150
+ records.push(record);
151
+ }
152
+ try {
153
+ return JSON.stringify(records);
154
+ } catch (e) {
155
+ throw new GukhanmunError("invalid-input", `Dictionary entries are not serialisable: ${e instanceof Error ? e.message : String(e)}`);
156
+ }
157
+ }
116
158
  async function resolveDictionary(source) {
159
+ if (typeof source !== "object" || source === null) throw new GukhanmunError("invalid-input", "Each dictionary must be an object");
160
+ if ("entries" in source) {
161
+ if ("format" in source || "data" in source) throw new GukhanmunError("invalid-input", "A dictionary must not combine 'entries' with 'format' or 'data'");
162
+ return { entriesJson: encodeEntries(source.entries) };
163
+ }
117
164
  let bytes;
118
165
  if (source.data instanceof ArrayBuffer) bytes = Buffer.from(source.data);
119
166
  else if (ArrayBuffer.isView(source.data)) {
@@ -259,9 +306,10 @@ var GukhanmunImpl = class {
259
306
  /**
260
307
  * Creates a Gukhanmun converter with the given options.
261
308
  *
262
- * The native addon is synchronously ready; dictionaries supplied via
263
- * `{@link GukhanmunOptions.dictionaries}` are fetched or read from disk and
264
- * passed to the Rust engine as `FileDictionarySource` values.
309
+ * The native addon is synchronously ready; compiled dictionaries supplied via
310
+ * `{@link GukhanmunOptions.dictionaries}` are fetched or read from disk, while
311
+ * `{@link MapDictionarySource}` entry lists are serialised and built in memory
312
+ * as Rust `MapDictionary` values.
265
313
  *
266
314
  * Note: unlike the Rust `ko-kr` preset, the JavaScript preset never includes a
267
315
  * bundled dictionary. Pass `dictionaries: [await stdictFst()]` to include the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gukhanmun/napi",
3
- "version": "0.4.0-dev.235",
3
+ "version": "0.4.0-dev.236",
4
4
  "description": "Node.js native addon (napi-rs) for the Gukhanmun hanja-to-hangul converter.",
5
5
  "type": "module",
6
6
  "exports": {
@@ -14,12 +14,12 @@
14
14
  "dist"
15
15
  ],
16
16
  "optionalDependencies": {
17
- "@gukhanmun/napi-aarch64-apple-darwin": "0.4.0-dev.235+2861f4b",
18
- "@gukhanmun/napi-x86_64-apple-darwin": "0.4.0-dev.235+2861f4b",
19
- "@gukhanmun/napi-aarch64-pc-windows-msvc": "0.4.0-dev.235+2861f4b",
20
- "@gukhanmun/napi-x86_64-pc-windows-msvc": "0.4.0-dev.235+2861f4b",
21
- "@gukhanmun/napi-aarch64-unknown-linux-gnu": "0.4.0-dev.235+2861f4b",
22
- "@gukhanmun/napi-x86_64-unknown-linux-gnu": "0.4.0-dev.235+2861f4b"
17
+ "@gukhanmun/napi-aarch64-apple-darwin": "0.4.0-dev.236+75afc34",
18
+ "@gukhanmun/napi-x86_64-apple-darwin": "0.4.0-dev.236+75afc34",
19
+ "@gukhanmun/napi-aarch64-pc-windows-msvc": "0.4.0-dev.236+75afc34",
20
+ "@gukhanmun/napi-x86_64-pc-windows-msvc": "0.4.0-dev.236+75afc34",
21
+ "@gukhanmun/napi-aarch64-unknown-linux-gnu": "0.4.0-dev.236+75afc34",
22
+ "@gukhanmun/napi-x86_64-unknown-linux-gnu": "0.4.0-dev.236+75afc34"
23
23
  },
24
24
  "homepage": "https://github.com/dahlia/gukhanmun",
25
25
  "bugs": "https://github.com/dahlia/gukhanmun/issues",
@@ -61,7 +61,7 @@
61
61
  "@gukhanmun/types": "*"
62
62
  },
63
63
  "devDependencies": {
64
- "@gukhanmun/types": "0.4.0-dev.235+2861f4b"
64
+ "@gukhanmun/types": "0.4.0-dev.236+75afc34"
65
65
  },
66
66
  "scripts": {
67
67
  "build": "tsdown"