@gukhanmun/wasm 0.1.0-dev.0

package/dist/index.js

@@ -0,0 +1,248 @@
+//#region index.ts
+function isNodeLike() {
+	return typeof globalThis.process?.versions?.node === "string";
+}
+/**
+* Error thrown by `{@link load}`, `{@link Gukhanmun.convert}`, and
+* `{@link Gukhanmun.stream}` when the Rust engine reports a failure.
+*
+* `code` identifies the failure class; `chain` carries the full causal chain
+* materialised at the FFI boundary so callers do not need additional round
+* trips.
+*/
+var GukhanmunError = class extends Error {
+	/**
+	* Machine-readable error code.
+	*
+	* @see {@link ErrorCode}
+	*/
+	code;
+	/**
+	* Full causal chain from the Rust `Error::source()` traversal, materialised
+	* at the FFI boundary.  The first element is the root cause; the last is
+	* the immediate error.
+	*/
+	chain;
+	/**
+	* Creates a new `GukhanmunError`.
+	*
+	* @param code - Machine-readable error code.
+	* @param message - Human-readable description.
+	* @param chain - Optional causal chain.
+	*/
+	constructor(code, message, chain = []) {
+		super(message);
+		this.name = "GukhanmunError";
+		this.code = code;
+		this.chain = chain;
+	}
+};
+let wasmInit;
+/**
+* Loads and caches the WASM module.  The module URL is resolved relative to
+* this source file so it works with Deno's module graph and `import.meta.url`.
+*
+* Node.js `fetch()` does not support `file://` URLs, so on Node.js the WASM
+* binary is read via `node:fs/promises` and passed directly as a `Uint8Array`
+* to the web-target init function, bypassing the streaming-fetch path.
+* Deno and Bun support `fetch()` for `file://` URLs and use the default path.
+*/
+function ensureWasm() {
+	if (!wasmInit) {
+		const glueHref = new URL("./wasm/web/gukhanmun_wasm.js", import.meta.url).href;
+		wasmInit = (async () => {
+			const mod = await import(glueHref);
+			if (isNodeLike()) {
+				const wasmUrl = new URL("./wasm/web/gukhanmun_wasm_bg.wasm", import.meta.url);
+				const buf = await (await import("node:fs/promises")).readFile(wasmUrl);
+				const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+				await mod.default({ module_or_path: bytes });
+			} else await mod.default();
+			return mod;
+		})();
+	}
+	return wasmInit;
+}
+async function resolveDictionary(source) {
+	if (source.data instanceof ArrayBuffer) return {
+		format: source.format,
+		bytes: new Uint8Array(source.data)
+	};
+	if (ArrayBuffer.isView(source.data)) {
+		const view = source.data;
+		return {
+			format: source.format,
+			bytes: new Uint8Array(view.buffer, view.byteOffset, view.byteLength)
+		};
+	}
+	let url;
+	if (source.data instanceof URL) url = source.data;
+	else {
+		const str = String(source.data);
+		if (str.includes("://")) url = new URL(str);
+		else if (isNodeLike()) url = (await import("node:url")).pathToFileURL(str);
+		else throw new GukhanmunError("invalid-input", "File path strings require a Node.js environment; use URL or ArrayBuffer in browsers");
+	}
+	if (isNodeLike() && url.protocol === "file:") {
+		const fs = await import("node:fs/promises");
+		let buf;
+		try {
+			buf = await fs.readFile(url);
+		} catch (e) {
+			throw new GukhanmunError("dictionary-load", `Failed to read dictionary: ${e instanceof Error ? e.message : String(e)}`);
+		}
+		return {
+			format: source.format,
+			bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+		};
+	}
+	let response;
+	try {
+		response = await fetch(url);
+	} catch (e) {
+		throw new GukhanmunError("dictionary-load", `Failed to fetch dictionary: ${e instanceof Error ? e.message : String(e)}`);
+	}
+	if (!response.ok) throw new GukhanmunError("dictionary-load", `Failed to fetch dictionary: HTTP ${response.status}`);
+	return {
+		format: source.format,
+		bytes: new Uint8Array(await response.arrayBuffer())
+	};
+}
+/** Internal implementation of the `Gukhanmun` contract. */
+var GukhanmunImpl = class {
+	#handle;
+	options;
+	constructor(handle, resolvedOpts) {
+		this.#handle = handle;
+		this.options = resolvedOpts;
+	}
+	/**
+	* Converts `source` in one shot.
+	*
+	* @param source - Input string.
+	* @param format - `"text"` (default), `"html"`, `"markdown"`, or
+	*   `{ format: "markdown"; gfm?: boolean }`.
+	* @returns Converted string.
+	* @throws {@link GukhanmunError} on conversion failure.
+	*/
+	convert(source, format) {
+		try {
+			return this.#handle.convert(source, format ?? null);
+		} catch (e) {
+			throw liftError(e);
+		}
+	}
+	/**
+	* Returns a `TransformStream` that converts string chunks.
+	*
+	* Chunks are buffered internally and the full conversion runs on `flush`.
+	* This satisfies batch-equivalence: the output of any chunk partition equals
+	* the output of `{@link convert}` on the concatenated input.
+	*
+	* @param format - Same as {@link convert}.
+	* @returns A `TransformStream<string, string>`.
+	*/
+	stream(format) {
+		let streamHandle;
+		try {
+			streamHandle = this.#handle.open_stream(format ?? null);
+		} catch (e) {
+			throw liftError(e);
+		}
+		return new TransformStream({
+			transform(chunk, controller) {
+				const out = streamHandle.push(chunk);
+				if (out) controller.enqueue(out);
+			},
+			flush(controller) {
+				try {
+					const out = streamHandle.finish();
+					if (out) controller.enqueue(out);
+				} catch (e) {
+					throw liftError(e);
+				} finally {
+					streamHandle.free();
+				}
+			}
+		});
+	}
+};
+/** Converts a raw error object thrown from the WASM boundary into a `GukhanmunError`. */
+function liftError(raw) {
+	if (raw instanceof GukhanmunError) return raw;
+	if (raw != null && typeof raw === "object") {
+		const obj = raw;
+		return new GukhanmunError(typeof obj["code"] === "string" ? obj["code"] : "internal", typeof obj["message"] === "string" ? obj["message"] : String(raw), Array.isArray(obj["chain"]) ? obj["chain"] : []);
+	}
+	return new GukhanmunError("internal", String(raw));
+}
+function resolveOptions(opts = {}) {
+	const preset = opts.preset ?? "ko-kr";
+	const koKp = preset === "ko-kp";
+	return {
+		preset,
+		rendering: opts.rendering ?? "hangul-only",
+		segmentation: opts.segmentation ?? "lattice",
+		numerals: opts.numerals ?? "hangul-phonetic",
+		initialSoundLaw: opts.initialSoundLaw ?? (koKp ? false : true),
+		homophoneWindow: opts.homophoneWindow ?? (koKp ? "off" : "per-block"),
+		firstOccurrenceWindow: opts.firstOccurrenceWindow ?? "off",
+		recovery: opts.recovery ?? "strict"
+	};
+}
+/**
+* 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.
+*
+* Note: unlike the Rust `ko-kr` preset, the JavaScript preset never includes a
+* bundled dictionary.  Pass `dictionaries: [await stdictFst()]` to include the
+* Standard Korean Language Dictionary.
+*
+* @param options - Conversion options.  All fields are optional; defaults match
+*   the `ko-kr` preset.
+* @returns A `{@link Gukhanmun}` instance.
+* @throws {@link GukhanmunError} on invalid options or dictionary load failure.
+*/
+async function load(options = {}) {
+	const wasm = await ensureWasm();
+	const resolved = resolveOptions(options);
+	const dicts = await Promise.all((options.dictionaries ?? []).map(resolveDictionary));
+	const rawOpts = buildRawOptions(options, resolved);
+	let handle;
+	try {
+		handle = new wasm.WasmGukhanmun(rawOpts, dicts);
+	} catch (e) {
+		throw liftError(e);
+	}
+	return new GukhanmunImpl(handle, resolved);
+}
+/** Builds the plain-object options passed across the WASM boundary. */
+function buildRawOptions(opts, resolved) {
+	const raw = {
+		preset: resolved.preset,
+		rendering: resolved.rendering,
+		segmentation: resolved.segmentation,
+		numerals: resolved.numerals,
+		initialSoundLaw: resolved.initialSoundLaw,
+		homophoneWindow: resolved.homophoneWindow,
+		firstOccurrenceWindow: resolved.firstOccurrenceWindow,
+		recovery: resolved.recovery
+	};
+	if (resolved.rendering === "original" && opts.originalGloss != null) raw["originalGloss"] = opts.originalGloss;
+	if (opts.directives != null) raw["directives"] = {
+		requireHanja: opts.directives.requireHanja ?? [],
+		requireHangul: opts.directives.requireHangul ?? [],
+		skipAnnotation: opts.directives.skipAnnotation ?? []
+	};
+	if (opts.html != null) raw["html"] = {
+		preserveClasses: opts.html.preserveClasses ?? [],
+		preserveAttributes: opts.html.preserveAttributes ?? []
+	};
+	return raw;
+}
+//#endregion
+export { GukhanmunError, load };

