@gukhanmun/napi 0.1.0-dev.0

package/dist/index.js

@@ -0,0 +1,272 @@
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region index.ts
+/**
+* @module
+*
+* Node.js native addon (napi-rs) implementation of the Gukhanmun
+* hanja-to-hangul converter.
+*
+* Provides the same `{@link load}` / `{@link Gukhanmun}` contract as
+* `@gukhanmun/wasm` but uses a precompiled native addon for maximum
+* throughput.  Node.js 20+ is required.  The native addon binary
+* (`gukhanmun_napi.node`) must be present in the package directory; build it
+* locally with `mise run napi-build`.
+*
+* The `load()` factory is asynchronous for API uniformity with the WASM
+* backend, but the native addon is synchronously ready — dictionary data is
+* the only async part.
+*
+* @example
+* ```ts
+* import { load } from "@gukhanmun/napi";
+* import { stdictFst } from "@gukhanmun/stdict-fst";
+*
+* const g = await load({ dictionaries: [await stdictFst()] });
+* console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
+* ```
+*/
+/** Returns the platform-specific optional-dependency package name. */
+function detectPlatformPackage() {
+	const map = {
+		"darwin-arm64": "aarch64-apple-darwin",
+		"darwin-x64": "x86_64-apple-darwin",
+		"win32-arm64": "aarch64-pc-windows-msvc",
+		"win32-x64": "x86_64-pc-windows-msvc",
+		"linux-arm64": "aarch64-unknown-linux-musl",
+		"linux-x64": "x86_64-unknown-linux-musl"
+	};
+	const key = `${process.platform}-${process.arch}`;
+	const target = map[key];
+	if (!target) throw new Error(`No prebuilt @gukhanmun/napi binary for ${key}`);
+	return `@gukhanmun/napi-${target}`;
+}
+/**
+* Loads the native addon at module initialisation time.
+*
+* When installed from npm the platform-specific optional dependency is tried
+* first.  Falls back to a locally-built binary (produced by
+* `mise run napi-build`) for development.
+*/
+const nativeAddon = (() => {
+	const req = createRequire(import.meta.url);
+	try {
+		return req(detectPlatformPackage());
+	} catch {
+		try {
+			return req("./gukhanmun_napi.node");
+		} catch {
+			return req("../gukhanmun_napi.node");
+		}
+	}
+})();
+/**
+* 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;
+	}
+};
+/**
+* Converts a raw error thrown at the NAPI boundary into a `GukhanmunError`.
+*
+* napi-rs encodes structured errors as JSON in the `message` field:
+* `{"code":"…","message":"…","chain":[…]}`.
+*/
+function liftNapiError(raw) {
+	if (raw instanceof GukhanmunError) return raw;
+	if (raw instanceof Error) try {
+		const parsed = JSON.parse(raw.message);
+		if (typeof parsed.code === "string") return new GukhanmunError(parsed.code, typeof parsed.message === "string" ? parsed.message : raw.message, Array.isArray(parsed.chain) ? parsed.chain : []);
+	} catch {}
+	return new GukhanmunError("internal", String(raw));
+}
+async function resolveDictionary(source) {
+	let bytes;
+	if (source.data instanceof ArrayBuffer) bytes = Buffer.from(source.data);
+	else if (ArrayBuffer.isView(source.data)) {
+		const view = source.data;
+		bytes = Buffer.from(view.buffer, view.byteOffset, view.byteLength);
+	} else {
+		let url;
+		if (source.data instanceof URL) url = source.data;
+		else {
+			const str = String(source.data);
+			url = str.includes("://") ? new URL(str) : pathToFileURL(str);
+		}
+		if (url.protocol === "file:") try {
+			bytes = await readFile(fileURLToPath(url));
+		} catch (e) {
+			throw new GukhanmunError("dictionary-load", `Failed to read dictionary: ${e instanceof Error ? e.message : String(e)}`);
+		}
+		else {
+			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}`);
+			bytes = Buffer.from(await response.arrayBuffer());
+		}
+	}
+	return {
+		format: source.format,
+		bytes
+	};
+}
+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"
+	};
+}
+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;
+}
+/** Internal implementation of the `Gukhanmun` contract backed by the native addon. */
+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 ? JSON.stringify(format) : null);
+		} catch (e) {
+			throw liftNapiError(e);
+		}
+	}
+	/**
+	* Returns a `TransformStream` that converts string chunks.
+	*
+	* Chunks are buffered internally; all output is produced 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) {
+		const formatJson = format != null ? JSON.stringify(format) : null;
+		let streamHandle;
+		try {
+			streamHandle = this.#handle.openStream(formatJson);
+		} catch (e) {
+			throw liftNapiError(e);
+		}
+		const handle = this.#handle;
+		return new TransformStream({
+			transform(chunk, controller) {
+				const out = handle.streamPush(streamHandle, chunk);
+				if (out) controller.enqueue(out);
+			},
+			flush(controller) {
+				try {
+					const out = handle.streamFinish(streamHandle);
+					if (out) controller.enqueue(out);
+				} catch (e) {
+					throw liftNapiError(e);
+				}
+			}
+		});
+	}
+};
+/**
+* Creates a Gukhanmun converter with the given options.
+*
+* The native addon is synchronously ready; dictionaries supplied via
+* `{@link GukhanmunOptions.dictionaries}` are fetched or read from disk 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 resolved = resolveOptions(options);
+	const dicts = await Promise.all((options.dictionaries ?? []).map(resolveDictionary));
+	const optionsJson = JSON.stringify(buildRawOptions(options, resolved));
+	let handle;
+	try {
+		handle = nativeAddon.NapiGukhanmun.load(optionsJson, dicts);
+	} catch (e) {
+		throw liftNapiError(e);
+	}
+	return new GukhanmunImpl(handle, resolved);
+}
+//#endregion
+export { GukhanmunError, load };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@gukhanmun/napi",
+  "version": "0.1.0-dev.0",
+  "description": "Node.js native addon (napi-rs) for the Gukhanmun hanja-to-hangul converter.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "optionalDependencies": {
+    "@gukhanmun/napi-aarch64-apple-darwin": "0.1.0-dev.0",
+    "@gukhanmun/napi-x86_64-apple-darwin": "0.1.0-dev.0",
+    "@gukhanmun/napi-aarch64-pc-windows-msvc": "0.1.0-dev.0",
+    "@gukhanmun/napi-x86_64-pc-windows-msvc": "0.1.0-dev.0",
+    "@gukhanmun/napi-aarch64-unknown-linux-musl": "0.1.0-dev.0",
+    "@gukhanmun/napi-x86_64-unknown-linux-musl": "0.1.0-dev.0"
+  },
+  "homepage": "https://github.com/dahlia/gukhanmun",
+  "bugs": "https://github.com/dahlia/gukhanmun/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/gukhanmun.git",
+    "directory": "packages/napi"
+  },
+  "license": "GPL-3.0-only",
+  "author": {
+    "name": "Hong Minhe (洪 民憙)",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "funding": "https://github.com/sponsors/dahlia",
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.0",
+    "deno": ">=2.0"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "korean",
+    "hanja",
+    "hangul",
+    "typography",
+    "napi"
+  ],
+  "peerDependencies": {
+    "@gukhanmun/types": "*"
+  },
+  "devDependencies": {
+    "@gukhanmun/types": "0.1.0-dev.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}