@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?)

Options

Entropy levels (defaults)

Charset detection

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