@ekaone/entropy

Primitive Shannon entropy measurement for strings.

Measures randomness density — best used for generated tokens, secrets, and API keys. Not intended for judging human-chosen passwords. Refer to Shannon entropy for details.

Installation

npm install @ekaone/entropy

yarn add @ekaone/entropy

pnpm add @ekaone/entropy

Usage

Basic — pure measurement

import { calculate } from "@ekaone/entropy"

calculate("hsg3-3;gs")
// { entropy: 3.46, length: 9, unique: 8 }

With level option

calculate("hsg3-3;gs", { level: true })
// { entropy: 3.46, length: 9, unique: 8, level: "medium" }

With charset option

calculate("hsg3-3;gs", { level: true, charset: true })
// { entropy: 3.46, length: 9, unique: 8, level: "medium", charset: "mixed" }

Custom thresholds

calculate("hsg3-3;gs", {
  level: { thresholds: { high: 5.0 } }
})

Tree-shakeable primitives

import { shannonEntropy } from "@ekaone/entropy"
import { classifyLevel, DEFAULT_THRESHOLDS } from "@ekaone/entropy"
import { detectCharset } from "@ekaone/entropy"

API

calculate(input, options?)

| Field | Type | Description | |---|---|---| | entropy | number | Shannon bits per character | | length | number | String length | | unique | number | Count of distinct characters | | level | EntropyLevel | Returned when options.level is set | | charset | CharSet | Returned when options.charset is set |

Options

| Option | Type | Description | |---|---|---| | level | boolean \| { thresholds? } | Enable level classification | | charset | boolean | Enable charset detection |

Entropy levels (defaults)

| Level | Bits | Typical example | |---|---|---| | low | < 2.5 | "aaaa", "1111" | | medium | 2.5–3.5 | "hsg3-3;gs" | | high | 3.5–4.5 | random hex hashes | | critical | ≥ 4.5 | API keys, JWT secrets |

Charset detection

| Charset | Rule | |---|---| | numeric | digits only | | alpha | letters only | | hex | [0-9a-fA-F] with both digits and letters, no letters outside a-f | | alphanumeric | letters + digits, not purely hex | | mixed | contains special characters |

Note: "deadbeef" classifies as alpha (no digits). "abc123" classifies as hex (all chars within hex range). This is expected — see charset ambiguity.

Charset ambiguity

Strings using only [0-9a-fA-F] characters are inherently ambiguous. @ekaone/entropy resolves this by requiring hex strings to contain both digits and letters within the a-f range. Pure-letter strings always classify as alpha regardless of whether their characters fall within hex range.

Building on top

This package is a primitive. Higher-level opinions live in consumer packages:

import { calculate } from "@ekaone/entropy"

// your app defines "strong"
const { entropy, length } = calculate(token)
const isStrong = entropy >= 4.0 && length >= 16

// your UI defines the label
const score = Math.round((entropy / 6.55) * 100)

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker