garu-ko 0.6.10 → 0.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Browser-native Korean morphological analyzer.** No server required.
 
-- **1.6MB model** bundled in npm package (no CDN needed)
+- **1.9MB model** bundled in npm package (no CDN needed)
 - **93KB WASM** engine -- runs in any modern browser
 - **F1 91.1%** on human-verified gold testset (vs. Kiwi 89.7%)
 - **< 1ms** inference per sentence
@@ -13,7 +13,7 @@
 
 |  | Kiwi | MeCab-ko | garu-ko |
 |---|---|---|---|
-| Model size | ~40MB | ~50MB | **1.6MB** |
+| Model size | ~40MB | ~50MB | **1.9MB** |
 | npm package | No | No | **Yes** |
 | F1 (gold testset) | 89.7% | — | **91.1%** |
 | F1 (NIKL MP) | 87.9% | ~85% | **93.7%** |
@@ -109,6 +109,28 @@ Returns surface-form strings only. Lightweight alternative to `analyze()`.
 
 Free WASM memory. Instance is unusable after this call.
 
+## Integrations
+
+Drop-in tokenizers for popular JS search libraries:
+
+- **[`garu-orama-tokenizer`](https://www.npmjs.com/package/garu-orama-tokenizer)** — Korean tokenization for [Orama](https://github.com/oramasearch/orama)
+- **[`garu-minisearch-tokenizer`](https://www.npmjs.com/package/garu-minisearch-tokenizer)** — Korean tokenization for [MiniSearch](https://github.com/lucaong/minisearch)
+
+Both solve the same problem: default tokenizers don't handle Korean particles or verb inflections, so `"먹다"` never matches `"먹었다"` and `"학교"` misses `"학교에"`. These adapters run morphological analysis so the inflections fall off before indexing.
+
+```ts
+import { create, insert, search } from '@orama/orama'
+import { createTokenizer } from 'garu-orama-tokenizer'
+
+const db = await create({
+  schema: { title: 'string' },
+  components: { tokenizer: await createTokenizer() }
+})
+await insert(db, { title: '학교에서 점심을 먹었다' })
+
+await search(db, { term: '먹다' })  // ← matches
+```
+
 ## Acknowledgments
 
 The morphological analysis model is trained on the **NIKL Morpheme-Tagged Corpus (v1.1)** provided by the National Institute of Korean Language (국립국어원). The model contains only derived frequency statistics, not original text.

package/dist/browser.d.ts

@@ -0,0 +1,13 @@
+import { GaruBase } from './core.js';
+import type { LoadOptions } from './core.js';
+export type { POS, Token, AnalyzeResult, AnalyzeOptions, NounsOptions, LoadOptions, ModelInfo, NormalizeOptions, Segment, } from './core.js';
+export { normalizeText, splitSentences } from './normalize.js';
+/**
+ * Browser-targeted Garu. Resolves WASM and model assets via `fetch` and
+ * `new URL(..., import.meta.url)`. Has no Node-only imports (`fs/promises`,
+ * `url`, `path`), so bundlers (Vite, Webpack, Rollup) emit a clean
+ * browser-only chunk.
+ */
+export declare class Garu extends GaruBase {
+    static load(options?: LoadOptions): Promise<Garu>;
+}

package/dist/browser.js

@@ -0,0 +1,42 @@
+import { GaruBase } from './core.js';
+export { normalizeText, splitSentences } from './normalize.js';
+/**
+ * Browser-targeted Garu. Resolves WASM and model assets via `fetch` and
+ * `new URL(..., import.meta.url)`. Has no Node-only imports (`fs/promises`,
+ * `url`, `path`), so bundlers (Vite, Webpack, Rollup) emit a clean
+ * browser-only chunk.
+ */
+export class Garu extends GaruBase {
+    static async load(options) {
+        // @ts-ignore dynamic WASM import
+        const wasmModule = await import('../pkg/garu_wasm.js');
+        await wasmModule.default();
+        let modelBytes;
+        if (options?.modelData) {
+            modelBytes = new Uint8Array(options.modelData);
+        }
+        else if (options?.modelUrl) {
+            const response = await fetch(options.modelUrl);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch model from ${options.modelUrl}: ${response.status} ${response.statusText}`);
+            }
+            modelBytes = new Uint8Array(await response.arrayBuffer());
+        }
+        else {
+            const url = new URL('../models/base.gmdl', import.meta.url).href;
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch model from ${url}: ${response.status} ${response.statusText}`);
+            }
+            modelBytes = new Uint8Array(await response.arrayBuffer());
+        }
+        const cnnUrl = new URL('../models/cnn2.bin', import.meta.url).href;
+        const cnnResp = await fetch(cnnUrl);
+        if (!cnnResp.ok) {
+            throw new Error(`Failed to fetch CNN model from ${cnnUrl}: ${cnnResp.status}`);
+        }
+        const cnnBytes = new Uint8Array(await cnnResp.arrayBuffer());
+        const wasmInstance = new wasmModule.GaruWasm(modelBytes, cnnBytes);
+        return new Garu(wasmInstance, modelBytes.byteLength + cnnBytes.byteLength);
+    }
+}