package/dist/wasm/deno/gukhanmun_wasm.d.ts

@@ -0,0 +1,68 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Owning hanja-to-hangul converter exposed to JavaScript.
+ *
+ * Construct via the `constructor` and keep the instance alive for the
+ * duration of all conversions.  Each call to [`WasmGukhanmun::open_stream`]
+ * borrows this instance via a reference count; calling `free()` on the JS
+ * side drops the Rust value when the last stream is also freed.
+ */
+export class WasmGukhanmun {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Converts `source` in one shot and returns the result string.
+     *
+     * `format` is `"text"` (default), `"html"`, `"markdown"`, or
+     * `{ format: "markdown", gfm?: boolean }`.  Throws a `GukhanmunError`
+     * on conversion failure.
+     */
+    convert(source: string, format: any): string;
+    /**
+     * Creates a new converter from a JS options object and an array of
+     * dictionary records.
+     *
+     * `options` is a JSON-serialisable `GukhanmunOptions` object (may be
+     * `null` / `undefined` for all-defaults).  `dictionaries` is a JS `Array`
+     * where each element is `{ format: "fst", bytes: Uint8Array }`.
+     *
+     * Throws a `GukhanmunError`-shaped object on invalid input or a failed
+     * dictionary load.
+     */
+    constructor(options: any, dictionaries: any);
+    /**
+     * Opens a streaming handle for chunked conversion.
+     *
+     * The caller must feed string chunks via [`WasmStream::push`] and call
+     * [`WasmStream::finish`] to flush the final output.  The batch-equivalence
+     * invariant holds: concatenating all `push` and `finish` return values
+     * equals the result of a single `convert` call on the concatenated input.
+     */
+    open_stream(format: any): WasmStream;
+}
+
+/**
+ * Chunked streaming handle produced by [`WasmGukhanmun::open_stream`].
+ *
+ * Accumulates string chunks and performs the full conversion at
+ * [`WasmStream::finish`].  This satisfies the batch-equivalence invariant:
+ * every arbitrary chunk partition of an input produces the same final output
+ * as a single [`WasmGukhanmun::convert`] call.
+ */
+export class WasmStream {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Converts the buffered input and returns the result.  Clears the buffer
+     * so the stream handle can be reused.
+     */
+    finish(): string;
+    /**
+     * Appends `chunk` to the internal buffer.  Returns an empty string; all
+     * output is deferred to [`WasmStream::finish`].
+     */
+    push(chunk: string): string;
+}