REFERENCE · API

JavaScript API

Package exports

The browser condition selects bundler ESM WASM; the Node condition selects the CommonJS WASM target. Both share the same TypeScript declarations.

Static assets are exported through raw subpaths and the @kfind/kfind/assets module based on new URL(relative, import.meta.url). The module resolves to an installed-package file: URL in Node.js and a content-hashed static asset URL in browser bundlers that support this pattern.

Asset self-hosting

componentResourceFileUrl points to the 35.4 MiB morphological-component verification asset from the exact installed package version. A browser bundler such as Vite emits it as a same-origin static asset in the SPA deployment. A Node.js server can pass the same export as a file: URL to createReadStream.

This compact index lets a smart plan verify same-POS component spans inside a source token and adjacent-token structure. It is not a whole-sentence analyzer or a full-POS dictionary for query expansion. The resolver does not choose a browser fetch or server route.

• Asset self-hosting operations

import { Kfind } from '@kfind/kfind';
import { componentResourceFileUrl } from '@kfind/kfind/assets';

const response = await fetch(componentResourceFileUrl);
if (!response.ok) throw new Error(`component resource: ${response.status}`);
const engine = Kfind.withResources({
  component: new Uint8Array(await response.arrayBuffer()),
});

Kfind and Matcher

Kfind.withResources({ fullPos?, enrichedPredicates?, component? }) creates a complete profile. compile(query, options) returns a reusable Matcher.

The API never guesses filesystem paths or URLs. Callers pass resource strings or Uint8Array values.

import { Kfind } from '@kfind/kfind';

const engine = new Kfind();
const matcher = engine.compile('걷다', { pos: 'verb' });
const matches = matcher.findAll('길을 걸어 갔다.');

findAllLimit(text, maxMatches) throws if more matches exist than the limit. findAt(text, offset) returns the first match at or after a UTF-16 offset, or null. findAllWithDiagnostics(text) returns the matches and structuralVerificationIncomplete.

UTF-16 spans

Match and atom start and end positions use UTF-16 code units and can be passed directly to JavaScript slice. An offset after an emoji is not a code-point count. findAt rejects an offset inside a surrogate pair.

Every atom preserves core, token, and all analysisIndex and rulePath origins. Matches from grouped or phrase alternatives include queryAtomIndices, identifying the original query atom chosen for each matched atom.