[Feature request] Add docs for cspell-lib so that it's easier to use it as a library

I’m working on a node.js spell-checking service.

I was looking for a good and actively maintained JS spell-checking JS library. It turned out that the most popular lib - typo.js despite having lots of daily downloads is not actively developed. It isn’t very powerful either. Other libs I found suffer from the same issue.

I found that cspell is used internally by VSCode, so it seemed to be a perfect candidate, until I found it’s not intended to be used as a library. The main purpose, from what I see, is a command line tool.

I started diging into the source code and I found that scpell-lib is a pretty decent tool and has everything I need. Thanks to unit tests I was able to figure out how to put all the pieces together and developed a little proof-of-concept:

import {
  checkText,
  combineTextAndLanguageSettings,
  CompoundWordsMethod,
  createSpellingDictionary,
  finalizeSettings,
  getDefaultSettings,
  getDictionary,
} from 'cspell-lib';
import { SpellingDictionaryCollection } from 'cspell-lib/dist/SpellingDictionary';

/**
 * @param customWords
 * @return {Promise<function(*=): Promise<(null|string)[]>>}
 * @constructor
 */
export const SpellcheckerFactory = async (customWords = []) => {
  const settings = {
    // I'm not sure if I need the entire default settings object
    ...getDefaultSettings(),
    // I want to use the lib just for plain text. I'm not sure if this is the best way to disable programming languages spell-checking
    enabledLanguageIds: [],
  };

  // I'm not sure if passing '' as a second argument is correct
  const fileSettings = combineTextAndLanguageSettings(settings, '', ['plaintext']);
  const finalSettings = finalizeSettings(fileSettings);
  const [dictionary, customDictionary] = await Promise.all([
    // Is it OK to get dictionary before I initialize the custom dictionary?
    getDictionary(finalSettings),
    // I'm not sure if `name` and `source` attributes make any difference.
    createSpellingDictionary(
      customWords,
      'customDictionary',
      'customWords',
      undefined
    ),
  ])
  const dictionariesCollection = new SpellingDictionaryCollection(
    [customDictionary, dictionary],
    'dictionaries'
  );

  const getSuggestion = word => {
    const suggestions = dictionariesCollection.suggest(word, 1, CompoundWordsMethod.SEPARATE_WORDS);
    return suggestions.length ? suggestions[0].word : null;
  };

  return async phrase => {
    const checkedText = await checkText(phrase, fileSettings);
    const errors = checkedText.items.filter(({ isError }) => isError);

    return Promise.all(errors.map(({ text }) => getSuggestion(text)));
  };
};

import { checkSpelling } from './spelchecker';

describe('checkSpelling', () => {
  it('should check spelling', async () => {
    expect(await checkSpelling('zażułć gęśla jaśń')).toEqual(['zażółć', 'gęślą', 'jaźń']);
  });
});

The problem is that I have no idea if what I’m doing is right. It works, but most likely it could be done better/cleaner/more efficiently. I have several doubts - see the comments in the code.

It would be great if cspell-lib was documented. This lib seems to be the best spell-checking lib on the market. It would be nice if we could use it with ease.

[Jason3S]

Is it faster than the current solution that relies on SpellingDictionaryCollection? Are there any pros/cons of using one technique over another?

Adding it via words: will 1. Create a SpellingDictionary with your words. 2. Enable your words to be used by checkText.

Experiment with the command line app to get a feel for things. Everything is configuration driven.

[Jason3S]

@wujekbogdan,

Cool idea to create a service. There are a LOT of questions in this request.

A few tips:

Configuration / Settings are your friend

If your custom word list is static, then store it in a text file with one word per line. You can reference it in the settings:

Store all your custom dictionary / settings in a cspell.json or cspell.config.js file and use readSettings function to load them.

If you only want to use your own custom word list, then the following will work:

  const settings = {
    // Needed to load existing dictionaries. Not needed if you only plan to use your own.
    ...getDefaultSettings(),
    // Not needed
    // enabledLanguageIds: [],
    // Optionally your custom words can go here.
    words: customWords // these words will be part of the dictionary returned by getDictionary
  };

I suggest using mergeSettings to build up the settings if you read settings from a file.

const settings = mergeSettings(getDefaultSettings(), readSettings('path to your cspell.config.js`));
// empty '' is fine. The method looks for embedded `cspell` settings in the document. Since you do not
// expect them, no need to send any text.
const fileSettings = combineTextAndLanguageSettings(settings, '', ['plaintext']);

Avoid using compound word suggestions.

Avoid using compound word suggestions, they are very slow. Only use them if you expect to be splitting words.

const suggestions = dictionary.suggest(word, 1);