Autocorrect

isa.zyins.autocorrector corrects typos in free text using a typo map, preserving cursor position.

Default map: zyins spelling_corrections dataset. Load with isa.zyins.datasets.get().

Custom map: Pass a typo map to isa.autocorrector.create({ typoMap }) or override autocorrector at constructor time.

The Autocorrector interface

interface Autocorrector {
  correct(text: string, options: { mode: "keyup" | "submit" }): string;
}

correct() never throws. Empty input returns empty. Trailing whitespace is preserved — the cursor stays in place across edits.

Modes

The guards prevent over-correction mid-typing versus after commit. Use keyup while the user edits, and submit before sending to prequalify.

Quick start

import { Isa } from "isa-sdk";

const isa = await Isa.withBearer();

await isa.zyins.datasets.get();

const fixed = isa.zyins.autocorrector.correct("hyprtension", {
  mode: "submit",
});
// → 'HYPERTENSION'

Algorithm

The default is DefaultAutocorrector, an n-gram sliding window:

1. Uppercase input; tokenize on whitespace.
2. Slide contiguous n-grams (size 1 to word count) across the token list.
3. Look up each n-gram in typoMap and apply the mode-appropriate guard.
4. Replace matches; mark consumed positions.
5. Fill unmatched positions with the original (uppercased) word.
6. Reassemble with single-space separators and reattach trailing whitespace.

The instance is synchronous, dependency-free, and safe for concurrent use.

Custom typo maps

For a domain other than zyins — or to extend the default — use the
top-level kernel:

import { Isa } from "isa-sdk";

const isa = await Isa.withBearer();
const corrector = isa.autocorrector.create({
  typoMap: new Map([
    ["HYPRTENSION", "HYPERTENSION"],
    ["HIGH BLOOD PRESURE", "HIGH BLOOD PRESSURE"],
  ]),
  versionTag: "2026-05-29",
  onApplied: (e) => console.log("autocorrect", e),
});

corrector.correct("hyprtension", { mode: "submit" });

Keys must be normalized (uppercase, single-space-joined). The zyins autocorrector normalizes the dataset for you.

onApplied — analytics hook

Fires only when a correction changes the text:

import { Isa } from "isa-sdk";

const isa = await Isa.withBearer();
const customMap = new Map([["HYPRTENSION", "HYPERTENSION"]]);
const corrector = isa.autocorrector.create({
  typoMap: customMap,
  onApplied: ({ input, output, mode }) => {
    console.log("correction", { input, output, mode });
  },
});

The event carries input (pre-correction), output (post-correction), and mode. It fires before correct() returns.

versionTag — staleness detection

Identifies which bundle or data snapshot the corrector uses. The default zyins autocorrector tracks the bundle's version token; custom correctors set their own:

import { Isa } from "isa-sdk";

const isa = await Isa.withBearer();
const typoMap = new Map([["HYPRTENSION", "HYPERTENSION"]]);
const corrector = isa.autocorrector.create({
  typoMap,
  versionTag: "house-typos-2026-05-29",
});

console.log(corrector.versionTag); // → 'house-typos-2026-05-29'

Useful for detecting whether a corrector is bound to a frozen snapshot or a live bundle without comparing maps.

clone(overrides) — swap the map without losing state

Swap the typo map after a fresh bundle arrives without losing the onApplied listener:

import { Isa } from "isa-sdk";

const isa = await Isa.withBearer();
const corrector = isa.autocorrector.create({ typoMap: new Map() });
const freshMap = new Map([["HYPRTENSION", "HYPERTENSION"]]);
const fresh = corrector.clone({
  typoMap: freshMap,
  versionTag: "2026-06-01",
});

clone() copies onApplied and versionTag from the original unless overridden.

Replacing the autocorrector

Plug a custom implementation at constructor time:

import { type Autocorrector, Isa } from "isa-sdk";

class MyServerSideCorrector implements Autocorrector {
  correct(text: string, _options: { mode: "keyup" | "submit" }): string {
    // your call to a server-side spell service, sync interface required
    return text;
  }
}

const isa = await Isa.withBearer(undefined, undefined, {
  autocorrector: new MyServerSideCorrector(),
});

isa.zyins.autocorrector.correct("hyprtension", { mode: "submit" });
// → routes through MyServerSideCorrector

The override applies to all autocorrector surfaces: isa.zyins.autocorrector and isa.zyins.reference.autocorrector.

Migration from bpp2.0

The bpp2.0 useAutocorrect.js hook has been replaced. Use isa.zyins.autocorrector instead. See Migrating from v2 to v3.