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 { Isa, type Autocorrector } 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.