alexxnica / hunspell-asm

WebAssembly based Javascript bindings for hunspell spellchecker

Hunspell-asm

Hunspell-asm is isomorphic javascript binding to hunspell spellchecker based on WebAssembly hunspell binary. This module aims to provide thin, lightweight interface to hunspell without requiring native modules.

Install

npm install hunspell-asm

Usage

Loading module asynchronously

Hunspell-asm relies on wasm binary (or asm.js where wasm is not supported) of hunspell, which need to be initialized first.

import { loadModule } from 'hunspell-asm';

const hunspellFactory = await loadModule();

loadModule loads wasm binary, initialize it, and returns factory function to create instance of hunspell.

loadModule(binaryEndpoint?: string, environment?: ENVIRONMENT): Promise<HunspellFactory>

It accepts binaryEndpoint as optional parameter for mainly browser environment. Unlike node, browser can't access wasm / asm binary directly in filesystem but have to fetch. Provide endpoints for paths to dist/src/lib/**/*.(wasm|mem) and it'll be fetched runtime. On node, this endpoint can be used to override physical path to binaries.

Additionally it accepts environment as well, allow to set running environment and ignores internal runtime detection. This is mostly for Electron's renderer process where node.js and fetch are available both, to selectively opt-in which way to use. It is important to note loadModule doesn't interop incorrect option value matching, like try to load correct binary when supply endpoint to file path with set env to browser.

Mounting files

Wasm binary uses different memory spaces allocated for its own and cannot access plain javascript object / or files directly. HunspellFactory provides few interfaces to interop physical file, or file contents into hunspell.

• mountDirectory(dirPath: string): string : (node.js only) Mount physical path. Once directory is mounted hunspell can read all files under mounted path. Returns virtual path to mounted path.
• mountBuffer(contents: ArrayBufferView, fileName?: string): string : Mount contents of file. Environment like browser which doesn't have access to filesystem can use this interface to create each file into memory.
• unmount(mountedFilePath: string) : Unmount path if it's exists in memory. If it's bufferFile created by mountBuffer, unmount will remove those file object in wasm memory as well.

All of virtual paths for mounted filesystem uses unix separator regardless of platform.

Creating spellchecker

Once you mounted dic / aff files you can create hunspell spellchecker instance via HunspellFactory::create. Each path for files are mounted path and should not be actual path or server endpoint.

create(affPath: string, dictPath: string): Hunspell

Hunspell exposes minimal interfaces to spellchecker.

• spell(word: string): boolean : Check spelling for word. False for misspelled, True otherwise.
• suggest(word: string): Array<string> : Get suggestion list for misspelled word. Empty if word is not misspelled or no suggestions.
• dispose(): void : Destroy current instance of hunspell. It is important to note created instance of hunspell will not be destroyed automatically.

There are simple examples for each environments using different apis. In each example directory do npm install && npm start.

Things to note

• Ensure all inputs (aff, dic, word for spell / suggest) are UTF-8 encoded correctly. While hunspell itself supports other encodings, all surrounding interfaces passing buffers are plain javascript doesn't detect / converts encodings automatically.

Building / Testing

Few npm scripts are supported for build / test code.

• build: Transpiles code to ES5 commonjs to dist.
• test: Run hunspell / hunspell-asm test both. Does not require build before execute test.
• test:hunspell: Run integration test for actual hunspell wasm binary, using hunspell's test case as-is.
• test:hunspell-asm: Run unit test against hunspell-asm interface
• lint: Run lint over all codebases
• lint:staged: Run lint only for staged changes. This'll be executed automatically with precommit hook.
• commit: Commit wizard to write commit message

License

• Hunspell: original license
• Hunspell-asm: MIT