package/dist/{index.d.ts → core.d.ts}

@@ -28,19 +28,17 @@ export interface ModelInfo {
     size: number;
     accuracy: number;
 }
-export declare class Garu {
-    private _wasm;
-    private _loaded;
-    private _modelSize;
-    private constructor();
-    /**
-     * Load the WASM module and model data, returning a ready-to-use Garu instance.
-     *
-     * @param options.modelData - Provide model bytes directly as an ArrayBuffer
-     * @param options.modelUrl  - Fetch model from this URL
-     * If neither is provided, the model is fetched from the default CDN URL.
-     */
-    static load(options?: LoadOptions): Promise<Garu>;
+export declare const EMPTY_RESULT: AnalyzeResult;
+/**
+ * Shared analyzer instance. The browser/node entry points subclass this and
+ * provide their own `static load()` that resolves WASM and model bytes via
+ * environment-appropriate APIs (fetch vs fs).
+ */
+export declare class GaruBase {
+    protected _wasm: any;
+    protected _loaded: boolean;
+    protected _modelSize: number;
+    protected constructor(wasmInstance: any, modelSize: number);
     /**
      * Analyze Korean text, returning morphological tokens with scores.
      *

package/dist/core.js

@@ -0,0 +1,97 @@
+export { normalizeText, splitSentences } from './normalize.js';
+export const EMPTY_RESULT = Object.freeze({
+    tokens: [],
+    score: 0,
+    elapsed: 0,
+});
+/**
+ * Shared analyzer instance. The browser/node entry points subclass this and
+ * provide their own `static load()` that resolves WASM and model bytes via
+ * environment-appropriate APIs (fetch vs fs).
+ */
+export class GaruBase {
+    constructor(wasmInstance, modelSize) {
+        this._wasm = wasmInstance;
+        this._loaded = true;
+        this._modelSize = modelSize;
+    }
+    /**
+     * Analyze Korean text, returning morphological tokens with scores.
+     *
+     * When `options.topN` is greater than 1, returns an array of N-best results.
+     * Otherwise returns a single AnalyzeResult.
+     *
+     * Note: topN > 1 is not yet fully supported and may return fewer results.
+     */
+    analyze(text, options) {
+        if (!this._loaded) {
+            throw new Error('Garu instance has been destroyed');
+        }
+        const topN = options?.topN ?? 1;
+        if (topN > 1) {
+            if (text === '') {
+                return [{ ...EMPTY_RESULT, tokens: [] }];
+            }
+            return this._wasm.analyze_topn(text, topN);
+        }
+        if (text === '') {
+            return { ...EMPTY_RESULT, tokens: [] };
+        }
+        return this._wasm.analyze(text);
+    }
+    /**
+     * Quick tokenisation — returns an array of surface-form strings.
+     */
+    tokenize(text) {
+        if (!this._loaded) {
+            throw new Error('Garu instance has been destroyed');
+        }
+        if (text === '') {
+            return [];
+        }
+        return this._wasm.tokenize(text);
+    }
+    /**
+     * Extract nouns (NNG, NNP) from text.
+     * Set `options.includeSL` to also include foreign tokens (SL) like "AI", "BM25".
+     */
+    nouns(text, options) {
+        if (!this._loaded) {
+            throw new Error('Garu instance has been destroyed');
+        }
+        if (text === '') {
+            return [];
+        }
+        const result = this._wasm.analyze(text);
+        const includeSL = options?.includeSL ?? false;
+        return result.tokens
+            .filter((t) => t.pos === 'NNG' || t.pos === 'NNP' || (includeSL && t.pos === 'SL'))
+            .map((t) => t.text);
+    }
+    /**
+     * Whether the WASM analyzer is loaded and ready.
+     */
+    isLoaded() {
+        return this._loaded;
+    }
+    /**
+     * Return metadata about the loaded model.
+     */
+    modelInfo() {
+        return {
+            version: this._wasm.constructor.version(),
+            size: this._modelSize,
+            accuracy: 0.939,
+        };
+    }
+    /**
+     * Free the WASM instance and mark this Garu as unloaded.
+     */
+    destroy() {
+        if (this._wasm) {
+            this._wasm.free();
+            this._wasm = null;
+        }
+        this._loaded = false;
+    }
+}

package/dist/node.d.ts

@@ -0,0 +1,13 @@
+import { GaruBase } from './core.js';
+import type { LoadOptions } from './core.js';
+export type { POS, Token, AnalyzeResult, AnalyzeOptions, NounsOptions, LoadOptions, ModelInfo, NormalizeOptions, Segment, } from './core.js';
+export { normalizeText, splitSentences } from './normalize.js';
+/**
+ * Node-targeted Garu. Resolves WASM and model bytes via `fs/promises`.
+ * Browser code paths must not import this entry — use `garu-ko` directly
+ * (resolves via package.json conditional exports) or import from
+ * `garu-ko/browser`.
+ */
+export declare class Garu extends GaruBase {
+    static load(options?: LoadOptions): Promise<Garu>;
+}

package/dist/node.js

@@ -0,0 +1,39 @@
+import { GaruBase } from './core.js';
+export { normalizeText, splitSentences } from './normalize.js';
+/**
+ * Node-targeted Garu. Resolves WASM and model bytes via `fs/promises`.
+ * Browser code paths must not import this entry — use `garu-ko` directly
+ * (resolves via package.json conditional exports) or import from
+ * `garu-ko/browser`.
+ */
+export class Garu extends GaruBase {
+    static async load(options) {
+        // @ts-ignore dynamic WASM import
+        const wasmModule = await import('../pkg/garu_wasm.js');
+        const { readFile } = await import('fs/promises');
+        const { fileURLToPath } = await import('url');
+        const { join, dirname } = await import('path');
+        const dir = dirname(fileURLToPath(import.meta.url));
+        const wasmBytes = await readFile(join(dir, '..', 'pkg', 'garu_wasm_bg.wasm'));
+        await wasmModule.default(wasmBytes);
+        let modelBytes;
+        if (options?.modelData) {
+            modelBytes = new Uint8Array(options.modelData);
+        }
+        else if (options?.modelUrl) {
+            const response = await fetch(options.modelUrl);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch model from ${options.modelUrl}: ${response.status} ${response.statusText}`);
+            }
+            modelBytes = new Uint8Array(await response.arrayBuffer());
+        }
+        else {
+            const buf = await readFile(join(dir, '..', 'models', 'base.gmdl'));
+            modelBytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        const cnnBuf = await readFile(join(dir, '..', 'models', 'cnn2.bin'));
+        const cnnBytes = new Uint8Array(cnnBuf.buffer, cnnBuf.byteOffset, cnnBuf.byteLength);
+        const wasmInstance = new wasmModule.GaruWasm(modelBytes, cnnBytes);
+        return new Garu(wasmInstance, modelBytes.byteLength + cnnBytes.byteLength);
+    }
+}

package/package.json

@@ -1,10 +1,27 @@
 {
   "name": "garu-ko",
-  "version": "0.6.10",
-  "description": "Ultra-lightweight Korean morphological analyzer for the web (1.7MB model, WASM, F1 93.7%)",
+  "version": "0.7.0",
+  "description": "Ultra-lightweight Korean morphological analyzer for the web (1.9MB model, WASM, F1 93.9%)",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/node.js",
+  "browser": "dist/browser.js",
+  "types": "dist/node.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/node.d.ts",
+      "browser": "./dist/browser.js",
+      "node": "./dist/node.js",
+      "default": "./dist/node.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
   "files": [
     "dist",
     "pkg",

package/pkg/garu_wasm.js

@@ -85,7 +85,7 @@ export class GaruWasm {
     }
 }
 if (Symbol.dispose) GaruWasm.prototype[Symbol.dispose] = GaruWasm.prototype.free;
-import * as import1 from "./snippets/garu-core-e0c86c49c213a331/inline0.js"
+import * as import1 from "./snippets/garu-core-5657584039ad7577/inline0.js"
 
 function __wbg_get_imports() {
     const import0 = {
@@ -146,7 +146,7 @@ function __wbg_get_imports() {
     return {
         __proto__: null,
         "./garu_wasm_bg.js": import0,
-        "./snippets/garu-core-e0c86c49c213a331/inline0.js": import1,
+        "./snippets/garu-core-5657584039ad7577/inline0.js": import1,
     };
 }
 

package/pkg/package.json

@@ -1,7 +1,7 @@
 {
   "name": "garu-wasm",
   "type": "module",
-  "version": "0.6.10",
+  "version": "0.7.0",
   "files": [
     "garu_wasm_bg.wasm",
     "garu_wasm.js",

package/pkg/snippets/garu-core-5657584039ad7577/inline0.js

@@ -0,0 +1 @@
+export function performance_now() { return performance.now(); }

package/pkg/snippets/garu-core-c1b6130374165958/inline0.js

@@ -0,0 +1 @@
+export function performance_now() { return performance.now(); }

package/dist/index.js

@@ -1,167 +0,0 @@
-export { normalizeText, splitSentences } from './normalize.js';
-const isNode = typeof process !== 'undefined' &&
-    process.versions != null &&
-    process.versions.node != null;
-const EMPTY_RESULT = Object.freeze({
-    tokens: [],
-    score: 0,
-    elapsed: 0,
-});
-export class Garu {
-    constructor(wasmInstance, modelSize) {
-        this._wasm = wasmInstance;
-        this._loaded = true;
-        this._modelSize = modelSize;
-    }
-    /**
-     * Load the WASM module and model data, returning a ready-to-use Garu instance.
-     *
-     * @param options.modelData - Provide model bytes directly as an ArrayBuffer
-     * @param options.modelUrl  - Fetch model from this URL
-     * If neither is provided, the model is fetched from the default CDN URL.
-     */
-    static async load(options) {
-        // Dynamic import of the WASM glue module and initialise it
-        // @ts-ignore dynamic WASM import
-        const wasmModule = await import('../pkg/garu_wasm.js');
-        if (isNode) {
-            const { readFile } = await import('fs/promises');
-            const { fileURLToPath } = await import('url');
-            const { join, dirname } = await import('path');
-            const dir = dirname(fileURLToPath(import.meta.url));
-            const wasmBytes = await readFile(join(dir, '..', 'pkg', 'garu_wasm_bg.wasm'));
-            await wasmModule.default(wasmBytes);
-        }
-        else {
-            await wasmModule.default();
-        }
-        // Resolve model bytes
-        let modelBytes;
-        if (options?.modelData) {
-            modelBytes = new Uint8Array(options.modelData);
-        }
-        else if (options?.modelUrl) {
-            const response = await fetch(options.modelUrl);
-            if (!response.ok) {
-                throw new Error(`Failed to fetch model from ${options.modelUrl}: ${response.status} ${response.statusText}`);
-            }
-            modelBytes = new Uint8Array(await response.arrayBuffer());
-        }
-        else if (isNode) {
-            const { readFile } = await import('fs/promises');
-            const { fileURLToPath } = await import('url');
-            const { join, dirname } = await import('path');
-            const dir = dirname(fileURLToPath(import.meta.url));
-            const buf = await readFile(join(dir, '..', 'models', 'base.gmdl'));
-            modelBytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-        }
-        else {
-            const url = new URL('../models/base.gmdl', import.meta.url).href;
-            const response = await fetch(url);
-            if (!response.ok) {
-                throw new Error(`Failed to fetch model from ${url}: ${response.status} ${response.statusText}`);
-            }
-            modelBytes = new Uint8Array(await response.arrayBuffer());
-        }
-        // Load CNN reranker
-        let cnnBytes;
-        if (isNode) {
-            const { readFile } = await import('fs/promises');
-            const { fileURLToPath } = await import('url');
-            const { join, dirname } = await import('path');
-            const dir = dirname(fileURLToPath(import.meta.url));
-            const buf = await readFile(join(dir, '..', 'models', 'cnn2.bin'));
-            cnnBytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-        }
-        else {
-            const cnnUrl = new URL('../models/cnn2.bin', import.meta.url).href;
-            const cnnResp = await fetch(cnnUrl);
-            if (!cnnResp.ok) {
-                throw new Error(`Failed to fetch CNN model from ${cnnUrl}: ${cnnResp.status}`);
-            }
-            cnnBytes = new Uint8Array(await cnnResp.arrayBuffer());
-        }
-        // Construct the WASM analyzer with both models
-        const wasmInstance = new wasmModule.GaruWasm(modelBytes, cnnBytes);
-        return new Garu(wasmInstance, modelBytes.byteLength + cnnBytes.byteLength);
-    }
-    /**
-     * Analyze Korean text, returning morphological tokens with scores.
-     *
-     * When `options.topN` is greater than 1, returns an array of N-best results.
-     * Otherwise returns a single AnalyzeResult.
-     *
-     * Note: topN > 1 is not yet fully supported and may return fewer results.
-     */
-    analyze(text, options) {
-        if (!this._loaded) {
-            throw new Error('Garu instance has been destroyed');
-        }
-        const topN = options?.topN ?? 1;
-        if (topN > 1) {
-            if (text === '') {
-                return [{ ...EMPTY_RESULT, tokens: [] }];
-            }
-            return this._wasm.analyze_topn(text, topN);
-        }
-        if (text === '') {
-            return { ...EMPTY_RESULT, tokens: [] };
-        }
-        return this._wasm.analyze(text);
-    }
-    /**
-     * Quick tokenisation — returns an array of surface-form strings.
-     */
-    tokenize(text) {
-        if (!this._loaded) {
-            throw new Error('Garu instance has been destroyed');
-        }
-        if (text === '') {
-            return [];
-        }
-        return this._wasm.tokenize(text);
-    }
-    /**
-     * Extract nouns (NNG, NNP) from text.
-     * Set `options.includeSL` to also include foreign tokens (SL) like "AI", "BM25".
-     */
-    nouns(text, options) {
-        if (!this._loaded) {
-            throw new Error('Garu instance has been destroyed');
-        }
-        if (text === '') {
-            return [];
-        }
-        const result = this._wasm.analyze(text);
-        const includeSL = options?.includeSL ?? false;
-        return result.tokens
-            .filter((t) => t.pos === 'NNG' || t.pos === 'NNP' || (includeSL && t.pos === 'SL'))
-            .map((t) => t.text);
-    }
-    /**
-     * Whether the WASM analyzer is loaded and ready.
-     */
-    isLoaded() {
-        return this._loaded;
-    }
-    /**
-     * Return metadata about the loaded model.
-     */
-    modelInfo() {
-        return {
-            version: this._wasm.constructor.version(),
-            size: this._modelSize,
-            accuracy: 0.939,
-        };
-    }
-    /**
-     * Free the WASM instance and mark this Garu as unloaded.
-     */
-    destroy() {
-        if (this._wasm) {
-            this._wasm.free();
-            this._wasm = null;
-        }
-        this._loaded = false;
-    }
-}