# how-similar

> Module to compare similarity between strings / arrays.

Latest version **3.0.0** (published 2026-04-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install how-similar
pnpm add how-similar
yarn add how-similar
bun add how-similar
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2026-04-07 |
| First published | 2019-01-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 0 |
| Unpacked size | 52.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Juan Convers |
| Maintainers | webdacjs |
| Keywords | similarity, compare, comparison, similar, string, levenshtein |

## Links

- npm: https://www.npmjs.com/package/how-similar
- Repository: https://github.com/webdacjs/how-similar
- Homepage: https://github.com/webdacjs/how-similar#readme
- Issues: https://github.com/webdacjs/how-similar/issues
- npm.io page: https://npm.io/package/how-similar

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 3.0.0 (latest) — 2026-04-07
- 1.0.0 — 2019-01-16

## README

# How Similar

A zero-dependency TypeScript module that compares strings and returns a similarity score from 0 to 1 using normalised Levenshtein distance.

```ts
import { similarity } from 'how-similar'

similarity('Dublin', 'Doblin') // 0.833
```

## Requirements

- Node.js ≥ 22 (uses native `--experimental-strip-types` for zero-build dev)

## Install

```sh
npm install how-similar
```

## Usage

```ts
import { similarity, stringSimilarity, stringArraySimilarity } from 'how-similar'
import type { SimilarityOptions, SimilarityResult } from 'how-similar'
```

### Compare two strings

```ts
similarity('Dublin', 'Doblin')  // 0.833
similarity('Dublin', 'Dublin')  // 1
```

### Compare a string against an array

Returns results sorted by similarity descending:

```ts
similarity('Dublin', ['Doblin', 'Devlin', 'Duuublin', 'Dublin'])
// [
//   { key: 'Dublin',   value: 1     },
//   { key: 'Doblin',   value: 0.875 },
//   { key: 'Devlin',   value: 0.75  },
//   { key: 'Duuublin', value: 0.75  }
// ]
```

### Options

All options are optional and can be combined:

| Option | Type | Description |
|---|---|---|
| `ignorecase` | `boolean` | Normalise both strings to lower-case before comparing |
| `stem` | `boolean` | Apply Porter stemming to each word before comparing |
| `except` | `string[]` | Words to strip from both strings before comparing |

```ts
// Ignore case
similarity('Dublin', 'dublin', { ignorecase: true })  // 1

// Stem words
similarity('Trying', 'Try', { stem: true })  // 1

// Exclude words
similarity('should be equal', 'should equal', { except: ['be'] })  // 1

// All options together
similarity('Trying to Be equal', 'try equal', {
  except: ['to', 'be'],
  ignorecase: true,
  stem: true
})  // 1
```

## Scripts

```sh
npm test          # Run tests directly from .ts source (no build needed)
npm run typecheck # Full tsc type-check
npm run build     # Emit dist/ with .js, .d.ts, and .map files
```

## License

Copyright © 2019, [Juan Convers](https://juanconvers.com).
Released under the [MIT License](LICENSE).

---
_Source: https://npm.io/package/how-similar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._