FAQ

This page answers common questions and recurring issues when using the CmpStr npm package. If your question is not covered here, consult the API Reference, Extending CmpStr, or open an issue on GitHub.

Frequently Asked Questions

How do I install CmpStr?

See the Installation & Setup page for details.
In short:

npm install cmpstr

How do I compare two strings for similarity?

Use the CmpStr class:

import { CmpStr } from 'cmpstr';

const cmp = CmpStr.create( { metric: 'levenshtein' } );
const result = cmp.test( 'kitten', 'sitting' );

For a step-by-step introduction, see Quick Start and the API Reference.

How do I use a different metric or phonetic algorithm?

Specify the metric or processors.phonetic option when creating or configuring a CmpStr instance.

Available options are documented under Similarity Metrics and Phonetic Algorithms.

How do I normalize or filter input data?

Use normalization flags (flags) for standard preprocessing, or the filter system for custom logic.

See Normalization & Filtering for details and examples.

How do I extend CmpStr with my own metric or phonetic algorithm?

Use the extension API exposed via cmpstr/root.

A complete guide is available on the Extending CmpStr page.

Can I use CmpStr asynchronously?

Yes. Use the CmpStrAsync class for fully Promise-based, non-blocking operations.

See the Asynchronous API page.

How do I contribute or request a feature?

Open an issue to discuss bugs or feature ideas.

Pull requests are welcome for bug fixes and well-scoped improvements.

Troubleshooting

I get an error: “No mapping specified for phonetic algorithm”

Ensure a valid map option is provided for the selected phonetic algorithm, or rely on its default mapping if available.

Example:

cmp.setProcessors( { phonetic: { algo: 'soundex', opt: { map: 'en' } } } );

I get an error: “Cannot set property … of …” when using options

This typically indicates invalid option merging in user code.

Make sure you are not:

• Passing primitive values instead of objects
• Passing frozen or immutable objects

If the issue appears to originate from CmpStr itself, please report it on GitHub.

Why do I get an error when passing empty arrays or strings?

By default, CmpStr throws an error when given empty inputs, as no comparison can be performed.

You can enable a “safe” mode by setting the safeEmpty option to return an empty array instead of throwing:`

const cmp = CmpStr.create( { safeEmpty: true } );
cmp.batchTest( [], [ 'foo' ] ); // returns []

Why is my custom metric/phonetic algorithm not recognized?

Make sure your implementation is registered at runtime using the appropriate registry:

• MetricRegistry
• PhoneticRegistry

Do not modify files inside node_modules/cmpstr.

See Extending CmpStr for correct usage.

How do I debug normalization or filtering issues?

Use the Normalizer and Filter classes directly to test individual steps of your preprocessing pipeline.

Check the Normalization & Filtering page for examples and tips.

How do I get help or report a bug?

First, check the API Reference and relevant documentation pages.

If the problem persists, open an issue on GitHub and include a minimal reproducible example.

Where can I find the changelog and license?

See the Changelog and License & Credits pages.

Still Need Help?

If your question is not answered here, please:

• Review the API Reference and documentation pages.
• Search or open an issue on GitHub.

CmpStr is actively maintained and community feedback is welcome!